签名说明文档

Signature Specification - MD5 & SM3withSM2

一、下单接口 - MD5 签名
接口名称
统一下单接口
签名算法
MD5
signType 值
MD5
参与签名的参数
参数名类型必填描述
outTradeNostring是商户订单号
merchantNostring是商户号
productCodestring是产品编码
totalFeeint是订单金额(分)
signTypestring是签名类型:MD5
timestampstring是毫秒时间戳
tradeTypeint否交易类型:1-代收,2-代付
notifyUrlstring是异步通知地址
clientIpstring否终端IP
nonceStrstring否随机字符串
attachstring否附加数据
签名步骤
1
参数排序
所有参数(排除 sign)按参数名 ASCII 码升序排序
2
拼接字符串
将排序后的参数按 key=value 格式用 & 连接
3
拼接密钥
末尾拼接 &key=商户密钥(商户密钥由平台分配)
4
MD5 加密
计算 MD5(32位小写)
签名示例代码(C#)
public static string GenerateMd5Sign(Dictionary<string, string> dict, string merchantKey)
{
    // 1. 过滤 sign 字段
    dict.Remove("sign");
    
    // 2. ASCII 升序排序
    var sortedDict = dict.OrderBy(x => x.Key);
    
    // 3. 拼接字符串
    string signStr = string.Join("&", sortedDict.Select(x => $"{x.Key}={x.Value}"));
    
    // 4. 拼接密钥
    signStr = $"{signStr}&key={merchantKey}";
    
    // 5. MD5 加密(32位小写)
    using var md5 = MD5.Create();
    var bytes = md5.ComputeHash(Encoding.UTF8.GetBytes(signStr));
    return BitConverter.ToString(bytes).Replace("-", "").ToLower();
}
待签名示例
merchantNo=M10001&nonceStr=abc123&notifyUrl=https://merchant.com/notify&outTradeNo=202405180001&productCode=ALIPAY_WAP&signType=MD5&timestamp=1716001234567&totalFee=100&tradeType=1&key=your_merchant_key
二、回调接口 - 国密 SM3withSM2 签名
接口名称
异步通知商户接口
签名算法
SM3withSM2
signType 值
SM3withSM2
签名格式
ASN.1 DER → Base64
参与签名的参数
参数名类型必填描述
merchantIdstring是商户ID
outTradeNostring是商户订单号
systemOrderNostring是平台系统订单号
amountstring是订单金额(分)
statestring是订单状态:1-成功,2-失败,3-处理中
successTimestring是成功时间(yyyy-MM-dd HH:mm:ss)
timestampstring是毫秒时间戳
nonceStrstring是随机字符串(16位)
attachstring否附加数据
signTypestring是签名类型:SM3withSM2
签名步骤
1
参数排序
所有参数(排除 sign)按参数名 ASCII 码升序排序
2
拼接字符串
将排序后的参数按 key=value 格式用 & 连接
3
生成待签名原文
将拼接后的字符串转换为 UTF-8 字节数组
4
国密签名
使用 SM3withSM2 算法,传入用户ID(1234567812345678)和私钥进行签名,输出 ASN.1 DER 格式 签名
5
Base64 编码
将 ASN.1 DER 格式签名进行 Base64 编码,得到最终的 sign 值
签名示例代码(C#)
using Org.BouncyCastle.Crypto;
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.Security;
using System.Text;

/// <summary>
/// 国密 SM3withSM2 签名(ASN.1 DER 格式)
/// </summary>
public static byte[] SignSm3WithSm2Asn1Rs(byte[] msg, byte[] userId, AsymmetricKeyParameter privateKey)
{
    ISigner signer = SignerUtilities.GetSigner("SM3withSM2");
    signer.Init(true, new ParametersWithID(privateKey, userId));
    signer.BlockUpdate(msg, 0, msg.Length);
    byte[] sig = signer.GenerateSignature();
    return sig; // ASN.1 DER 格式
}

/// <summary>
/// 生成签名(完整流程)
/// </summary>
public static string GenerateSm2Sign(Dictionary<string, string> param, AsymmetricKeyParameter privateKey)
{
    // 1. 过滤 sign 字段并按 key 排序
    var sortedDict = param.Where(x => x.Key != "sign").OrderBy(x => x.Key);
    
    // 2. 拼接参数字符串
    string signStr = string.Join("&", sortedDict.Select(x => $"{x.Key}={x.Value}"));
    
    // 3. 转为 UTF-8 字节数组
    byte[] msg = Encoding.UTF8.GetBytes(signStr);
    
    // 4. 用户ID(固定值,与微信支付官方一致)
    byte[] userId = Encoding.UTF8.GetBytes("1234567812345678");
    
    // 5. 国密签名(ASN.1 DER 格式)
    byte[] signature = SignSm3WithSm2Asn1Rs(msg, userId, privateKey);
    
    // 6. Base64 编码
    return Convert.ToBase64String(signature);
}
验签示例代码(C#)
/// <summary>
/// 国密 SM3withSM2 验签(ASN.1 DER 格式)
/// </summary>
public static bool VerifySm3WithSm2Asn1Rs(byte[] msg, byte[] userId, byte[] signature, AsymmetricKeyParameter publicKey)
{
    ISigner signer = SignerUtilities.GetSigner("SM3withSM2");
    signer.Init(false, new ParametersWithID(publicKey, userId));
    signer.BlockUpdate(msg, 0, msg.Length);
    return signer.VerifySignature(signature);
}

/// <summary>
/// 完整验签流程
/// </summary>
public static bool VerifySm2Notify(Dictionary<string, string> param, AsymmetricKeyParameter publicKey)
{
    if (!param.ContainsKey("sign")) return false;
    
    // 1. Base64 解码签名
    byte[] signature = Convert.FromBase64String(param["sign"]);
    
    // 2. 构建待签名原文
    var sortedDict = param.Where(x => x.Key != "sign").OrderBy(x => x.Key);
    string signStr = string.Join("&", sortedDict.Select(x => $"{x.Key}={x.Value}"));
    byte[] msg = Encoding.UTF8.GetBytes(signStr);
    
    // 3. 用户ID(与签名时一致)
    byte[] userId = Encoding.UTF8.GetBytes("1234567812345678");
    
    // 4. 验签
    return VerifySm3WithSm2Asn1Rs(msg, userId, signature, publicKey);
}
待签名示例
amount=100&attach=测试订单&merchantId=10001&nonceStr=abc123def456&outTradeNo=202405180001&signType=SM3withSM2&state=1&successTime=2024-05-18 15:30:00&systemOrderNo=T202405180001234&timestamp=1716015000000
三、两种签名方式对比
对比项下单接口(MD5)回调接口(SM3withSM2)
签名算法MD5国密 SM3withSM2
signType 值MD5SM3withSM2
密钥类型对称密钥(商户密钥)非对称密钥(私钥签名、公钥验签)
签名格式32位十六进制字符串ASN.1 DER → Base64
用户ID不涉及固定值:1234567812345678
拼接密钥末尾拼接 &key=xxx不需要拼接密钥
安全性较低较高(国密标准)
四、注意事项
⚠️ 重要提醒
  • 下单接口(MD5):所有字段(除sign外)参与签名,末尾需拼接 &key=商户密钥,最终输出32位小写MD5
  • 回调接口(SM3withSM2):所有字段(除sign外)参与签名,不需要拼接密钥,使用私钥签名,输出 ASN.1 DER 格式后 Base64 编码
  • 用户ID:国密签名使用固定值 1234567812345678
  • 参数排序:两种签名方式均按参数名 ASCII 码升序排序
  • 空值处理:参数值为空时不参与签名
  • 字符编码:统一使用 UTF-8