X.509 トークンを使用した Web サービスの保護

Liberty では、Oasis Web Services Security X.509 Certificate Token Profile 1.1 がサポートされています。X.509 トークンを使用して、メッセージの署名と暗号化により、メッセージの保全性と機密性を実現することができます。

WS-Security ポリシー

X.509 トークンを使用して XML メッセージを保護するには、まず、Web サービス記述言語 (WSDL) で指定された契約を作成する必要があります。Web サービスの WSDL ファイルに WS-Security ポリシーが含まれている必要があります。WS-Security ポリシーには、AsymmetricBinding アサーションまたは SymmetricBinding アサーションを含めることができます。

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. 要求/応答チェーンの各パートでのイニシエーターおよび受信側のトークンの使用
* イニシエーター・トークン 受信側トークン
要求の発信 (要求側) 署名 暗号化
要求の着信 (プロバイダー) 署名の検証 暗号化解除
応答の発信 (プロバイダー) 暗号化 署名
応答の着信 (要求側) 暗号化解除 署名の検証
秘密鍵は、メッセージの署名と暗号化解除に使用されます。 パブリック証明書は、メッセージの暗号化と署名の検証に使用されます。 秘密鍵は、鍵のユーザー (署名者または暗号化解除者) に属します。

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 アサーションもそのトークン・アサーションに含まれる場合、 そのトークンは、メッセージに 2 回組み込まれる必要があります。 そうした組み合わせは誤りではありませんが、効率上の理由では避けたほうが適切です。

IncludeToken アサーションは Liberty で適用されますが、WebSphere Application Server traditional の 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 Services Security のデフォルト構成』を参照してください。

鍵ストア・ファイル、鍵、および証明書

メッセージの署名と暗号化には、パブリック証明書と秘密鍵を使用する必要があります。これらのパブリック証明書と秘密鍵は、鍵ストア・ファイルに保管されます。 鍵ストア・ファイルは、X509Token アサーションの使用時に必要になります。クライアント・サイドの鍵ストア・ファイルには、クライアントの秘密鍵、およびサーバーの公開鍵に対応する証明書のチェーンが含まれます。サーバー・サイドの鍵ストア・ファイルには、サーバーの秘密鍵、およびクライアントの公開鍵に対応する証明書のチェーンが含まれます。

SOAP メッセージの署名および暗号化を行う際、 signaturePropertiesencryptionProperties のプロパティーは WS-Security ランタイム環境によって次のように解釈されます。
  • AsymmetricBinding アサーション

    signatureProperties プロパティーで指定された鍵は、アウトバウンド・メッセージを署名するための秘密鍵として使用され、また、インバウンド・メッセージの暗号化解除にも使用されます。

    encryptionProperties プロパティーで指定された鍵は、アウトバウンド・メッセージを暗号化するための公開鍵として使用され、また、インバウンド・メッセージの署名の検証にも使用されます。

  • SymmetricBinding アサーション

    encryptionProperties プロパティーで指定された鍵が使用され、signatureProperties プロパティーは無視されます。

秘密鍵のパスワードの CallbackHandler

鍵ストアの秘密鍵にアクセスするには、2 つの異なるパスワードを知っている必要があります。 1 つは、秘密鍵が保管された鍵ストアのパスワードです。 もう 1 つは、秘密鍵自体のパスワードです。 鍵ストアのパスワードは signatureProperties または encryptionProperties のいずれかの暗号プロパティーに指定され、 通常、CallbackHandler クラスを WS-Security が使用して鍵ストア内の秘密鍵にアクセスします。 Liberty では、この CallbackHandler クラスを Liberty フィーチャーとしてパッケージ化して、そのクラス名を security.xmlws-security.callback-handler カスタム・プロパティーの値として指定する必要があります。

この CallbackHandler クラスは、WS-Security が鍵ストア内の秘密鍵にアクセスするために必要です。

パスワードの CallbackHandler クラスについて詳しくは、 『WS-Security 用のパスワード・コールバック・ハンドラーの開発』を参照してください。

CallbackHandler クラスが秘密鍵のパスワードを指定しな い場合、秘密鍵のパスワードが 指定されるように ws-security ランタイムが CallbackHandler を試行してから、暗号プロパティーに指 定されたパスワードが秘密鍵のデフォルト・パスワードとして使用されます。このプロパティーは org.apache.ws.security.crypto.merlin.keystore.private.password として構成されます。

security.xml ファイルの wsSecurityClientwsSecurityProvider の各セクションでサポートされる ws-security.callback-handler カスタム・プロパティーは 1 つしかないため、 単一のパスワード・コールバック・ハンドラーで、各アプリケーション・タイプ (クライアントまたはサーバー) の、デフォルトを使用する必要なすべてのパスワードをサポートする必要があります。 プロバイダー・アプリケーションはすべて、デフォルトのパスワード・コールバック・ハンドラーを使用しなければなりません。 クライアント・アプリケーションは、当該クライアントの 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 を使用して、サービスへのアクセスを制御する ことができます。

CRL ファイルで失効検査を実行するように、Liberty の WS-Security フィーチャーを構成するには、2 つのステップが必要です。CRL ファイルによる証明書失効検査を有効にするには、 server.xml ファイルで WS-Security ランタイム構成を変更してください。
  1. wsSecurityProvider エレメントまたは wsSecurityClient エレメントの中に、次のプロパティーを追加します。
    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