Package cn.gmkit.sm2

Class SM2Util

java.lang.Object
cn.gmkit.sm2.SM2Util
public final class SM2Util extends Object
SM2 静态工具入口。

这个类提供与 SM2 对象式入口等价的静态方法，适合以下场景： 老项目中已经大量使用工具类调用方式，或调用链本身不需要显式持有实例。

除了调用风格不同外，静态接口与对象式接口的行为、默认值和异常语义保持一致。 当需要显式绑定 GmSecurityContext 时，可使用带上下文参数的静态重载。

  • Field Details

    • DEFAULT_USER_ID

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

    • GM_2023_USER_ID

      @Deprecated public static final String GM_2023_USER_ID
      Deprecated.
      当前选项 Builder 会把空字符串映射为兼容默认身份，不能表达独立的空用户标识
      历史空用户标识常量。
      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:

  • Method Details

    • generateKeyPair

      public static SM2KeyPair generateKeyPair()
      生成一组未压缩公钥形式的 SM2 密钥对。
      Returns:
      SM2 密钥对

    • generateKeyPair

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

    • generateKeyPair

      public static SM2KeyPair generateKeyPair(GmSecurityContext securityContext)
      使用指定安全上下文生成一组未压缩公钥形式的 SM2 密钥对。
      Parameters:
      securityContext - 安全上下文
      Returns:
      SM2 密钥对

    • generateKeyPair

      public static SM2KeyPair generateKeyPair(boolean compressedPublicKey, GmSecurityContext securityContext)
      使用指定安全上下文生成一组 SM2 密钥对。
      Parameters:
      compressedPublicKey - 是否输出压缩公钥
      securityContext - 安全上下文
      Returns:
      SM2 密钥对

    • getPublicKeyFromPrivateKey

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

    • compressPublicKey

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

    • decompressPublicKey

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

    • encrypt

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

    • encrypt

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

    • encrypt

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

    • encrypt

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

    • encrypt

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

    • encryptHex

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

    • encryptHex

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

    • encryptHex

      public static String encryptHex(String publicKeyHex, byte[] data, SM2CipherMode mode, GmSecurityContext securityContext)
      使用指定安全上下文加密并输出十六进制密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字节数组
      mode - 密文布局；传入 null 时默认使用 C1C3C2
      securityContext - 安全上下文
      Returns:
      十六进制密文

    • encryptHex

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

    • encryptHex

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

    • encryptBase64

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

    • encryptBase64

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

    • encryptBase64

      public static String encryptBase64(String publicKeyHex, byte[] data, SM2CipherMode mode, GmSecurityContext securityContext)
      使用指定安全上下文加密并输出 Base64 密文。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      data - 明文字节数组
      mode - 密文布局；传入 null 时默认使用 C1C3C2
      securityContext - 安全上下文
      Returns:
      Base64 密文

    • encryptBase64

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

    • encryptBase64

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

    • decrypt

      public static byte[] decrypt(String privateKeyHex, byte[] ciphertext)
      使用默认密文布局解密字节密文。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 密文字节数组
      Returns:
      明文字节数组

    • decrypt

      public static byte[] decrypt(String privateKeyHex, byte[] ciphertext, SM2CipherMode mode)
      使用指定密文布局解密字节密文。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 密文字节数组
      mode - 密文布局；传入 null 时默认使用 C1C3C2
      Returns:
      明文字节数组

    • decrypt

      public static byte[] decrypt(String privateKeyHex, String ciphertext)
      自动识别十六进制或 Base64 字符串密文并解密。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 十六进制或 Base64 字符串密文
      Returns:
      明文字节数组

    • decrypt

      public static byte[] decrypt(String privateKeyHex, String ciphertext, SM2CipherMode mode)
      使用指定密文布局解密字符串形式密文。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 十六进制或 Base64 字符串密文
      mode - 密文布局；传入 null 时默认使用 C1C3C2
      Returns:
      明文字节数组

    • decryptToUtf8

      public static String decryptToUtf8(String privateKeyHex, byte[] ciphertext, SM2CipherMode mode)
      解密字节密文并按 UTF-8 解码。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 密文字节数组
      mode - 密文布局；传入 null 时默认使用 C1C3C2
      Returns:
      UTF-8 字符串

    • decryptToUtf8

      public static String decryptToUtf8(String privateKeyHex, String ciphertext, SM2CipherMode mode)
      解密字符串形式密文并按 UTF-8 解码。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      ciphertext - 十六进制或 Base64 字符串密文
      mode - 密文布局；传入 null 时默认使用 C1C3C2
      Returns:
      UTF-8 字符串

    • decryptToString

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

    • sign

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

    • sign

      public static byte[] sign(String privateKeyHex, String message, SM2SignOptions options)
      对 UTF-8 字符串进行签名。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名选项；传入 null 时使用默认选项
      Returns:
      签名字节数组

    • sign

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

    • signHex

      public static String signHex(String privateKeyHex, byte[] message, SM2SignOptions options)
      对消息签名并输出十六进制字符串。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名选项；传入 null 时使用默认选项
      Returns:
      十六进制签名

    • signHex

      public static String signHex(String privateKeyHex, String message, SM2SignOptions options)
      对 UTF-8 字符串签名并输出十六进制字符串。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名选项；传入 null 时使用默认选项
      Returns:
      十六进制签名

    • signHex

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

    • signBase64

      public static String signBase64(String privateKeyHex, byte[] message, SM2SignOptions options)
      对消息签名并输出 Base64 字符串。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名选项；传入 null 时使用默认选项
      Returns:
      Base64 签名

    • signBase64

      public static String signBase64(String privateKeyHex, String message, SM2SignOptions options)
      对 UTF-8 字符串签名并输出 Base64 字符串。
      Parameters:
      privateKeyHex - 私钥十六进制字符串
      message - 原文消息
      options - 签名选项；传入 null 时使用默认选项
      Returns:
      Base64 签名

    • signBase64

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

    • signWithoutZ

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

    • signDigest

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

    • signDigest

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

    • verify

      public static boolean verify(String publicKeyHex, byte[] message, byte[] signature, SM2VerifyOptions options)
      对字节消息和字节签名进行验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 签名字节数组
      options - 验签选项；传入 null 时使用默认选项
      Returns:
      验签结果

    • verify

      public static boolean verify(String publicKeyHex, byte[] message, String signature, SM2VerifyOptions options)
      对字节消息和字符串签名进行验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 十六进制或 Base64 形式签名
      options - 验签选项；传入 null 时使用默认选项
      Returns:
      验签结果

    • verify

      public static boolean verify(String publicKeyHex, String message, byte[] signature, SM2VerifyOptions options)
      对 UTF-8 字符串消息和字节签名进行验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 签名字节数组
      options - 验签选项；传入 null 时使用默认选项
      Returns:
      验签结果

    • verify

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

    • verify

      public static boolean verify(String publicKeyHex, String message, String signature, SM2VerifyOptions options)
      对 UTF-8 字符串消息和字符串签名进行验签。
      Parameters:
      publicKeyHex - 公钥十六进制字符串
      message - 原文消息
      signature - 十六进制或 Base64 形式签名
      options - 验签选项；传入 null 时使用默认选项
      Returns:
      验签结果

    • verifyWithoutZ

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

    • computeZ

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

    • computeE

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

    • computeE

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

    • computeEWithoutZ

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

    • computeEWithoutZ

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

    • keyExchange

      public static byte[] keyExchange(String selfStaticPrivateKeyHex, String selfEphemeralPrivateKeyHex, String peerStaticPublicKeyHex, String peerEphemeralPublicKeyHex, SM2KeyExchangeOptions options)
      执行 SM2 密钥交换。
      Parameters:
      selfStaticPrivateKeyHex - 己方静态私钥
      selfEphemeralPrivateKeyHex - 己方临时私钥
      peerStaticPublicKeyHex - 对方静态公钥
      peerEphemeralPublicKeyHex - 对方临时公钥
      options - 协商参数；传入 null 时使用默认选项
      Returns:
      共享密钥

    • keyExchangeWithConfirmation

      public static SM2KeyExchangeResult keyExchangeWithConfirmation(String selfStaticPrivateKeyHex, String selfEphemeralPrivateKeyHex, String peerStaticPublicKeyHex, String peerEphemeralPublicKeyHex, SM2KeyExchangeOptions options)
      执行带确认标签的 SM2 密钥交换。
      Parameters:
      selfStaticPrivateKeyHex - 己方静态私钥
      selfEphemeralPrivateKeyHex - 己方临时私钥
      peerStaticPublicKeyHex - 对方静态公钥
      peerEphemeralPublicKeyHex - 对方临时公钥
      options - 协商参数；传入 null 时使用默认选项
      Returns:
      包含共享密钥与确认标签的结果对象

    • confirmResponder

      public static boolean confirmResponder(byte[] expectedS2, byte[] confirmationTag)
      比较对端确认标签是否匹配。
      Parameters:
      expectedS2 - 期望的 S2 标签
      confirmationTag - 实际返回的确认标签
      Returns:
      常量时间比较结果