0
# Trust Management
1

2
SSL trust configuration with support for various trust models including PEM CA files, trust stores, system defaults, composite configurations, and trust-everything modes with certificate validation and restriction capabilities.
3

4
## Capabilities
5

6
### SSL Trust Configuration Interface
7

8
Core interface for SSL trust configuration providing trust managers and certificate access.
9

10
```java { .api }
11
/**
12
 * Interface for SSL trust configuration
13
 */
14
public interface SslTrustConfig {
15
    /**
16
     * Gets all certificate files this trust configuration depends on
17
     * @return collection of file paths for monitoring changes
18
     */
19
    Collection<Path> getDependentFiles();
20
    
21
    /**
22
     * Creates a trust manager from this trust configuration
23
     * @return configured X509ExtendedTrustManager for SSL contexts
24
     * @throws SslConfigException if trust manager creation fails
25
     */
26
    X509ExtendedTrustManager createTrustManager();
27
    
28
    /**
29
     * Gets all configured certificates with metadata
30
     * @return collection of trusted certificates
31
     */
32
    Collection<? extends StoredCertificate> getConfiguredCertificates();
33
    
34
    /**
35
     * Checks if this configuration uses the system default trust
36
     * @return true if using JDK default trusted CAs
37
     */
38
    default boolean isSystemDefault();
39
}
40
```
41

42
### PEM Trust Configuration
43

44
Trust configuration that reads PEM encoded trusted certificates (CAs) from files.
45

46
```java { .api }
47
/**
48
 * SSL trust configuration using PEM encoded certificate authority files
49
 */
50
public final class PemTrustConfig implements SslTrustConfig {
51
    /**
52
     * Creates a PEM-based trust configuration
53
     * @param certificateAuthorities list of CA certificate file paths (relative to basePath)
54
     * @param basePath base path for resolving relative paths
55
     */
56
    public PemTrustConfig(List<String> certificateAuthorities, Path basePath);
57
    
58
    /**
59
     * Gets dependent CA certificate file paths
60
     * @return collection of CA certificate file paths
61
     */
62
    public Collection<Path> getDependentFiles();
63
    
64
    /**
65
     * Gets configured CA certificates with metadata
66
     * @return collection of CA certificates from PEM files
67
     */
68
    public Collection<? extends StoredCertificate> getConfiguredCertificates();
69
    
70
    /**
71
     * Creates X509ExtendedTrustManager from PEM CA files
72
     * @return configured trust manager with CA certificates
73
     * @throws GeneralSecurityException if PEM parsing or trust manager creation fails
74
     */
75
    public X509ExtendedTrustManager createTrustManager() throws GeneralSecurityException;
76
    
77
    @Override
78
    public String toString();
79
    
80
    @Override
81
    public boolean equals(Object o);
82
    
83
    @Override
84
    public int hashCode();
85
}
86
```
87

88
**Usage Examples:**
89

90
```java
91
import org.elasticsearch.common.ssl.PemTrustConfig;
92
import javax.net.ssl.X509ExtendedTrustManager;
93
import java.nio.file.Paths;
94
import java.util.List;
95

96
// Single CA certificate
97
PemTrustConfig singleCA = new PemTrustConfig(
98
    List.of("ca.pem"),        // single CA file
99
    Paths.get("/etc/ssl/certs") // base path
100
);
101

102
// Multiple CA certificates
103
PemTrustConfig multipleCA = new PemTrustConfig(
104
    List.of(
105
        "root-ca.pem",        // root CA
106
        "intermediate-ca.pem", // intermediate CA
107
        "additional-ca.pem"   // additional trusted CA
108
    ),
109
    Paths.get("/config/ssl")  // base path
110
);
111

112
// Create trust manager
113
X509ExtendedTrustManager trustManager = singleCA.createTrustManager();
114

115
// Get dependent files for monitoring
116
Collection<Path> caFiles = singleCA.getDependentFiles();
117

118
// Get configured certificates
119
Collection<? extends StoredCertificate> caCerts = singleCA.getConfiguredCertificates();
120
```
121

122
### Store Trust Configuration
123

124
Trust configuration that builds trust managers from truststore files (JKS, PKCS12, etc.).
125

126
```java { .api }
127
/**
128
 * SSL trust configuration using truststore files
129
 */
130
public final class StoreTrustConfig implements SslTrustConfig {
131
    /**
132
     * Creates a truststore-based trust configuration
133
     * @param path path to truststore file (relative to configBasePath)
134
     * @param password password for truststore access
135
     * @param type truststore type (JKS, PKCS12, etc.) or null to infer from extension
136
     * @param algorithm trust manager algorithm (e.g., "PKIX", "SunX509")
137
     * @param requireTrustAnchors whether to require at least one trust anchor
138
     * @param configBasePath base path for resolving relative paths
139
     */
140
    public StoreTrustConfig(String path, char[] password, String type, String algorithm, 
141
                           boolean requireTrustAnchors, Path configBasePath);
142
    
143
    /**
144
     * Gets dependent truststore file paths
145
     * @return collection containing truststore file path
146
     */
147
    public Collection<Path> getDependentFiles();
148
    
149
    /**
150
     * Gets configured certificates with metadata
151
     * @return collection of certificates from truststore
152
     */
153
    public Collection<? extends StoredCertificate> getConfiguredCertificates();
154
    
155
    /**
156
     * Creates X509ExtendedTrustManager from truststore
157
     * @return configured trust manager
158
     * @throws GeneralSecurityException if trust manager creation fails
159
     */
160
    public X509ExtendedTrustManager createTrustManager() throws GeneralSecurityException;
161
    
162
    @Override
163
    public boolean equals(Object o);
164
    
165
    @Override
166
    public int hashCode();
167
    
168
    @Override
169
    public String toString();
170
}
171
```
172

173
**Usage Examples:**
174

175
```java
176
import org.elasticsearch.common.ssl.StoreTrustConfig;
177
import java.nio.file.Paths;
178

179
// PKCS12 truststore
180
StoreTrustConfig p12Trust = new StoreTrustConfig(
181
    "truststore.p12",         // truststore file
182
    "trustpass".toCharArray(), // truststore password
183
    "PKCS12",                 // truststore type
184
    "PKIX",                   // trust manager algorithm
185
    true,                     // require trust anchors
186
    Paths.get("/etc/ssl")     // base path
187
);
188

189
// JKS truststore with auto-detection
190
StoreTrustConfig jkssTrust = new StoreTrustConfig(
191
    "cacerts.jks",            // truststore file
192
    "changeit".toCharArray(), // truststore password
193
    null,                     // auto-detect type from extension
194
    "SunX509",               // trust manager algorithm
195
    false,                    // don't require trust anchors
196
    Paths.get("/config")      // base path
197
);
198

199
// Create trust manager
200
X509ExtendedTrustManager trustManager = p12Trust.createTrustManager();
201

202
// Get certificates
203
Collection<? extends StoredCertificate> certificates = p12Trust.getConfiguredCertificates();
204
```
205

206
### Default JDK Trust Configuration
207

208
Trust configuration that uses the JDK's default trusted certificate authorities.
209

210
```java { .api }
211
/**
212
 * SSL trust configuration using JDK default trusted CAs
213
 */
214
public final class DefaultJdkTrustConfig implements SslTrustConfig {
215
    /**
216
     * Singleton instance for default JDK trust
217
     */
218
    public static final DefaultJdkTrustConfig DEFAULT_INSTANCE;
219
    
220
    /**
221
     * Always returns true (uses system default trust)
222
     * @return true
223
     */
224
    public boolean isSystemDefault();
225
    
226
    /**
227
     * Creates trust manager using JDK default truststore
228
     * @return trust manager with JDK default CAs
229
     * @throws GeneralSecurityException if trust manager creation fails
230
     */
231
    public X509ExtendedTrustManager createTrustManager() throws GeneralSecurityException;
232
    
233
    /**
234
     * Gets empty collection (no specific dependent files)
235
     * @return empty collection
236
     */
237
    public Collection<Path> getDependentFiles();
238
    
239
    /**
240
     * Gets configured certificates from JDK default truststore
241
     * @return collection of JDK default CA certificates
242
     */
243
    public Collection<? extends StoredCertificate> getConfiguredCertificates();
244
    
245
    @Override
246
    public String toString();
247
    
248
    @Override
249
    public boolean equals(Object o);
250
    
251
    @Override
252
    public int hashCode();
253
}
254
```
255

256
**Usage Examples:**
257

258
```java
259
import org.elasticsearch.common.ssl.DefaultJdkTrustConfig;
260

261
// Use JDK default trust configuration
262
SslTrustConfig defaultTrust = DefaultJdkTrustConfig.DEFAULT_INSTANCE;
263

264
// Check if system default
265
boolean isDefault = defaultTrust.isSystemDefault(); // true
266

267
// Create trust manager with JDK defaults
268
X509ExtendedTrustManager trustManager = defaultTrust.createTrustManager();
269

270
// Get JDK default CA certificates
271
Collection<? extends StoredCertificate> jdkCAs = defaultTrust.getConfiguredCertificates();
272

273
// Use in SSL configuration
274
SslConfiguration config = new SslConfiguration(
275
    "https",
276
    false,                        // not explicitly configured (using defaults)
277
    DefaultJdkTrustConfig.DEFAULT_INSTANCE, // JDK default trust
278
    keyConfig,
279
    SslVerificationMode.FULL,
280
    SslClientAuthenticationMode.NONE,
281
    List.of(),
282
    List.of("TLSv1.3", "TLSv1.2")
283
);
284
```
285

286
### Composite Trust Configuration
287

288
Trust configuration that combines multiple trust configurations into a single trust manager.
289

290
```java { .api }
291
/**
292
 * SSL trust configuration that merges multiple trust configs
293
 */
294
public class CompositeTrustConfig implements SslTrustConfig {
295
    /**
296
     * Gets dependent files from all composite trust configurations
297
     * @return collection of all dependent file paths
298
     */
299
    public Collection<Path> getDependentFiles();
300
    
301
    /**
302
     * Always returns false (not system default since it's composite)
303
     * @return false
304
     */
305
    public boolean isSystemDefault();
306
    
307
    /**
308
     * Creates composite trust manager that trusts certificates from any constituent config
309
     * @return trust manager that combines all trust configurations
310
     * @throws GeneralSecurityException if trust manager creation fails
311
     */
312
    public X509ExtendedTrustManager createTrustManager() throws GeneralSecurityException;
313
    
314
    /**
315
     * Gets certificates from all constituent trust configurations
316
     * @return collection of all certificates from composite configs
317
     */
318
    public Collection<? extends StoredCertificate> getConfiguredCertificates();
319
    
320
    @Override
321
    public boolean equals(Object o);
322
    
323
    @Override
324
    public int hashCode();
325
    
326
    @Override
327
    public String toString();
328
}
329
```
330

331
**Usage Examples:**
332

333
```java
334
// Composite trust configuration is typically created internally by the configuration loader
335
// when combining multiple trust sources, but can be used directly:
336

337
// Example: Combine JDK defaults with custom CA
338
SslTrustConfig composite = new CompositeTrustConfig(
339
    List.of(
340
        DefaultJdkTrustConfig.DEFAULT_INSTANCE,
341
        new PemTrustConfig(List.of("custom-ca.pem"), basePath)
342
    )
343
);
344

345
// The resulting trust manager will trust both JDK default CAs and the custom CA
346
X509ExtendedTrustManager trustManager = composite.createTrustManager();
347
```
348

349
### Trust Everything Configuration
350

351
Trust configuration that accepts all certificates (insecure - for testing only).
352

353
```java { .api }
354
/**
355
 * SSL trust configuration that trusts all certificates (INSECURE)
356
 */
357
public final class TrustEverythingConfig implements SslTrustConfig {
358
    /**
359
     * Singleton instance for trust-everything configuration
360
     */
361
    public static final TrustEverythingConfig TRUST_EVERYTHING;
362
    
363
    /**
364
     * Gets empty collection (no dependent files)
365
     * @return empty collection
366
     */
367
    public Collection<Path> getDependentFiles();
368
    
369
    /**
370
     * Gets empty collection (no specific certificates)
371
     * @return empty collection
372
     */
373
    public Collection<? extends StoredCertificate> getConfiguredCertificates();
374
    
375
    /**
376
     * Creates trust manager that accepts all certificates (INSECURE)
377
     * @return trust manager that accepts any certificate
378
     */
379
    public X509ExtendedTrustManager createTrustManager();
380
    
381
    @Override
382
    public String toString();
383
}
384
```
385

386
**Usage Examples:**
387

388
```java
389
import org.elasticsearch.common.ssl.TrustEverythingConfig;
390

391
// WARNING: Only for testing/development - never use in production
392
SslTrustConfig insecureTrust = TrustEverythingConfig.TRUST_EVERYTHING;
393

394
// Use with verification disabled
395
SslConfiguration testConfig = new SslConfiguration(
396
    "test",
397
    true,
398
    TrustEverythingConfig.TRUST_EVERYTHING, // trust everything (insecure)
399
    keyConfig,
400
    SslVerificationMode.NONE,               // no verification
401
    SslClientAuthenticationMode.NONE,
402
    List.of(),
403
    List.of("TLSv1.3")
404
);
405

406
// Create SSL context (will accept any certificate)
407
SSLContext sslContext = testConfig.createSslContext();
408
```
409

410
## Trust Configuration Patterns
411

412
### Certificate Authority Chain Handling
413

414
When working with CA certificate chains, include the full chain:
415

416
```java
417
// CA chain in PEM file:
418
// -----BEGIN CERTIFICATE-----
419
// (root CA certificate)
420
// -----END CERTIFICATE-----
421
// -----BEGIN CERTIFICATE-----
422
// (intermediate CA certificate)
423
// -----END CERTIFICATE-----
424

425
PemTrustConfig caChain = new PemTrustConfig(
426
    List.of("ca-chain.pem"),  // file with full CA chain
427
    basePath
428
);
429
```
430

431
### Mixed Trust Sources
432

433
Combine different trust sources for flexibility:
434

435
```java
436
// Configuration loader can automatically create composite trust:
437
// - JDK defaults + custom CAs
438
// - Multiple truststore files
439
// - PEM files + keystores
440

441
// This is typically handled by SslConfigurationLoader internally
442
```
443

444
### Trust Store vs Certificate Files
445

446
Choose the appropriate trust configuration based on your certificate format:
447

448
```java
449
// Use PemTrustConfig for:
450
// - Individual PEM certificate files
451
// - Certificate bundles in PEM format
452
// - When you need to easily inspect/modify CA certificates
453

454
// Use StoreTrustConfig for:
455
// - Existing Java truststore files (JKS, PKCS12)
456
// - Integration with Java keystore tooling
457
// - When you need password-protected truststore access
458

459
// Use DefaultJdkTrustConfig for:
460
// - Standard web PKI trust (browser-like behavior)
461
// - When you want to trust well-known CAs
462
// - Default behavior for most applications
463
```
464

465
### Trust Validation Restrictions
466

467
The library supports restricting trust validation to specific certificate fields:
468

469
```java
470
// This is typically configured through SslConfigurationLoader
471
// with restricted trust fields for additional security
472
List<X509Field> restrictedFields = List.of(
473
    X509Field.SAN_DNS,                    // restrict to DNS names in SAN
474
    X509Field.SAN_OTHERNAME_COMMONNAME    // restrict to common names
475
);
476

477
// Applied during trust manager creation for additional validation
478
```