0
# SSL Diagnostics
1

2
Advanced diagnostic capabilities for troubleshooting SSL trust failures, certificate issues, and connection problems with detailed error reporting and trust validation analysis.
3

4
## Capabilities
5

6
### SSL Diagnostics Engine
7

8
Comprehensive diagnostic engine for analyzing SSL trust failures and providing detailed troubleshooting information.
9

10
```java { .api }
11
/**
12
 * SSL diagnostics for troubleshooting trust failures
13
 */
14
public class SslDiagnostics {
15
    /**
16
     * Singleton instance for SSL diagnostics
17
     */
18
    public static final SslDiagnostics INSTANCE;
19
    
20
    /**
21
     * Creates SSL diagnostics with custom clock
22
     * @param clock clock for timestamp generation in diagnostics
23
     */
24
    public SslDiagnostics(Clock clock);
25
    
26
    /**
27
     * Gets comprehensive diagnostic information for SSL trust failures
28
     * @param chain certificate chain that failed validation
29
     * @param peerType type of peer (CLIENT or SERVER)
30
     * @param session SSL session information
31
     * @param contextName descriptive name for the SSL context
32
     * @param trustedIssuers map of trusted issuer DN to certificate lists (optional)
33
     * @return detailed diagnostic message explaining the trust failure
34
     */
35
    public String getTrustDiagnosticFailure(X509Certificate[] chain, PeerType peerType, 
36
                                          SSLSession session, String contextName, 
37
                                          @Nullable Map<String, List<X509Certificate>> trustedIssuers);
38
    
39
    /**
40
     * Describes valid hostnames for a certificate
41
     * @param certificate X509 certificate to analyze
42
     * @return list of valid hostname patterns from certificate
43
     */
44
    public static List<String> describeValidHostnames(X509Certificate certificate);
45
    
46
    /**
47
     * Checks issuer trust status for a certificate
48
     * @param trustedIssuers map of trusted issuer DN to certificate lists
49
     * @param peerCert certificate to check issuer trust for
50
     * @return issuer trust analysis result
51
     */
52
    public static IssuerTrust checkIssuerTrust(Map<String, List<X509Certificate>> trustedIssuers, 
53
                                              X509Certificate peerCert);
54
}
55
```
56

57
**Usage Examples:**
58

59
```java
60
import org.elasticsearch.common.ssl.SslDiagnostics;
61
import org.elasticsearch.common.ssl.SslDiagnostics.PeerType;
62
import javax.net.ssl.SSLSession;
63
import java.security.cert.X509Certificate;
64
import java.util.List;
65
import java.util.Map;
66

67
// Get diagnostic information for trust failure
68
X509Certificate[] failedChain = // ... certificate chain that failed validation
69
SSLSession session = // ... SSL session
70
Map<String, List<X509Certificate>> trustedIssuers = // ... trusted CA certificates
71

72
String diagnostic = SslDiagnostics.INSTANCE.getTrustDiagnosticFailure(
73
    failedChain,
74
    PeerType.SERVER,                    // analyzing server certificate
75
    session,
76
    "Elasticsearch HTTPS connection",   // context description
77
    trustedIssuers                      // trusted CAs for comparison
78
);
79

80
System.out.println("SSL Trust Failure Diagnosis:");
81
System.out.println(diagnostic);
82

83
// Analyze certificate hostname validity
84
X509Certificate serverCert = failedChain[0];
85
List<String> validHostnames = SslDiagnostics.describeValidHostnames(serverCert);
86
System.out.println("Certificate is valid for hostnames: " + validHostnames);
87

88
// Check issuer trust
89
SslDiagnostics.IssuerTrust issuerTrust = SslDiagnostics.checkIssuerTrust(
90
    trustedIssuers, 
91
    serverCert
92
);
93
System.out.println("Issuer trust status: " + issuerTrust);
94
```
95

96
### Peer Type Enumeration
97

98
Enumeration for SSL peer types in diagnostic analysis.
99

100
```java { .api }
101
/**
102
 * SSL peer types for diagnostic analysis
103
 */
104
public enum PeerType {
105
    /**
106
     * Client peer (analyzing client certificate)
107
     */
108
    CLIENT,
109
    
110
    /**
111
     * Server peer (analyzing server certificate)
112
     */
113
    SERVER
114
}
115
```
116

117
### Diagnostic Trust Manager
118

119
X509ExtendedTrustManager wrapper that provides detailed diagnostic logging for SSL trust operations and failures.
120

121
```java { .api }
122
/**
123
 * Trust manager wrapper that provides diagnostic logging for SSL trust failures
124
 */
125
public final class DiagnosticTrustManager extends X509ExtendedTrustManager {
126
    /**
127
     * Creates diagnostic trust manager wrapper
128
     * @param delegate underlying trust manager to wrap
129
     * @param contextName supplier for context name in diagnostic messages
130
     * @param logger logger for diagnostic messages
131
     */
132
    public DiagnosticTrustManager(X509ExtendedTrustManager delegate, 
133
                                 Supplier<String> contextName, 
134
                                 DiagnosticLogger logger);
135
    
136
    /**
137
     * Checks client certificate trust with socket context and diagnostic logging
138
     * @param chain client certificate chain to validate
139
     * @param authType authentication type
140
     * @param socket SSL socket for context
141
     * @throws CertificateException if certificate validation fails
142
     */
143
    public void checkClientTrusted(X509Certificate[] chain, String authType, Socket socket) 
144
        throws CertificateException;
145
    
146
    /**
147
     * Checks server certificate trust with socket context and diagnostic logging
148
     * @param chain server certificate chain to validate
149
     * @param authType authentication type
150
     * @param socket SSL socket for context
151
     * @throws CertificateException if certificate validation fails
152
     */
153
    public void checkServerTrusted(X509Certificate[] chain, String authType, Socket socket) 
154
        throws CertificateException;
155
    
156
    /**
157
     * Checks client certificate trust with SSL engine context and diagnostic logging
158
     * @param chain client certificate chain to validate
159
     * @param authType authentication type
160
     * @param engine SSL engine for context
161
     * @throws CertificateException if certificate validation fails
162
     */
163
    public void checkClientTrusted(X509Certificate[] chain, String authType, SSLEngine engine) 
164
        throws CertificateException;
165
    
166
    /**
167
     * Checks server certificate trust with SSL engine context and diagnostic logging
168
     * @param chain server certificate chain to validate
169
     * @param authType authentication type
170
     * @param engine SSL engine for context
171
     * @throws CertificateException if certificate validation fails
172
     */
173
    public void checkServerTrusted(X509Certificate[] chain, String authType, SSLEngine engine) 
174
        throws CertificateException;
175
    
176
    /**
177
     * Checks client certificate trust with basic context and diagnostic logging
178
     * @param chain client certificate chain to validate
179
     * @param authType authentication type
180
     * @throws CertificateException if certificate validation fails
181
     */
182
    public void checkClientTrusted(X509Certificate[] chain, String authType) 
183
        throws CertificateException;
184
    
185
    /**
186
     * Checks server certificate trust with basic context and diagnostic logging
187
     * @param chain server certificate chain to validate
188
     * @param authType authentication type
189
     * @throws CertificateException if certificate validation fails
190
     */
191
    public void checkServerTrusted(X509Certificate[] chain, String authType) 
192
        throws CertificateException;
193
    
194
    /**
195
     * Gets accepted certificate authorities from underlying trust manager
196
     * @return array of accepted CA certificates
197
     */
198
    public X509Certificate[] getAcceptedIssuers();
199
}
200
```
201

202
### Diagnostic Logger Interface
203

204
Functional interface for diagnostic message logging.
205

206
```java { .api }
207
/**
208
 * Functional interface for diagnostic message logging
209
 */
210
@FunctionalInterface
211
public interface DiagnosticLogger {
212
    /**
213
     * Logs diagnostic warning message with exception cause
214
     * @param message diagnostic message to log
215
     * @param cause underlying security exception that triggered the diagnostic
216
     */
217
    void warning(String message, GeneralSecurityException cause);
218
}
219
```
220

221
**Usage Examples:**
222

223
```java
224
import org.elasticsearch.common.ssl.DiagnosticTrustManager;
225
import org.elasticsearch.common.ssl.DiagnosticTrustManager.DiagnosticLogger;
226
import javax.net.ssl.X509ExtendedTrustManager;
227
import java.util.function.Supplier;
228
import java.util.logging.Logger;
229

230
// Create diagnostic logger
231
DiagnosticLogger logger = (message, cause) -> {
232
    Logger.getLogger("ssl-diagnostics").warning(message + " - " + cause.getMessage());
233
};
234

235
// Create diagnostic trust manager
236
X509ExtendedTrustManager baseTrustManager = // ... base trust manager
237
DiagnosticTrustManager diagnosticTrustManager = new DiagnosticTrustManager(
238
    baseTrustManager,
239
    () -> "Elasticsearch cluster connection",  // context name
240
    logger                                     // diagnostic logger
241
);
242

243
// Use diagnostic trust manager in SSL context
244
SSLContext sslContext = SSLContext.getInstance("TLS");
245
sslContext.init(
246
    keyManagers,
247
    new TrustManager[] { diagnosticTrustManager },  // use diagnostic wrapper
248
    secureRandom
249
);
250

251
// When trust failures occur, detailed diagnostic messages will be logged:
252
// "SSL trust failed for Elasticsearch cluster connection: Certificate hostname mismatch. 
253
//  Expected: [elasticsearch.example.com], Found: [old-server.example.com]"
254
```
255

256
### Advanced Diagnostic Patterns
257

258
### Custom Diagnostic Logging
259

260
Implement custom diagnostic logging for different use cases:
261

262
```java
263
// Console diagnostic logger
264
DiagnosticLogger consoleLogger = (message, cause) -> {
265
    System.err.println("SSL DIAGNOSTIC: " + message);
266
    if (cause != null) {
267
        System.err.println("Caused by: " + cause.getClass().getSimpleName() + ": " + cause.getMessage());
268
    }
269
};
270

271
// File-based diagnostic logger
272
DiagnosticLogger fileLogger = (message, cause) -> {
273
    try (FileWriter writer = new FileWriter("ssl-diagnostics.log", true)) {
274
        writer.write(String.format("[%s] %s%n", Instant.now(), message));
275
        if (cause != null) {
276
            writer.write(String.format("Caused by: %s%n", cause.toString()));
277
        }
278
    } catch (IOException e) {
279
        // Handle logging error
280
    }
281
};
282

283
// Structured logging with JSON
284
DiagnosticLogger jsonLogger = (message, cause) -> {
285
    JsonObject diagnostic = new JsonObject();
286
    diagnostic.addProperty("timestamp", Instant.now().toString());
287
    diagnostic.addProperty("message", message);
288
    diagnostic.addProperty("context", "ssl-trust-validation");
289
    if (cause != null) {
290
        diagnostic.addProperty("exception", cause.getClass().getSimpleName());
291
        diagnostic.addProperty("exceptionMessage", cause.getMessage());
292
    }
293
    logger.warn(diagnostic.toString());
294
};
295
```
296

297
### Certificate Analysis Utilities
298

299
Use diagnostic utilities for certificate analysis:
300

301
```java
302
import org.elasticsearch.common.ssl.SslDiagnostics;
303
import java.security.cert.X509Certificate;
304
import java.util.List;
305

306
// Analyze certificate hostname validity
307
public void analyzeCertificate(X509Certificate cert) {
308
    List<String> hostnames = SslDiagnostics.describeValidHostnames(cert);
309
    
310
    System.out.println("Certificate Analysis:");
311
    System.out.println("Subject: " + cert.getSubjectX500Principal().getName());
312
    System.out.println("Issuer: " + cert.getIssuerX500Principal().getName());
313
    System.out.println("Valid hostnames: " + String.join(", ", hostnames));
314
    System.out.println("Valid from: " + cert.getNotBefore());
315
    System.out.println("Valid until: " + cert.getNotAfter());
316
    
317
    // Check if certificate is currently valid
318
    try {
319
        cert.checkValidity();
320
        System.out.println("Certificate is currently valid");
321
    } catch (Exception e) {
322
        System.out.println("Certificate validity issue: " + e.getMessage());
323
    }
324
}
325

326
// Check hostname match
327
public boolean checkHostnameMatch(X509Certificate cert, String hostname) {
328
    List<String> validHostnames = SslDiagnostics.describeValidHostnames(cert);
329
    
330
    return validHostnames.stream().anyMatch(pattern -> {
331
        if (pattern.startsWith("*.")) {
332
            // Wildcard match
333
            String domain = pattern.substring(2);
334
            return hostname.endsWith("." + domain) || hostname.equals(domain);
335
        } else {
336
            // Exact match
337
            return hostname.equalsIgnoreCase(pattern);
338
        }
339
    });
340
}
341
```
342

343
### Trust Failure Analysis
344

345
Comprehensive analysis of trust failures:
346

347
```java
348
public void analyzeTrustFailure(X509Certificate[] chain, Map<String, List<X509Certificate>> trustedIssuers) {
349
    // Check each certificate in the chain
350
    for (int i = 0; i < chain.length; i++) {
351
        X509Certificate cert = chain[i];
352
        System.out.println("Certificate " + i + ":");
353
        System.out.println("  Subject: " + cert.getSubjectX500Principal().getName());
354
        System.out.println("  Issuer: " + cert.getIssuerX500Principal().getName());
355
        
356
        // Check issuer trust
357
        SslDiagnostics.IssuerTrust issuerTrust = SslDiagnostics.checkIssuerTrust(trustedIssuers, cert);
358
        System.out.println("  Issuer trust: " + issuerTrust);
359
        
360
        // Check validity period
361
        try {
362
            cert.checkValidity();
363
            System.out.println("  Validity: OK");
364
        } catch (Exception e) {
365
            System.out.println("  Validity: FAILED - " + e.getMessage());
366
        }
367
    }
368
    
369
    // Get comprehensive diagnostic
370
    String diagnostic = SslDiagnostics.INSTANCE.getTrustDiagnosticFailure(
371
        chain, 
372
        SslDiagnostics.PeerType.SERVER, 
373
        null,  // no session info
374
        "Trust Analysis", 
375
        trustedIssuers
376
    );
377
    
378
    System.out.println("\nDetailed Diagnostic:");
379
    System.out.println(diagnostic);
380
}
381
```
382

383
## Diagnostic Output Examples
384

385
The diagnostic system provides detailed, human-readable error messages:
386

387
### Hostname Mismatch Example
388
```
389
SSL trust failed for Elasticsearch HTTPS connection: Certificate hostname verification failed.
390
Certificate is valid for: [old-server.example.com, *.old-domain.com]
391
Requested hostname: elasticsearch.example.com
392
```
393

394
### Untrusted Certificate Authority Example
395
```
396
SSL trust failed for Elasticsearch HTTPS connection: Certificate signed by untrusted authority.
397
Certificate issuer: CN=Internal CA, O=Example Corp
398
Trusted authorities: [29 certificates including CN=DigiCert Global Root CA, CN=Let's Encrypt Authority X3, ...]
399
```
400

401
### Expired Certificate Example
402
```
403
SSL trust failed for Elasticsearch HTTPS connection: Certificate has expired.
404
Certificate valid from: 2023-01-01T00:00:00Z
405
Certificate expired on: 2024-01-01T00:00:00Z
406
Current time: 2024-02-15T10:30:00Z
407
```
408

409
### Chain Building Failure Example
410
```
411
SSL trust failed for Elasticsearch HTTPS connection: Unable to build certificate chain.
412
End entity certificate: CN=elasticsearch.example.com
413
Missing intermediate certificate: CN=Example Intermediate CA
414
Available trusted roots: [CN=Example Root CA, CN=DigiCert Global Root CA, ...]
415
```