Signaturdaten mit der API WSSSignature konfigurieren

Sie können die SOAP-Nachrichten ohne Verwendung von Richtliniensätzen für die Konfiguration sichern, indem Sie die Anwendungsprogrammierschnittstellen (API, Application Programming Interface) von Web Services Security (WSS-API) verwenden. Verwenden Sie zum Konfigurieren der Signaturdaten für die Abschnitte mit den Generatorbindungen für die clientseitige Anforderungen die API WSSSignature. Die API WSSSignature gehört zum Paket com.ibm.websphere.wssecurity.wssapi.signature.

Vorbereitende Schritte

Zum Aktivieren der Signaturdaten können Sie die WSS-API verwenden oder die Richtliniensätze über die Administrationskonsole konfigurieren. Wenn Sie SOAP-Nachrichten sichern möchten, müssen Sie die folgenden Signaturtasks ausführen:

  • Signaturdaten konfigurieren,
  • Signaturmethoden auswählen,
  • signierte Abschnitte bei Bedarf hinzufügen oder ändern.

Informationen zu diesem Vorgang

WebSphere Application Server verwendet die Signaturdaten für den Standardgenerator, um Abschnitte der Nachricht zu signieren, und verwendet die digitale XML-Signatur mit vorhandenen Algorithmen wie RSA-SHA1 und HMAC-SHA1.

Die XML-Signatur definiert viele Methoden zur Beschreibung von Schlüsselinformationen und ermöglicht die Definition einer neuen Methode. XML-Kanonisierung (C14N) ist häufig erforderlich, wenn Sie mit XML-Signaturen arbeiten. Informationen können auf vielerlei Weise in serialisierten XML-Dokumenten verwendet werden. Der C14N-Prozess wird zum Kanonisieren von XML-Daten verwendet. Wählen Sie einen entsprechenden C14N-Algorithmus aus, weil die Daten, die kanonisiert werden, von diesem Algorithmus abhängig sind.

Die Signaturdaten geben die Integritätsbedingungen an, die auf generierte Nachrichten angewendet werden. Zu diesen Bedingungen gehört auch, welche Nachrichtenabschnitte digital signiert und welchen Nachrichtenabschnitten digital signierte Nonce- und Zeitmarkenelemente zugeordnet werden müssen. Die folgenden Signaturdaten und zugehörigen Signaturabschnittsdaten werden konfiguriert:

Tabelle 1. Informationen zu Signaturabschnitten. Verwenden Sie die Signaturabschnitte, um Nachrichten zu sichern.
Signaturabschnitte Beschreibung
keyword
Fügt einen Signaturabschnitt mit Schlüsselwörtern hinzu. Verwenden Sie die folgenden Schlüsselwörter für die zu signierenden Abschnitte:
  • ADDRESSING_HEADERS
  • BODY
  • TIMESTAMP
Die WS-Addressing-Header werden nicht verschlüsselt, können aber signiert werden.
xpath Fügt einen Signaturabschnitt mit einem XPath-Ausdruck hinzu.
part Fügt ein WSSSignPart-Objekt als Ziel des Signaturabschnitts hinzu.
timestamp Fügt ein WSSTimestamp-Objekt als Ziel des Signaturabschnitts hinzu. Wenn diese Option angegeben ist, geben die Zeitmarkeninformationen auch an, wann die Nachricht generiert wird und wann sie verfällt.
header Fügt den Header nach QName als Ziel des Signaturabschnitts hinzu.
securityToken Fügt ein SecurityToken-Objekt als Ziel des Signaturabschnitts hinzu.

Bei Signaturabschnitten sind bestimmte Standardverhalten zu beobachten. Die API WSSSignature lässt sich am einfachsten über den Einsatz des Standardverhaltens verwenden (siehe Beispielcode). Die Standardwerte für die Signaturmethode, die Kanonisierungsmethode, die Sicherheitstokenreferenzen und die Signaturabschnitte werden von der WSS-API definiert.

Tabelle 2. Standardverhalten für Signatur. Für die Signatur werden verschiedene Verhaltensweisen standardmäßig konfiguriert.
Entscheidungen bzgl. der Signatur Standardverhalten
Zu verwendende Schlüsselwörter Legt die Schlüsselwörter fest. WebSphere Application Server unterstützt standardmäßig die folgenden Schlüsselwörter:
  • ADDRESSING_HEADERS
  • BODY
  • TIMESTAMP
Zu verwendende Signaturmethode Legt den Signaturalgorithmus fest. Die Standardsignaturmethode ist RSA SHA1. WebSphere Application Server unterstützt die folgenden vorkonfigurierten Signaturmethoden:
  • WSSSignature.RSA_SHA1: http://www.w3.org/2000/09/xmldsig#rsa-sha1
  • WSSSignature.HMAC_SHA1: http://www.w3.org/2000/09/xmldsig#hmac-sha1
Die digitale Signaturmethode DSA-SHA1 (http://www.w3.org/2000/09/xmldsig#dsa-sha1) wird nicht unterstützt.
Zu verwendende Kanonisierungsmethode Legt den Kanonisierungsalgorithmus fest. Die Standardkanonisierungsmethode ist EXC C14N. WebSphere Application Server unterstützt die folgenden vorkonfigurierten Kanonisierungsmethoden:
  • WSSSignature.EXC_C14N; http://www.w3.org/2001/10/xml-exc-c14n#
  • WSSSignature.C14N: http://www.w3.org/2001/10/xml-c14n#
Signaturbestätigung erforderlich? Legt fest, ob eine Signaturbestätigung erforderlich ist. Der Standardwert ist false. Signaturdaten sind in der OASIS-Spezifikation OASIS Web Services Security Version 1.1 definiert. Sofern erforderlich, wird der Wert Ihrer Signaturdaten gespeichert, um ihn nach dem Empfang der Nachricht, die die Signaturbestätigung in der Antwortnachricht generiert hat, für die Validierung der Signaturbestätigung zu verwenden. Diese Methode ist für die Anfordererseite bestimmt.
Zu verwendendes Sicherheitstoken

Legt das SecurityToken fest. Der Tokentyp gibt an, welcher Typ von Token für die Signatur und Validierung von Nachrichten verwendet werden soll. Standardmäßig wird ein X.509-Token verwendet.

WebSphere Application Server stellt die folgenden vorkonfigurierten Typen von Konsumententoken bereit:

  • Abgeleitetes Schlüsseltoken
  • X509-Token

Bei Bedarf können Sie aus angepasste Tokentypen erstellen:

Festzulegende Tokenreferenz Legt den refType fest. SecurityToken.REF_STR ist der Standardwert für den Tokenreferenztyp. WebSphere Application Server unterstützt die folgenden vorkonfigurierten Typen von Tokenreferenzen:
  • SecurityToken.REF_STR
  • SecurityToken.REF_KEYID
  • SecurityToken.REF_EMBEDDED
  • SecurityToken.REF_THUMBPRINT

Wenn WSSSignature.requireSignatureConfirmation() aufgerufen wird, erwartet die API WSSSignature, dass die Antwortnachricht die Signaturbestätigung enthält.

Vorgehensweise

  1. Wenn Sie die Signaturdaten in einer SOAP-Nachricht über die WSS-API konfigurieren möchten, müssen Sie zuerst sicherstellen, dass der Anwendungsserver installiert ist.
  2. Verwenden Sie die API WSSSignature, um die Nachrichtenabschnitte zu signieren und die Algorithmen in einer SOAP-Nachricht anzugeben. Der WSS-API-Prozess für die Signatur teilt sich in die folgenden Schritte auf:
    1. Mit WSSFactory.getInstance() die Instanz der WSS-API-Implementierung abrufen.
    2. WSSGenerationContext-Instanz aus der WSSFactory-Instanz erstellen. In einer JAX-WS-Clientanwendung muss WSSGenerationContext aufgerufen werden.
    3. SecurityToken aus WSSFactory erstellen, um den Schlüssel für die Signatur zu konfigurieren.
    4. Mit dem SecurityToken die WSSSignature aus der WSSFactory-Instanz erstellen. Standardmäßig signiert WSSSignature die folgenden Signaturabschnitte: BODY, ADDRESSING_HEADERS und TIMESTAMP.
    5. Zu signierenden Abschnitt hinzufügen, wenn der Standardabschnitt nicht angemessen ist. Wenn die Digest- oder Umsetzungsmethode geändert wird, WSSSignPart erstellen und WSSSignature hinzufügen.
    6. WSSSignaturePart erstellen und WSSSignature hinzufügen. Die Methode requiredSignatureConfirmation() aufrufen, wenn die Signaturbestätigung angewendet werden soll.
    7. Kanonisierungsmethode festlegen, wenn die Standardmethode nicht angemessen ist.
    8. Signaturmethode festlegen, wenn die Standardmethode nicht angemessen ist.
    9. Tokenreferenz festlegen, wenn die Standardeinstellung nicht angemessen ist.
    10. WSSSignature zu WSSGenerationContext hinzufügen.
    11. WSSGenerationContext.process() mit dem SOAPMessageContext aufrufen.

Ergebnisse

Sie haben die Schritte zum Konfigurieren der Signatur für den Generatorabschnitt der Bindungen ausgeführt. Wenn beim Signieren der Nachrichtenabschnitte eine Fehlerbedingung eintritt, wird eine Ausnahme vom Typ WSSException ausgelöst. Bei erfolgreicher Signatur wird WSSGenerationContext.process() aufgerufen, und Web Services Security wird auf die SOAP-Nachricht angewendet.

Beispiel

Im folgenden Beispielcode werden Methoden verwendet, die in der API WSSignature definiert sind.

// Nachrichtenkontext abrufen
   Object msgcontext = getMessageContext();

// Instanz von "com.ibm.websphere.wssecurity.wssapi.WSSFactory" generieren (Schritt: a)
   WSSFactory factory = com.ibm.websphere.wssecurity.wssapi.WSSFactory.getInstance();

// WSSGenerationContext-Instanz generieren (Schritt b)
   WSSGenerationContext gencont = factory.newWSSGenerationContext();

// Callback-Handler generieren
   X509GenerateCallbackHandler callbackHandler = new 
       X509GenerateCallbackHandler(
       "",
       "dsig-sender.ks",
       "jks", 
       "client".toCharArray(), 
       "soaprequester", 
       "client".toCharArray(), 
       "CN=SOAPRequester, OU=TRL, O=IBM, ST=Kanagawa, C=JP", null);

// Für die Signatur zu verwendendes Sicherheitstoken generieren (Schritt c)
   SecurityToken token = factory.newSecurityToken(X509Token.class, 
        callbackHandler);

// WSSSignature-Instanz generieren (Schritt d)
   WSSSignature sig = factory.newWSSSignature(token);

// Zu signierenden Abschnitt festlegen (Schritt e)
// STANDARD: WSSSignature.BODY, WSSSignature.ADDRESSING_HEADERS
//          und WSSSignature.TIMESTAMP.

// Mit dem QName angegebenen Abschnitt im SOAP-Header festlegen (Schritt e)
      sig.addSignHeader(new 
                        QName("http://www.w3.org/2005/08/addressing", 
                        "MessageID"));

// Mit dem Schlüsselwort angegebenen Abschnitt festlegen (Schritt e)
      sig.addSignPart(WSSSignature.BODY);

// Von SecurityToken angegebenen Abschnitt festlegen (Schritt e)
   UNTGenerateCallbackHandler untCallbackHandler = new 
      UNTGenerateCallbackHandler("Chris", "sirhC");
      SecurityToken unt = factory.newSecurityToken(UsernameToken.class, 
         untCallbackHandler);
      sig.addSignPart(unt);

// Von WSSSignPart angegebenen Abschnitt festlegen (Schritt e)
   WSSSignPart sigPart = factory.newWSSSignPart();
      sigPart.setSignPart(WSSSignature.TIMESTAMP);
      sigPart.setDigestMethod(WSSSignPart.SHA256);
      sig.addSignPart(sigPart);

// Von WSSTimestamp angegebenen Abschnitt festlegen (Schritt e)
   WSSTimestamp timestamp = factory.newWSSTimestamp();
      sig.addSignPart(timestamp);

// Mit dem XPath-Ausdruck angegebenen Abschnitt festlegen (Schritt e)
   		StringBuffer sb = new StringBuffer();
      sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
         and local-name()='Envelope']");
      sb.append("/*[namespace-uri()='http://schemas.xmlsoap.org/soap/envelope/' 
         and local-name()='Body']");
      sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping' 
         and local-name()='Ping']");
      sb.append("/*[namespace-uri()='http://xmlsoap.org/Ping' 
         and local-name()='Text']");
      sig.addSignPartByXPath(sb.toString());

// Anwenden der Signaturbestätigung festlegen (Schritt f)
      sig.requireSignatureConfirmation();

// Kanonisierungsmethode festlegen (Schritt g)
// STANDARD: WSSSignature.EXC_C14N
      sig.setCanonicalizationMethod(WSSSignature.C14N);

// Signaturmethode festlegen (Schritt h)
// STANDARD: WSSSignature.RSA_SHA1
      sig.setSignatureMethod(WSSSignature.HMAC_SHA1);

// Tokenreferenz festlegen (Schritt i)
// STANDARD: SecurityToken.REF_STR
      sig.setTokenReference(SecurityToken.REF_KEYID);
	
// WSSSignature zu WSSGenerationContext hinzufügen (Schritt j)
   gencont.add(sig);

// WS-Security-Header generieren (Schritt k)
gencont.process(msgctx);
Anmerkung: Der X509GenerationCallbackHandler benötigt das Schlüsselkennwort, weil der private Schlüssel für die Signatur verwendet wird.

Nächste Schritte

Wählen Sie als Nächstes die Algorithmusmethoden aus, wenn Sie eine von den Standardwerten abweichende Methode verwenden möchten. Wenn die Algorithmusmethoden nicht geändert werden müssen, verwenden Sie als Nächstes die API WSSVerification, um die Signatur zu prüfen und die Algorithmusmethoden im Konsumentenabschnitt der Bindung anzugeben. Die API WSSVerification wird nur im Antwortkonsumenten (Clientseite) unterstützt.


Symbol, das den Typ des Artikels anzeigt. Taskartikel



Symbol für Zeitmarke Letzte Aktualisierung: 25.05.2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_confsignaturegen
Dateiname:twbs_confsignaturegen.html