System.Security.Cryptography.Xml.SignedXml 类

2025-06-19

本文提供了此 API 参考文档的补充说明。

此类 SignedXml 是万维网联盟（W3C） XML 签名语法和处理规范的 .NET 实现，也称为 XMLDSIG （XML 数字签名）。 XMLDSIG 是一种基于标准的可互作方式，用于对 XML 文档或可从统一资源标识符（URI）寻址的所有或部分 XML 文档或其他数据进行签名和验证。

SignedXml每当需要以标准方式在应用程序或组织之间共享签名的 XML 数据时，请使用该类。使用此类签名的任何数据都可以通过符合 W3C 规范的 XMLDSIG 实现进行验证。

类 SignedXml 允许创建以下三种类型的 XML 数字签名：

签名类型	DESCRIPTION
信封签名	签名包含在正在签名的 XML 元素中。
封装签名	签名的 XML 被包含在 `<Signature>` 元素中。
内部分离签名	签名和签名 XML 位于同一文档中，但两个元素均不包含另一个元素。

还有第四种签名称为外部分离签名，即数据和签名位于单独的 XML 文档中。 SignedXml 类不支持外部分离签名。

XML 签名的结构

XMLDSIG 创建一个 <Signature> 元素，其中包含 XML 文档的数字签名或其他可从 URI 寻址的数据。该 <Signature> 元素可以选择包含有关在何处查找密钥的信息，该密钥将验证签名以及用于签名的加密算法。基本结构如下所示：

<Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
      <Reference URI="">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
        <DigestValue>Base64EncodedValue==</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>AnotherBase64EncodedValue===</SignatureValue>
</Signature>

此结构的主要部分包括：

<CanonicalizationMethod> 元素

指定将 Signature 元素从 XML/文本重写为字节用于签名验证的规则。在 .NET 中，默认值是 http://www.w3.org/TR/2001/REC-xml-c14n-20010315，用于标识可信算法。此元素由 SignedInfo.CanonicalizationMethod 属性表示。
<SignatureMethod> 元素

指定用于生成签名和验证的算法，该算法应用于元素 <Signature> 以生成值 <SignatureValue>。在前面的示例中，该值 http://www.w3.org/2000/09/xmldsig#rsa-sha1 标识 RSA PKCS1 SHA-1 签名。由于 SHA-1 冲突问题，Microsoft建议基于 SHA-256 或更高版本的安全模型。此元素由 SignatureMethod 属性表示。
<SignatureValue> 元素

指定 <Signature> 元素的加密签名。如果无法验证签名，那么<Signature> 块的某些部分可能已被篡改，文档因此被视为无效。只要 <CanonicalizationMethod> 该值可信，此值就高度抵御篡改。此元素由 SignatureValue 属性表示。
URI元素的<Reference>属性

使用 URI 引用指定数据对象。此属性由 Reference.Uri 属性表示。
- 不指定 URI 属性（即将 Reference.Uri 属性设置为 null）意味着接收应用程序应知道对象的标识。在大多数情况下，null URI 将引发异常。除非应用程序与需要 URI 的协议进行互作，否则不要使用 null URI。
- 将 URI 属性设置为空字符串表示文档的根元素正在签名，这是一种信封签名形式。
- URI如果属性值以 #开头，则该值必须解析为当前文档中的元素。此表单可以与任何受支持的签名类型（信封签名、封装签名或内部分离签名）一起使用。
- 任何其他情况均被视为外部资源分离签名，且不被 SignedXml 类支持。
<Transforms> 元素

包含一个 <Transform> 元素的有序列表，这些元素描述了签名者获取经过摘要处理的数据对象的方式。转换算法类似于规范化方法，但它不是重写<Signature>元素，而是重写元素URI的<Reference>属性所标识的内容。该 <Transforms> 元素由 TransformChain 类表示。
- 每个转换算法都定义为采用 XML（XPath 节点集）或字节作为输入。如果当前数据的格式与转换输入要求不同，则应用转换规则。
- 每个转换算法都定义为生成 XML 或字节作为输出。
- 如果最后一个转换算法的输出未以字节为单位定义（或未指定转换），则规范化方法将用作隐式转换（即使元素 <CanonicalizationMethod> 中指定了其他算法）。
- 转换算法的http://www.w3.org/2000/09/xmldsig#enveloped-signature值被解释为规定从文档中删除<Signature>元素的规则。否则，封装签名的验证程序将消化该文档（包括签名），但签名者会在应用签名之前消化该文档，从而导致不同的答案。
<DigestMethod> 元素

标识要应用于由 URI 元素的 <Reference> 属性标识的转换内容的摘要（加密哈希）方法。这个由Reference.DigestMethod属性表示。

选择规范化方法

除非与需要使用不同值的规范进行互作，否则我们建议使用默认的 .NET 规范化方法，即其值为 http://www.w3.org/TR/2001/REC-xml-c14n-200103151.0 的 XML-C14N 算法。 XML-C14N 1.0 算法需要得到 XMLDSIG 的所有实现的支持，特别是因为它是一种隐式的最终转换。

有一些版本的规范化算法支持保留注释。不建议使用保留注释的规范化方法，因为它们违反了“所见即所签”原则。也就是说，元素中的 <Signature> 注释不会更改签名的执行方式的处理逻辑，而只会更改签名值。与弱签名算法结合使用时，允许包含注释会给攻击者提供不必要的自由来强制发生哈希冲突，从而使篡改的文档看起来是合法的。在 .NET Framework 中，默认仅支持内置规范化程序。要支持附加或自定义规范化程序，请参阅 SafeCanonicalizationMethods 属性。如果文档使用不在 SafeCanonicalizationMethods 属性所表示的集合中的规范化方法，则 CheckSignature 方法将返回 false。

注释

极其防御的应用程序可以删除它不希望签名者从 SafeCanonicalizationMethods 集合中使用的任何值。

参考值是否防止篡改？

是的，<Reference> 的值是防篡改的。 .NET 在处理任何 <SignatureValue> 值及其关联的转换之前，会先验证 <Reference> 的计算，并将提前中止以避免潜在的恶意处理指令。

选择要签名的元素

如果可能，建议对属性使用“” URI 值（或将 Uri 属性设置为空字符串）。整个文档都会被用作摘要计算，这样整个文档就能得到防篡改的保护。

以定位点形式出现的 URI 值（例如 #foo）很常见，它指的是 ID 属性为“foo”的元素。遗憾的是，这很容易被篡改，因为这只包括目标元素的内容，而不是上下文。滥用这种区别被称为 XML 签名包装 (XSW)。

如果应用程序认为注释是语义（处理 XML 时不常见），则应使用“#xpointer（/）”而不是“”和“#xpointer（id（'foo'）”而不是“#foo”。 #xpointer 版本被解释为包括注释，而短名称表单不包括注释。

如果需要接受仅部分受保护的文档，并且想要确保所读取的内容与签名保护的内容相同，请使用 GetIdElement 方法。

有关 KeyInfo 元素的安全注意事项

可选 <KeyInfo> 元素（即 KeyInfo 属性）中的数据（即包含用于验证签名的密钥）不应受信任。

具体而言，当 KeyInfo 值表示裸 RSA、DSA 或 ECDSA 公钥时，尽管 CheckSignature 方法报告签名有效，文档可能已被篡改。之所以发生这种情况，是因为执行篡改的实体只需生成新密钥，并使用该新密钥重新对被篡改的文档进行签名。因此，除非应用程序验证公钥是否为预期值，否则文档应被视为被篡改。这要求应用程序检查文档中嵌入的公钥，并针对文档上下文的已知值列表对其进行验证。例如，如果认为某个已知用户可能颁发了该文档，则您可以根据该用户使用的已知密钥列表来检查密钥。

还可以使用 CheckSignatureReturningKey 该方法（而不是使用 CheckSignature 该方法）在处理文档后验证密钥。但是，为了获得最佳安全性，应事先验证密钥。

或者，考虑尝试用户注册的公钥，而不是读取 <KeyInfo> 元素中的内容。

有关 X509Data 元素的安全注意事项

可选 <X509Data> 元素是元素的 <KeyInfo> 子元素，包含 X509 证书的一个或多个 X509 证书或标识符。 <X509Data> 元素中的数据从本质上讲也不应被信任。

使用嵌入 <X509Data> 元素验证文档时，.NET 仅验证数据是否解析为 X509 证书，该证书的公钥可用于验证文档签名。与调用 CheckSignature 方法并将 verifySignatureOnly 参数设置为 false 不同，不执行撤销检查，不检查链信任，也不验证到期情况。即使应用程序提取证书本身并将其传递给 CheckSignature 方法，并将 verifySignatureOnly 参数设置为 false，这仍然不足以防止文档被篡改。仍需要验证证书是否适合正在签名的文档。

使用嵌入式签名证书可以提供有用的密钥轮换策略，无论是在 <X509Data> 节中还是在文档内容中。使用此方法时，应用程序应手动提取证书并执行与以下类似的验证操作：

证书是通过证书颁发机构（CA）直接或通过证书链颁发的，该证书颁发机构（CA）将其公共证书嵌入到应用程序中。

仅使用 OS 提供的信任列表而不进行额外检查（例如已知的主题名称）不足以防止 SignedXml 中的篡改。
该证书在文档签名时（或对于近实时文档处理而言的“当前时刻”）经核实未过期。
对于由支持撤销功能的 CA 签发的长期有效证书，请验证该证书是否已被撤销。
证书主题已验证为适用于当前文档。

选择转换算法

如果要与指定特定值（如 XrML）的规范进行互作，则需要遵循规范。如果你有一个信封签名（如签名整个文档时），则需要使用 http://www.w3.org/2000/09/xmldsig#enveloped-signature （由 XmlDsigEnvelopedSignatureTransform 类表示）。也可以指定隐式 XML-C14N 转换，但没有必要。对于封装或分离的签名，无需进行任何变换。隐式 XML-C14N 转换会自动处理所有内容。

随着 Microsoft 安全公告 MS16-035 引入的安全更新，.NET 默认限制了可在文档验证中使用的转换，对于不受信任的转换，CheckSignature 将始终返回 false。特别是，那些需要额外输入（在 XML 中指定为子元素）的转换，由于容易被恶意用户滥用，现在不再被允许。 W3C 建议避免 XPath 和 XSLT 转换，这是受这些限制影响的两个主要转换。

外部引用存在的问题

如果应用程序未验证外部引用是否适合当前上下文，则可以以提供许多安全漏洞（包括拒绝服务、分布式反射拒绝服务、信息泄露、签名绕过和远程代码执行）的方式滥用它们。即使应用程序验证了外部引用 URI，仍然存在资源被加载两次的问题：一次是当应用程序读取资源时，另一次是SignedXml读取它时。由于无法保证应用程序读取和文档验证步骤具有相同的内容，因此签名不提供可信度。

鉴于外部引用的风险， SignedXml 在遇到外部引用时将引发异常。有关此问题的详细信息，请参阅知识库文章3148821。

通过