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 アサーションを含めることができます。
<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 が、プロバイダーから要求側へのメッセージの署名、および要求側からプロバイダーへのメッセージの暗号化に使用されます。
* | イニシエーター・トークン | 受信側トークン |
---|---|---|
要求の発信 (要求側) | 署名 | 暗号化 |
要求の着信 (プロバイダー) | 署名の検証 | 暗号化解除 |
応答の発信 (プロバイダー) | 暗号化 | 署名 |
応答の着信 (要求側) | 暗号化解除 | 署名の検証 |
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 アサーションもそのトークン・アサーションに含まれる場合、 そのトークンは、メッセージに 2 回組み込まれる必要があります。 そうした組み合わせは誤りではありませんが、効率上の理由では避けたほうが適切です。
IncludeToken アサーションは Liberty で適用されますが、WebSphere Application Server traditional の 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 Services Security のデフォルト構成』を参照してください。
鍵ストア・ファイル、鍵、および証明書
メッセージの署名と暗号化には、パブリック証明書と秘密鍵を使用する必要があります。これらのパブリック証明書と秘密鍵は、鍵ストア・ファイルに保管されます。 鍵ストア・ファイルは、X509Token アサーションの使用時に必要になります。クライアント・サイドの鍵ストア・ファイルには、クライアントの秘密鍵、およびサーバーの公開鍵に対応する証明書のチェーンが含まれます。サーバー・サイドの鍵ストア・ファイルには、サーバーの秘密鍵、およびクライアントの公開鍵に対応する証明書のチェーンが含まれます。
- AsymmetricBinding アサーション
signatureProperties プロパティーで指定された鍵は、アウトバウンド・メッセージを署名するための秘密鍵として使用され、また、インバウンド・メッセージの暗号化解除にも使用されます。
encryptionProperties プロパティーで指定された鍵は、アウトバウンド・メッセージを暗号化するための公開鍵として使用され、また、インバウンド・メッセージの署名の検証にも使用されます。
- SymmetricBinding アサーション
encryptionProperties プロパティーで指定された鍵が使用され、signatureProperties プロパティーは無視されます。
秘密鍵のパスワードの CallbackHandler
鍵ストアの秘密鍵にアクセスするには、2 つの異なるパスワードを知っている必要があります。 1 つは、秘密鍵が保管された鍵ストアのパスワードです。 もう 1 つは、秘密鍵自体のパスワードです。 鍵ストアのパスワードは signatureProperties または encryptionProperties のいずれかの暗号プロパティーに指定され、 通常、CallbackHandler クラスを WS-Security が使用して鍵ストア内の秘密鍵にアクセスします。 Liberty では、この CallbackHandler クラスを Liberty フィーチャーとしてパッケージ化して、そのクラス名を security.xml で ws-security.callback-handler カスタム・プロパティーの値として指定する必要があります。
この CallbackHandler クラスは、WS-Security が鍵ストア内の秘密鍵にアクセスするために必要です。
パスワードの CallbackHandler クラスについて詳しくは、 『WS-Security 用のパスワード・コールバック・ハンドラーの開発』を参照してください。CallbackHandler クラスが秘密鍵のパスワードを指定しな い場合、秘密鍵のパスワードが 指定されるように ws-security ランタイムが CallbackHandler を試行してから、暗号プロパティーに指 定されたパスワードが秘密鍵のデフォルト・パスワードとして使用されます。このプロパティーは org.apache.ws.security.crypto.merlin.keystore.private.password として構成されます。
security.xml ファイルの wsSecurityClient と wsSecurityProvider の各セクションでサポートされる 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 を使用して、サービスへのアクセスを制御する ことができます。
- 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>