javax.xml.crypto.dsig
类 XMLSignatureFactory

java.lang.Object
  javax.xml.crypto.dsig.XMLSignatureFactory

public abstract class XMLSignatureFactory
extends Object

用于从头创建 XMLSignature 对象或从相应的 XML 表示形式解组 XMLSignature 对象的工厂。

XMLSignatureFactory 类型

每个 XMLSignatureFactory 实例都支持一个特定的 XML 机制类型。要创建 XMLSignatureFactory，则需要调用一个静态 getInstance 方法，以传入所需的 XML 机制类型，例如：

XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");

此工厂生成的对象将基于 DOM 并遵守 DOM 互操作性要求，正如 API 概述的 DOM Mechanism Requirements 部分中所定义的。标准机制类型列表，请参阅 API 概述的 Service Providers 部分。

使用 Provider 机制来注册和加载 XMLSignatureFactory 实现。例如，支持 DOM 机制的服务提供者将在 Provider 子类中指定，如下所示：

put("XMLSignatureFactory.DOM", "org.example.DOMXMLSignatureFactory");
 

实现至少必须支持默认的机制类型：DOM。

注意，调用者必须使用相同的 XMLSignatureFactory 实例来创建要生成的特定 XMLStructure 的 XMLSignature。如果同时使用取自不同提供者或不同机制类型的 XMLStructure，则行为是不明确的。

同时，由此工厂创建的 XMLStructure 可能包含特定于 XMLSignature 的状态，并且该状态是不可重用的。

从头创建 XMLSignature

创建了 XMLSignatureFactory 后，就可以通过调用适当的方法来实例化这些对象。例如，可以通过调用一个 newReference 方法来创建 Reference 实例。

从 XML 解组 XMLSignature

此外，通过调用 unmarshalXMLSignature 方法，并向其传递包含 XML 内容的特定于机制的 XMLValidateContext 实例，可以从现有 XML 表示形式创建 XMLSignature：

DOMValidateContext context = new DOMValidateContext(key, signatureElement);
XMLSignature signature = factory.unmarshalXMLSignature(context);
 

将 XMLSignatures 签名并编组到 XML

DOMSignContext context = new DOMSignContext(privateKey, document);
signature.sign(context);
 

可保证此类的静态方法是线程安全的。多个线程可以并发调用此类中所定义的静态方法，而不会产生不良效果。

但是，对于此类所定义的非静态方法并非如此。除非具体的提供者另行指定，否则需要并发访问单个 XMLSignatureFactory 实例的多个线程应该在它们之间实现同步并提供所需的锁定。对于每个线程都操作一个不同 XMLSignatureFactory 实例的多个线程而言，无需实现同步。

从以下版本开始：

1.6

XMLSignatureFactory

protected XMLSignatureFactory()

默认的构造方法，由子类调用。

getInstance

public static XMLSignatureFactory getInstance(String mechanismType)

返回 XMLSignatureFactory，它支持指定的 XML 处理机制和表示形式类型（比如：“DOM”）。

此方法使用标准的 JCA 提供者查找机制来查找并实例化所需机制类型的 XMLSignatureFactory 实现。它将从首选的 Provider 开始，遍历已注册的安全 Provider 的列表。返回取自第一个支持指定机制的 Provider 中的新 XMLSignatureFactory 对象。

注意，已注册提供者的列表可以通过 Security.getProviders() 方法获得。

参数：

mechanismType - XML 处理机制和表示形式的类型。有关标准机制类型列表，请参阅 API 概述的 Service Providers 部分。

返回：

新的 XMLSignatureFactory

抛出：

NullPointerException - 如果 mechanismType 为 null

NoSuchMechanismException - 如果没有任何 Provider 支持指定机制的 XMLSignatureFactory 实现

另请参见：

Provider

getInstance

public static XMLSignatureFactory getInstance(String mechanismType,
                                              Provider provider)

返回支持请求的 XML 处理机制和表示形式类型（比如：“DOM”）的 XMLSignatureFactory，由指定提供者提供。注意，指定的 Provider 对象不必已经在提供者列表中注册。

参数：

mechanismType - XML 处理机制和表示形式的类型。有关标准机制类型列表，请参阅 API 概述的 Service Providers 部分。

provider - Provider 对象

返回：

新的 XMLSignatureFactory

抛出：

NullPointerException - 如果 provider 或 mechanismType 为 null

NoSuchMechanismException - 如果不能从指定的 Provider 对象得到指定机制的 XMLSignatureFactory 实现

另请参见：

Provider

getInstance

public static XMLSignatureFactory getInstance(String mechanismType,
                                              String provider)
                                       throws NoSuchProviderException

返回支持所需的 XML 处理机制和表示形式类型（比如：“DOM”）的 XMLSignatureFactory，由指定提供者提供。指定的提供者必须已在安全提供者列表中注册。

注意，已注册提供者的列表可以通过 Security.getProviders() 方法获得。

参数：

mechanismType - XML 处理机制和表示形式的类型。有关标准机制类型列表，请参阅 API 概述的 Service Providers 部分。

provider - 提供者的字符串名称

返回：

新的 XMLSignatureFactory

抛出：

NoSuchProviderException - 如果指定的提供者没有在安全提供者列表中进行注册

NullPointerException - 如果 provider 或 mechanismType 为 null

NoSuchMechanismException - 如果从指定的提供者不能得到指定机制的 XMLSignatureFactory 实现

另请参见：

Provider

getInstance

public static XMLSignatureFactory getInstance()

返回支持默认的 XML 处理机制和表示形式类型（“DOM”） 的 XMLSignatureFactory。

此方法使用标准的 JCA 提供者查找机制来查找并实例化默认机制类型的 XMLSignatureFactory 实现。它将从首选的 Provider 开始，遍历已注册的安全 Provider 的列表。返回取自第一个支持 DOM 机制的Provider 中的新 XMLSignatureFactory 对象。

注意，已注册提供者的列表可以通过 Security.getProviders() 方法获得。

返回：

新的 XMLSignatureFactory

抛出：

NoSuchMechanismException - 如果没有任何 Provider 支持 DOM 机制的 XMLSignatureFactory 实现

另请参见：

Provider

getMechanismType

public final String getMechanismType()

返回此 XMLSignatureFactory 支持的 XML 处理机制类型和表示形式类型（比如：“DOM”）。

返回：

此 XMLSignatureFactory 支持的 XML 处理机制类型

getProvider

public final Provider getProvider()

返回此 XMLSignatureFactory 的提供者。

返回：

此 XMLSignatureFactory 的提供者

newXMLSignature

public abstract XMLSignature newXMLSignature(SignedInfo si,
                                             KeyInfo ki)

创建一个 XMLSignature，并使用指定的 SignedInfo 和 KeyInfo 对象的内容对其进行初始化。

参数：

si - 签名信息

ki - 密钥信息（可能为 null）

返回：

XMLSignature

抛出：

NullPointerException - 如果 si 为 null

newXMLSignature

public abstract XMLSignature newXMLSignature(SignedInfo si,
                                             KeyInfo ki,
                                             List objects,
                                             String id,
                                             String signatureValueId)

创建一个 XMLSignature，并使用指定的参数对其进行初始化。

参数：

si - 签名信息

ki - 密钥信息（可以为 null）

objects - XMLObject 列表（可以为空或 null）

id - Id（可以为 null）

signatureValueId - SignatureValue Id（可以为 null）

返回：

XMLSignature

抛出：

NullPointerException - 如果 si 为 null

ClassCastException - 如果有些 objects 的类型不是 XMLObject

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm)

创建带指定 URI 和摘要方法的 Reference。

参数：

uri - 引用 URI（可以为 null）

dm - 摘要方法

返回：

Reference

抛出：

IllegalArgumentException - 如果 uri 与 RFC 2396 不兼容

NullPointerException - 如果 dm 为 null

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List transforms,
                                       String type,
                                       String id)

创建带指定参数的 Reference。

参数：

uri - 引用 URI（可以为 null）

dm - 摘要方法

transforms - Transform 列表。需要复制该列表，以防止随后被修改。可以为 null 或空。

type - URI 形式的引用类型（可以为 null）

id - 引用 ID（可以为 null）

返回：

Reference

抛出：

ClassCastException - 如果有些 transforms 的类型不是 Transform

IllegalArgumentException - 如果 uri 与 RFC 2396 不兼容

NullPointerException - 如果 dm 为 null

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List transforms,
                                       String type,
                                       String id,
                                       byte[] digestValue)

创建带指定参数和预计算的摘要值的 Reference。

如果先前已经计算了 Reference 的摘要值，则此方法很有用。有关示例，请参阅 OASIS-DSS（数字签名服务）规范。

参数：

uri - 引用 URI（可以为 null）

dm - 摘要方法

transforms - Transform 列表。需要复制该列表，以防止随后被修改。可以为 null 或空。

type - URI 形式的引用类型（可以为 null）

id - 引用 ID（可以为 null）

digestValue - 摘要值。复制该数组，以防止随后被修改。

返回：

Reference

抛出：

ClassCastException - 如果任何 transforms 的类型不是 Transform

IllegalArgumentException - 如果 uri 与 RFC 2396 不兼容

NullPointerException - 如果 dm 或 digestValue 为 null

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List appliedTransforms,
                                       Data result,
                                       List transforms,
                                       String type,
                                       String id)

创建带指定参数的 Reference。

在已将转换列表应用于 Reference 时，此方法很有用。例如，请参阅 OASIS-DSS（数字签名服务）规范。

生成了包含此引用的 XMLSignature 之后，将指定的 transforms（如果为非空）应用于指定的 result。所得 Reference 元素的 Transforms 元素被设置为 appliedTransforms 和 transforms 的串联。

参数：

uri - 引用 URI（可以为 null）

dm - 摘要方法

appliedTransforms - 已应用的 Transform 的列表。需要复制该列表，以防止随后被修改。列表至少必须包含一个条目。

result - 处理 appliedTransforms 的序列的结果

transforms - 生成签名时将应用的 Transform 的列表。需要复制该列表，以防止随后被修改。可以为 null 或空。

type - URI 形式的引用类型（可以为 null）

id - 引用 ID（可以为 null）

返回：

Reference

抛出：

ClassCastException - 如果任何转换（任一列表中）的类型不是 Transform

IllegalArgumentException - 如果 uri 与 RFC 2396 不兼容或 appliedTransforms 为空

NullPointerException - 如果 dm、appliedTransforms 或 result 为 null

newSignedInfo

public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
                                         SignatureMethod sm,
                                         List references)

创建带指定的规范化方法和签名方法、以及一个或多个引用的列表的 SignedInfo。

参数：

cm - 规范化方法

sm - 签名方法

references - 一个列表，由一个或多个 Reference 组成。需要复制该列表，以防止随后被修改。

返回：

SignedInfo

抛出：

ClassCastException - 如果任何引用的类型不是 Reference

IllegalArgumentException - 如果 references 为空

NullPointerException - 如果任何参数为 null

newSignedInfo

public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
                                         SignatureMethod sm,
                                         List references,
                                         String id)

创建带指定参数的 SignedInfo。

参数：

cm - 规范化方法

sm - 签名方法

references - 一个列表，由一个或多个 Reference 组成。需要复制该列表，以防止随后被修改。

id - id（可以为 null）

返回：

SignedInfo

抛出：

ClassCastException - 如果任何引用的类型不是 Reference

IllegalArgumentException - 如果 references 为空

NullPointerException - 如果 cm、sm 或 references 为 null

newXMLObject

public abstract XMLObject newXMLObject(List content,
                                       String id,
                                       String mimeType,
                                       String encoding)

根据指定参数创建 XMLObject。

参数：

content - XMLStructure 的列表。需要复制该列表，以防止随后被修改。可以为 null 或空。

id - Id（可以为 null）

mimeType - MIME 类型（可以为 null）

encoding - 编码（可以为 null）

返回：

XMLObject

抛出：

ClassCastException - 如果 content 包含任何类型不是 XMLStructure 的条目

newManifest

public abstract Manifest newManifest(List references)

创建包含指定的 Reference 列表的 Manifest。

参数：

references - 一个列表，由一个或多个 Reference 组成。需要复制该列表，以防止随后被修改。

返回：

Manifest

抛出：

NullPointerException - 如果 references 为 null

IllegalArgumentException - 如果 references 为空

ClassCastException - 如果 references 包含任何类型不是 Reference 的条目

newManifest

public abstract Manifest newManifest(List references,
                                     String id)

创建包含指定的 Reference 列表和可选 id 的 Manifest。

参数：

references - 一个列表，由一个或多个 Reference 组成。需要复制该列表，以防止随后被修改。

id - id（可以为 null）

返回：

Manifest

抛出：

NullPointerException - 如果 references 为 null

IllegalArgumentException - 如果 references 为空

ClassCastException - 如果 references 包含任何类型不是 Reference 的条目

newSignatureProperty

public abstract SignatureProperty newSignatureProperty(List content,
                                                       String target,
                                                       String id)

创建包含指定的 XMLStructure 列表、目标 URI 和可选 id 的SignatureProperty。

参数：

content - 一个列表，由一个或多个 XMLStructure 组成。需要复制该列表，以防止随后被修改。

target - 使用此属性的 Signature 的目标 URI

id - id（可以为 null）

返回：

SignatureProperty

抛出：

NullPointerException - 如果 content 或 target 为 null

IllegalArgumentException - 如果 content 为空

ClassCastException - 如果 content 包含任何类型不是 XMLStructure 的条目

newSignatureProperties

public abstract SignatureProperties newSignatureProperties(List properties,
                                                           String id)

创建包含指定的 SignatureProperty 列表和可选 id 的 SignatureProperties。

参数：

properties - 一个列表，由一个或多个 SignatureProperty 组成。需要复制该列表，以防止随后被修改。

id - id（可以为 null）

返回：

SignatureProperties

抛出：

NullPointerException - 如果 properties 为 null

IllegalArgumentException - 如果 properties 为空

ClassCastException - 如果 properties 包含任何类型不是 SignatureProperty 的条目

newDigestMethod

public abstract DigestMethod newDigestMethod(String algorithm,
                                             DigestMethodParameterSpec params)
                                      throws NoSuchAlgorithmException,
                                             InvalidAlgorithmParameterException

针对指定的算法 URI 和参数创建 DigestMethod。

参数：

algorithm - 标识摘要算法的 URI

params - 特定于算法的摘要参数（可以为 null）

返回：

DigestMethod

抛出：

InvalidAlgorithmParameterException - 如果指定的参数不适合请求的算法

NoSuchAlgorithmException - 如果无法找到指定算法的实现

NullPointerException - 如果 algorithm 为 null

newSignatureMethod

public abstract SignatureMethod newSignatureMethod(String algorithm,
                                                   SignatureMethodParameterSpec params)
                                            throws NoSuchAlgorithmException,
                                                   InvalidAlgorithmParameterException

针对指定的算法 URI 和参数创建 SignatureMethod。

参数：

algorithm - 标识签名算法的 URI

params - 特定于算法的签名参数（可以为 null）

返回：

SignatureMethod

抛出：

InvalidAlgorithmParameterException - 如果指定的参数不适合请求的算法

NoSuchAlgorithmException - 如果无法找到指定算法的实现

NullPointerException - 如果 algorithm 为 null

newTransform

public abstract Transform newTransform(String algorithm,
                                       TransformParameterSpec params)
                                throws NoSuchAlgorithmException,
                                       InvalidAlgorithmParameterException

针对指定的算法 URI 和参数创建 Transform。

参数：

algorithm - 标识转换算法的 URI

params - 特定于算法的转换参数（可以为 null）

返回：

Transform

抛出：

InvalidAlgorithmParameterException - 如果指定的参数不适合请求的算法

NoSuchAlgorithmException - 如果无法找到指定算法的实现

NullPointerException - 如果 algorithm 为 null

newTransform

public abstract Transform newTransform(String algorithm,
                                       XMLStructure params)
                                throws NoSuchAlgorithmException,
                                       InvalidAlgorithmParameterException

针对指定的算法 URI 和参数创建 Transform。该参数被指定为特定于机制的 XMLStructure（比如：DOMStructure）。当参数是 XML 形式或没有任何用于指定参数的标准类时，此方法很有用。

参数：

algorithm - 标识转换算法的 URI

params - 从中解组参数的特定于机制的 XML 结构（如果该结构不是必需的或是可选的，则此参数为 null）

返回：

Transform

抛出：

ClassCastException - 如果 params 类型不适合此 XMLSignatureFactory

InvalidAlgorithmParameterException - 如果指定的参数不适合请求的算法

NoSuchAlgorithmException - 如果无法找到指定算法的实现

NullPointerException - 如果 algorithm 为 null

newCanonicalizationMethod

public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm,
                                                                 C14NMethodParameterSpec params)
                                                          throws NoSuchAlgorithmException,
                                                                 InvalidAlgorithmParameterException

针对指定的算法 URI 和参数创建 CanonicalizationMethod。

参数：

algorithm - 标识规范化算法的 URI

params - 特定于算法的规范化参数（可以为 null）

返回：

CanonicalizationMethod

抛出：

InvalidAlgorithmParameterException - 如果指定的参数不适合请求的算法

NoSuchAlgorithmException - 如果无法找到指定算法的实现

NullPointerException - 如果 algorithm 为 null

newCanonicalizationMethod

public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm,
                                                                 XMLStructure params)
                                                          throws NoSuchAlgorithmException,
                                                                 InvalidAlgorithmParameterException

针对指定的算法 URI 和参数创建 CanonicalizationMethod。该参数被指定为特定于机制的 XMLStructure（比如：DOMStructure）。当参数是 XML 形式或没有任何用于指定参数的标准类时，此方法很有用。

参数：

algorithm - 标识规范化算法的 URI

params - 从中解组参数的特定于机制的 XML 结构（如果该结构不是必需的或是可选的，则此参数为 null）

返回：

CanonicalizationMethod

抛出：

ClassCastException - 如果 params 类型不适合此 XMLSignatureFactory

InvalidAlgorithmParameterException - 如果指定的参数不适合请求的算法

NoSuchAlgorithmException - 如果无法找到指定算法的实现

NullPointerException - 如果 algorithm 为 null

getKeyInfoFactory

public final KeyInfoFactory getKeyInfoFactory()

返回创建 KeyInfo 对象的 KeyInfoFactory。返回的 KeyInfoFactory 具有与此 XMLSignatureFactory 相同的机制类型和提供者。

返回：

KeyInfoFactory

抛出：

NoSuchMechanismException - 如果具有相同机制类型和提供者的 KeyFactory 实现不可用

unmarshalXMLSignature

public abstract XMLSignature unmarshalXMLSignature(XMLValidateContext context)
                                            throws MarshalException

从特定于机制的 XMLValidateContext 实例解组新的 XMLSignature 实例。

参数：

context - 从中解组签名的特定于机制的上下文

返回：

XMLSignature

抛出：

NullPointerException - 如果 context 为 null

ClassCastException - 如果 context 类型不适合此工厂

MarshalException - 如果解组过程中发生不可恢复的异常

unmarshalXMLSignature

public abstract XMLSignature unmarshalXMLSignature(XMLStructure xmlStructure)
                                            throws MarshalException

从特定于机制的 XMLStructure 实例解组新的 XMLSignature 实例。如果只想解组（且不验证） XMLSignature 时，此方法很有用。

参数：

xmlStructure - 从中解组签名的特定于机制的 XML 结构

返回：

XMLSignature

抛出：

NullPointerException - 如果 xmlStructure 为 null

ClassCastException - 如果 xmlStructure 类型不适合此工厂

MarshalException - 如果解组过程中发生不可恢复的异常。

isFeatureSupported

public abstract boolean isFeatureSupported(String feature)

指示是否支持指定的功能。

参数：

feature - 功能名称（作为抽象 URI）

返回：

如果支持指定功能，则返回 true，否则返回 false

抛出：

NullPointerException - 如果 feature 为 null

getURIDereferencer

public abstract URIDereferencer getURIDereferencer()

返回对 URIDereferencer 的引用，默认情况下该引用用于取消 Reference 对象中对 URI 的引用。

返回：

对默认 URIDereferencer 的引用（不能为 null）

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。