使用 X.509 令牌来保护 Web Service

Liberty 支持 Oasis Web Service 安全性 X.509 证书令牌概要文件 1.1。可以使用 X.509 令牌对消息进行签名和加密,从而提供消息完整性和机密性。

WS-Security 策略

要使用 X.509 令牌来保护 XML 消息,必须先创建一个在 Web 服务描述语言 (WSDL) 中指定的合同。Web Service 必须在 WSDL 文件中包含 WS-Security 策略。WS-Security 策略可以包含 AsymmetricBindingSymmetricBinding 断言。

X.509 令牌的需求表示为 WS-Security 策略中的 X509Token 断言类型。以下示例说明了一个样本 X509Token 断言:
<sp:X509Token sp:IncludeToken=
  "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
  <wsp:Policy>
    <sp:WssX509V3Token10 />
  </wsp:Policy>
</sp:X509Token>
AsymmetricBinding 断言中:
  • 发起方 X509Token 用于对从请求者传递到提供者的消息进行签名,以及对从提供者传递到请求者的消息进行加密。
  • 接收方 X509Token 用于对从提供者传递到请求者的消息进行签名,以及对从请求者传递到提供者的消息进行加密。
下表说明了发起方令牌和接收方令牌如何用于请求/响应链的每一部分:
表 1. 发起方令牌和接收方令牌用于请求/响应链的每一部分
* 发起方令牌 接收方令牌
请求传出(请求者) 签名 encrypt
请求传入(提供者) 验证签名 解密
响应传出(提供者) encrypt 签名
响应传入(请求者) 解密 验证签名
专用密钥用来对消息进行签名和解密。公用证书用来对消息进行加密和验证签名。专用密钥用于密钥的用户(签署者或者解密者)。

SymmetricBinding 断言中,为 X.509 令牌保护的密钥或临时密钥供发起方和接收方共享。而密钥用于加密和解密。

以下示例说明了在 AsymmetricBinding 断言中使用 X.509 令牌的样本 WS-Security 策略。此策略使得能够使用时间戳记对请求和响应的主体进行签名和加密。
<wsp:Policy wsu:Id="SampleAsymmetricX509TokensPolicy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:AsymmetricBinding>
        <wsp:Policy>
          <sp:InitiatorToken>
            <wsp:Policy>
              <sp:X509Token sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                <wsp:Policy>
                  <sp:WssX509V3Token10 />
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:InitiatorToken>
          <sp:RecipientToken>
            <wsp:Policy>
              <sp:X509Token sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                <wsp:Policy>
                  <sp:WssX509V3Token10 />
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:RecipientToken>
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic128 />
            </wsp:Policy>
          </sp:AlgorithmSuite>
          <sp:Layout>
            <wsp:Policy>
              <sp:Strict />
            </wsp:Policy>
          </sp:Layout>
          <sp:IncludeTimestamp />
          <sp:ProtectTokens />
          <sp:OnlySignEntireHeadersAndBody />
        </wsp:Policy>
      </sp:AsymmetricBinding>
      <sp:SignedParts>
        <sp:Body />
      </sp:SignedParts>
      <sp:EncryptedParts>
        <sp:Body />
      </sp:EncryptedParts>
      <sp:Wss10>
        <wsp:Policy>
          <sp:MustSupportRefKeyIdentifier />
        </wsp:Policy>
      </sp:Wss10>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>
以下示例说明了在 SymmetricBinding 断言中使用 X.509 令牌的样本 WS-Security 策略。此策略使得能够使用时间戳记对请求和响应的主体进行签名。
<wsp:Policy wsu:Id="SampleSymmetricX509TokensPolicy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:SymmetricBinding>
        <wsp:Policy>
          <sp:ProtectionToken>
            <wsp:Policy>
              <sp:X509Token sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                <wsp:Policy>
                  <sp:WssX509V3Token11 />
                  <sp:RequireThumbprintReference />
                </wsp:Policy>
              </sp:X509Token>
            </wsp:Policy>
          </sp:ProtectionToken>
          <sp:Layout>
            <wsp:Policy>
              <sp:Lax />
            </wsp:Policy>
          </sp:Layout>
          <sp:IncludeTimestamp />
          <sp:OnlySignEntireHeadersAndBody />
          <sp:SignBeforeEncrypting />
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic128 />
            </wsp:Policy>
          </sp:AlgorithmSuite>
        </wsp:Policy>
      </sp:SymmetricBinding>
      <sp:EncryptedParts>
        <sp:Body />
      </sp:EncryptedParts>
      <sp:SignedParts>
        <sp:Body />
      </sp:SignedParts>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

令牌引用和令牌包括

令牌断言可以携带 sp:IncludeToken 属性,该属性要求将令牌包括在消息中。除了直接引用以外,若干令牌断言还支持有关引用令牌的机制。如果令牌断言中包含多个引用断言,那么对于该令牌的引用需要包含所指定的所有引用类型。例如,如果一个令牌断言携带了 sp:IncludeToken 属性,该属性的值为 ../Always,并且该令牌断言还包含嵌套的 sp:RequireIssuerSerialReference 断言,那么消息中必须包括该令牌两次。虽然这样的组合并不算错误,但是,由于效率方面的原因,最好是避免使用这样的组合。

IncludeToken 断言在 Liberty 中强制实施,但在 WebSphere Application Server 传统版的 WS-Security 运行时环境中被忽略。

WS-Security 策略支持下列令牌引用机制:
  • KeyIdentifier: <sp:RequireKeyIdentifierReference... />
  • IssuerSerial: <sp:RequireIssuerSerialReference ... />
  • Thumbprint: <sp:RequireThumbprintReference ... />

在客户端/生成者端生成 X.509 令牌时使用这些引用,且在服务器端/使用者端未强制实施这些引用。

运行时配置

对于使用 X.509 令牌来保护消息,Liberty 中的 WS-Security 功能部件运行时比 WS-Security 策略提供了更多配置选项。运行时配置是在 server.xml 文件中定义。运行时配置包括密码属性(例如,signaturePropertiesencryptionProperties)、密钥和密钥库。

以下示例说明了 X509Token 断言的客户机配置:
<wsSecurityClient id="default"
                  ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler">
  <signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                       org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Client"
                       org.apache.ws.security.crypto.merlin.keystore.alias="x509ClientDefault"
                       org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks" />
  <encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                        org.apache.ws.security.crypto.merlin.keystore.password="LibertyXClient"
                        org.apache.ws.security.crypto.merlin.keystore.alias="x509DefaultCert"
                        org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks" />
</wsSecurityClient>
以下示例说明了 X509Token 断言的服务器配置:
<wsSecurityProvider id="default"
                    ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler">
  <signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                       org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
                       org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
                       org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks" />
  <encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                        org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
                        org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
                        org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks" />
</wsSecurityProvider>

在运行时配置中,signaturePropertiesencryptionProperties 属性等价于 WSS4J 配置中的 crypto 属性。有关更多信息,请参阅 WSS4J 配置。许多 crypto 属性具有有效的缺省值,因此,不需要指定这些属性。但是,必须指定其他属性(例如,与密钥库和密钥相关的属性)。

有关这些属性的更多信息,请参阅 Web Service 安全性缺省配置

密钥库文件、密钥和证书

对消息进行签名和加密需要使用公用证书和专用密钥。这些公用证书和专用密钥存储在密钥库文件中。当您使用 X509Token 断言时需要密钥库文件。客户端密钥库文件包含客户机的专用密钥,以及对应于服务器公用密钥的证书链。服务器端密钥库文件包含服务器的专用密钥,以及对应于客户机公用密钥的证书链。

对 SOAP 消息进行签名和加密之后,由 WS-Security 运行时环境按如下所示来解释 signaturePropertiesencryptionProperties 属性:
  • AsymmetricBinding 断言

    signatureProperties 属性所指定的密钥用作对出站消息进行签名的专用密钥,还用于对入站消息进行解密。

    encryptionProperties 属性所指定的密钥用作对出站消息进行加密的公用密钥,还用于验证入站消息中的签名。

  • SymmetricBinding 断言

    使用了由 encryptionProperties 属性所指定的密钥,而忽略了 signatureProperties 属性。

专用密钥密码 CallbackHandler

要访问密钥库中的专用密钥,您必须知道两个不同的密码。一个密码用于存储了专用密钥的密钥库。另一个密码用于专用密钥本身。虽然在其中一个 crypto 属性(signaturePropertiesencryptionProperties)中指定了密钥库的密码,但是 WS-Security 通常使用 CallbackHandler 类来访问密钥库中的专用密钥。在 Liberty 中,必须将此 CallbackHandler 类作为 Liberty 功能部件进行打包,并且其类名指定为 security.xml 中的 ws-security.callback-handler 定制属性的值。

WS-Security 需要此 CallbackHandler 类才能访问密钥库中的专用密钥。

有关密码 CallbackHandler 类的更多信息,请参阅为 WS-Security 开发密码回调处理程序

如果 CallbackHandler 类未提供专用密钥密码,那么 ws-security 运行时会首次尝试 CallbackHandler,因此必须提供密码,才能将密码属性中指定的密码用作专用密钥的缺省密码。此属性配置为 org.apache.ws.security.crypto.merlin.keystore.private.password

因为在 security.xml 文件的每个 wsSecurityClientwsSecurityProvider 部分中仅支持一个 ws-security.callback-handler 定制属性,所以单个密码回调处理程序必须支持每种使用缺省密码回调处理程序的应用程序类型(客户机或服务器)所需要的所有密码。所有提供者应用程序必须使用缺省密码回调处理程序。客户机应用程序可以通过在客户机的 Web Service 调用的请求上下文中指定 ws-security.callback-handler 定制属性来覆盖缺省回调处理程序。

如果您需要为单个 Web Service 调用提供 X.509 专用密钥和 UsernameToken 的密码,那么您无法每次都提供不同的回调处理程序以供使用。在这种情况下,您必须实现单个回调处理程序来处理这两种密码。如前一个示例所述,您必须使用 WSPasswordCallback.getUsage() 方法来确定要返回哪种密码。请参阅 WSPasswordCallback API 文档以了解受支持的用法代码:http://ws.apache.org/wss4j/apidocs/org/apache/wss4j/common/ext/WSPasswordCallback.html

证书撤销列表

证书撤销列表 (CRL) 是已撤销证书的序列号的列表。CRL 可以是一个独立文件,也可以将其打包在 PKCS#7 包装器中。可以将 CRL 与信任库配合使用来控制对服务的访问。

需要执行两个步骤来配置 Liberty 中的 WS-Security 功能部件以对 CRL 文件执行撤销检查。要对 CRL 文件启用证书撤销检查,您必须修改 server.xml 文件中的 WS-Security 运行时配置。
  1. wsSecurityProviderwsSecurityClient 元素中,添加以下属性:
    ws-security.enableRevocation="true"
  2. signatureProperties 元素中,添加以下属性,并将值设置为 CRL 文件:
    org.apache.ws.security.crypto.merlin.x509crl.file
以下示例说明了一个对 CRL 文件启用证书撤销检查的样本 WS-Security 提供者配置:
<wsSecurityProvider id="default"
    ws-security.callback-handler="com.acme.example.cbh.CommonPasswordCallback"
    ws-security.signature.username="x509ServerDefault"
    ws-security.enableRevocation="true">
  <signatureProperties
      org.apache.ws.security.crypto.merlin.keystore.type="jks"
      org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
      org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
      org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.ks"
      org.apache.ws.security.crypto.merlin.truststore.password="LibertyX509Server"
      org.apache.ws.security.crypto.merlin.truststore.file="${server.config.dir}/x509DefaultServer.ks"
      org.apache.ws.security.crypto.merlin.x509crl.file="${server.config.dir}/revokedCerts.crl"/>
</wsSecurityProvider>

用于指示主题类型的图标 概念主题



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