使用 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 策略可以包含 AsymmetricBinding 或 SymmetricBinding 断言。
<sp:X509Token sp:IncludeToken=
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:WssX509V3Token10 />
</wsp:Policy>
</sp:X509Token>
- 发起方 X509Token 用于对从请求者传递到提供者的消息进行签名,以及对从提供者传递到请求者的消息进行加密。
- 接收方 X509Token 用于对从提供者传递到请求者的消息进行签名,以及对从请求者传递到提供者的消息进行加密。
* | 发起方令牌 | 接收方令牌 |
---|---|---|
请求传出(请求者) | 签名 | encrypt |
请求传入(提供者) | 验证签名 | 解密 |
响应传出(提供者) | encrypt | 签名 |
响应传入(请求者) | 解密 | 验证签名 |
在 SymmetricBinding 断言中,为 X.509 令牌保护的密钥或临时密钥供发起方和接收方共享。而密钥用于加密和解密。
<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>
<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 运行时环境中被忽略。
- KeyIdentifier: <sp:RequireKeyIdentifierReference... />
- IssuerSerial: <sp:RequireIssuerSerialReference ... />
- Thumbprint: <sp:RequireThumbprintReference ... />
在客户端/生成者端生成 X.509 令牌时使用这些引用,且在服务器端/使用者端未强制实施这些引用。
运行时配置
对于使用 X.509 令牌来保护消息,Liberty 中的 WS-Security 功能部件运行时比 WS-Security 策略提供了更多配置选项。运行时配置是在 server.xml 文件中定义。运行时配置包括密码属性(例如,signatureProperties 和 encryptionProperties)、密钥和密钥库。
<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>
<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>
在运行时配置中,signatureProperties 和 encryptionProperties 属性等价于 WSS4J 配置中的 crypto 属性。有关更多信息,请参阅 WSS4J 配置。许多 crypto 属性具有有效的缺省值,因此,不需要指定这些属性。但是,必须指定其他属性(例如,与密钥库和密钥相关的属性)。
有关这些属性的更多信息,请参阅 Web Service 安全性缺省配置。
密钥库文件、密钥和证书
对消息进行签名和加密需要使用公用证书和专用密钥。这些公用证书和专用密钥存储在密钥库文件中。当您使用 X509Token 断言时需要密钥库文件。客户端密钥库文件包含客户机的专用密钥,以及对应于服务器公用密钥的证书链。服务器端密钥库文件包含服务器的专用密钥,以及对应于客户机公用密钥的证书链。
- AsymmetricBinding 断言
由 signatureProperties 属性所指定的密钥用作对出站消息进行签名的专用密钥,还用于对入站消息进行解密。
由 encryptionProperties 属性所指定的密钥用作对出站消息进行加密的公用密钥,还用于验证入站消息中的签名。
- SymmetricBinding 断言
使用了由 encryptionProperties 属性所指定的密钥,而忽略了 signatureProperties 属性。
专用密钥密码 CallbackHandler
要访问密钥库中的专用密钥,您必须知道两个不同的密码。一个密码用于存储了专用密钥的密钥库。另一个密码用于专用密钥本身。虽然在其中一个 crypto 属性(signatureProperties 或 encryptionProperties)中指定了密钥库的密码,但是 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 文件的每个 wsSecurityClient 和 wsSecurityProvider 部分中仅支持一个 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 与信任库配合使用来控制对服务的访问。
- 在 wsSecurityProvider 或 wsSecurityClient 元素中,添加以下属性:
ws-security.enableRevocation="true"
- 在 signatureProperties 元素中,添加以下属性,并将值设置为 CRL 文件:
org.apache.ws.security.crypto.merlin.x509crl.file
<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>