0
# Configuration Types and Enums
1

2
Strongly-typed enums and data classes for SSL configuration options, verification modes, certificate handling, and authentication settings with parsing and validation capabilities.
3

4
## Capabilities
5

6
### SSL Verification Mode Enum
7

8
Enumeration defining SSL connection verification modes for certificate and hostname validation.
9

10
```java { .api }
11
/**
12
 * SSL connection verification modes
13
 */
14
public enum SslVerificationMode {
15
    /**
16
     * No verification - accept any certificate and hostname (INSECURE)
17
     */
18
    NONE,
19
    
20
    /**
21
     * Certificate verification only - validate certificate chain but not hostname
22
     */
23
    CERTIFICATE,
24
    
25
    /**
26
     * Full verification - validate both certificate chain and hostname
27
     */
28
    FULL;
29
    
30
    /**
31
     * Checks if hostname verification is enabled for this mode
32
     * @return true if hostname verification should be performed
33
     */
34
    public boolean isHostnameVerificationEnabled();
35
    
36
    /**
37
     * Checks if certificate verification is enabled for this mode
38
     * @return true if certificate chain verification should be performed
39
     */
40
    public boolean isCertificateVerificationEnabled();
41
    
42
    /**
43
     * Parses verification mode from string value
44
     * @param value string representation (case-insensitive)
45
     * @return corresponding SslVerificationMode
46
     * @throws IllegalArgumentException if value is not recognized
47
     */
48
    public static SslVerificationMode parse(String value);
49
}
50
```
51

52
**Usage Examples:**
53

54
```java
55
import org.elasticsearch.common.ssl.SslVerificationMode;
56

57
// Parse from string configuration
58
SslVerificationMode mode1 = SslVerificationMode.parse("full");        // FULL
59
SslVerificationMode mode2 = SslVerificationMode.parse("certificate"); // CERTIFICATE  
60
SslVerificationMode mode3 = SslVerificationMode.parse("none");        // NONE
61

62
// Check verification capabilities
63
if (mode1.isHostnameVerificationEnabled()) {
64
    System.out.println("Hostname verification is enabled");
65
}
66

67
if (mode1.isCertificateVerificationEnabled()) {
68
    System.out.println("Certificate verification is enabled");
69
}
70

71
// Use in SSL configuration
72
SslConfiguration config = new SslConfiguration(
73
    "https",
74
    true,
75
    trustConfig,
76
    keyConfig,
77
    SslVerificationMode.FULL,  // full verification
78
    clientAuth,
79
    ciphers,
80
    protocols
81
);
82

83
// Configure SSL parameters based on verification mode
84
SSLParameters sslParams = new SSLParameters();
85
if (!mode1.isHostnameVerificationEnabled()) {
86
    sslParams.setEndpointIdentificationAlgorithm(null); // disable hostname verification
87
}
88
```
89

90
### SSL Client Authentication Mode Enum
91

92
Enumeration defining client authentication modes for SSL servers.
93

94
```java { .api }
95
/**
96
 * Client authentication modes for SSL servers
97
 */
98
public enum SslClientAuthenticationMode {
99
    /**
100
     * No client authentication - never request client certificates
101
     */
102
    NONE,
103
    
104
    /**
105
     * Optional client authentication - request but don't require client certificates
106
     */
107
    OPTIONAL,
108
    
109
    /**
110
     * Required client authentication - request and require client certificates
111
     */
112
    REQUIRED;
113
    
114
    /**
115
     * Checks if client authentication is enabled for this mode
116
     * @return true if client authentication is requested
117
     */
118
    public boolean enabled();
119
    
120
    /**
121
     * Configures SSL parameters for this client authentication mode
122
     * @param sslParameters SSL parameters to configure
123
     */
124
    public void configure(SSLParameters sslParameters);
125
    
126
    /**
127
     * Parses client authentication mode from string value
128
     * @param value string representation (case-insensitive)
129
     * @return corresponding SslClientAuthenticationMode
130
     * @throws IllegalArgumentException if value is not recognized
131
     */
132
    public static SslClientAuthenticationMode parse(String value);
133
}
134
```
135

136
**Usage Examples:**
137

138
```java
139
import org.elasticsearch.common.ssl.SslClientAuthenticationMode;
140
import javax.net.ssl.SSLParameters;
141

142
// Parse from string configuration
143
SslClientAuthenticationMode auth1 = SslClientAuthenticationMode.parse("required");  // REQUIRED
144
SslClientAuthenticationMode auth2 = SslClientAuthenticationMode.parse("optional"); // OPTIONAL
145
SslClientAuthenticationMode auth3 = SslClientAuthenticationMode.parse("none");     // NONE
146

147
// Check if client authentication is enabled
148
if (auth1.enabled()) {
149
    System.out.println("Client authentication is enabled");
150
}
151

152
// Configure SSL parameters
153
SSLParameters sslParams = new SSLParameters();
154
auth1.configure(sslParams);  // sets client auth mode on SSL parameters
155

156
// Use in SSL configuration
157
SslConfiguration serverConfig = new SslConfiguration(
158
    "xpack.security.http.ssl",
159
    true,
160
    trustConfig,
161
    keyConfig,
162
    SslVerificationMode.FULL,
163
    SslClientAuthenticationMode.OPTIONAL,  // request but don't require client certs
164
    ciphers,
165
    protocols
166
);
167

168
// Example server-side usage
169
SSLContext sslContext = serverConfig.createSslContext();
170
SSLServerSocket serverSocket = (SSLServerSocket) sslContext.getServerSocketFactory().createServerSocket(8443);
171

172
// Client auth mode is automatically applied through SSL configuration
173
```
174

175
### X509 Field Enum
176

177
Enumeration for referencing specific parts of X509 certificates by canonical string values, used for trust restriction.
178

179
```java { .api }
180
/**
181
 * X509 certificate field references for trust restrictions
182
 */
183
public enum X509Field {
184
    /**
185
     * Subject Alternative Name - Other Name with Common Name component
186
     */
187
    SAN_OTHERNAME_COMMONNAME,
188
    
189
    /**
190
     * Subject Alternative Name - DNS Name
191
     */
192
    SAN_DNS;
193
    
194
    /**
195
     * Gets string representation of this field
196
     * @return canonical string representation
197
     */
198
    @Override
199
    public String toString();
200
    
201
    /**
202
     * Parses X509 field from string for restricted trust configuration
203
     * @param s string representation of the field
204
     * @return corresponding X509Field
205
     * @throws IllegalArgumentException if field is not recognized
206
     */
207
    public static X509Field parseForRestrictedTrust(String s);
208
}
209
```
210

211
**Usage Examples:**
212

213
```java
214
import org.elasticsearch.common.ssl.X509Field;
215
import java.util.List;
216

217
// Parse X509 field references
218
X509Field dnsField = X509Field.parseForRestrictedTrust("san_dns");
219
X509Field cnField = X509Field.parseForRestrictedTrust("san_othername_commonname");
220

221
// Use in restricted trust configuration
222
List<X509Field> restrictedFields = List.of(
223
    X509Field.SAN_DNS,                    // only trust DNS names in SAN
224
    X509Field.SAN_OTHERNAME_COMMONNAME    // and common names in SAN other names
225
);
226

227
// Configure with SslConfigurationLoader
228
SslConfigurationLoader loader = new MyConfigurationLoader("https");
229
loader.setDefaultRestrictedTrustFields(restrictedFields);
230

231
// The trust manager will only validate certificates against the specified fields
232
```
233

234
### Stored Certificate Record
235

236
Record class containing information about a locally stored certificate including metadata.
237

238
```java { .api }
239
/**
240
 * Information about a locally stored certificate with metadata
241
 */
242
public record StoredCertificate(
243
    /**
244
     * The X509 certificate
245
     */
246
    X509Certificate certificate,
247
    
248
    /**
249
     * Path to the certificate file (null if not from file)
250
     */
251
    @Nullable String path,
252
    
253
    /**
254
     * Format of the certificate storage (PEM, JKS, PKCS12, etc.)
255
     */
256
    String format,
257
    
258
    /**
259
     * Alias within keystore (null if not from keystore)
260
     */
261
    @Nullable String alias,
262
    
263
    /**
264
     * Whether this certificate has an associated private key
265
     */
266
    boolean hasPrivateKey
267
) {}
268
```
269

270
**Usage Examples:**
271

272
```java
273
import org.elasticsearch.common.ssl.StoredCertificate;
274
import java.security.cert.X509Certificate;
275

276
// Create stored certificate metadata
277
StoredCertificate pemCert = new StoredCertificate(
278
    certificate,           // X509Certificate instance
279
    "/etc/ssl/server.pem", // file path
280
    "PEM",                // format
281
    null,                 // no alias (PEM files don't have aliases)
282
    true                  // has associated private key
283
);
284

285
StoredCertificate keystoreCert = new StoredCertificate(
286
    certificate,              // X509Certificate instance
287
    "/etc/ssl/keystore.p12", // keystore file path
288
    "PKCS12",                // keystore format
289
    "server-cert",           // alias within keystore
290
    true                     // has associated private key
291
);
292

293
StoredCertificate caCert = new StoredCertificate(
294
    caCertificate,           // CA certificate
295
    "/etc/ssl/ca.pem",      // CA file path
296
    "PEM",                  // format
297
    null,                   // no alias
298
    false                   // no private key (CA cert only)
299
);
300

301
// Use stored certificate information
302
System.out.println("Certificate from: " + pemCert.path());
303
System.out.println("Format: " + pemCert.format());
304
System.out.println("Has private key: " + pemCert.hasPrivateKey());
305

306
if (keystoreCert.alias() != null) {
307
    System.out.println("Keystore alias: " + keystoreCert.alias());
308
}
309

310
// Get certificate details
311
X509Certificate cert = pemCert.certificate();
312
System.out.println("Subject: " + cert.getSubjectX500Principal().getName());
313
System.out.println("Issuer: " + cert.getIssuerX500Principal().getName());
314
```
315

316
### SSL Configuration Exception
317

318
Base exception class for SSL configuration problems with comprehensive error information.
319

320
```java { .api }
321
/**
322
 * Base exception for SSL configuration problems
323
 */
324
public class SslConfigException extends Exception {
325
    /**
326
     * Creates SSL configuration exception with message and cause
327
     * @param message descriptive error message
328
     * @param cause underlying exception that caused this error
329
     */
330
    public SslConfigException(String message, Exception cause);
331
    
332
    /**
333
     * Creates SSL configuration exception with message only
334
     * @param message descriptive error message
335
     */
336
    public SslConfigException(String message);
337
}
338
```
339

340
**Usage Examples:**
341

342
```java
343
import org.elasticsearch.common.ssl.SslConfigException;
344
import java.io.IOException;
345
import java.security.GeneralSecurityException;
346

347
// Catch and handle SSL configuration exceptions
348
try {
349
    SslConfiguration config = loader.load(basePath);
350
    SSLContext sslContext = config.createSslContext();
351
} catch (SslConfigException e) {
352
    System.err.println("SSL configuration failed: " + e.getMessage());
353
    if (e.getCause() != null) {
354
        System.err.println("Caused by: " + e.getCause().getMessage());
355
    }
356
    
357
    // Handle specific causes
358
    if (e.getCause() instanceof IOException) {
359
        System.err.println("File access problem - check certificate/key file paths and permissions");
360
    } else if (e.getCause() instanceof GeneralSecurityException) {
361
        System.err.println("Security/cryptography problem - check certificate validity and formats");
362
    }
363
}
364

365
// Throw SSL configuration exceptions
366
public SslKeyConfig loadKeyConfig(String path) throws SslConfigException {
367
    try {
368
        return new PemKeyConfig(certPath, keyPath, password, basePath);
369
    } catch (IOException e) {
370
        throw new SslConfigException("Failed to read key configuration from " + path, e);
371
    } catch (GeneralSecurityException e) {
372
        throw new SslConfigException("Invalid key material at " + path, e);
373
    }
374
}
375
```
376

377
## Type Usage Patterns
378

379
### Configuration Validation
380

381
Use enums for robust configuration validation:
382

383
```java
384
// Validate and parse configuration strings
385
public SslConfiguration parseConfiguration(Map<String, String> settings) {
386
    // Parse with validation
387
    SslVerificationMode verificationMode;
388
    try {
389
        verificationMode = SslVerificationMode.parse(
390
            settings.getOrDefault("verification_mode", "full")
391
        );
392
    } catch (IllegalArgumentException e) {
393
        throw new SslConfigException("Invalid verification mode: " + settings.get("verification_mode"));
394
    }
395
    
396
    SslClientAuthenticationMode clientAuth;
397
    try {
398
        clientAuth = SslClientAuthenticationMode.parse(
399
            settings.getOrDefault("client_authentication", "none")
400
        );
401
    } catch (IllegalArgumentException e) {
402
        throw new SslConfigException("Invalid client authentication mode: " + settings.get("client_authentication"));
403
    }
404
    
405
    return new SslConfiguration(prefix, true, trustConfig, keyConfig, verificationMode, clientAuth, ciphers, protocols);
406
}
407
```
408

409
### Certificate Metadata Collection
410

411
Use StoredCertificate for comprehensive certificate tracking:
412

413
```java
414
// Collect certificate metadata from various sources
415
public List<StoredCertificate> collectCertificateMetadata(SslConfiguration config) {
416
    List<StoredCertificate> allCerts = new ArrayList<>();
417
    
418
    // Add certificates from key configuration
419
    allCerts.addAll(config.keyConfig().getConfiguredCertificates());
420
    
421
    // Add certificates from trust configuration
422
    allCerts.addAll(config.trustConfig().getConfiguredCertificates());
423
    
424
    // Analyze certificate sources
425
    Map<String, List<StoredCertificate>> byFormat = allCerts.stream()
426
        .collect(Collectors.groupingBy(StoredCertificate::format));
427
    
428
    System.out.println("Certificate sources:");
429
    byFormat.forEach((format, certs) -> {
430
        System.out.println("  " + format + ": " + certs.size() + " certificates");
431
    });
432
    
433
    // Find certificates with private keys
434
    List<StoredCertificate> withPrivateKeys = allCerts.stream()
435
        .filter(StoredCertificate::hasPrivateKey)
436
        .toList();
437
    
438
    System.out.println("Certificates with private keys: " + withPrivateKeys.size());
439
    
440
    return allCerts;
441
}
442
```
443

444
### Enum-Based Configuration Defaults
445

446
Use enums to provide sensible defaults:
447

448
```java
449
public class SslDefaults {
450
    public static final SslVerificationMode DEFAULT_VERIFICATION_MODE = SslVerificationMode.FULL;
451
    public static final SslClientAuthenticationMode DEFAULT_CLIENT_AUTH = SslClientAuthenticationMode.NONE;
452
    public static final List<String> DEFAULT_PROTOCOLS = List.of("TLSv1.3", "TLSv1.2");
453
    
454
    public static SslConfiguration createDefaultConfiguration(SslTrustConfig trustConfig, SslKeyConfig keyConfig) {
455
        return new SslConfiguration(
456
            "ssl",
457
            false,  // using defaults
458
            trustConfig,
459
            keyConfig,
460
            DEFAULT_VERIFICATION_MODE,
461
            DEFAULT_CLIENT_AUTH,
462
            List.of(),  // use JVM cipher defaults
463
            DEFAULT_PROTOCOLS
464
        );
465
    }
466
}
467
```
468

469
### X509 Field Validation
470

471
Use X509Field enum for certificate field validation:
472

473
```java
474
// Configure trust field restrictions
475
public void configureRestrictedTrust(SslConfigurationLoader loader, List<String> fieldNames) {
476
    List<X509Field> fields = fieldNames.stream()
477
        .map(name -> {
478
            try {
479
                return X509Field.parseForRestrictedTrust(name);
480
            } catch (IllegalArgumentException e) {
481
                throw new SslConfigException("Invalid X509 field for trust restriction: " + name, e);
482
            }
483
        })
484
        .toList();
485
    
486
    loader.setDefaultRestrictedTrustFields(fields);
487
}
488
```