or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mddiagnostics.mdenums-types.mdindex.mdkey-management.mdtrust-management.mdutilities.md
tile.json

tessl/maven-org-elasticsearch--elasticsearch-ssl-config

SSL/TLS configuration library for Elasticsearch providing comprehensive security management utilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.elasticsearch/elasticsearch-ssl-config@9.1.x

To install, run

npx @tessl/cli install tessl/maven-org-elasticsearch--elasticsearch-ssl-config@9.1.0

index.mddocs/

Elasticsearch SSL Configuration Library

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.

Package Information

  • Package Name: org.elasticsearch:elasticsearch-ssl-config
  • Package Type: maven
  • Language: Java
  • Installation: Add to your Maven pom.xml:
<dependency>
    <groupId>org.elasticsearch</groupId>
    <artifactId>elasticsearch-ssl-config</artifactId>
    <version>9.1.3</version>
</dependency>

For Gradle:

implementation 'org.elasticsearch:elasticsearch-ssl-config:9.1.3'

Core Imports

import org.elasticsearch.common.ssl.SslConfiguration;
import org.elasticsearch.common.ssl.SslConfigurationLoader;
import org.elasticsearch.common.ssl.SslKeyConfig;
import org.elasticsearch.common.ssl.SslTrustConfig;
import org.elasticsearch.common.ssl.SslVerificationMode;
import org.elasticsearch.common.ssl.SslClientAuthenticationMode;

Basic Usage

import org.elasticsearch.common.ssl.*;
import javax.net.ssl.SSLContext;
import java.nio.file.Path;
import java.util.List;

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

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

// Use the SSL context for secure connections
// (with HttpsURLConnection, SSLSocketFactory, etc.)

Architecture

The library is built around several key architectural components:

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

Capabilities

SSL Configuration Management

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

public record SslConfiguration(
    String settingPrefix,
    boolean explicitlyConfigured,
    SslTrustConfig trustConfig,
    SslKeyConfig keyConfig,
    SslVerificationMode verificationMode,
    SslClientAuthenticationMode clientAuth,
    List<String> ciphers,
    List<String> supportedProtocols
) {
    public SSLContext createSslContext();
    public List<String> getCipherSuites();
    public Collection<Path> getDependentFiles();
    public Collection<? extends StoredCertificate> getConfiguredCertificates();
}

SSL Configuration Management

Key Management

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

public interface SslKeyConfig {
    Collection<Path> getDependentFiles();
    X509ExtendedKeyManager createKeyManager();
    List<Tuple<PrivateKey, X509Certificate>> getKeys();
    Collection<StoredCertificate> getConfiguredCertificates();
    default boolean hasKeyMaterial();
    default SslTrustConfig asTrustConfig();
}

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

public class StoreKeyConfig implements SslKeyConfig {
    public StoreKeyConfig(String path, char[] storePassword, String type, 
                         Function<KeyStore, KeyStore> filter, char[] keyPassword, 
                         String algorithm, Path configBasePath);
}

Key Management

Trust Management

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

public interface SslTrustConfig {
    Collection<Path> getDependentFiles();
    X509ExtendedTrustManager createTrustManager();
    Collection<? extends StoredCertificate> getConfiguredCertificates();
    default boolean isSystemDefault();
}

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

public class StoreTrustConfig implements SslTrustConfig {
    public StoreTrustConfig(String path, char[] password, String type, String algorithm, 
                           boolean requireTrustAnchors, Path configBasePath);
}

Trust Management

SSL Utilities

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

public final class KeyStoreUtil {
    public static String inferKeyStoreType(String path);
    public static KeyStore readKeyStore(Path path, String ksType, char[] password);
    public static KeyStore buildKeyStore(Collection<Certificate> certificateChain, PrivateKey privateKey, char[] password);
    public static X509ExtendedKeyManager createKeyManager(Certificate[] certificateChain, PrivateKey privateKey, char[] password);
    public static X509ExtendedTrustManager createTrustManager(Collection<Certificate> certificates);
}

public final class PemUtils {
    public static PrivateKey readPrivateKey(Path path, Supplier<char[]> passwordSupplier);
    public static List<Certificate> readCertificates(Collection<Path> certPaths);
    public static PrivateKey parsePKCS8PemString(String pemString);
}

SSL Utilities

SSL Diagnostics

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

public class SslDiagnostics {
    public static final SslDiagnostics INSTANCE;
    
    public String getTrustDiagnosticFailure(X509Certificate[] chain, PeerType peerType, 
                                          SSLSession session, String contextName, 
                                          Map<String, List<X509Certificate>> trustedIssuers);
    public static List<String> describeValidHostnames(X509Certificate certificate);
    public static IssuerTrust checkIssuerTrust(Map<String, List<X509Certificate>> trustedIssuers, 
                                              X509Certificate peerCert);
}

public final class DiagnosticTrustManager extends X509ExtendedTrustManager {
    public DiagnosticTrustManager(X509ExtendedTrustManager delegate, Supplier<String> contextName, 
                                 DiagnosticLogger logger);
}

SSL Diagnostics

Configuration Types and Enums

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

public enum SslVerificationMode {
    NONE, CERTIFICATE, FULL;
    
    public abstract boolean isHostnameVerificationEnabled();
    public abstract boolean isCertificateVerificationEnabled();
    public static SslVerificationMode parse(String value);
}

public enum SslClientAuthenticationMode {
    NONE, OPTIONAL, REQUIRED;
    
    public abstract boolean enabled();
    public abstract void configure(SSLParameters sslParameters);
    public static SslClientAuthenticationMode parse(String value);
}

public record StoredCertificate(
    X509Certificate certificate,
    String path,
    String format,
    String alias,
    boolean hasPrivateKey
) {}

Configuration Types and Enums