0
# Elasticsearch SSL Configuration Library
1

2
The Elasticsearch SSL Configuration Library provides comprehensive SSL/TLS configuration management utilities for Java applications. It offers a robust framework for handling SSL configurations including key stores, trust stores, certificate management, PEM utilities, and various SSL verification modes with extensive validation and diagnostic capabilities.
3

4
## Package Information
5

6
- **Package Name**: org.elasticsearch:elasticsearch-ssl-config
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>org.elasticsearch</groupId>
14
    <artifactId>elasticsearch-ssl-config</artifactId>
15
    <version>9.1.3</version>
16
</dependency>
17
```
18

19
For Gradle:
20

21
```gradle
22
implementation 'org.elasticsearch:elasticsearch-ssl-config:9.1.3'
23
```
24

25
## Core Imports
26

27
```java
28
import org.elasticsearch.common.ssl.SslConfiguration;
29
import org.elasticsearch.common.ssl.SslConfigurationLoader;
30
import org.elasticsearch.common.ssl.SslKeyConfig;
31
import org.elasticsearch.common.ssl.SslTrustConfig;
32
import org.elasticsearch.common.ssl.SslVerificationMode;
33
import org.elasticsearch.common.ssl.SslClientAuthenticationMode;
34
```
35

36
## Basic Usage
37

38
```java
39
import org.elasticsearch.common.ssl.*;
40
import javax.net.ssl.SSLContext;
41
import java.nio.file.Path;
42
import java.util.List;
43

44
// Create SSL configuration
45
SslConfiguration config = new SslConfiguration(
46
    "https",                                    // setting prefix
47
    true,                                       // explicitly configured
48
    new PemTrustConfig(List.of("ca.pem"), basePath),  // trust config
49
    new PemKeyConfig("cert.pem", "key.pem", null, basePath), // key config
50
    SslVerificationMode.FULL,                   // verification mode
51
    SslClientAuthenticationMode.OPTIONAL,      // client auth
52
    List.of(),                                  // cipher suites (use defaults)
53
    List.of("TLSv1.3", "TLSv1.2")             // supported protocols
54
);
55

56
// Create SSL context
57
SSLContext sslContext = config.createSslContext();
58

59
// Use the SSL context for secure connections
60
// (with HttpsURLConnection, SSLSocketFactory, etc.)
61
```
62

63
## Architecture
64

65
The library is built around several key architectural components:
66

67
- **Configuration Management**: Central `SslConfiguration` record that encapsulates all SSL settings and can create `SSLContext` instances
68
- **Pluggable Key Sources**: `SslKeyConfig` interface with implementations for PEM files, keystores, and empty configurations
69
- **Flexible Trust Models**: `SslTrustConfig` interface supporting PEM CA files, trust stores, system defaults, composite configurations, and trust-everything modes
70
- **Configuration Loading**: Abstract `SslConfigurationLoader` for building configurations from various settings sources
71
- **Utility Layer**: Comprehensive utilities for keystore operations, PEM parsing, certificate handling, and SSL diagnostics
72
- **Type Safety**: Strong typing with enums for verification modes, client authentication, and certificate fields
73

74
## Capabilities
75

76
### SSL Configuration Management
77

78
Core SSL configuration functionality providing immutable configuration objects and SSL context creation.
79

80
```java { .api }
81
public record SslConfiguration(
82
    String settingPrefix,
83
    boolean explicitlyConfigured,
84
    SslTrustConfig trustConfig,
85
    SslKeyConfig keyConfig,
86
    SslVerificationMode verificationMode,
87
    SslClientAuthenticationMode clientAuth,
88
    List<String> ciphers,
89
    List<String> supportedProtocols
90
) {
91
    public SSLContext createSslContext();
92
    public List<String> getCipherSuites();
93
    public Collection<Path> getDependentFiles();
94
    public Collection<? extends StoredCertificate> getConfiguredCertificates();
95
}
96
```
97

98
[SSL Configuration Management](./configuration.md)
99

100
### Key Management
101

102
SSL key material management with support for PEM files, keystores, and programmatic key configurations.
103

104
```java { .api }
105
public interface SslKeyConfig {
106
    Collection<Path> getDependentFiles();
107
    X509ExtendedKeyManager createKeyManager();
108
    List<Tuple<PrivateKey, X509Certificate>> getKeys();
109
    Collection<StoredCertificate> getConfiguredCertificates();
110
    default boolean hasKeyMaterial();
111
    default SslTrustConfig asTrustConfig();
112
}
113

114
public class PemKeyConfig implements SslKeyConfig {
115
    public PemKeyConfig(String certificatePath, String keyPath, char[] keyPassword, Path configBasePath);
116
}
117

118
public class StoreKeyConfig implements SslKeyConfig {
119
    public StoreKeyConfig(String path, char[] storePassword, String type, 
120
                         Function<KeyStore, KeyStore> filter, char[] keyPassword, 
121
                         String algorithm, Path configBasePath);
122
}
123
```
124

125
[Key Management](./key-management.md)
126

127
### Trust Management
128

129
SSL trust configuration with support for various trust models including PEM CA files, trust stores, and system defaults.
130

131
```java { .api }
132
public interface SslTrustConfig {
133
    Collection<Path> getDependentFiles();
134
    X509ExtendedTrustManager createTrustManager();
135
    Collection<? extends StoredCertificate> getConfiguredCertificates();
136
    default boolean isSystemDefault();
137
}
138

139
public class PemTrustConfig implements SslTrustConfig {
140
    public PemTrustConfig(List<String> certificateAuthorities, Path basePath);
141
}
142

143
public class StoreTrustConfig implements SslTrustConfig {
144
    public StoreTrustConfig(String path, char[] password, String type, String algorithm, 
145
                           boolean requireTrustAnchors, Path configBasePath);
146
}
147
```
148

149
[Trust Management](./trust-management.md)
150

151
### SSL Utilities
152

153
Comprehensive utility functions for keystore operations, PEM file parsing, certificate handling, and SSL-related tasks.
154

155
```java { .api }
156
public final class KeyStoreUtil {
157
    public static String inferKeyStoreType(String path);
158
    public static KeyStore readKeyStore(Path path, String ksType, char[] password);
159
    public static KeyStore buildKeyStore(Collection<Certificate> certificateChain, PrivateKey privateKey, char[] password);
160
    public static X509ExtendedKeyManager createKeyManager(Certificate[] certificateChain, PrivateKey privateKey, char[] password);
161
    public static X509ExtendedTrustManager createTrustManager(Collection<Certificate> certificates);
162
}
163

164
public final class PemUtils {
165
    public static PrivateKey readPrivateKey(Path path, Supplier<char[]> passwordSupplier);
166
    public static List<Certificate> readCertificates(Collection<Path> certPaths);
167
    public static PrivateKey parsePKCS8PemString(String pemString);
168
}
169
```
170

171
[SSL Utilities](./utilities.md)
172

173
### SSL Diagnostics
174

175
Advanced diagnostic capabilities for troubleshooting SSL trust failures and certificate issues.
176

177
```java { .api }
178
public class SslDiagnostics {
179
    public static final SslDiagnostics INSTANCE;
180
    
181
    public String getTrustDiagnosticFailure(X509Certificate[] chain, PeerType peerType, 
182
                                          SSLSession session, String contextName, 
183
                                          Map<String, List<X509Certificate>> trustedIssuers);
184
    public static List<String> describeValidHostnames(X509Certificate certificate);
185
    public static IssuerTrust checkIssuerTrust(Map<String, List<X509Certificate>> trustedIssuers, 
186
                                              X509Certificate peerCert);
187
}
188

189
public final class DiagnosticTrustManager extends X509ExtendedTrustManager {
190
    public DiagnosticTrustManager(X509ExtendedTrustManager delegate, Supplier<String> contextName, 
191
                                 DiagnosticLogger logger);
192
}
193
```
194

195
[SSL Diagnostics](./diagnostics.md)
196

197
### Configuration Types and Enums
198

199
Strongly-typed enums and data classes for SSL configuration options, verification modes, and certificate handling.
200

201
```java { .api }
202
public enum SslVerificationMode {
203
    NONE, CERTIFICATE, FULL;
204
    
205
    public abstract boolean isHostnameVerificationEnabled();
206
    public abstract boolean isCertificateVerificationEnabled();
207
    public static SslVerificationMode parse(String value);
208
}
209

210
public enum SslClientAuthenticationMode {
211
    NONE, OPTIONAL, REQUIRED;
212
    
213
    public abstract boolean enabled();
214
    public abstract void configure(SSLParameters sslParameters);
215
    public static SslClientAuthenticationMode parse(String value);
216
}
217

218
public record StoredCertificate(
219
    X509Certificate certificate,
220
    String path,
221
    String format,
222
    String alias,
223
    boolean hasPrivateKey
224
) {}
225
```
226

227
[Configuration Types and Enums](./enums-types.md)