0
# Certificate Management
1

2
Certificate creation and management functionality for TLS authentication, including self-signed certificates, certificate authorities, and complete certificate chains with proper security practices.
3

4
## Capabilities
5

6
### HeldCertificate Class
7

8
Represents a certificate and its private key, providing the foundation for TLS authentication.
9

10
```kotlin { .api }
11
/**
12
 * A certificate and its private key for TLS authentication
13
 * @param keyPair The public/private key pair
14
 * @param certificate The X.509 certificate
15
 */
16
class HeldCertificate(
17
    val keyPair: KeyPair,
18
    val certificate: X509Certificate
19
)
20
```
21

22
### Certificate PEM Encoding
23

24
Export certificates in PEM format for storage or transmission.
25

26
```kotlin { .api }
27
/**
28
 * Returns the certificate encoded in PEM format
29
 * @return Certificate in PEM format with BEGIN/END markers
30
 */
31
fun certificatePem(): String
32
```
33

34
**Usage Example:**
35

36
```kotlin
37
val certificate = HeldCertificate.Builder().build()
38
val pemString = certificate.certificatePem()
39
println(pemString)
40
// Output:
41
// -----BEGIN CERTIFICATE-----
42
// MIIBSjCB8aADAgECAgEBMAoGCCqGSM49BAMCMC8x...
43
// -----END CERTIFICATE-----
44
```
45

46
### Private Key PEM Encoding
47

48
Export private keys in standard PEM formats.
49

50
```kotlin { .api }
51
/**
52
 * Returns the RSA private key encoded in PKCS #8 PEM format
53
 * @return Private key in PKCS #8 PEM format
54
 */
55
fun privateKeyPkcs8Pem(): String
56

57
/**
58
 * Returns the RSA private key encoded in PKCS #1 PEM format  
59
 * @return Private key in PKCS #1 PEM format
60
 * @throws IllegalStateException if key is not RSA
61
 */
62
fun privateKeyPkcs1Pem(): String
63
```
64

65
**Usage Example:**
66

67
```kotlin
68
val certificate = HeldCertificate.Builder().rsa2048().build()
69

70
// PKCS #8 format (universal)
71
val pkcs8Key = certificate.privateKeyPkcs8Pem()
72

73
// PKCS #1 format (RSA only)
74
val pkcs1Key = certificate.privateKeyPkcs1Pem()
75
```
76

77
### Certificate Decoding
78

79
Parse certificates and private keys from PEM format strings.
80

81
```kotlin { .api }
82
/**
83
 * Decodes a multiline string containing both certificate and private key in PEM format
84
 * @param certificateAndPrivateKeyPem PEM string with certificate and private key
85
 * @return HeldCertificate instance with parsed certificate and key
86
 * @throws IllegalArgumentException if parsing fails or format is invalid
87
 */
88
companion object {
89
    fun decode(certificateAndPrivateKeyPem: String): HeldCertificate
90
}
91
```
92

93
**Usage Example:**
94

95
```kotlin
96
val pemString = """
97
    -----BEGIN CERTIFICATE-----
98
    MIIBYTCCAQegAwIBAgIBKjAKBggqhkjOPQQDAjApMRQwEgYDVQQLEwtlbmdpbmVl
99
    cmluZzERMA0GA1UEAxMIY2FzaC5hcHAwHhcNNzAwMTAxMDAwMDA1WhcNNzAwMTAx
100
    ...
101
    -----END CERTIFICATE-----
102
    -----BEGIN PRIVATE KEY-----
103
    MEECAQAwEwYHKoZIzj0CAQYIKoZIzj0DAQcEJzAlAgEBBCA7ODT0xhGSNn4ESj6J
104
    lu/GJQZoU9lDrCPeUcQ28tzOWw==
105
    -----END PRIVATE KEY-----
106
""".trimIndent()
107

108
val heldCertificate = HeldCertificate.decode(pemString)
109
```
110

111
## Certificate Builder
112

113
Create certificates with flexible configuration options using the builder pattern.
114

115
### HeldCertificate.Builder Class
116

117
Builder for creating HeldCertificate instances with configurable properties.
118

119
```kotlin { .api }
120
class Builder {
121
    fun validityInterval(notBefore: Long, notAfter: Long): Builder
122
    fun duration(duration: Long, unit: TimeUnit): Builder
123
    fun addSubjectAlternativeName(altName: String): Builder
124
    fun commonName(cn: String): Builder
125
    fun organizationalUnit(ou: String): Builder
126
    fun serialNumber(serialNumber: BigInteger): Builder
127
    fun serialNumber(serialNumber: Long): Builder
128
    fun keyPair(keyPair: KeyPair): Builder
129
    fun keyPair(publicKey: PublicKey, privateKey: PrivateKey): Builder
130
    fun signedBy(signedBy: HeldCertificate?): Builder
131
    fun certificateAuthority(maxIntermediateCas: Int): Builder
132
    fun ecdsa256(): Builder
133
    fun rsa2048(): Builder
134
    fun build(): HeldCertificate
135
}
136
```
137

138
### Validity Configuration
139

140
Set certificate validity periods.
141

142
```kotlin { .api }
143
/**
144
 * Sets the certificate validity interval using timestamps
145
 * @param notBefore Start of validity in milliseconds since epoch (-1L for default)
146
 * @param notAfter End of validity in milliseconds since epoch (-1L for default)
147
 * @return Builder instance for chaining
148
 */
149
fun validityInterval(notBefore: Long, notAfter: Long): Builder
150

151
/**
152
 * Sets the certificate to be valid immediately for specified duration
153
 * @param duration Duration value
154
 * @param unit Time unit (DAYS, HOURS, etc.)
155
 * @return Builder instance for chaining
156
 */
157
fun duration(duration: Long, unit: TimeUnit): Builder
158
```
159

160
**Usage Example:**
161

162
```kotlin
163
// Valid for 30 days starting now
164
val certificate = HeldCertificate.Builder()
165
    .duration(30, TimeUnit.DAYS)
166
    .build()
167

168
// Custom validity interval
169
val now = System.currentTimeMillis()
170
val certificate2 = HeldCertificate.Builder()
171
    .validityInterval(now, now + TimeUnit.DAYS.toMillis(365))
172
    .build()
173
```
174

175
### Subject Configuration
176

177
Configure certificate subject information.
178

179
```kotlin { .api }
180
/**
181
 * Adds a subject alternative name (SAN) to the certificate
182
 * @param altName Hostname, IP address, or hostname pattern (*.example.com)
183
 * @return Builder instance for chaining
184
 */
185
fun addSubjectAlternativeName(altName: String): Builder
186

187
/**
188
 * Set the certificate's common name (CN)
189
 * @param cn Common name string
190
 * @return Builder instance for chaining
191
 */
192
fun commonName(cn: String): Builder
193

194
/**
195
 * Sets the certificate's organizational unit (OU)
196
 * @param ou Organizational unit string
197
 * @return Builder instance for chaining
198
 */
199
fun organizationalUnit(ou: String): Builder
200
```
201

202
**Usage Example:**
203

204
```kotlin
205
val certificate = HeldCertificate.Builder()
206
    .commonName("Test Server")
207
    .organizationalUnit("Engineering")
208
    .addSubjectAlternativeName("localhost")
209
    .addSubjectAlternativeName("127.0.0.1")
210
    .addSubjectAlternativeName("*.test.local")
211
    .build()
212
```
213

214
### Certificate Serialization
215

216
Configure certificate serial numbers.
217

218
```kotlin { .api }
219
/**
220
 * Sets the certificate's serial number
221
 * @param serialNumber Certificate serial number as BigInteger
222
 * @return Builder instance for chaining
223
 */
224
fun serialNumber(serialNumber: BigInteger): Builder
225

226
/**
227
 * Sets the certificate's serial number
228
 * @param serialNumber Certificate serial number as long
229
 * @return Builder instance for chaining  
230
 */
231
fun serialNumber(serialNumber: Long): Builder
232
```
233

234
### Key Pair Configuration
235

236
Configure public/private key pairs for the certificate.
237

238
```kotlin { .api }
239
/**
240
 * Sets the public/private key pair for the certificate
241
 * @param keyPair Pre-existing key pair
242
 * @return Builder instance for chaining
243
 */
244
fun keyPair(keyPair: KeyPair): Builder
245

246
/**
247
 * Sets the public/private key pair from individual keys
248
 * @param publicKey Public key
249
 * @param privateKey Private key
250
 * @return Builder instance for chaining
251
 */
252
fun keyPair(publicKey: PublicKey, privateKey: PrivateKey): Builder
253
```
254

255
### Certificate Authority Configuration
256

257
Configure certificates as certificate authorities that can sign other certificates.
258

259
```kotlin { .api }
260
/**
261
 * Sets the certificate that will issue/sign this certificate
262
 * @param signedBy Signing certificate (null for self-signed)
263
 * @return Builder instance for chaining
264
 */
265
fun signedBy(signedBy: HeldCertificate?): Builder
266

267
/**
268
 * Make this certificate a signing certificate authority
269
 * @param maxIntermediateCas Maximum number of intermediate CAs allowed beneath this CA
270
 * @return Builder instance for chaining
271
 */
272
fun certificateAuthority(maxIntermediateCas: Int): Builder
273
```
274

275
**Usage Example:**
276

277
```kotlin
278
// Create root CA
279
val rootCa = HeldCertificate.Builder()
280
    .certificateAuthority(1)
281
    .commonName("Test Root CA")
282
    .build()
283

284
// Create intermediate CA signed by root
285
val intermediateCa = HeldCertificate.Builder()
286
    .certificateAuthority(0)
287
    .commonName("Test Intermediate CA")
288
    .signedBy(rootCa)
289
    .build()
290

291
// Create server certificate signed by intermediate
292
val serverCert = HeldCertificate.Builder()
293
    .commonName("Test Server")
294
    .addSubjectAlternativeName("localhost")
295
    .signedBy(intermediateCa)
296
    .build()
297
```
298

299
### Key Algorithm Configuration
300

301
Configure cryptographic algorithms for key generation.
302

303
```kotlin { .api }
304
/**
305
 * Configure certificate to generate a 256-bit ECDSA key (default)
306
 * Provides ~128 bits of security, faster than RSA
307
 * @return Builder instance for chaining
308
 */
309
fun ecdsa256(): Builder
310

311
/**
312
 * Configure certificate to generate a 2048-bit RSA key
313
 * Provides ~112 bits of security, compatible with older clients
314
 * @return Builder instance for chaining
315
 */
316
fun rsa2048(): Builder
317
```
318

319
**Usage Example:**
320

321
```kotlin
322
// Default ECDSA certificate (recommended)
323
val ecdsaCert = HeldCertificate.Builder()
324
    .ecdsa256()
325
    .build()
326

327
// RSA certificate for legacy compatibility
328
val rsaCert = HeldCertificate.Builder()
329
    .rsa2048()
330
    .build()
331
```
332

333
### Build Certificate
334

335
Create the final HeldCertificate instance.
336

337
```kotlin { .api }
338
/**
339
 * Builds the HeldCertificate with configured properties
340
 * @return Complete HeldCertificate instance
341
 * @throws IllegalArgumentException if configuration is invalid
342
 */
343
fun build(): HeldCertificate
344
```