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

Overview

Eval results

Files

Handshake Configuration

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

TLS handshake configuration functionality for managing certificate validation and trust relationships between clients and servers, supporting both server authentication and mutual client authentication.

Capabilities

HandshakeCertificates Class

Manages certificates for TLS handshakes, defining which certificates to present and which to trust.

/**
 * Certificates to identify which peers to trust and also to earn the trust of those peers
 * @param keyManager Manages client certificates for authentication
 * @param trustManager Manages trusted root certificates for peer validation
 */
class HandshakeCertificates private constructor(
    val keyManager: X509KeyManager,
    val trustManager: X509TrustManager
)

SSL Socket Factory Creation

Create SSL socket factories for use with OkHttp or other SSL clients.

/**
 * Creates an SSL socket factory using the configured certificates
 * @return SSLSocketFactory for creating SSL connections
 */
fun sslSocketFactory(): SSLSocketFactory

/**
 * Creates an SSL context using the configured certificates  
 * @return SSLContext configured with key and trust managers
 */
fun sslContext(): SSLContext

Usage Example:

val handshakeCertificates = HandshakeCertificates.Builder()
    .addPlatformTrustedCertificates()
    .build()

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

// Use with raw SSL sockets
val sslContext = handshakeCertificates.sslContext()
val socket = sslContext.socketFactory.createSocket("example.com", 443)

Handshake Builder

Configure TLS handshakes using the builder pattern.

HandshakeCertificates.Builder Class

Builder for creating HandshakeCertificates instances with specific trust and identity configurations.

class Builder {
    fun heldCertificate(heldCertificate: HeldCertificate, vararg intermediates: X509Certificate): Builder
    fun addTrustedCertificate(certificate: X509Certificate): Builder
    fun addPlatformTrustedCertificates(): Builder
    fun addInsecureHost(hostname: String): Builder
    fun build(): HandshakeCertificates
}

Identity Configuration

Configure the certificate chain to present during authentication.

/**
 * Configure the certificate chain to use when being authenticated
 * @param heldCertificate The certificate and private key for authentication
 * @param intermediates Additional intermediate certificates in the chain (vararg)
 * @return Builder instance for chaining
 */
fun heldCertificate(
    heldCertificate: HeldCertificate,
    vararg intermediates: X509Certificate
): Builder

Usage Example:

// Self-signed certificate (simple case)
val serverCert = HeldCertificate.Builder()
    .addSubjectAlternativeName("localhost")
    .build()

val serverHandshake = HandshakeCertificates.Builder()
    .heldCertificate(serverCert)
    .build()

// Certificate chain with intermediates
val rootCa = HeldCertificate.Builder().certificateAuthority(1).build()
val intermediateCa = HeldCertificate.Builder()
    .certificateAuthority(0)
    .signedBy(rootCa)
    .build()
val serverCert2 = HeldCertificate.Builder()
    .addSubjectAlternativeName("example.com")
    .signedBy(intermediateCa)
    .build()

val serverHandshake2 = HandshakeCertificates.Builder()
    .heldCertificate(serverCert2, intermediateCa.certificate)
    .build()

Trust Configuration

Configure which root certificates to trust for peer authentication.

/**
 * Add a trusted root certificate to use when authenticating a peer
 * @param certificate Trusted root certificate
 * @return Builder instance for chaining
 */
fun addTrustedCertificate(certificate: X509Certificate): Builder

/**
 * Add all of the host platform's trusted root certificates
 * Includes certificates from the system trust store (varies by platform)
 * @return Builder instance for chaining
 */
fun addPlatformTrustedCertificates(): Builder

Usage Example:

// Trust specific certificates (typical for testing)
val clientHandshake = HandshakeCertificates.Builder()
    .addTrustedCertificate(serverCert.certificate)
    .build()

// Trust platform certificates (typical for production)
val productionClientHandshake = HandshakeCertificates.Builder()
    .addPlatformTrustedCertificates()
    .build()

// Combined trust (platform + custom)
val hybridHandshake = HandshakeCertificates.Builder()
    .addPlatformTrustedCertificates()
    .addTrustedCertificate(customRootCa.certificate)
    .build()

Insecure Configuration

Configure insecure hosts for testing (development only).

/**
 * Configures this to not authenticate the HTTPS server for the specified hostname
 * WARNING: This makes connections vulnerable to man-in-the-middle attacks
 * Only use in private development environments with test data
 * @param hostname Exact hostname to allow insecure connections to
 * @return Builder instance for chaining
 */
fun addInsecureHost(hostname: String): Builder

Usage Example:

// For testing only - never use in production
val testHandshake = HandshakeCertificates.Builder()
    .addPlatformTrustedCertificates()
    .addInsecureHost("localhost")
    .addInsecureHost("test.local")
    .build()

Build HandshakeCertificates

Create the final HandshakeCertificates instance.

/**
 * Builds the HandshakeCertificates with configured trust and identity settings
 * @return Complete HandshakeCertificates instance
 */
fun build(): HandshakeCertificates

Common Usage Patterns

Server Authentication (Standard HTTPS)

Most common TLS pattern where clients verify server identity.

// Server setup
val serverCert = HeldCertificate.Builder()
    .addSubjectAlternativeName("api.example.com")
    .build()

val serverHandshake = HandshakeCertificates.Builder()
    .heldCertificate(serverCert)
    .build()

// Client setup
val clientHandshake = HandshakeCertificates.Builder()
    .addPlatformTrustedCertificates() // Trust well-known CAs
    .build()

val client = OkHttpClient.Builder()
    .sslSocketFactory(
        clientHandshake.sslSocketFactory(),
        clientHandshake.trustManager
    )
    .build()

Mutual Authentication (Client Certificates)

Both client and server authenticate each other using certificates.

// Create root CA for mutual trust
val rootCa = HeldCertificate.Builder()
    .certificateAuthority(0)
    .commonName("Test Root CA")
    .build()

// Create server certificate
val serverCert = HeldCertificate.Builder()
    .commonName("Test Server")
    .addSubjectAlternativeName("localhost")
    .signedBy(rootCa)
    .build()

// Create client certificate  
val clientCert = HeldCertificate.Builder()
    .commonName("Test Client")
    .signedBy(rootCa)
    .build()

// Server configuration (presents server cert, trusts root CA for clients)
val serverHandshake = HandshakeCertificates.Builder()
    .addTrustedCertificate(rootCa.certificate)
    .heldCertificate(serverCert)
    .build()

// Client configuration (presents client cert, trusts root CA for server)
val clientHandshake = HandshakeCertificates.Builder()
    .addTrustedCertificate(rootCa.certificate)
    .heldCertificate(clientCert)
    .build()

val client = OkHttpClient.Builder()
    .sslSocketFactory(
        clientHandshake.sslSocketFactory(),
        clientHandshake.trustManager
    )
    .build()

Self-Signed Testing Setup

Simple setup for testing with self-signed certificates.

// Create self-signed certificate
val testCert = HeldCertificate.Builder()
    .addSubjectAlternativeName("localhost")
    .addSubjectAlternativeName("127.0.0.1")
    .build()

// Server trusts nothing (no client auth)
val serverHandshake = HandshakeCertificates.Builder()
    .heldCertificate(testCert)
    .build()

// Client trusts the server's self-signed certificate
val clientHandshake = HandshakeCertificates.Builder()
    .addTrustedCertificate(testCert.certificate)
    .build()

// Use for testing
val mockServer = MockWebServer()
mockServer.useHttps(serverHandshake.sslSocketFactory(), false)

val client = OkHttpClient.Builder()
    .sslSocketFactory(
        clientHandshake.sslSocketFactory(),
        clientHandshake.trustManager
    )
    .build()

Install with Tessl CLI

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

docs

certificate-management.md

handshake-configuration.md

index.md

pem-utilities.md

tile.json

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