0
# Key Management
1

2
SSL key material management with support for PEM files, keystores, programmatic key configurations, and key manager creation with comprehensive validation and security features.
3

4
## Capabilities
5

6
### SSL Key Configuration Interface
7

8
Core interface for SSL key material configuration providing key managers and key material access.
9

10
```java { .api }
11
/**
12
 * Interface for SSL key material configuration
13
 */
14
public interface SslKeyConfig {
15
    /**
16
     * Gets all certificate and key files this configuration depends on
17
     * @return collection of file paths for monitoring changes
18
     */
19
    Collection<Path> getDependentFiles();
20
    
21
    /**
22
     * Creates a key manager from this key configuration
23
     * @return configured X509ExtendedKeyManager for SSL contexts
24
     * @throws SslConfigException if key manager creation fails
25
     */
26
    X509ExtendedKeyManager createKeyManager();
27
    
28
    /**
29
     * Gets all private keys and their associated certificates
30
     * @return list of private key and certificate tuples
31
     */
32
    List<Tuple<PrivateKey, X509Certificate>> getKeys();
33
    
34
    /**
35
     * Gets all configured certificates with metadata
36
     * @return collection of stored certificates
37
     */
38
    Collection<StoredCertificate> getConfiguredCertificates();
39
    
40
    /**
41
     * Checks if this configuration contains any key material
42
     * @return true if key material is available
43
     */
44
    default boolean hasKeyMaterial();
45
    
46
    /**
47
     * Converts this key configuration to a trust configuration
48
     * @return SslTrustConfig using the certificates from this key config
49
     */
50
    default SslTrustConfig asTrustConfig();
51
}
52
```
53

54
### PEM Key Configuration
55

56
Key configuration that reads from PEM formatted certificate and private key files.
57

58
```java { .api }
59
/**
60
 * SSL key configuration using PEM formatted certificate and key files
61
 */
62
public final class PemKeyConfig implements SslKeyConfig {
63
    /**
64
     * Creates a PEM-based key configuration
65
     * @param certificatePath path to PEM certificate file (relative to configBasePath)
66
     * @param keyPath path to PEM private key file (relative to configBasePath)
67
     * @param keyPassword password for encrypted private key (null if unencrypted)
68
     * @param configBasePath base path for resolving relative paths
69
     */
70
    public PemKeyConfig(String certificatePath, String keyPath, char[] keyPassword, Path configBasePath);
71
    
72
    /**
73
     * Checks if this configuration contains key material
74
     * @return true if both certificate and key files are configured
75
     */
76
    public boolean hasKeyMaterial();
77
    
78
    /**
79
     * Gets dependent certificate and key file paths
80
     * @return collection containing certificate and key file paths
81
     */
82
    public Collection<Path> getDependentFiles();
83
    
84
    /**
85
     * Gets configured certificates with metadata
86
     * @return collection of certificates from the PEM file
87
     */
88
    public Collection<StoredCertificate> getConfiguredCertificates();
89
    
90
    /**
91
     * Creates X509ExtendedKeyManager from PEM files
92
     * @return configured key manager
93
     * @throws SslConfigException if PEM parsing or key manager creation fails
94
     */
95
    public X509ExtendedKeyManager createKeyManager();
96
    
97
    /**
98
     * Gets private keys and certificates from PEM files
99
     * @return list of private key and certificate pairs
100
     */
101
    public List<Tuple<PrivateKey, X509Certificate>> getKeys();
102
    
103
    /**
104
     * Converts to trust configuration using the certificates
105
     * @return PemTrustConfig using this configuration's certificates
106
     */
107
    public SslTrustConfig asTrustConfig();
108
    
109
    @Override
110
    public String toString();
111
    
112
    @Override
113
    public boolean equals(Object o);
114
    
115
    @Override
116
    public int hashCode();
117
}
118
```
119

120
**Usage Examples:**
121

122
```java
123
import org.elasticsearch.common.ssl.PemKeyConfig;
124
import javax.net.ssl.X509ExtendedKeyManager;
125
import java.nio.file.Path;
126
import java.nio.file.Paths;
127

128
// Create PEM key configuration with unencrypted key
129
PemKeyConfig keyConfig = new PemKeyConfig(
130
    "server.crt",           // certificate file
131
    "server.key",           // private key file  
132
    null,                   // no password (unencrypted key)
133
    Paths.get("/etc/ssl")   // base path
134
);
135

136
// Create PEM key configuration with encrypted key
137
PemKeyConfig encryptedKeyConfig = new PemKeyConfig(
138
    "certs/server.pem",     // certificate file
139
    "private/server.key",   // private key file
140
    "secret123".toCharArray(), // key password
141
    Paths.get("/config")    // base path
142
);
143

144
// Create key manager
145
X509ExtendedKeyManager keyManager = keyConfig.createKeyManager();
146

147
// Check for key material
148
if (keyConfig.hasKeyMaterial()) {
149
    // Get dependent files for monitoring
150
    Collection<Path> files = keyConfig.getDependentFiles();
151
    
152
    // Get certificates with metadata
153
    Collection<StoredCertificate> certificates = keyConfig.getConfiguredCertificates();
154
    
155
    // Convert to trust configuration
156
    SslTrustConfig trustConfig = keyConfig.asTrustConfig();
157
}
158
```
159

160
### Store Key Configuration
161

162
Key configuration that builds key managers from keystore files (JKS, PKCS12, etc.) with optional filtering.
163

164
```java { .api }
165
/**
166
 * SSL key configuration using keystore files
167
 */
168
public class StoreKeyConfig implements SslKeyConfig {
169
    /**
170
     * Creates a keystore-based key configuration
171
     * @param path path to keystore file (relative to configBasePath)
172
     * @param storePassword password for keystore access
173
     * @param type keystore type (JKS, PKCS12, etc.) or null to infer from file extension
174
     * @param filter optional function to filter keystore entries
175
     * @param keyPassword password for private key extraction (may differ from store password)
176
     * @param algorithm key manager algorithm (e.g., "SunX509", "PKIX")
177
     * @param configBasePath base path for resolving relative paths
178
     */
179
    public StoreKeyConfig(String path, char[] storePassword, String type, 
180
                         @Nullable Function<KeyStore, KeyStore> filter, char[] keyPassword, 
181
                         String algorithm, Path configBasePath);
182
    
183
    /**
184
     * Converts to trust configuration using keystore certificates
185
     * @return StoreTrustConfig using this keystore for trust
186
     */
187
    public SslTrustConfig asTrustConfig();
188
    
189
    /**
190
     * Gets dependent keystore file paths
191
     * @return collection containing keystore file path
192
     */
193
    public Collection<Path> getDependentFiles();
194
    
195
    /**
196
     * Checks if keystore contains key material
197
     * @return true if keystore has private key entries
198
     */
199
    public boolean hasKeyMaterial();
200
    
201
    /**
202
     * Gets private keys and certificates from keystore
203
     * @return list of private key and certificate pairs
204
     * @throws GeneralSecurityException if keystore access fails
205
     */
206
    public List<Tuple<PrivateKey, X509Certificate>> getKeys() throws GeneralSecurityException;
207
    
208
    /**
209
     * Gets private keys and certificates with optional filtering
210
     * @param filterKeystore whether to apply the configured filter
211
     * @return list of private key and certificate pairs
212
     * @throws GeneralSecurityException if keystore access fails
213
     */
214
    public List<Tuple<PrivateKey, X509Certificate>> getKeys(boolean filterKeystore) throws GeneralSecurityException;
215
    
216
    /**
217
     * Gets configured certificates with metadata
218
     * @return collection of certificates from keystore
219
     */
220
    public Collection<StoredCertificate> getConfiguredCertificates();
221
    
222
    /**
223
     * Creates X509ExtendedKeyManager from keystore
224
     * @return configured key manager
225
     * @throws GeneralSecurityException if key manager creation fails
226
     */
227
    public X509ExtendedKeyManager createKeyManager() throws GeneralSecurityException;
228
    
229
    @Override
230
    public String toString();
231
    
232
    @Override
233
    public boolean equals(Object o);
234
    
235
    @Override
236
    public int hashCode();
237
}
238
```
239

240
**Usage Examples:**
241

242
```java
243
import org.elasticsearch.common.ssl.StoreKeyConfig;
244
import java.security.KeyStore;
245
import java.util.function.Function;
246
import java.nio.file.Paths;
247

248
// Simple keystore configuration
249
StoreKeyConfig keystoreConfig = new StoreKeyConfig(
250
    "keystore.p12",           // keystore file
251
    "storepass".toCharArray(), // keystore password
252
    "PKCS12",                 // keystore type
253
    null,                     // no filtering
254
    "keypass".toCharArray(),  // private key password
255
    "PKIX",                   // key manager algorithm
256
    Paths.get("/etc/ssl")     // base path
257
);
258

259
// Keystore configuration with filtering (only include specific aliases)
260
Function<KeyStore, KeyStore> filter = keystore -> {
261
    // Custom logic to filter keystore entries
262
    return KeyStoreUtil.filter(keystore, entry -> 
263
        entry.getAlias().startsWith("server-"));
264
};
265

266
StoreKeyConfig filteredConfig = new StoreKeyConfig(
267
    "combined.jks",           // keystore file
268
    "password".toCharArray(), // keystore password
269
    null,                     // infer type from extension
270
    filter,                   // apply custom filter
271
    "keypass".toCharArray(),  // private key password
272
    "SunX509",               // key manager algorithm
273
    Paths.get("/config/ssl") // base path
274
);
275

276
// Use the configuration
277
X509ExtendedKeyManager keyManager = keystoreConfig.createKeyManager();
278

279
// Get specific keys and certificates
280
List<Tuple<PrivateKey, X509Certificate>> keys = keystoreConfig.getKeys();
281

282
// Convert to trust configuration
283
SslTrustConfig trustConfig = keystoreConfig.asTrustConfig();
284
```
285

286
### Empty Key Configuration
287

288
Singleton key configuration that provides no key material (null key manager).
289

290
```java { .api }
291
/**
292
 * SSL key configuration that provides no key material
293
 */
294
public final class EmptyKeyConfig implements SslKeyConfig {
295
    /**
296
     * Singleton instance for empty key configuration
297
     */
298
    public static final EmptyKeyConfig INSTANCE;
299
    
300
    /**
301
     * Gets empty collection (no dependent files)
302
     * @return empty collection
303
     */
304
    public Collection<Path> getDependentFiles();
305
    
306
    /**
307
     * Gets empty list (no keys)
308
     * @return empty list
309
     */
310
    public List<Tuple<PrivateKey, X509Certificate>> getKeys();
311
    
312
    /**
313
     * Gets empty collection (no certificates)
314
     * @return empty collection
315
     */
316
    public Collection<StoredCertificate> getConfiguredCertificates();
317
    
318
    /**
319
     * Always returns false (no key material)
320
     * @return false
321
     */
322
    public boolean hasKeyMaterial();
323
    
324
    /**
325
     * Creates a null key manager (no client authentication)
326
     * @return null (no key manager)
327
     */
328
    public X509ExtendedKeyManager createKeyManager();
329
    
330
    @Override
331
    public String toString();
332
}
333
```
334

335
**Usage Examples:**
336

337
```java
338
import org.elasticsearch.common.ssl.EmptyKeyConfig;
339

340
// Use empty key configuration (no client certificates)
341
SslKeyConfig keyConfig = EmptyKeyConfig.INSTANCE;
342

343
// Check for key material
344
boolean hasKeys = keyConfig.hasKeyMaterial(); // always false
345

346
// Create key manager (returns null)
347
X509ExtendedKeyManager keyManager = keyConfig.createKeyManager(); // null
348

349
// Use in SSL configuration for server-only SSL (no client auth)
350
SslConfiguration config = new SslConfiguration(
351
    "https",
352
    true,
353
    trustConfig,           // some trust configuration
354
    EmptyKeyConfig.INSTANCE, // no client key material
355
    SslVerificationMode.FULL,
356
    SslClientAuthenticationMode.NONE,
357
    List.of(),
358
    List.of("TLSv1.3")
359
);
360
```
361

362
## Key Configuration Patterns
363

364
### Certificate Chain Handling
365

366
When working with certificate chains, the library automatically handles intermediate certificates:
367

368
```java
369
// PEM files can contain certificate chains
370
// cert.pem:
371
// -----BEGIN CERTIFICATE-----
372
// (end entity certificate)
373
// -----END CERTIFICATE-----
374
// -----BEGIN CERTIFICATE-----  
375
// (intermediate CA certificate)
376
// -----END CERTIFICATE-----
377

378
PemKeyConfig keyConfig = new PemKeyConfig("cert.pem", "key.pem", null, basePath);
379
List<Tuple<PrivateKey, X509Certificate>> keys = keyConfig.getKeys();
380
// Only returns the end entity certificate, but chain is preserved in key manager
381
```
382

383
### Keystore Type Detection
384

385
The library can automatically detect keystore types based on file extensions:
386

387
```java
388
// These will automatically detect the correct keystore type:
389
new StoreKeyConfig("keystore.jks", password, null, null, keyPassword, algorithm, basePath);    // JKS
390
new StoreKeyConfig("keystore.p12", password, null, null, keyPassword, algorithm, basePath);    // PKCS12
391
new StoreKeyConfig("keystore.pfx", password, null, null, keyPassword, algorithm, basePath);    // PKCS12
392

393
// Or explicitly specify the type:
394
new StoreKeyConfig("keystore.store", password, "JKS", null, keyPassword, algorithm, basePath);
395
```
396

397
### Key Password Handling
398

399
Different scenarios for key password management:
400

401
```java
402
// Same password for keystore and private keys
403
char[] password = "secret".toCharArray();
404
new StoreKeyConfig(path, password, type, null, password, algorithm, basePath);
405

406
// Different passwords
407
char[] storePassword = "storepass".toCharArray();
408
char[] keyPassword = "keypass".toCharArray();
409
new StoreKeyConfig(path, storePassword, type, null, keyPassword, algorithm, basePath);
410

411
// Encrypted PEM key
412
char[] pemKeyPassword = "pempass".toCharArray();
413
new PemKeyConfig(certPath, keyPath, pemKeyPassword, basePath);
414

415
// Unencrypted PEM key
416
new PemKeyConfig(certPath, keyPath, null, basePath);
417
```