0
# SSL Configuration Management
1

2
Core SSL configuration functionality providing immutable configuration objects, configuration loading from various sources, and SSL context creation with comprehensive validation.
3

4
## Capabilities
5

6
### SSL Configuration Record
7

8
Immutable configuration object that encapsulates all SSL context settings and provides SSL context creation.
9

10
```java { .api }
11
/**
12
 * Immutable SSL configuration record containing all SSL context settings
13
 */
14
public record SslConfiguration(
15
    String settingPrefix,
16
    boolean explicitlyConfigured,
17
    SslTrustConfig trustConfig,
18
    SslKeyConfig keyConfig,
19
    SslVerificationMode verificationMode,
20
    SslClientAuthenticationMode clientAuth,
21
    List<String> ciphers,
22
    List<String> supportedProtocols
23
) {
24
    /**
25
     * Creates an SSL context from this configuration
26
     * @return configured SSLContext ready for use
27
     * @throws SslConfigException if SSL context creation fails
28
     */
29
    public SSLContext createSslContext() throws SslConfigException;
30
    
31
    /**
32
     * Gets the effective cipher suites for this configuration
33
     * @return list of cipher suite names
34
     */
35
    public List<String> getCipherSuites();
36
    
37
    /**
38
     * Gets all certificate and key files this configuration depends on
39
     * @return collection of file paths
40
     */
41
    public Collection<Path> getDependentFiles();
42
    
43
    /**
44
     * Gets all configured certificates from key and trust configurations
45
     * @return collection of stored certificates with metadata
46
     */
47
    public Collection<? extends StoredCertificate> getConfiguredCertificates();
48
}
49
```
50

51
**Usage Examples:**
52

53
```java
54
import org.elasticsearch.common.ssl.*;
55
import javax.net.ssl.SSLContext;
56
import java.util.List;
57

58
// Create a complete SSL configuration
59
SslConfiguration config = new SslConfiguration(
60
    "xpack.security.http.ssl",          // setting prefix for logging/errors
61
    true,                               // explicitly configured (not defaults)
62
    new PemTrustConfig(                 // trust configuration
63
        List.of("/path/to/ca.pem"), 
64
        Paths.get("/config")
65
    ),
66
    new PemKeyConfig(                   // key configuration
67
        "/path/to/cert.pem", 
68
        "/path/to/key.pem", 
69
        "keypass".toCharArray(), 
70
        Paths.get("/config")
71
    ),
72
    SslVerificationMode.FULL,           // full certificate and hostname verification
73
    SslClientAuthenticationMode.OPTIONAL, // request but don't require client cert
74
    List.of("TLS_AES_256_GCM_SHA384"),  // specific cipher suites
75
    List.of("TLSv1.3", "TLSv1.2")      // supported TLS versions
76
);
77

78
// Create SSL context from configuration
79
SSLContext sslContext = config.createSslContext();
80

81
// Get effective cipher suites (includes defaults if none specified)
82
List<String> ciphers = config.getCipherSuites();
83

84
// Get all dependent files for monitoring changes
85
Collection<Path> files = config.getDependentFiles();
86
```
87

88
### SSL Configuration Loader
89

90
Abstract base class for loading SSL configurations from various settings sources with configurable defaults.
91

92
```java { .api }
93
/**
94
 * Abstract factory for loading SSL configurations from settings
95
 */
96
public abstract class SslConfigurationLoader {
97
    public static final List<String> DEFAULT_PROTOCOLS;
98
    public static final List<String> DEFAULT_CIPHERS;
99
    public static final List<X509Field> GLOBAL_DEFAULT_RESTRICTED_TRUST_FIELDS;
100
    
101
    /**
102
     * Creates a configuration loader for the specified setting prefix
103
     * @param settingPrefix the prefix for all SSL settings (e.g., "xpack.security.http.ssl")
104
     */
105
    public SslConfigurationLoader(String settingPrefix);
106
    
107
    /**
108
     * Sets the default trust configuration to use when none is explicitly configured
109
     * @param defaultTrustConfig the default trust configuration
110
     */
111
    public void setDefaultTrustConfig(SslTrustConfig defaultTrustConfig);
112
    
113
    /**
114
     * Sets the default key configuration to use when none is explicitly configured
115
     * @param defaultKeyConfig the default key configuration
116
     */
117
    public void setDefaultKeyConfig(SslKeyConfig defaultKeyConfig);
118
    
119
    /**
120
     * Sets the default SSL verification mode
121
     * @param defaultVerificationMode the default verification mode
122
     */
123
    public void setDefaultVerificationMode(SslVerificationMode defaultVerificationMode);
124
    
125
    /**
126
     * Sets the default client authentication mode
127
     * @param defaultClientAuth the default client authentication mode
128
     */
129
    public void setDefaultClientAuth(SslClientAuthenticationMode defaultClientAuth);
130
    
131
    /**
132
     * Sets the default cipher suites
133
     * @param defaultCiphers list of default cipher suite names
134
     */
135
    public void setDefaultCiphers(List<String> defaultCiphers);
136
    
137
    /**
138
     * Sets the default TLS protocols
139
     * @param defaultProtocols list of default protocol names
140
     */
141
    public void setDefaultProtocols(List<String> defaultProtocols);
142
    
143
    /**
144
     * Sets a filter function to apply to loaded keystores
145
     * @param keyStoreFilter function to filter keystore entries
146
     */
147
    public void setKeyStoreFilter(Function<KeyStore, KeyStore> keyStoreFilter);
148
    
149
    /**
150
     * Sets default fields to restrict trust validation to
151
     * @param x509Fields list of certificate fields for trust restriction
152
     */
153
    public void setDefaultRestrictedTrustFields(List<X509Field> x509Fields);
154
    
155
    /**
156
     * Loads a complete SSL configuration from settings
157
     * @param basePath base path for resolving relative file paths
158
     * @return fully configured SslConfiguration
159
     * @throws SslConfigException if configuration loading fails
160
     */
161
    public SslConfiguration load(Path basePath) throws SslConfigException;
162
    
163
    /**
164
     * Builds just the key configuration from settings
165
     * @param basePath base path for resolving relative file paths
166
     * @return configured SslKeyConfig
167
     * @throws SslConfigException if key configuration loading fails
168
     */
169
    public SslKeyConfig buildKeyConfig(Path basePath) throws SslConfigException;
170
    
171
    // Abstract methods that subclasses must implement to access settings
172
    protected abstract boolean hasSettings(String prefix) throws Exception;
173
    protected abstract String getSettingAsString(String key) throws Exception;
174
    protected abstract char[] getSecureSetting(String key) throws Exception;
175
    protected abstract List<String> getSettingAsList(String key) throws Exception;
176
    
177
    /**
178
     * Resolves a path setting relative to the base path
179
     * @param settingKey the setting key being resolved
180
     * @param basePath the base path for relative resolution
181
     * @return resolved absolute path
182
     */
183
    protected Path resolvePath(String settingKey, Path basePath);
184
}
185
```
186

187
**Usage Examples:**
188

189
```java
190
import org.elasticsearch.common.ssl.*;
191
import java.nio.file.Path;
192
import java.util.List;
193
import java.util.Map;
194

195
// Example implementation of SslConfigurationLoader
196
public class MapBasedSslLoader extends SslConfigurationLoader {
197
    private final Map<String, Object> settings;
198
    
199
    public MapBasedSslLoader(String prefix, Map<String, Object> settings) {
200
        super(prefix);
201
        this.settings = settings;
202
    }
203
    
204
    @Override
205
    protected boolean hasSettings(String prefix) {
206
        return settings.keySet().stream().anyMatch(key -> key.startsWith(prefix));
207
    }
208
    
209
    @Override
210
    protected String getSettingAsString(String key) {
211
        return (String) settings.get(key);
212
    }
213
    
214
    @Override
215
    protected char[] getSecureSetting(String key) {
216
        String value = (String) settings.get(key);
217
        return value != null ? value.toCharArray() : null;
218
    }
219
    
220
    @Override
221
    protected List<String> getSettingAsList(String key) {
222
        Object value = settings.get(key);
223
        if (value instanceof List) {
224
            return (List<String>) value;
225
        }
226
        return value != null ? List.of(value.toString()) : List.of();
227
    }
228
}
229

230
// Using the configuration loader
231
Map<String, Object> sslSettings = Map.of(
232
    "xpack.security.http.ssl.certificate", "/path/to/cert.pem",
233
    "xpack.security.http.ssl.key", "/path/to/key.pem",
234
    "xpack.security.http.ssl.certificate_authorities", List.of("/path/to/ca.pem"),
235
    "xpack.security.http.ssl.verification_mode", "full",
236
    "xpack.security.http.ssl.client_authentication", "optional"
237
);
238

239
MapBasedSslLoader loader = new MapBasedSslLoader("xpack.security.http.ssl", sslSettings);
240

241
// Set custom defaults
242
loader.setDefaultVerificationMode(SslVerificationMode.CERTIFICATE);
243
loader.setDefaultProtocols(List.of("TLSv1.3"));
244

245
// Load configuration
246
SslConfiguration config = loader.load(Paths.get("/config"));
247
```
248

249
### SSL Configuration Keys
250

251
Utility class providing standard SSL configuration setting keys and metadata about setting types.
252

253
```java { .api }
254
/**
255
 * Standard SSL configuration setting keys and utilities
256
 */
257
public class SslConfigurationKeys {
258
    // Core SSL settings
259
    public static final String PROTOCOLS = "supported_protocols";
260
    public static final String CIPHERS = "cipher_suites";
261
    public static final String VERIFICATION_MODE = "verification_mode";
262
    public static final String CLIENT_AUTH = "client_authentication";
263
    
264
    // Trust configuration settings
265
    public static final String CERTIFICATE_AUTHORITIES = "certificate_authorities";
266
    public static final String TRUSTSTORE_PATH = "truststore.path";
267
    public static final String TRUSTSTORE_SECURE_PASSWORD = "truststore.secure_password";
268
    public static final String TRUSTSTORE_PASSWORD = "truststore.password";
269
    public static final String TRUSTSTORE_TYPE = "truststore.type";
270
    public static final String TRUSTSTORE_ALGORITHM = "truststore.algorithm";
271
    
272
    // Key configuration settings  
273
    public static final String CERTIFICATE = "certificate";
274
    public static final String KEY = "key";
275
    public static final String KEY_SECURE_PASSPHRASE = "secure_key_passphrase";
276
    public static final String KEY_PASSPHRASE = "key_passphrase";
277
    public static final String KEYSTORE_PATH = "keystore.path";
278
    public static final String KEYSTORE_SECURE_PASSWORD = "keystore.secure_password";
279
    public static final String KEYSTORE_PASSWORD = "keystore.password";
280
    public static final String KEYSTORE_TYPE = "keystore.type";
281
    public static final String KEYSTORE_KEY_PASSWORD = "keystore.key_password";
282
    public static final String KEYSTORE_SECURE_KEY_PASSWORD = "keystore.secure_key_password";
283
    public static final String KEYSTORE_ALGORITHM = "keystore.algorithm";
284
    
285
    /**
286
     * Gets all setting keys that expect string values
287
     * @return list of string setting keys
288
     */
289
    public static List<String> getStringKeys();
290
    
291
    /**
292
     * Gets all setting keys that expect list values
293
     * @return list of list setting keys
294
     */
295
    public static List<String> getListKeys();
296
    
297
    /**
298
     * Gets all setting keys that expect secure string values (passwords, etc.)
299
     * @return list of secure string setting keys
300
     */
301
    public static List<String> getSecureStringKeys();
302
    
303
    /**
304
     * Checks if a setting key is deprecated
305
     * @param key the setting key to check
306
     * @return true if the key is deprecated
307
     */
308
    public static boolean isDeprecated(String key);
309
}
310
```
311

312
**Usage Examples:**
313

314
```java
315
import org.elasticsearch.common.ssl.SslConfigurationKeys;
316
import java.util.List;
317

318
// Check setting types
319
List<String> stringKeys = SslConfigurationKeys.getStringKeys();
320
List<String> listKeys = SslConfigurationKeys.getListKeys();
321
List<String> secureKeys = SslConfigurationKeys.getSecureStringKeys();
322

323
// Build setting key for a specific prefix
324
String certSetting = "xpack.security.http.ssl." + SslConfigurationKeys.CERTIFICATE;
325
String keystoreSetting = "xpack.security.http.ssl." + SslConfigurationKeys.KEYSTORE_PATH;
326

327
// Check if a setting is deprecated
328
boolean deprecated = SslConfigurationKeys.isDeprecated("ssl.trust_all_certs");
329
```
330

331
## Error Handling
332

333
SSL configuration operations can throw `SslConfigException` for various error conditions:
334

335
```java { .api }
336
/**
337
 * Base exception for SSL configuration problems
338
 */
339
public class SslConfigException extends Exception {
340
    public SslConfigException(String message);
341
    public SslConfigException(String message, Exception cause);
342
}
343
```
344

345
Common error scenarios:
346
- Invalid file paths or unreadable certificate/key files
347
- Malformed PEM files or corrupted keystores
348
- Incompatible cipher suites or protocol versions
349
- Missing required settings or invalid setting values
350
- Keystore password mismatches or key extraction failures