使用 WSSSignature API 来配置签名信息

可通过使用 Web Service 安全性 API (WSS API) 保护 SOAP 消息,而不必对配置使用策略集。要配置客户端请求的生成器绑定部分的签名信息,请使用 WSSSignature API。WSSSignature API 是 com.ibm.websphere.wssecurity.wssapi.signature 包的一部分。

开始之前

可以使用 WSS API,或者通过管理控制台配置策略集来启用签名信息。要保护 SOAP 消息,您必须完成下列签名任务:

  • 配置签名信息。
  • 选择签名方法。
  • 根据需要添加或更改签署部件。

关于此任务

WebSphere® Application Server 使用缺省生成器的签名信息来签署消息的部件,并将 XML 数字签名与诸如 RSA-SHA1 和 HMAC-SHA1 之类的现有算法配合使用。

XML 签名定义许多用于描述密钥信息的方法并启用新方法的定义。使用 XML 签名时,通常需要 XML 规范化 (C14N)。在已序列化的 XML 文档中可用各种方法表示信息。C14N 过程用于对 XML 信息进行规范化。由于规范化的信息取决于此算法,因此要选择适当的 C14N 算法。

签名信息指定适用于已生成消息的完整性约束。约束包括指定已生成消息中必须进行数字签署的消息部件,以及需要连接数字签署现时标志和时间戳记元素的消息部件。配置了以下签名及相关的签名部件信息:

表 1. 签名部件信息. 使用签名部件来保护消息。
签名部件 描述
keyword
使用关键字添加签名部件。对签名部件使用下列关键字:
  • ADDRESSING_HEADERS
  • BODY
  • TIMESTAMP
WS-Addressing 头未进行加密,但可以签署。
xpath 使用 XPath 表达式添加签名部件。
part 将 WSSSignPart 对象添加为签名部件的目标。
timestamp 将 WSSTimestamp 对象添加为签名部件的目标。如果指定,那么时间戳记信息还指定生成消息及消息到期的时间。
header 将由 QName 指定的头添加为签名部件的目标。
securityToken 将 SecurityToken 对象添加为签名部件的目标。

为了获取签名信息,将执行特定的缺省行为。使用 WSSSignature API 的最简单方法是使用缺省行为(请参阅示例代码)。WSS API 为签名方法、规范方法、安全性令牌引用及签名部件定义了缺省值。

表 2. 缺省签名行为. 缺省情况下,已配置多个签名行为。
签名决定 缺省行为
要使用的关键字 设置关键字。WebSphere Application Server 在缺省情况下支持以下关键字:
  • ADDRESSING_HEADERS
  • BODY
  • TIMESTAMP
要使用的签名方法 设置签名算法。缺省签名方法是 RSA SHA1。WebSphere Application Server 支持以下预配置的签名方法:
  • WSSSignature.RSA_SHA1:http://www.w3.org/2000/09/xmldsig#rsa-sha1
  • WSSSignature.HMAC_SHA1:http://www.w3.org/2000/09/xmldsig#hmac-sha1
不支持 DSA-SHA1 数字签名方法 (http://www.w3.org/2000/09/xmldsig#dsa-sha1)。
要使用的规范方法 设置规范算法。缺省规范方法是 EXC C14N。WebSphere Application Server 支持以下预配置的规范方法:
  • WSSSignature.EXC_C14N:http://www.w3.org/2001/10/xml-exc-c14n#
  • WSSSignature.C14N:http://www.w3.org/2001/10/xml-c14n#
签名确认是否是必需的 设置是否需要签名确认。缺省值为 false。签名确认在 OASIS Web Services Security V1.1 规范中定义。如果需要,将存储签名确认的值,以便回收在响应消息中生成签名确认的消息后,使用此值来验证签名确认。此方法用于生成器端。
要使用的安全性令牌

设置 SecurityToken。令牌类型指定要用于签署和验证消息的令牌类型。X.509 令牌是缺省令牌类型。

WebSphere Application Server 提供以下预配置的使用者令牌类型:

  • 派生密钥令牌
  • X509 令牌

还可以根据需要创建定制令牌类型。

要设置的令牌引用 设置 refType。SecurityToken.REF_STR 是令牌引用类型的缺省值。WebSphere Application Server 支持以下预配置的令牌引用类型:
  • SecurityToken.REF_STR
  • SecurityToken.REF_KEYID
  • SecurityToken.REF_EMBEDDED
  • SecurityToken.REF_THUMBPRINT

如果调用了 WSSSignature.requireSignatureConfirmation(),那么 WSSSignature API 期望响应消息将包含签名确认。

过程

  1. 要通过使用 WSS API 来配置 SOAP 消息中的签名信息,请首先确保安装了应用程序服务器。
  2. 使用 WSSSignature API 来签署消息部件并在 SOAP 消息中指定算法。 用于签名的 WSS API 过程遵循以下过程步骤:
    1. 使用 WSSFactory.getInstance() 获取 WSS API 实现实例。
    2. 根据 WSSFactory 实例创建 WSSGenerationContext 实例。 必须在 JAX-WS 客户机应用程序中调用 WSSGenerationContext。
    3. 根据 WSSFactory 创建 SecurityToken 以配置密钥进行签署。
    4. 根据 WSSFactory 实例使用 SecurityToken 创建 WSSSignature。 WSSSignature 的缺省行为是签署以下签名部件:BODY、ADDRESSING_HEADERS 和 TIMESTAMP。
    5. 添加要签署的部件(如果缺省部件不合适)。 如果更改了摘要方法或变换方法,请创建 WSSSignPart 并将其添加至 WSSSignature。
    6. 创建 WSSSignaturePart 并将其添加至 WSSSignature。 调用 requiredSignatureConfirmation() 方法(如果要应用签名确认)。
    7. 设置规范方法(如果缺省值不合适)。
    8. 设置签名方法(如果缺省值不合适)。
    9. 设置令牌引用(如果缺省值不合适)。
    10. 将 WSSSignature 添加至 WSSGenerationContext。
    11. 使用 SOAPMessageContext 调用 WSSGenerationContext.process()。

结果

您完成了相应的步骤来配置绑定的生成器部分的签名。如果在签署消息部件时存在错误情况,那么将提供 WSSException。如果成功,那么将调用 WSSGenerationContext.process() 并将 Web Service 安全性应用于 SOAP 消息。

示例

以下示例提供了样本代码,这段代码使用了在 WSSignature API 中定义的方法。

// Get the message context
   Object msgcontext = getMessageContext();

// Generate the com.ibm.websphere.wssecurity.wssapi.WSSFactory instance  (step: a)
   WSSFactory factory = com.ibm.websphere.wssecurity.wssapi.WSSFactory.getInstance();

// Generate the WSSGenerationContext instance  (step: b)
   WSSGenerationContext gencont = factory.newWSSGenerationContext();

// Generate the callback handler
   X509GenerateCallbackHandler callbackHandler = new
       X509GenerateCallbackHandler(
       "",
       "dsig-sender.ks",
       "jks",
       "client".toCharArray(),
       "soaprequester",
       "client".toCharArray(),
       "CN=SOAPRequester, OU=TRL, O=IBM, ST=Kanagawa, C=JP", null);

// Generate the security token to be used for the signature  (step: c)
   SecurityToken token = factory.newSecurityToken(X509Token.class, 
        callbackHandler);

// Generate the WSSSignature instance (step: d)
   WSSSignature sig = factory.newWSSSignature(token);

// Set the part to be signed  (step: e)
// DEFAULT: WSSSignature.BODY, WSSSignature.ADDRESSING_HEADERS, 
//          and WSSSignature.TIMESTAMP.

// Set the part in the SOAP Header specified by QName  (step: e)
      sig.addSignHeader(new 
                        QName("http://www.w3.org/2005/08/addressing", 
                        "MessageID"));

// Set the part specified by the keyword (step: e)
      sig.addSignPart(WSSSignature.BODY);

// Set the part specified by SecurityToken  (step: e)
   UNTGenerateCallbackHandler untCallbackHandler = new 
      UNTGenerateCallbackHandler("Chris", "sirhC");
      SecurityToken unt = factory.newSecurityToken(UsernameToken.class, 
         untCallbackHandler);
      sig.addSignPart(unt);

// Set the part specified by WSSSignPart  (step: e)
   WSSSignPart sigPart = factory.newWSSSignPart();
      sigPart.setSignPart(WSSSignature.TIMESTAMP);
      sigPart.setDigestMethod(WSSSignPart.SHA256);
      sig.addSignPart(sigPart);

// Set the part specified by WSSTimestamp  (step: e)
   WSSTimestamp timestamp = factory.newWSSTimestamp();
      sig.addSignPart(timestamp);

// Set the part specified by XPath expression  (step: e) 
   		StringBuffer sb = new StringBuffer();
      sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
         and local-name()='Envelope']");
      sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
         and local-name()='Body']");
      sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping' 
         and local-name()='Ping']");
      sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping' 
         and local-name()='Text']");
      sig.addSignPartByXPath(sb.toString());

// Set to apply the signature confirmation  (step: f)
      sig.requireSignatureConfirmation();

// Set the canonicalization method  (step: g)
// DEFAULT: WSSSignature.EXC_C14N
      sig.setCanonicalizationMethod(WSSSignature.C14N);

// Set the signature method  (step: h)
// DEFAULT: WSSSignature.RSA_SHA1
      sig.setSignatureMethod(WSSSignature.HMAC_SHA1);

// Set the token reference (step: i)
// DEFAULT: SecurityToken.REF_STR
      sig.setTokenReference(SecurityToken.REF_KEYID);
	
// Add the WSSSignature to WSSGenerationContext  (step: j)
   gencont.add(sig);

// Generate the WS-Security header  (step: k)
gencont.process(msgctx);
注: 由于使用专用密钥进行签署,因此 X509GenerationCallbackHandler 需要密钥密码。

下一步做什么

接下来,如果需要有别于缺省值的方法,请选择算法方法。如果不需要更改算法方法,那么,接下来使用 WSSVerification API 来验证签名并在绑定的使用者部分中指定算法方法。注意,仅响应使用者(客户端)支持 WSSVerification API。


指示主题类型的图标 任务主题



时间戳记图标 最近一次更新时间: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_confsignaturegen
文件名:twbs_confsignaturegen.html