Class CertificatePinner

java.lang.Object
cloud.opencode.base.crypto.ssl.CertificatePinner
public final class CertificatePinner extends Object
Certificate Pinner - SHA-256 SPKI Fingerprint Certificate Pinning 证书固定器 - SHA-256 SPKI 指纹证书固定

Protects against certificate authority (CA) compromise by pinning the SHA-256 fingerprint of a certificate's SubjectPublicKeyInfo (SPKI). Format follows the OkHttp convention: sha256/base64==.

通过固定证书 SubjectPublicKeyInfo（SPKI）的 SHA-256 指纹，防范证书颁发机构（CA）被攻击。 格式遵循 OkHttp 约定：sha256/base64==。

Why SPKI pinning? | 为什么使用 SPKI 固定？
Pinning the public key (SPKI) rather than the full certificate fingerprint means the pin remains valid after a certificate renewal, as long as the same key pair is reused. This dramatically reduces operational burden.

固定公钥（SPKI）而非完整证书指纹，意味着只要复用相同密钥对，证书续期后固定仍然有效， 大幅降低运维负担。

How to obtain a pin | 如何获取固定值:

# From a live server:
openssl s_client -connect api.example.com:443 -servername api.example.com \
  | openssl x509 -pubkey -noout \
  | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256 -binary \
  | openssl base64

// Or from Java code:
String pin = CertificatePinner.computePin(cert);

Example | 示例:

CertificatePinner pinner = CertificatePinner.builder()
    .add("sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
    .add("sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=")
    .build();

HttpClient client = HttpClient.builder()
    .sslContext(pinner.toSslContext())
    .build();

Features | 主要功能:

  • SHA-256 SPKI fingerprint pinning - SHA-256 SPKI 指纹固定
  • Certificate pin computation - 证书固定值计算
  • SSLContext with pinning enforcement - 强制固定的 SSLContext

Usage Examples | 使用示例:

CertificatePinner pinner = CertificatePinner.builder()
    .add("sha256/AAAA...")
    .build();
SSLContext ctx = pinner.toSslContext();

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
  • Null-safe: Partial - 空值安全: 部分
Since:
JDK 25, opencode-base-crypto V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • builder

      public static CertificatePinner.Builder builder()
      Creates a builder for configuring certificate pins. 创建用于配置证书固定的构建器。
      Returns:
      the builder - 构建器

    • computePin

      public static String computePin(X509Certificate cert)
      Computes the sha256/base64== pin for the given certificate. Useful for obtaining pin values during development or CI verification. 计算给定证书的 sha256/base64== 固定值。 适用于开发期间获取固定值或 CI 验证。
      Parameters:
      cert - the X.509 certificate - X.509 证书
      Returns:
      the pin string in sha256/base64== format - sha256/base64== 格式的固定字符串

    • toSslContext

      public SSLContext toSslContext()
      Creates an SSLContext that enforces certificate pinning during TLS handshake. The pinning check is layered on top of the JVM's default trust store: a certificate must pass both normal CA verification and at least one pinned hash must match. 创建在 TLS 握手期间强制执行证书固定的 SSLContext。 固定检查叠加在 JVM 默认信任库之上：证书必须通过正常 CA 验证， 且至少有一个固定哈希匹配。
      Returns:
      the SSL context - SSL 上下文
      Throws:
      OpenCryptoException - if the SSL context cannot be created - 如果无法创建 SSL 上下文