ASP.NET中使用USB令牌(X509证书)实现JSON文件数字签名

核心实现逻辑说明 #

USB令牌中的X509证书私钥一般为硬件保护、不可导出状态，插入设备后证书会自动注册到Windows系统证书存储区，不需要手动提取私钥，直接通过系统加密API调用硬件完成签名运算即可，安全性符合电子签名合规要求。

步骤1：从系统存储中定位USB令牌内的签名证书 #

优先通过证书指纹精准匹配目标证书，避免主题名重复导致的证书选错问题，代码如下：

using System.Security.Cryptography.X509Certificates;

// 打开当前用户个人证书存储（只读模式）
using var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadOnly | OpenFlags.OpenExistingOnly);

// 替换为你自己证书的指纹，可在证书管理控制台查看详情获取
var targetCert = store.Certificates
    .Find(X509FindType.FindByThumbprint, "替换为你的证书指纹", true)
    .OfType<X509Certificate2>()
    .FirstOrDefault(cert => cert.HasPrivateKey);

store.Close();

if (targetCert == null)
{
    throw new InvalidOperationException("未找到可用签名证书，请确认USB令牌已插入、驱动安装正常且证书在有效期内");
}

部署注意事项：如果是IIS托管ASP.NET应用，需要将对应应用程序池的「加载用户配置文件」属性设置为True，否则无法读取当前用户存储下的USB令牌证书；如果使用本地计算机证书存储，需要给应用池运行账号授予对应证书私钥的读取权限。

步骤2：规范化待签名JSON内容 #

JSON格式存在空格、缩进、字段顺序的灵活度，如果不对原始内容做统一规范化，后续验签会因为格式差异失败，必须固定序列化规则：

using System.Text.Json;
using System.Text.Json.Nodes;
using System.Text;

// 读取原始输入JSON文件
var rawJsonContent = await File.ReadAllTextAsync("输入JSON文件路径.json", Encoding.UTF8);
var rawDataNode = JsonNode.Parse(rawJsonContent) ?? throw new InvalidDataException("输入JSON格式非法");

// 固定序列化配置：紧凑无缩进、UTF8编码、严格转义规则，作为签名的基准输入
var strictSerializeOpts = new JsonSerializerOptions
{
    WriteIndented = false,
    Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping
};
var signPayload = rawDataNode.ToJsonString(strictSerializeOpts);
var signPayloadBytes = Encoding.UTF8.GetBytes(signPayload);

步骤3：调用硬件完成签名并组装输出结构 #

签名运算会直接在USB令牌硬件内部执行，私钥不会进入应用内存，符合硬件数字签名的安全要求，最后按照目标格式组装输出JSON：

using System.Security.Cryptography;

byte[] signResultBytes;
// 这里以RSA+SHA256签名算法为例，国密场景替换为SM2对应实现即可
using (var rsaKey = targetCert.GetRSAPrivateKey())
{
    if (rsaKey == null) throw new NotSupportedException("当前证书不支持RSA签名，请确认证书类型");
    signResultBytes = rsaKey.SignData(
        signPayloadBytes, 
        HashAlgorithmName.SHA256, 
        RSASignaturePadding.Pkcs1);
}

// 组装最终输出结构，原始数据放在data节点，签名信息放在signature节点
var signedOutput = new JsonObject
{
    ["data"] = rawDataNode,
    ["signature"] = new JsonObject
    {
        ["signValue"] = Convert.ToBase64String(signResultBytes),
        ["certSerialNo"] = targetCert.SerialNumber,
        ["signAlgorithm"] = "SHA256withRSA",
        ["signTime"] = DateTimeOffset.Now.LocalDateTime.ToString("yyyy-MM-dd HH:mm:ss")
    }
};

// 写入输出文件，保留缩进方便阅读
var outputJson = signedOutput.ToJsonString(new JsonSerializerOptions{WriteIndented = true});
await File.WriteAllTextAsync("签名后输出文件路径.json", outputJson, Encoding.UTF8);

常见踩坑提示 #

• 不要尝试导出USB令牌的私钥：绝大多数合规USB令牌的私钥被硬件标记为不可导出，强行调用私钥导出方法会直接抛出异常，直接通过证书句柄调用签名方法即可。
• 编码统一：待签名内容全程使用UTF8编码，不要混用GBK、GB2312等编码，否则跨平台、跨系统验签必然失败。
• 驱动适配：部分厂商的USB令牌需要安装专属CSP/CNG驱动才能被系统加密API识别，部署前先在服务器本地测试证书可正常调用签名。
• 验签逻辑配套：如果需要后续验签，要和签名端使用完全一致的规范化规则、哈希算法、填充模式，否则会出现签名有效但验签不通过的问题。
• IIS部署权限：不要用Local Service之类的低权限账号运行应用池，这类账号默认没有访问USB硬件加密模块的权限，推荐用专用的本地服务账号运行，并授予对应证书私钥的读取权限。

内容的提问来源于stack exchange，提问作者Sunil Yadav