or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

certificate-management.mdhandshake-configuration.mdindex.mdpem-utilities.md
tile.json

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.squareup.okhttp3/okhttp-tls@4.12.x

To install, run

npx @tessl/cli install tessl/maven-com-squareup-okhttp3--okhttp-tls@4.12.0

index.mddocs/

OkHttp TLS

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