Web-Services mit einem X.509-Token schützen
Liberty unterstützt die OASIS-Spezifikation "Web Services Security X.509 Certificate Token Profile 1.1". Ein X.509-Token kann für die Signatur und Verschlüsselung von Nachrichten verwendet werden und so die Nachrichtenintegrität und -vertraulichkeit gewährleisten.
WS-Security-Richtlinie
Wenn Sie eine XML-Nachricht mit einem X.509-Token schützen möchten, muss zunächst ein in Web Services Description Language (WSDL) angegebener Vertrag erstellt werden. In der WSDL-Datei muss eine WS-Security-Richtlinie für den Web-Service eingefügt werden. Die WS-Security-Richtlinie kann Zusicherungen vom Typ AsymmetricBinding oder SymmetricBinding enthalten.
<sp:X509Token sp:IncludeToken=
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:WssX509V3Token10 />
</wsp:Policy>
</sp:X509Token>
- Der Initiator-X509Token wird verwendet, um die Nachrichtensignatur vom Anforderer an den Provider und die Nachrichtenverschlüsselung vom Provider an den Anforderer zu senden.
- Das Empfänger-X509Token wird verwendet, um die Nachrichtensignatur vom Provider an den Anforderer und die Nachrichtenverschlüsselung vom Anforderer an den Provider zu senden.
* | Initiatortoken | Empfängertoken |
---|---|---|
Abgehende Anforderung (Anforderer) | Signieren | Verschlüsseln |
Eingehende Anforderung (Provider) | Signatur überprüfen | Entschlüsseln |
Abgehende Antwort (Provider) | Verschlüsseln | Signieren |
Eingehende Antwort (Anforderer) | Entschlüsseln | Signatur überprüfen |
In einer Zusicherung des Typs SymmetricBinding wird ein geheimer oder ephemerer Schlüssel, der für ein X.509-Token geschützt ist, vom Initiator und vom Empfänger gemeinsam genutzt. Außerdem wird der Schlüssel für die Verschlüsselung und die Entschlüsselung verwendet.
<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>
Tokenreferenz und Tokeneinschluss
Eine Tokenzusicherung kann ein Attribut vom Typ sp:IncludeToken enthalten, das den Einschluss des Tokens in die Nachricht voraussetzt. Mehrere Tokenzusicherungen unterstützen, zusätzlich zu direkten Referenzen, Mechanismen für die Referenzierung von Token. Wenn eine Tokenzusicherung mehrere Referenzzusicherungen enthält, müssen die Referenzen auf dieses Token alle angegebenen Referenztypen enthalten. Wenn eine Tokenzusicherung beispielsweise ein Attribut vom Typ sp:IncludeToken mit dem Wert ../Always und außerdem noch eine verschachtelte Zusicherung vom Typ sp:RequireIssuerSerialReference enthält, muss das Token zweimal in die Nachricht eingeschlossen werden. Kombinationen dieser Art sind zwar keine Fehler, sollten jedoch aus Effizienzgründen vermieden werden.
Die IncludeToken-Zusicherung wird in Liberty erzwungen, in der WS-Security-Laufzeitumgebung von WebSphere Application Server Traditional jedoch ignoriert.
- KeyIdentifier: <sp:RequireKeyIdentifierReference... />
- IssuerSerial: <sp:RequireIssuerSerialReference ... />
- Thumbprint: <sp:RequireThumbprintReference ... />
Diese Referenzen werden verwendet, wenn man ein X.509-Token auf der Client/Generatorseite generiert. Sie werden nicht auf der Server-/Konsumentenseite erzwungen.
Laufzeitkonfiguration
Die Laufzeit des WS-Security-Features in Liberty stellt mehr Konfigurationsoptionen für Nachrichtenschutz mit einem X.509-Token zur Verfügung als von der WS-Security-Richtlinie abgedeckt werden. Die Laufzeitkonfiguration wird in der Datei server.xml definiert. Die Laufzeitkonfiguration enthält Verschlüsselungseigenschaften wie signatureProperties und encryptionProperties, Schlüssel und Keystores.
<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>
Die Eigenschaften signatureProperties und encryptionProperties in der Laufzeitkonfiguration sind äquivalent zu den Verschlüsselungseigenschaften in der WSS4J-Konfiguration. Weitere Informationen finden Sie unter WSS4J configuration. Viele Verschlüsselungseigenschaften haben gültige Standardwerte, d. h., sie müssen nicht angegeben werden. Andere Eigenschaften, wie Keystoreeigenschaften und Eigenschaften, die sich auf Schlüssel beziehen, müssen jedoch angegeben werden.
Weitere Informationen zu diesen Eigenschaften finden Sie im Artikel WS-Security-Standardkonfiguration.
Keystoredateien, Schlüssel und Zertifikate
Für die Nachrichtensignatur und -verschlüsselung werden öffentliche Zertifikate und private Schlüssel benötigt. Diese öffentlichen Zertifikate und privaten Schlüssel werden in Keystoredateien gespeichert. Keystoredateien sind erforderlich, wenn Sie X509Token-Zusicherungen verwenden. Die clientseitige Keystoredatei enthält den privaten Schlüssel des Clients und eine Kette von Zertifikaten, die dem öffentlichen Schlüssel des Servers entsprechen. Die serverseitige Keystoredatei enthält den privaten Schlüssel des Servers und eine Kette von Zertifikaten, die dem öffentlichen Schlüssel des Clients entsprechen.
- Zusicherung vom Typ "AsymmetricBinding"
Der von der Eigenschaft signatureProperties angegebene Schlüssel wird als privater Schlüssel für das Signieren der abgehenden Nachricht und außerdem für das Entschlüsseln der eingehenden Nachricht verwendet.
Der von der Eigenschaft encryptionProperties angegebene Schlüssel wird als öffentlicher Schlüssel für die Verschlüsselung der abgehenden Nachricht und außerdem für die Überprüfung der Signatur in der eingehenden Nachricht verwendet.
- Zusicherung vom Typ "SymmetricBinding"
Der von den encryptionProperties-Eigenschaften angegebene Schlüssel wird verwendet, die Eigenschaft signatureProperties wird ignoriert.
Kennwort-Callback-Handler des privaten Schlüssels
Sie müssen zwei verschiedene Kennwörter kennen, um auf einen privaten Schlüssel in einem Keystore zuzugreifen. Ein Kennwort ist für den Keystore vorgesehen, in dem der private Schlüssel gespeichert wird. Das andere Kennwort ist für den privaten Schlüssel selbst vorgesehen. Das Kennwort für den Keystore wird in einer der Verschlüsselungseigenschaften, signatureProperties oder encryptionProperties, angegeben, und die Klasse CallbackHandler wird normalerweise von WS-Security für den Zugriff auf den privaten Schlüssel in einem Keystore verwendet. In Liberty muss diese Callbackhandler-Klasse als Liberty-Feature gepackt und ihr Klassenname als Wert für die angepasste Eigenschaft ws-security.callback-handler in der Datei security.xml angegeben werden.
Diese CallbackHandler-Klasse wird von WS-Security für den Zugriff auf den privaten Schlüssel in einem Keystore vorausgesetzt.
Weitere Informationen zur Kennwortklasse CallbackHandler finden Sie unter Kennwort-Callback-Handler für WS-Security entwickeln.Wenn die CallbackHandler-Klasse kein Kennwort für den privaten Schlüssel bereitstellt, probiert die ws-security-Laufzeit zuerst CallbackHandler, damit es bereitgestellt wird. Anschließend wird das Kennwort, das in den crypto-Eigenschaften angegeben ist, als Standardkennwort für den privaten Schlüssel verwendet. Diese Eigenschaft wird als org.apache.ws.security.crypto.merlin.keystore.private.password konfiguriert.
Da es in jedem wsSecurityClient- und wsSecurityProvider-Abschnitt der Datei security.xml nur eine angepasste Eigenschaft vom Typ ws-security.callback-handler gibt, muss ein einziger Kennwort-Callback-Handler alle erforderlichen Kennwörter für jeden Anwendungstyp (Client oder Server) unterstützen, die die Standardwerte verwenden. Alle Provideranwendungen müssen den standardmäßig verwendeten Kennwort-Callback-Handler nutzen. Clientanwendungen können den Standard-Callback-Handler durch Angabe der angepassten Eigenschaft ws-security.callback-handler im Anforderungskontext für den Web-Service-Aufruf des Clients außer Kraft setzen.
Wenn Sie Kennwörter für einen privaten X.509-Schlüssel und ein Benutzernamenstoken für einzelne Web-Service-Aufrufe bereitstellen müssen, können Sie nicht für jede Verwendung eigenständige Callback-Handler angeben. In diesem Fall müssen Sie einen einzelnen Callback-Handler implementieren, der beide Arten von Kennwörtern handhabt. Wie im vorherigen Beispiel veranschaulicht, müssen Sie die Methode WSPasswordCallback.getUsage() verwenden, um festzustellen, welche Art von Kennwort zurückgegeben wird. Die unterstützten Verwendungscodes können Sie der Dokumentation zur API WSPasswordCallback entnehmen: http://ws.apache.org/wss4j/apidocs/org/apache/wss4j/common/ext/WSPasswordCallback.html.
Zertifikatswiderrufsliste
Eine Zertifikatswiderrufsliste (Certificate Revocation List = CRL) ist eine Liste mit Seriennummern für Zertifikate, die widerrufen wurden. Eine Zertifikatswiderrufsliste ist entweder eine eigenständige Datei oder sie ist in einem PKCS#7-Wrapper gepackt. Sie können eine Zertifikatswiderrufsliste zusammen mit einem Truststore verwenden, um den Zugriff auf einen Service zu steuern.
- Fügen Sie im Element wsSecurityProvider oder wsSecurityClient die folgende Eigenschaft hinzu:
ws-security.enableRevocation="true"
- Fügen Sie im Element signatureProperties die folgende Eigenschaft hinzu, und geben Sie als Wert eine CRL-Datei an:
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>