0
# Handshake Configuration
1

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

4
## Capabilities
5

6
### HandshakeCertificates Class
7

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

10
```kotlin { .api }
11
/**
12
 * Certificates to identify which peers to trust and also to earn the trust of those peers
13
 * @param keyManager Manages client certificates for authentication
14
 * @param trustManager Manages trusted root certificates for peer validation
15
 */
16
class HandshakeCertificates private constructor(
17
    val keyManager: X509KeyManager,
18
    val trustManager: X509TrustManager
19
)
20
```
21

22
### SSL Socket Factory Creation
23

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

26
```kotlin { .api }
27
/**
28
 * Creates an SSL socket factory using the configured certificates
29
 * @return SSLSocketFactory for creating SSL connections
30
 */
31
fun sslSocketFactory(): SSLSocketFactory
32

33
/**
34
 * Creates an SSL context using the configured certificates  
35
 * @return SSLContext configured with key and trust managers
36
 */
37
fun sslContext(): SSLContext
38
```
39

40
**Usage Example:**
41

42
```kotlin
43
val handshakeCertificates = HandshakeCertificates.Builder()
44
    .addPlatformTrustedCertificates()
45
    .build()
46

47
// Use with OkHttp
48
val client = OkHttpClient.Builder()
49
    .sslSocketFactory(
50
        handshakeCertificates.sslSocketFactory(),
51
        handshakeCertificates.trustManager
52
    )
53
    .build()
54

55
// Use with raw SSL sockets
56
val sslContext = handshakeCertificates.sslContext()
57
val socket = sslContext.socketFactory.createSocket("example.com", 443)
58
```
59

60
## Handshake Builder
61

62
Configure TLS handshakes using the builder pattern.
63

64
### HandshakeCertificates.Builder Class
65

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

68
```kotlin { .api }
69
class Builder {
70
    fun heldCertificate(heldCertificate: HeldCertificate, vararg intermediates: X509Certificate): Builder
71
    fun addTrustedCertificate(certificate: X509Certificate): Builder
72
    fun addPlatformTrustedCertificates(): Builder
73
    fun addInsecureHost(hostname: String): Builder
74
    fun build(): HandshakeCertificates
75
}
76
```
77

78
### Identity Configuration
79

80
Configure the certificate chain to present during authentication.
81

82
```kotlin { .api }
83
/**
84
 * Configure the certificate chain to use when being authenticated
85
 * @param heldCertificate The certificate and private key for authentication
86
 * @param intermediates Additional intermediate certificates in the chain (vararg)
87
 * @return Builder instance for chaining
88
 */
89
fun heldCertificate(
90
    heldCertificate: HeldCertificate,
91
    vararg intermediates: X509Certificate
92
): Builder
93
```
94

95
**Usage Example:**
96

97
```kotlin
98
// Self-signed certificate (simple case)
99
val serverCert = HeldCertificate.Builder()
100
    .addSubjectAlternativeName("localhost")
101
    .build()
102

103
val serverHandshake = HandshakeCertificates.Builder()
104
    .heldCertificate(serverCert)
105
    .build()
106

107
// Certificate chain with intermediates
108
val rootCa = HeldCertificate.Builder().certificateAuthority(1).build()
109
val intermediateCa = HeldCertificate.Builder()
110
    .certificateAuthority(0)
111
    .signedBy(rootCa)
112
    .build()
113
val serverCert2 = HeldCertificate.Builder()
114
    .addSubjectAlternativeName("example.com")
115
    .signedBy(intermediateCa)
116
    .build()
117

118
val serverHandshake2 = HandshakeCertificates.Builder()
119
    .heldCertificate(serverCert2, intermediateCa.certificate)
120
    .build()
121
```
122

123
### Trust Configuration
124

125
Configure which root certificates to trust for peer authentication.
126

127
```kotlin { .api }
128
/**
129
 * Add a trusted root certificate to use when authenticating a peer
130
 * @param certificate Trusted root certificate
131
 * @return Builder instance for chaining
132
 */
133
fun addTrustedCertificate(certificate: X509Certificate): Builder
134

135
/**
136
 * Add all of the host platform's trusted root certificates
137
 * Includes certificates from the system trust store (varies by platform)
138
 * @return Builder instance for chaining
139
 */
140
fun addPlatformTrustedCertificates(): Builder
141
```
142

143
**Usage Example:**
144

145
```kotlin
146
// Trust specific certificates (typical for testing)
147
val clientHandshake = HandshakeCertificates.Builder()
148
    .addTrustedCertificate(serverCert.certificate)
149
    .build()
150

151
// Trust platform certificates (typical for production)
152
val productionClientHandshake = HandshakeCertificates.Builder()
153
    .addPlatformTrustedCertificates()
154
    .build()
155

156
// Combined trust (platform + custom)
157
val hybridHandshake = HandshakeCertificates.Builder()
158
    .addPlatformTrustedCertificates()
159
    .addTrustedCertificate(customRootCa.certificate)
160
    .build()
161
```
162

163
### Insecure Configuration
164

165
Configure insecure hosts for testing (development only).
166

167
```kotlin { .api }
168
/**
169
 * Configures this to not authenticate the HTTPS server for the specified hostname
170
 * WARNING: This makes connections vulnerable to man-in-the-middle attacks
171
 * Only use in private development environments with test data
172
 * @param hostname Exact hostname to allow insecure connections to
173
 * @return Builder instance for chaining
174
 */
175
fun addInsecureHost(hostname: String): Builder
176
```
177

178
**Usage Example:**
179

180
```kotlin
181
// For testing only - never use in production
182
val testHandshake = HandshakeCertificates.Builder()
183
    .addPlatformTrustedCertificates()
184
    .addInsecureHost("localhost")
185
    .addInsecureHost("test.local")
186
    .build()
187
```
188

189
### Build HandshakeCertificates
190

191
Create the final HandshakeCertificates instance.
192

193
```kotlin { .api }
194
/**
195
 * Builds the HandshakeCertificates with configured trust and identity settings
196
 * @return Complete HandshakeCertificates instance
197
 */
198
fun build(): HandshakeCertificates
199
```
200

201
## Common Usage Patterns
202

203
### Server Authentication (Standard HTTPS)
204

205
Most common TLS pattern where clients verify server identity.
206

207
```kotlin
208
// Server setup
209
val serverCert = HeldCertificate.Builder()
210
    .addSubjectAlternativeName("api.example.com")
211
    .build()
212

213
val serverHandshake = HandshakeCertificates.Builder()
214
    .heldCertificate(serverCert)
215
    .build()
216

217
// Client setup
218
val clientHandshake = HandshakeCertificates.Builder()
219
    .addPlatformTrustedCertificates() // Trust well-known CAs
220
    .build()
221

222
val client = OkHttpClient.Builder()
223
    .sslSocketFactory(
224
        clientHandshake.sslSocketFactory(),
225
        clientHandshake.trustManager
226
    )
227
    .build()
228
```
229

230
### Mutual Authentication (Client Certificates)
231

232
Both client and server authenticate each other using certificates.
233

234
```kotlin
235
// Create root CA for mutual trust
236
val rootCa = HeldCertificate.Builder()
237
    .certificateAuthority(0)
238
    .commonName("Test Root CA")
239
    .build()
240

241
// Create server certificate
242
val serverCert = HeldCertificate.Builder()
243
    .commonName("Test Server")
244
    .addSubjectAlternativeName("localhost")
245
    .signedBy(rootCa)
246
    .build()
247

248
// Create client certificate  
249
val clientCert = HeldCertificate.Builder()
250
    .commonName("Test Client")
251
    .signedBy(rootCa)
252
    .build()
253

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

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

266
val client = OkHttpClient.Builder()
267
    .sslSocketFactory(
268
        clientHandshake.sslSocketFactory(),
269
        clientHandshake.trustManager
270
    )
271
    .build()
272
```
273

274
### Self-Signed Testing Setup
275

276
Simple setup for testing with self-signed certificates.
277

278
```kotlin
279
// Create self-signed certificate
280
val testCert = HeldCertificate.Builder()
281
    .addSubjectAlternativeName("localhost")
282
    .addSubjectAlternativeName("127.0.0.1")
283
    .build()
284

285
// Server trusts nothing (no client auth)
286
val serverHandshake = HandshakeCertificates.Builder()
287
    .heldCertificate(testCert)
288
    .build()
289

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

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

299
val client = OkHttpClient.Builder()
300
    .sslSocketFactory(
301
        clientHandshake.sslSocketFactory(),
302
        clientHandshake.trustManager
303
    )
304
    .build()
305
```