利用 X.509 記號保護 Web 服務
Liberty 支援 Oasis Web 服務安全 X.509 憑證記號設定檔 1.1。X.509 記號可用來簽署及加密訊息,以提供訊息完整性和機密性。
WS-Security 原則
如果要利用 X.509 記號來保護 XML 訊息,您必須先建立「Web 服務說明語言 (WSDL)」中所指定的合約。 Web 服務必須有一項併入 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 用於從提供者到要求者的訊息簽章,以及從要求者到提供者的訊息加密。
* | 起始者記號 | 收件者記號 |
---|---|---|
送出要求(要求者) | sign | encrypt |
送入要求(提供者) | 驗證簽章 | 解密 |
送出回應(提供者) | encrypt | sign |
送入回應(要求者) | 解密 | 驗證簽章 |
在 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 屬性,其要求在訊息中包含記號。 有些記號主張在直接參照之外,還支援記號的參照機制。 如果一個記號主張包含多個參照主張,對於這個記號的參照都必須包含所有必要的參照類型。 比方說,如果記號主張攜帶其值為 ../Always 的 sp:IncludeToken 屬性,且這個記號主張也包含巢狀的 sp:RequireIssuerSerialReference 主張,就必須在訊息中包含這個記號兩次。 這類組合雖不是錯誤,但為了有效性,最好要避免。
Liberty 施行 IncludeToken 主張,但在 WebSphere Application Server 傳統版的 WS-Security 執行時期環境中會忽略這個主張。
- KeyIdentifier:<sp:RequireKeyIdentifierReference... />
- IssuerSerial:<sp:RequireIssuerSerialReference ... />
- Thumbprint:<sp:RequireThumbprintReference ... />
當在用戶端/產生者端產生 X.509 記號時,會使用這些參照,伺服器/消費者端不會強制使用這些參照。
執行時期配置
Liberty 中的 WS-Security 特性執行時期以 X.509 記號來提供的訊息保護配置選項,大於 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 配置中的加密內容。 如需相關資訊,請參閱 WSS4J 配置。許多加密內容都有有效的預設值,因此,不需要指定它們。 但仍需指定其他內容,例如金鑰儲存庫及金鑰相關內容。
如需這些內容的相關資訊,請參閱 Web 服務安全預設配置。
金鑰儲存庫檔、金鑰和憑證
訊息簽章和加密需要使用公用憑證和私密金鑰。這些公用憑證和私密金鑰都儲存在金鑰儲存庫檔中。 當您使用 X509Token 主張時,需要金鑰儲存庫檔。 用戶端金鑰儲存庫檔包含用戶端的私密金鑰,以及對應於伺服器公開金鑰的憑證鏈。 伺服器端金鑰儲存庫檔包含伺服器的私密金鑰,以及對應於用戶端公開金鑰的憑證鏈。
- AsymmetricBinding 主張
signatureProperties 內容所指定的金鑰是用來作為簽署出埠訊息的私密金鑰,也用來進行入埠訊息的解密。
encryptionProperties 內容所指定的金鑰用來作為加密出埠訊息的公開金鑰,也用來驗證入埠訊息的簽章。
- SymmetricBinding 主張
使用 encryptionProperties 內容所指定的金鑰,但忽略 signatureProperties 內容。
私密金鑰密碼 CallbackHandler
如果要存取金鑰儲存庫中的私密金鑰,您必須知道兩個不同的密碼。 一個密碼用於儲存私密金鑰的金鑰儲存庫。 另一個密碼用於私密金鑰本身。 金鑰儲存庫的密碼由 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 服務呼叫的要求環境定義上指定 ws-security.callback-handler 自訂內容來置換預設回呼處理常式。
如果您需要針對單一 Web 服務呼叫來提供 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>