利用 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 原則可以包含 AsymmetricBindingSymmetricBinding 主張。

在 WS-Security 原則中,X.509 記號需求以一個 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. 要求/回應鏈各部分的起始者和收件者記號用法
* 起始者記號 收件者記號
送出要求(要求者) sign encrypt
送入要求(提供者) 驗證簽章 解密
送出回應(提供者) encrypt sign
送入回應(要求者) 解密 驗證簽章
私密金鑰用來簽署及解密訊息。 公用憑證用來加密訊息及驗證簽章。 私密金鑰屬於金鑰的使用者(簽章者或解密者)。

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 屬性,其要求在訊息中包含記號。 有些記號主張在直接參照之外,還支援記號的參照機制。 如果一個記號主張包含多個參照主張,對於這個記號的參照都必須包含所有必要的參照類型。 比方說,如果記號主張攜帶其值為 ../Alwayssp:IncludeToken 屬性,且這個記號主張也包含巢狀的 sp:RequireIssuerSerialReference 主張,就必須在訊息中包含這個記號兩次。 這類組合雖不是錯誤,但為了有效性,最好要避免。

Liberty 施行 IncludeToken 主張,但在 WebSphere Application Server 傳統版的 WS-Security 執行時期環境中會忽略這個主張。

WS-Security 原則支援下列記號參照機制:
  • KeyIdentifier: <sp:RequireKeyIdentifierReference... />
  • IssuerSerial: <sp:RequireIssuerSerialReference ... />
  • Thumbprint: <sp:RequireThumbprintReference ... />

當在用戶端/產生者端產生 X.509 記號時,會使用這些參照,伺服器/消費者端不會強制使用這些參照。

執行時期配置

Liberty 中的 WS-Security 特性執行時期以 X.509 記號來提供的訊息保護配置選項,大於 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 配置中的加密內容。 如需相關資訊,請參閱 WSS4J 配置。許多加密內容都有有效的預設值,因此,不需要指定它們。 但仍需指定其他內容,例如金鑰儲存庫及金鑰相關內容。

如需這些內容的相關資訊,請參閱 Web 服務安全預設配置

金鑰儲存庫檔、金鑰和憑證

訊息簽章和加密需要使用公用憑證和私密金鑰。這些公用憑證和私密金鑰都儲存在金鑰儲存庫檔中。 當您使用 X509Token 主張時,需要金鑰儲存庫檔。 用戶端金鑰儲存庫檔包含用戶端的私密金鑰,以及對應於伺服器公開金鑰的憑證鏈。 伺服器端金鑰儲存庫檔包含伺服器的私密金鑰,以及對應於用戶端公開金鑰的憑證鏈。

當簽署及加密 SOAP 訊息時,WS-Security 執行時期環境會依照下列方式來解譯 signaturePropertiesencryptionProperties 內容:
  • AsymmetricBinding 主張

    signatureProperties 內容所指定的金鑰是用來作為簽署出埠訊息的私密金鑰,也用來進行入埠訊息的解密。

    encryptionProperties 內容所指定的金鑰用來作為加密出埠訊息的公開金鑰,也用來驗證入埠訊息的簽章。

  • SymmetricBinding 主張

    使用 encryptionProperties 內容所指定的金鑰,但忽略 signatureProperties 內容。

私密金鑰密碼 CallbackHandler

如果要存取金鑰儲存庫中的私密金鑰,您必須知道兩個不同的密碼。 一個密碼用於儲存私密金鑰的金鑰儲存庫。 另一個密碼用於私密金鑰本身。 金鑰儲存庫的密碼由 signaturePropertiesencryptionProperties 這兩個加密內容的其中一個指定,WS-Security 通常利用 CallbackHandler 類別來存取金鑰儲存庫中的私密金鑰。 在 Liberty 中,這個 Callbackhandler 類別必須包裝成一項 Liberty 特性,它的類別名稱指定為 security.xmlws-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 服務呼叫的要求環境定義上指定 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 與信任儲存庫搭配使用,以便控制對服務的存取。

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>

指示主題類型的圖示 概念主題

檔名:cwlp_wssec_x509.html