java.lang.Object

cloud.opencode.base.crypto.ssl.SslContextBuilder

public final class SslContextBuilder extends Object

SSL Context Builder - Fluent SSL Context Configuration SSL 上下文构建器 - 流式 SSL 上下文配置

This builder provides a fluent API for creating SSLContext instances with various configurations including keystores, truststores, and protocols.

此构建器提供流式 API 来创建带有各种配置的 SSLContext 实例，包括密钥库、信任库和协议。

Example | 示例:

SSLContext sslContext = SslContextBuilder.create()
    .keyStore(Path.of("/path/to/keystore.p12"), "password")
    .trustStore(Path.of("/path/to/truststore.jks"), "password")
    .protocol("TLSv1.3")
    .build();

Features | 主要功能:

Fluent SSLContext configuration - 流式 SSLContext 配置
Keystore and truststore loading - 密钥库和信任库加载
PEM certificate support - PEM 证书支持
Mutual TLS (mTLS) configuration - 双向 TLS（mTLS）配置

Usage Examples | 使用示例:

SSLContext ctx = SslContextBuilder.create()
    .keyStore(Path.of("keystore.p12"), "password")
    .trustStore(Path.of("truststore.jks"), "password")
    .protocol("TLSv1.3")
    .build();

Security | 安全性:

Thread-safe: No - 线程安全: 否
Null-safe: Partial - 空值安全: 部分

Performance | 性能特性:

Time complexity: O(1) - 时间复杂度: O(1)
Space complexity: O(1) - 空间复杂度: O(1)

Since:

JDK 25, opencode-base-crypto V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

SSLContext

build()

Builds the SSLContext.

static SslContextBuilder

create()

Creates a new builder.

SslContextBuilder

keyManagers(KeyManager... keyManagers)

Sets key managers.

SslContextBuilder

keyStore(InputStream inputStream, String password)

Loads keystore from input stream.

SslContextBuilder

keyStore(InputStream inputStream, String password, String type)

Loads keystore from input stream with type.

SslContextBuilder

keyStore(Path path, String password)

Loads keystore from file.

SslContextBuilder

keyStore(Path path, String password, String type)

Loads keystore from file with type.

SslContextBuilder

pemCertificate(String pemContent)

Loads a PEM-encoded certificate and trusts it (as a CA or leaf certificate).

SslContextBuilder

pemCertificate(Path pemPath)

Loads a PEM-encoded certificate from a file.

SslContextBuilder

pemClientCertificate(String certPem, String keyPem)

Configures mutual TLS (mTLS) using PEM-encoded client certificate and PKCS8 private key.

SslContextBuilder

pemClientCertificate(Path certPath, Path keyPath)

Configures mutual TLS (mTLS) from PEM files on disk.

SslContextBuilder

protocol(String protocol)

Sets the SSL protocol.

SslContextBuilder

secureRandom(SecureRandom secureRandom)

Sets secure random.

SslContextBuilder

tlsV12()

Sets TLS 1.2 protocol.

SslContextBuilder

tlsV13()

Sets TLS 1.3 protocol.

SslContextBuilder

trustAll()

Configures to trust all certificates (DANGEROUS - development only).

SslContextBuilder

trustManagers(TrustManager... trustManagers)

Sets trust managers.

SslContextBuilder

trustStore(InputStream inputStream, String password)

Loads truststore from input stream.

SslContextBuilder

trustStore(InputStream inputStream, String password, String type)

Loads truststore from input stream with type.

SslContextBuilder

trustStore(Path path, String password)

Loads truststore from file.

SslContextBuilder

trustStore(Path path, String password, String type)

Loads truststore from file with type.

SslContextBuilder

withExtraCA(String caCertPem)

Merges the JVM default system trust store with a PEM-encoded CA certificate string.

SslContextBuilder

withExtraCA(Path caCertPemPath)

Merges the JVM default system trust store with one or more extra PEM CA certificates.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- create
  
  public static SslContextBuilder create()
  
  Creates a new builder. 创建新的构建器。
  
  Returns:
  
  the builder - 构建器
- protocol
  
  public SslContextBuilder protocol(String protocol)
  
  Sets the SSL protocol. 设置 SSL 协议。
  
  Parameters:
  
  protocol - the protocol (e.g., "TLS", "TLSv1.2", "TLSv1.3") - 协议
  
  Returns:
  
  this builder - 此构建器
- tlsV12
  
  public SslContextBuilder tlsV12()
  
  Sets TLS 1.2 protocol. 设置 TLS 1.2 协议。
  
  Returns:
  
  this builder - 此构建器
- tlsV13
  
  public SslContextBuilder tlsV13()
  
  Sets TLS 1.3 protocol. 设置 TLS 1.3 协议。
  
  Returns:
  
  this builder - 此构建器
- keyManagers
  
  public SslContextBuilder keyManagers(KeyManager... keyManagers)
  
  Sets key managers. 设置密钥管理器。
  
  Parameters:
  
  keyManagers - the key managers - 密钥管理器
  
  Returns:
  
  this builder - 此构建器
- trustManagers
  
  public SslContextBuilder trustManagers(TrustManager... trustManagers)
  
  Sets trust managers. 设置信任管理器。
  
  Parameters:
  
  trustManagers - the trust managers - 信任管理器
  
  Returns:
  
  this builder - 此构建器
- secureRandom
  
  public SslContextBuilder secureRandom(SecureRandom secureRandom)
  
  Sets secure random. 设置安全随机数。
  
  Parameters:
  
  secureRandom - the secure random - 安全随机数
  
  Returns:
  
  this builder - 此构建器
- trustAll
  
  public SslContextBuilder trustAll()
  
  Configures to trust all certificates (DANGEROUS - development only). 配置为信任所有证书（危险 - 仅用于开发）。
  
  Returns:
  
  this builder - 此构建器
- keyStore
  
  public SslContextBuilder keyStore(Path path, String password)
  
  Loads keystore from file. 从文件加载密钥库。
  
  Parameters:
  
  path - the keystore path - 密钥库路径
  
  password - the keystore password - 密钥库密码
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if loading fails - 如果加载失败
- keyStore
  
  public SslContextBuilder keyStore(Path path, String password, String type)
  
  Loads keystore from file with type. 从文件加载指定类型的密钥库。
  
  Parameters:
  
  path - the keystore path - 密钥库路径
  
  password - the keystore password - 密钥库密码
  
  type - the keystore type - 密钥库类型
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if loading fails - 如果加载失败
- keyStore
  
  public SslContextBuilder keyStore(InputStream inputStream, String password)
  
  Loads keystore from input stream. 从输入流加载密钥库。
  
  Parameters:
  
  inputStream - the input stream - 输入流
  
  password - the keystore password - 密钥库密码
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if loading fails - 如果加载失败
- keyStore
  
  public SslContextBuilder keyStore(InputStream inputStream, String password, String type)
  
  Loads keystore from input stream with type. 从输入流加载指定类型的密钥库。
  
  Parameters:
  
  inputStream - the input stream - 输入流
  
  password - the keystore password - 密钥库密码
  
  type - the keystore type - 密钥库类型
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if loading fails - 如果加载失败
- trustStore
  
  public SslContextBuilder trustStore(Path path, String password)
  
  Loads truststore from file. 从文件加载信任库。
  
  Parameters:
  
  path - the truststore path - 信任库路径
  
  password - the truststore password - 信任库密码
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if loading fails - 如果加载失败
- trustStore
  
  public SslContextBuilder trustStore(Path path, String password, String type)
  
  Loads truststore from file with type. 从文件加载指定类型的信任库。
  
  Parameters:
  
  path - the truststore path - 信任库路径
  
  password - the truststore password - 信任库密码
  
  type - the truststore type - 信任库类型
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if loading fails - 如果加载失败
- trustStore
  
  public SslContextBuilder trustStore(InputStream inputStream, String password)
  
  Loads truststore from input stream. 从输入流加载信任库。
  
  Parameters:
  
  inputStream - the input stream - 输入流
  
  password - the truststore password - 信任库密码
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if loading fails - 如果加载失败
- trustStore
  
  public SslContextBuilder trustStore(InputStream inputStream, String password, String type)
  
  Loads truststore from input stream with type. 从输入流加载指定类型的信任库。
  
  Parameters:
  
  inputStream - the input stream - 输入流
  
  password - the truststore password - 信任库密码
  
  type - the truststore type - 信任库类型
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if loading fails - 如果加载失败
- pemCertificate
  public SslContextBuilder pemCertificate(String pemContent)
  
  Loads a PEM-encoded certificate and trusts it (as a CA or leaf certificate). 加载 PEM 格式的证书并将其作为受信任证书（CA 或叶证书）。
  Useful when the server uses a self-signed certificate or a private CA, and you want to trust only that specific certificate without disabling all certificate validation.
  
  适用于服务器使用自签名证书或私有 CA 的场景，只信任该特定证书而不禁用所有证书验证。
  
  Example | 示例:
  
  String pem = Files.readString(Path.of("/etc/ssl/server.pem")); SSLContext ctx = SslContextBuilder.create().pemCertificate(pem).build();
  
  Parameters:
  
  pemContent - the PEM-encoded certificate string - PEM 格式的证书字符串
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if the PEM is invalid - 如果 PEM 无效
- pemCertificate
  
  public SslContextBuilder pemCertificate(Path pemPath)
  
  Loads a PEM-encoded certificate from a file. 从文件加载 PEM 格式的证书。
  
  Parameters:
  
  pemPath - the path to the PEM file - PEM 文件路径
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if the file cannot be read - 如果文件无法读取
- withExtraCA
  public SslContextBuilder withExtraCA(Path caCertPemPath)
  
  Merges the JVM default system trust store with one or more extra PEM CA certificates. 将 JVM 默认系统信任库与额外的 PEM 格式 CA 证书合并。
  This is the recommended approach for corporate environments where the server is signed by an internal CA not included in the JVM default trust store. Unlike trustAll(), this method preserves full certificate validation for all other hosts.
  
  推荐用于企业环境，服务器由不在 JVM 默认信任库中的内部 CA 签署。与 trustAll() 不同，此方法对所有其他主机保留完整的证书验证。
  
  Example | 示例:
  
  SSLContext ctx = SslContextBuilder.create() .withExtraCA(Path.of("/etc/corp/ca.pem")) .build();
  
  Parameters:
  
  caCertPemPath - the path to the extra CA PEM file - 额外 CA PEM 文件路径
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if the file cannot be read or the cert is invalid - 如果文件无法读取或证书无效
- withExtraCA
  
  public SslContextBuilder withExtraCA(String caCertPem)
  
  Merges the JVM default system trust store with a PEM-encoded CA certificate string. 将 JVM 默认系统信任库与 PEM 格式的 CA 证书字符串合并。
  
  Parameters:
  
  caCertPem - the PEM-encoded CA certificate - PEM 格式的 CA 证书字符串
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if the certificate is invalid - 如果证书无效
- pemClientCertificate
  public SslContextBuilder pemClientCertificate(String certPem, String keyPem)
  
  Configures mutual TLS (mTLS) using PEM-encoded client certificate and PKCS8 private key. This is the standard format used in Kubernetes / cloud-native environments. 使用 PEM 格式的客户端证书和 PKCS8 私钥配置双向 TLS（mTLS）。这是 Kubernetes / 云原生环境中的标准格式。
  The private key must be in PKCS8 unencrypted format (-----BEGIN PRIVATE KEY-----). To convert from PKCS1 (BEGIN RSA PRIVATE KEY): openssl pkcs8 -topk8 -nocrypt -in key.pem -out key-pkcs8.pem
  
  私钥必须是 PKCS8 未加密格式（-----BEGIN PRIVATE KEY-----）。从 PKCS1 转换：openssl pkcs8 -topk8 -nocrypt -in key.pem -out key-pkcs8.pem
  
  Example | 示例:
  
  String cert = Files.readString(Path.of("/etc/ssl/client.pem")); String key = Files.readString(Path.of("/etc/ssl/client-key.pem")); SSLContext ctx = SslContextBuilder.create() .pemClientCertificate(cert, key) .withExtraCA("/etc/ssl/ca.pem") // optional: custom CA .build(); HttpClient client = HttpClient.builder().sslContext(ctx).build();
  
  Parameters:
  
  certPem - PEM-encoded client certificate - PEM 格式的客户端证书
  
  keyPem - PEM-encoded PKCS8 private key - PEM 格式的 PKCS8 私钥
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if the certificate or key is invalid - 如果证书或密钥无效
- pemClientCertificate
  
  public SslContextBuilder pemClientCertificate(Path certPath, Path keyPath)
  
  Configures mutual TLS (mTLS) from PEM files on disk. 从磁盘上的 PEM 文件配置双向 TLS（mTLS）。
  
  Parameters:
  
  certPath - path to the PEM client certificate file - PEM 客户端证书文件路径
  
  keyPath - path to the PKCS8 private key file - PKCS8 私钥文件路径
  
  Returns:
  
  this builder - 此构建器
  
  Throws:
  
  OpenCryptoException - if the files cannot be read - 如果文件无法读取
- build
  
  public SSLContext build()
  
  Builds the SSLContext. 构建 SSLContext。
  
  Returns:
  
  the SSLContext - SSLContext
  
  Throws:
  
  OpenCryptoException - if building fails - 如果构建失败

Class SslContextBuilder

Method Summary

Methods inherited from class Object

Method Details

create

protocol

tlsV12

tlsV13

keyManagers

trustManagers

secureRandom

trustAll

keyStore

keyStore

keyStore

keyStore

trustStore

trustStore

trustStore

trustStore

pemCertificate

pemCertificate

withExtraCA

withExtraCA

pemClientCertificate

pemClientCertificate

build