Interface SignGenerator

All Known Implementing Classes:
HmacSignGenerator, RsaSignGenerator, Sm2SignGenerator, Sm3SignGenerator
public interface SignGenerator
签名生成器接口

用于生成和验证请求签名

实现类： 1. HmacSignGenerator：HMAC-SHA256签名生成器（对称） 2. Sm2SignGenerator：国密SM2签名生成器（非对称） 3. RsaSignGenerator：RSA签名生成器（非对称）

Author:
Kerbores(kerbores@riemann.tech)

  • Method Details

    • buildSignContent

      default String buildSignContent(Map<String,String> params, String timestamp, String requestPath, String nonce)
      构造待签名内容（规范化）

      各算法共用同一套内容规范化规则，仅最后的「签名/哈希」步骤不同（HMAC 用密钥，SM2/RSA 用私钥）。 规范化组成（按字典序排序后连接）： 1. 请求参数的SHA-256摘要（paramsMd5，字段名沿用既有结构兼容） 2. 时间戳（timestamp，非空时） 3. 请求路径（requestPath，非空时） 4. 随机字符串（nonce，非空时）

      Parameters:
      params - 业务参数
      timestamp - 时间戳（秒）
      requestPath - 请求路径
      nonce - 随机字符串
      Returns:
      规范化后的待签名字符串

    • calculateParamsMd5

      default String calculateParamsMd5(Map<String,String> params)
      计算请求参数的SHA-256摘要（十六进制）

      原为 MD5 预哈希，2026-09 安全评审（M1）升级为 SHA-256，消除签名安全路径上的弱原语。 该摘要仅作为参数字符串绑定的非安全指纹，真正的完整性仍由 HMAC-SHA256（强 MAC）保证； 字段名沿用 paramsMd5 以保留既有签名结构兼容。

      Parameters:
      params - 请求参数
      Returns:
      SHA-256 摘要（十六进制）

    • bytesToHex

      default String bytesToHex(byte[] bytes)
      字节数组转十六进制
      Parameters:
      bytes - 字节数组
      Returns:
      十六进制字符串

    • generate

      String generate(Map<String,String> params, String secret)
      生成签名

      签名生成流程： 1. 按ASCII排序参数 2. 拼接成 key1=value1&key2=value2 格式 3. 在末尾追加密钥 4. 计算哈希值

      Parameters:
      params - 业务参数（已过滤空 * @param secret 密钥
      Returns:
      签名字符串（十六进制）

    • generate

      default String generate(Map<String,String> params, String secret, String timestamp, String requestPath, String nonce)
      生成签名（完整参数）

      签名内容组成（按字典序排序后连接）： 1. 请求参数的SHA-256摘要（paramsMd5，字段名沿用既有结构兼容） 2. 应用密钥（appSecret） 3. 时间戳（timestamp） 4. 请求路径（requestPath） 5. 随机字符串（nonce）

      Parameters:
      params - 业务参数（已过滤空值）
      secret - 密钥
      timestamp - 时间戳（秒）
      requestPath - 请求路径
      nonce - 随机字符串
      Returns:
      签名字符串（十六进制）

    • verify

      boolean verify(Map<String,String> params, String sign, String secret)
      验证签名
      Parameters:
      params - 请求参数
      sign - 签名值
      secret - 密钥
      Returns:
      是否验证通过

    • verify

      default boolean verify(Map<String,String> params, String sign, String secret, String timestamp, String requestPath, String nonce)
      验证签名（完整参数）
      Parameters:
      params - 请求参数
      sign - 签名值
      secret - 密钥
      timestamp - 时间戳（秒）
      requestPath - 请求路径
      nonce - 随机字符串
      Returns:
      是否验证通过

    • getAlgorithm

      SignAlgorithm getAlgorithm()
      获取支持的算法
      Returns:
      ical算法

    • sign

      default String sign(String content, PrivateKey privateKey)
      使用密钥对象签名（非对称算法专用）

      对称算法（HMAC）不需要密钥对象，默认抛 UnsupportedOperationException； 非对称算法（SM2/RSA）应覆盖此方法接收私钥。

      Parameters:
      content - 待签名内容（已规范化）
      privateKey - 私钥
      Returns:
      签名值（Base64 或 Hex 字符串，由实现决定）

    • verify

      default boolean verify(String content, String signature, PublicKey publicKey)
      使用密钥对象验签（非对称算法专用）

      对称算法（HMAC）不需要密钥对象，默认抛 UnsupportedOperationException； 非对称算法（SM2/RSA）应覆盖此方法接收公钥。

      Parameters:
      content - 待验签内容（已规范化）
      signature - 签名值
      publicKey - 公钥
      Returns:
      是否验证通过