0
# OkHttp TLS
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: okhttp-tls
7
- **Package Type**: maven
8
- **Group ID**: com.squareup.okhttp3
9
- **Artifact ID**: okhttp-tls
10
- **Language**: Kotlin/Java
11
- **Installation**: `implementation("com.squareup.okhttp3:okhttp-tls:4.12.0")`
12

13
## Core Imports
14

15
```kotlin
16
import okhttp3.tls.HeldCertificate
17
import okhttp3.tls.HandshakeCertificates
18
import okhttp3.tls.certificatePem
19
import okhttp3.tls.decodeCertificatePem
20
```
21

22
For Java:
23

24
```java
25
import okhttp3.tls.HeldCertificate;
26
import okhttp3.tls.HandshakeCertificates;
27
import static okhttp3.tls.CertificatesKt.certificatePem;
28
import static okhttp3.tls.CertificatesKt.decodeCertificatePem;
29
```
30

31
## Basic Usage
32

33
```kotlin
34
import okhttp3.tls.HeldCertificate
35
import okhttp3.tls.HandshakeCertificates
36
import java.net.InetAddress
37

38
// Create a self-signed certificate for localhost
39
val localhost = InetAddress.getByName("localhost").canonicalHostName
40
val localhostCertificate = HeldCertificate.Builder()
41
    .addSubjectAlternativeName(localhost)
42
    .build()
43

44
// Create server handshake certificates
45
val serverCertificates = HandshakeCertificates.Builder()
46
    .heldCertificate(localhostCertificate)
47
    .build()
48

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

54
// Use with OkHttp
55
val client = OkHttpClient.Builder()
56
    .sslSocketFactory(clientCertificates.sslSocketFactory(), clientCertificates.trustManager)
57
    .build()
58
```
59

60
## Architecture
61

62
OkHttp TLS is built around three core components:
63

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

70
## Capabilities
71

72
### Certificate Creation and Management
73

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

76
```kotlin { .api }
77
class HeldCertificate(
78
    val keyPair: KeyPair,
79
    val certificate: X509Certificate
80
) {
81
    fun certificatePem(): String
82
    fun privateKeyPkcs8Pem(): String
83
    fun privateKeyPkcs1Pem(): String
84
    
85
    companion object {
86
        fun decode(certificateAndPrivateKeyPem: String): HeldCertificate
87
    }
88
}
89
```
90

91
[Certificate Management](./certificate-management.md)
92

93
### TLS Handshake Configuration
94

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

97
```kotlin { .api }
98
class HandshakeCertificates private constructor(
99
    val keyManager: X509KeyManager,
100
    val trustManager: X509TrustManager  
101
) {
102
    fun sslSocketFactory(): SSLSocketFactory
103
    fun sslContext(): SSLContext
104
}
105
```
106

107
[Handshake Configuration](./handshake-configuration.md)
108

109
### PEM Certificate Utilities
110

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

113
```kotlin { .api }
114
fun String.decodeCertificatePem(): X509Certificate
115
fun X509Certificate.certificatePem(): String
116
```
117

118
[PEM Utilities](./pem-utilities.md)
119

120
## Types
121

122
```kotlin { .api }
123
// Java standard library types used throughout
124
import java.security.KeyPair
125
import java.security.cert.X509Certificate
126
import javax.net.ssl.X509KeyManager
127
import javax.net.ssl.X509TrustManager
128
import javax.net.ssl.SSLSocketFactory
129
import javax.net.ssl.SSLContext
130
```