Package cn.gmkit.sm2

Class SM2

java.lang.Object
cn.gmkit.sm2.SM2
public final class SM2 extends Object
SM2 对象式入口。

这个类面向希望保留实例并重复调用的场景，例如： 使用同一个安全上下文连续生成密钥、执行加解密、签名验签，或完成密钥交换。

如果业务更偏好传统工具类风格，可改用 SM2Util 的静态方法；两套 API 在能力上保持一致，只是调用方式不同。

兼容性说明： 本类依赖 BouncyCastle Provider，目标运行环境为 JDK 8 及以上版本。

  • Field Details

    • DEFAULT_USER_ID

      public static final String DEFAULT_USER_ID
      默认用户标识。

      当前库默认按公开资料里最常见的 16 字节用户标识处理， 便于与大多数 SM2 示例、测试向量和历史系统保持一致。

      See Also:

    • GM_2023_USER_ID

      @Deprecated public static final String GM_2023_USER_ID
      Deprecated.
      当前选项 Builder 会把空字符串映射为 DEFAULT_USER_ID， 因此该常量不能表达独立的空用户标识。请为协议显式约定非空 user ID。
      历史空用户标识常量。
      See Also:

    • CURVE_NAME

      public static final String CURVE_NAME
      SM2 标准曲线名称。
      See Also:

    • SM3_DIGEST_LENGTH

      public static final int SM3_DIGEST_LENGTH
      SM3 摘要长度，单位为字节。
      See Also:

  • Constructor Details

    • SM2

      public SM2()
      创建一个使用默认安全上下文的 SM2 实例。

      默认情况下会自动解析 Provider 和随机源，适合绝大多数直接调用场景。

    • SM2

      public SM2(GmSecurityContext securityContext)
      创建一个绑定指定安全上下文的 SM2 实例。

      绑定后，该实例的密钥生成、加密、签名和密钥交换会优先使用这里指定的 Provider 与随机源；当参数为 null 时，内部会自动回退到默认安全上下文。

      Parameters:
      securityContext - Provider 和随机源配置；传入 null 时回退为默认配置

  • Method Details

    • securityContext

      public GmSecurityContext securityContext()
      返回当前实例绑定的安全上下文。
      Returns:
      当前实例使用的安全上下文

    • generateKeyPair

      public SM2KeyPair generateKeyPair()
      生成一组 SM2 密钥，默认输出未压缩公钥。
      Returns:
      SM2 密钥对

    • generateKeyPair

      public SM2KeyPair generateKeyPair(boolean compressedPublicKey)
      生成一组 SM2 密钥。
      Parameters:
      compressedPublicKey - 是否输出压缩公钥
      Returns:
      SM2 密钥对

    • getPublicKeyFromPrivateKey

      public String getPublicKeyFromPrivateKey(String privateKeyHex, boolean compressed)
      根据私钥推导公钥。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      compressed - 是否输出压缩公钥
      Returns:
      公钥十六进制字符串

    • compressPublicKey

      public String compressPublicKey(String publicKeyHex)
      将未压缩公钥压缩编码。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      Returns:
      压缩公钥

    • decompressPublicKey

      public String decompressPublicKey(String publicKeyHex)
      将压缩公钥恢复为未压缩编码。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      Returns:
      未压缩公钥

    • encrypt

      public byte[] encrypt(String publicKeyHex, byte[] data)
      使用默认密文布局 C1C3C2 加密。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字节数组
      Returns:
      原始密文

    • encrypt

      public byte[] encrypt(String publicKeyHex, String data)
      使用 UTF-8 编码后的字符串进行加密。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字符串
      Returns:
      原始密文

    • encrypt

      public byte[] encrypt(String publicKeyHex, String data, Charset charset, SM2CipherMode mode)
      使用指定字符集编码字符串后进行加密。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字符串
      charset - 字符集；传入 null 时默认使用 UTF-8
      mode - 密文布局
      Returns:
      原始密文

    • encrypt

      public byte[] encrypt(String publicKeyHex, byte[] data, SM2CipherMode mode)
      使用指定密文布局加密。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字节数组
      mode - 密文布局，传入 null 时默认 C1C3C2
      Returns:
      原始密文

    • encryptHex

      public String encryptHex(String publicKeyHex, byte[] data)
      加密并输出十六进制密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字节数组
      Returns:
      十六进制密文

    • encryptHex

      public String encryptHex(String publicKeyHex, String data, SM2CipherMode mode)
      使用 UTF-8 编码后的字符串加密并输出十六进制密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字符串
      mode - 密文布局
      Returns:
      十六进制密文

    • encryptHex

      public String encryptHex(String publicKeyHex, String data, Charset charset, SM2CipherMode mode)
      使用指定字符集编码字符串后加密并输出十六进制密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字符串
      charset - 字符集；传入 null 时默认使用 UTF-8
      mode - 密文布局
      Returns:
      十六进制密文

    • encryptHex

      public String encryptHex(String publicKeyHex, byte[] data, SM2CipherMode mode)
      加密并输出十六进制密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字节数组
      mode - 密文布局
      Returns:
      十六进制密文

    • encryptBase64

      public String encryptBase64(String publicKeyHex, byte[] data)
      加密并输出 Base64 密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字节数组
      Returns:
      Base64 密文

    • encryptBase64

      public String encryptBase64(String publicKeyHex, String data, SM2CipherMode mode)
      使用 UTF-8 编码后的字符串加密并输出 Base64 密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字符串
      mode - 密文布局
      Returns:
      Base64 密文

    • encryptBase64

      public String encryptBase64(String publicKeyHex, String data, Charset charset, SM2CipherMode mode)
      使用指定字符集编码字符串后加密并输出 Base64 密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字符串
      charset - 字符集；传入 null 时默认使用 UTF-8
      mode - 密文布局
      Returns:
      Base64 密文

    • encryptBase64

      public String encryptBase64(String publicKeyHex, byte[] data, SM2CipherMode mode)
      加密并输出 Base64 密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字节数组
      mode - 密文布局
      Returns:
      Base64 密文

    • decrypt

      public byte[] decrypt(String privateKeyHex, byte[] ciphertext)
      使用默认密文布局 C1C3C2 解密。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 原始密文字节数组，支持自动识别 ASN.1 DER
      Returns:
      明文字节数组

    • decrypt

      public byte[] decrypt(String privateKeyHex, byte[] ciphertext, SM2CipherMode mode)
      使用指定密文布局解密。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 原始密文字节数组，支持自动识别 ASN.1 DER
      mode - 密文布局
      Returns:
      明文字节数组

    • decrypt

      public byte[] decrypt(String privateKeyHex, String ciphertext)
      解密十六进制或 Base64 形式的密文字符串。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 十六进制或 Base64 密文
      Returns:
      明文字节数组

    • decrypt

      public byte[] decrypt(String privateKeyHex, String ciphertext, SM2CipherMode mode)
      解密十六进制或 Base64 形式的密文字符串。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 十六进制或 Base64 密文
      mode - 密文布局
      Returns:
      明文字节数组

    • decryptToUtf8

      public String decryptToUtf8(String privateKeyHex, byte[] ciphertext, SM2CipherMode mode)
      使用 UTF-8 解码解密结果。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 原始密文字节数组
      mode - 密文布局
      Returns:
      明文字符串

    • decryptToUtf8

      public String decryptToUtf8(String privateKeyHex, String ciphertext, SM2CipherMode mode)
      使用 UTF-8 解码字符串形式的密文解密结果。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 十六进制或 Base64 密文
      mode - 密文布局
      Returns:
      明文字符串

    • decryptToString

      public String decryptToString(String privateKeyHex, byte[] ciphertext, Charset charset, SM2CipherMode mode)
      使用指定字符集解码解密结果。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 原始密文字节数组
      charset - 字符集；传入 null 时默认使用 UTF-8
      mode - 密文布局
      Returns:
      明文字符串

    • sign

      public byte[] sign(String privateKeyHex, byte[] message)
      使用默认签名参数签名，默认输出 RAW r||s。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      Returns:
      签名字节数组

    • sign

      public byte[] sign(String privateKeyHex, String message, SM2SignOptions options)
      对 UTF-8 文本签名。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名参数
      Returns:
      签名字节数组

    • sign

      public byte[] sign(String privateKeyHex, String message, Charset charset, SM2SignOptions options)
      对指定字符集编码后的文本签名。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      charset - 字符集；传入 null 时默认使用 UTF-8
      options - 签名参数
      Returns:
      签名字节数组

    • sign

      public byte[] sign(String privateKeyHex, byte[] message, SM2SignOptions options)
      使用指定签名参数签名。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名参数，传入 null 时使用默认值
      Returns:
      签名字节数组

    • signHex

      public String signHex(String privateKeyHex, byte[] message, SM2SignOptions options)
      签名并输出十六进制结果。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名参数
      Returns:
      十六进制签名

    • signHex

      public String signHex(String privateKeyHex, String message, SM2SignOptions options)
      对 UTF-8 文本签名并输出十六进制结果。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名参数
      Returns:
      十六进制签名

    • signHex

      public String signHex(String privateKeyHex, String message, Charset charset, SM2SignOptions options)
      对指定字符集编码后的文本签名并输出十六进制结果。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      charset - 字符集；传入 null 时默认使用 UTF-8
      options - 签名参数
      Returns:
      十六进制签名

    • signBase64

      public String signBase64(String privateKeyHex, byte[] message, SM2SignOptions options)
      签名并输出 Base64 结果。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名参数
      Returns:
      Base64 签名

    • signBase64

      public String signBase64(String privateKeyHex, String message, SM2SignOptions options)
      对 UTF-8 文本签名并输出 Base64 结果。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名参数
      Returns:
      Base64 签名

    • signBase64

      public String signBase64(String privateKeyHex, String message, Charset charset, SM2SignOptions options)
      对指定字符集编码后的文本签名并输出 Base64 结果。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      charset - 字符集；传入 null 时默认使用 UTF-8
      options - 签名参数
      Returns:
      Base64 签名

    • signWithoutZ

      @Deprecated public byte[] signWithoutZ(String privateKeyHex, byte[] message, SM2SignatureFormat signatureFormat)
      Deprecated.
      非标准旧协议兼容入口；新协议应使用标准 SM3(Z || M) 签名
      按旧 no-Z 约定计算 e = SM3(M) 后签名。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      signatureFormat - 输出签名格式
      Returns:
      签名字节数组

    • signDigest

      public byte[] signDigest(String privateKeyHex, byte[] eHash, SM2SignatureFormat signatureFormat)
      对外部已计算好的 e 值直接签名。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      eHash - 已计算好的 e 值
      signatureFormat - 输出签名格式
      Returns:
      签名字节数组

    • verify

      public boolean verify(String publicKeyHex, byte[] message, byte[] signature)
      使用默认验签参数验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 签名字节数组，支持 RAW/DER 自动识别
      Returns:
      验签结果

    • verify

      public boolean verify(String publicKeyHex, byte[] message, byte[] signature, SM2VerifyOptions options)
      使用指定验签参数验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 签名字节数组，支持 RAW/DER 自动识别
      options - 验签参数
      Returns:
      验签结果

    • verify

      public boolean verify(String publicKeyHex, byte[] message, String signature, SM2VerifyOptions options)
      验签十六进制或 Base64 形式的签名字符串。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 十六进制或 Base64 形式的签名
      options - 验签参数
      Returns:
      验签结果

    • verify

      public boolean verify(String publicKeyHex, String message, byte[] signature, SM2VerifyOptions options)
      对 UTF-8 文本验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 签名字节数组
      options - 验签参数
      Returns:
      验签结果

    • verify

      public boolean verify(String publicKeyHex, String message, Charset charset, byte[] signature, SM2VerifyOptions options)
      对指定字符集编码后的文本验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      charset - 字符集；传入 null 时默认使用 UTF-8
      signature - 签名字节数组
      options - 验签参数
      Returns:
      验签结果

    • verify

      public boolean verify(String publicKeyHex, String message, String signature, SM2VerifyOptions options)
      对 UTF-8 文本和字符串形式签名进行验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 十六进制或 Base64 形式的签名
      options - 验签参数
      Returns:
      验签结果

    • verifyWithoutZ

      @Deprecated public boolean verifyWithoutZ(String publicKeyHex, byte[] message, byte[] signature, SM2SignatureInputFormat signatureFormat)
      Deprecated.
      非标准旧协议兼容入口；新协议应使用标准 SM3(Z || M) 验签
      按旧 no-Z 约定计算 e = SM3(M) 后验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 签名字节数组
      signatureFormat - 签名输入格式
      Returns:
      验签结果

    • verifyDigest

      public boolean verifyDigest(String publicKeyHex, byte[] eHash, byte[] derSignature)
      对外部提供的 e 值和 DER 签名直接验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      eHash - 已计算好的 e 值
      derSignature - ASN.1 DER 签名
      Returns:
      验签结果

    • computeZ

      public byte[] computeZ(String userId, String publicKeyHex)
      计算 SM2 Z 值。
      Parameters:
      userId - 用户标识，传入 null 时使用默认值
      publicKeyHex - 公钥十六进制字符串
      Returns:
      Z 值

    • computeE

      public byte[] computeE(String publicKeyHex, byte[] message, String userId, boolean skipZComputation)
      计算 SM2 中用于签名的 e 值。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      userId - 用户标识
      skipZComputation - 是否跳过 Z 计算
      Returns:
      e 值

    • computeE

      public byte[] computeE(String publicKeyHex, String message, Charset charset, String userId, boolean skipZComputation)
      使用指定字符集编码消息后计算 SM2 的 e 值。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      charset - 字符集；传入 null 时默认使用 UTF-8
      userId - 用户标识
      skipZComputation - 是否跳过 Z 计算
      Returns:
      e 值

    • computeEWithoutZ

      @Deprecated public byte[] computeEWithoutZ(byte[] message)
      Deprecated.
      非标准旧协议兼容入口；需要预计算 e 时应明确实现协议规定的摘要过程
      按旧 no-Z 约定计算 e = SM3(M)。
      Parameters:
      message - 原文消息
      Returns:
      e 值

    • computeEWithoutZ

      @Deprecated public byte[] computeEWithoutZ(String message, Charset charset)
      Deprecated.
      非标准旧协议兼容入口；需要预计算 e 时应明确实现协议规定的摘要过程
      使用指定字符集编码消息后，按旧 no-Z 约定计算 e = SM3(M)。
      Parameters:
      message - 原文消息
      charset - 字符集；传入 null 时默认使用 UTF-8
      Returns:
      e 值

    • keyExchange

      public byte[] keyExchange(String selfStaticPrivateKeyHex, String selfEphemeralPrivateKeyHex, String peerStaticPublicKeyHex, String peerEphemeralPublicKeyHex, SM2KeyExchangeOptions options)
      执行 SM2 密钥交换。
      Parameters:
      selfStaticPrivateKeyHex - 己方静态私钥
      selfEphemeralPrivateKeyHex - 己方临时私钥
      peerStaticPublicKeyHex - 对方静态公钥
      peerEphemeralPublicKeyHex - 对方临时公钥
      options - 交换参数
      Returns:
      共享密钥

    • keyExchangeWithConfirmation

      public SM2KeyExchangeResult keyExchangeWithConfirmation(String selfStaticPrivateKeyHex, String selfEphemeralPrivateKeyHex, String peerStaticPublicKeyHex, String peerEphemeralPublicKeyHex, SM2KeyExchangeOptions options)
      执行带确认信息的 SM2 密钥交换。
      Parameters:
      selfStaticPrivateKeyHex - 己方静态私钥
      selfEphemeralPrivateKeyHex - 己方临时私钥
      peerStaticPublicKeyHex - 对方静态公钥
      peerEphemeralPublicKeyHex - 对方临时公钥
      options - 交换参数
      Returns:
      共享密钥和确认标签

    • confirmResponder

      public boolean confirmResponder(byte[] expectedS2, byte[] confirmationTag)
      常量时间比较响应方确认标签。
      Parameters:
      expectedS2 - 本地计算出的 S2
      confirmationTag - 对端返回的确认标签
      Returns:
      一致时返回 true