tessl/maven-com-squareup-okhttp3--okhttp-tls

OkHttp Transport Layer Security (TLS) library providing approachable APIs for using TLS, including certificate handling, certificate authorities, and client authentication

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

OkHttp TLS

Name: tessl/maven-com-squareup-okhttp3--okhttp-tls
Author: tessl

OkHttp TLS provides approachable APIs for using TLS, including certificate handling, certificate authorities, and client authentication. It enables developers to easily create self-signed certificates for testing, configure certificate authorities for production, and handle complex TLS scenarios like mutual authentication without compromising security practices.

Package Information

Package Name: okhttp-tls
Package Type: maven
Group ID: com.squareup.okhttp3
Artifact ID: okhttp-tls
Language: Kotlin/Java
Installation: implementation("com.squareup.okhttp3:okhttp-tls:4.12.0")

Core Imports

import okhttp3.tls.HeldCertificate
import okhttp3.tls.HandshakeCertificates
import okhttp3.tls.certificatePem
import okhttp3.tls.decodeCertificatePem

For Java:

import okhttp3.tls.HeldCertificate;
import okhttp3.tls.HandshakeCertificates;
import static okhttp3.tls.CertificatesKt.certificatePem;
import static okhttp3.tls.CertificatesKt.decodeCertificatePem;

Basic Usage

import okhttp3.tls.HeldCertificate
import okhttp3.tls.HandshakeCertificates
import java.net.InetAddress

// Create a self-signed certificate for localhost
val localhost = InetAddress.getByName("localhost").canonicalHostName
val localhostCertificate = HeldCertificate.Builder()
    .addSubjectAlternativeName(localhost)
    .build()

// Create server handshake certificates
val serverCertificates = HandshakeCertificates.Builder()
    .heldCertificate(localhostCertificate)
    .build()

// Create client handshake certificates that trust the server
val clientCertificates = HandshakeCertificates.Builder()
    .addTrustedCertificate(localhostCertificate.certificate)
    .build()

// Use with OkHttp
val client = OkHttpClient.Builder()
    .sslSocketFactory(clientCertificates.sslSocketFactory(), clientCertificates.trustManager)
    .build()

Architecture

OkHttp TLS is built around three core components:

Certificate Management: HeldCertificate class representing a certificate and its private key, with a fluent builder for creation
Handshake Configuration: HandshakeCertificates class managing trust relationships between clients and servers
PEM Utilities: Extension functions for encoding/decoding certificates in PEM format
Builder Pattern: Consistent builder pattern throughout for configurable, secure defaults
Security Focus: Designed to eliminate common TLS misconfigurations and insecure practices

Capabilities

Certificate Creation and Management

Create certificates with private keys for TLS authentication. Supports self-signed certificates, certificate authorities, and complete certificate chains.

class HeldCertificate(
    val keyPair: KeyPair,
    val certificate: X509Certificate
) {
    fun certificatePem(): String
    fun privateKeyPkcs8Pem(): String
    fun privateKeyPkcs1Pem(): String
    
    companion object {
        fun decode(certificateAndPrivateKeyPem: String): HeldCertificate
    }
}

Certificate Management

TLS Handshake Configuration

Configure TLS handshakes with proper certificate validation and trust relationships. Handles both server authentication and mutual client authentication.

class HandshakeCertificates private constructor(
    val keyManager: X509KeyManager,
    val trustManager: X509TrustManager  
) {
    fun sslSocketFactory(): SSLSocketFactory
    fun sslContext(): SSLContext
}

Handshake Configuration

PEM Certificate Utilities

Utility functions for encoding and decoding X.509 certificates in PEM format, enabling easy certificate persistence and exchange.

fun String.decodeCertificatePem(): X509Certificate
fun X509Certificate.certificatePem(): String

PEM Utilities

Types

// Java standard library types used throughout
import java.security.KeyPair
import java.security.cert.X509Certificate
import javax.net.ssl.X509KeyManager
import javax.net.ssl.X509TrustManager
import javax.net.ssl.SSLSocketFactory
import javax.net.ssl.SSLContext