SOAP-Nachrichten mit der Anwendungsprogrammierschnittstelle "WSSDecryption" entschlüsseln

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. Wenn Sie den Client für Entschlüsselung auf Antwortkonsumentenseite (Client) konfigurieren möchten, verwenden Sie die API "WSSDecryption", um die SOAP-Nachrichten zu entschlüsseln. Die API "WSSDecryption" gibt beim Konfigurieren des Clients an, welche Abschnitte der SOAP-Nachrichten entschlüsselt werden sollen.

Vorbereitende Schritte

Sie können die WSS-API oder Richtliniensätze in der Administrationskonsole verwenden, um die Entschlüsselung zu aktivieren und Konsumentensicherheitstoken in der SOAP-Nachricht hinzuzufügen. Zum Sichern der SOAP-Nachrichten müssen Sie die folgenden Entschlüsselungstasks ausgeführt haben:

  • Die SOAP-Nachricht wurde verschlüsselt.
  • Die Entschlüsselungsmethode wurde ausgewählt.

Informationen zu dieser Task

Die Entschlüsselungsdaten auf der Konsumentenseite werden verwendet, um eine eingehende SOAP-Nachricht für die Antwortkonsumentenbindungen (Clientseite) zu entschlüsseln. Die Konfiguration des Clientkonsumenten muss mit der Konfiguration des Providergenerators übereinstimmen.

Vertraulichkeitseinstellungen erfordern, dass Vertraulichkeitsbedingungen auf generierte Nachrichten angewendet werden.

Die folgenden Entschlüsselungsabschnitte können konfiguriert werden:

Tabelle 1. Entschlüsselungsabschnitte. Verwenden Sie die Entschlüsselungsabschnitte, um Nachrichten zu sichern.
Entschlüsselungsabschnitte Beschreibung
Abschnitt Fügt das WSSDecryptPart-Objekt als Ziel für den Entschlüsselungsabschnitt hinzu.
Schlüsselwort Fügt den Entschlüsselungsabschnitt mit Schlüsselwörtern hinzu. WebSphere® Application Server unterstützt die folgenden Schlüsselwörter:
  • BODY_CONTENT
  • SIGNATUR
  • USERNAME_TOKEN
xpath Fügt den Entschlüsselungsabschnitt mit einem XPath-Ausdruck hinzu.
Prüfung Fügt die WSSVerification-Instanz als Ziel des Entschlüsselungsabschnitts hinzu.
Überschrift Fügt den SOAP-Header nach QName als Ziel des Entschlüsselungsabschnitts hinzu.

Bei der Entschlüsselung sind bestimmte Standardverhalten zu beobachten. Die WSS-API lässt sich am einfachsten über den Einsatz des Standardverhaltens verwenden (siehe Beispielcode). WSSDecryption stellt Standardeinstellungen für den Algorithmus für Schlüsselchiffrierung, den Algorithmus für Datenverschlüsselung und die Entschlüsselungsabschnitte, wie z. B. den Inhalt des SOAP-Hauptteils (Body) und die Signatur, bereit. Im Folgenden sind die Standardverhalten bei der Entschlüsselung beschrieben:

Tabelle 2. Entschlüsselungsentscheidungen. Verschiedene Kenndaten von Entschlüsselungsabschnitten werden standardmäßig konfiguriert.
Entscheidungen bzgl. der Entschlüsselung Standardverhalten
Zu entschlüsselnde Abschnitte

Die Standardentschlüsselungsabschnitte sind BODY_CONTENT und SIGNATURE. WebSphere Application Server unterstützt die Verwendung der folgenden Schlüsselwörter:

  • WSSDecryption.BODY_CONTENT
  • WSSDecryption.SIGNATURE
  • WSSDecryption.USERNAME_TOKEN

Nachdem Sie die zu entschlüsselnden Nachrichtenabschnitte angegeben haben, müssen Sie die Methode angeben, die zum Entschlüsseln der Konsumentenanforderungsnachricht verwendet werden soll. Wenn beispielsweise Signatur und Hauptteilinhalt für Verschlüsselung ausgewählt wurden, werden dieselben Abschnitte der SOAP-Nachricht auch entschlüsselt.

Verschlüsselung des Schlüssels (isEncrypt) Standardmäßig wird der Schlüssel verschlüsselt (true).
Auszuwählender Algorithmus für Datenentschlüsselung (Methode)

Der Standardalgorithmus für die Datenentschlüsselung ist AES128. WebSphere Application Server unterstützt die folgenden Datenverschlüsselungsverfahren:

  • WSSDecryption.AES128: http://www.w3.org/2001/04/xmlenc#aes128-cbc
  • WSSDecryption.AES192: http://www.w3.org/2001/04/xmlenc#aes192-cbc
  • WSSDecryption.AES256: http://www.w3.org/2001/04/xmlenc#aes256-cbc
  • WSSDecryption.TRIPLE_DES: http://www.w3.org/2001/04/xmlenc#tripledes-cbc
Auszuwählende Methode für Schlüsseldechiffrierung (Algorithmus)

Der Standardalgorithmus für die Schlüsseldechiffrierung ist RSA OAEP. WebSphere Application Server unterstützt die folgenden Schlüsselverschlüsselungsverfahren:

  • WSSDecryption.KW_AES128: http://www.w3.org/2001/04/xmlenc#kw-aes128
  • WSSDecryption.KW_AES192: http://www.w3.org/2001/04/xmlenc#kw-aes192
  • WSSDecryption.KW_AES256: http://www.w3.org/2001/04/xmlenc#kw-aes256
  • WSSDecryption.KW_RSA_OAEP: http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
  • WSSDecryption.KW_RSA15: http://www.w3.org/2001/04/xmlenc#rsa-1_5
  • WSSDecryption.KW_TRIPLE_DES: http://www.w3.org/2001/04/xmlenc#kw-tripledes
Anzugebendes Sicherheitstoken

Der Standardtyp für Sicherheitstoken ist X509. WebSphere Application Server stellt die folgenden vorkonfigurierten Tokentypen für Konsumenten bereit:

  • Abgeleitetes Schlüsseltoken
  • X509-Token

Vorgehensweise

  1. Wenn Sie die SOAP-Nachricht mithilfe der Anwendungsprogrammierschnittstelle "WSSDecryption" entschlüsseln möchten, müssen Sie zuerst sicherstellen, dass der Anwendungsserver installiert ist.
  2. Der WSS-API-Prozess zur Entschlüsselung teilt sich in die folgenden Schritte auf:
    1. Mit WSSFactory.getInstance() die Instanz der WSS-API-Implementierung abrufen.
    2. WSSConsumingContext-Instanz aus der WSSFactory-Instanz erstellen.
      WSSConsumingContext muss immer in der JAX-WS-Clientanwendung aufgerufen werden.
    3. Callback-Handler für die Konsumentenseite erstellen.
    4. WSSDecryption mit der Klasse für das Sicherheitstoken und den Callback-Handler aus der WSSFactory-Instanz erstellen.
      Standardmäßig geht WSSDecryption davon aus, dass der Hautteilinhalt und die Signatur verschlüsselt sind.
    5. Zu entschlüsselnden Abschnitte hinzufügen, falls die Standardeinstellungen nicht angemessen sind.
    6. Für die Entschlüsselung in Frage kommenden Kandidaten für die Datenverschlüsselungsmethoden hinzufügen.
    7. Für die Entschlüsselung in Frage kommenden Kandidaten für die Schlüsselchiffriermethoden hinzufügen.
    8. Für die Entschlüsselung in Frage kommenden Kandidaten für das Sicherheitstoken hinzufügen.
    9. WSSDecryption.encryptKey(false) aufrufen, wenn die Anwendung keine Verschlüsselung des Schlüssels in der eingehenden Nachricht wünscht.
    10. WSSDecryption zu WSSConsumingContext hinzufügen.
    11. WSSConsumingContext.process() mit dem SOAPMessageContext aufrufen.

Ergebnisse

Wenn bei der Entschlüsselung eine Fehlerbedingung eintritt, wird eine Ausnahme vom Typ "WSSException" angezeigt. Bei erfolgreicher Ausführung wird WSSConsumingContext.process() aufgerufen, und Web Services Security wird auf die SOAP-Nachricht angewendet.

Beispiel

Im folgenden Beispiel wird Code für die Entschlüsselung des Inhalts des SOAP-Nachrichtenhauptteils gezeigt:

// Get the message context
   Object msgcontext = getMessageContext();

// Generate the WSSFactory instance (step: a)
   WSSFactory factory = WSSFactory.getInstance();

// Generate the WSSConsumingContext instance (step: b)
   WSSConsumingContext gencont = factory.newWSSConsumingContext();

// Generate the callback handler (step: c)
   X509ConsumeCallbackHandler callbackHandler = new 
       X509ConsumeCallbackHandler(
                                  "",
                                  "enc-sender.jceks",
                                  "jceks", 
                                  "storepass".toCharArray(), 
                                  "alice", 
                                  "keypass".toCharArray(), 
	"CN=Alice, O=IBM, C=US");

// Generate the WSSDecryption instance (step: d)
   WSSDecryption dec = factory.newWSSDecryption(X509Token.class, 
                                                callbackHandler);

// Set the part to be encrypted (step: e)
// DEFAULT: WSSEncryption.BODY_CONTENT and WSSEncryption.SIGNATURE

// Set the part to be encrypted (step: e)
// DEFAULT: WSSEncryption.BODY_CONTENT and WSSEncryption.SIGNATURE

// Set the part specified by the keyword (step: e)
      dec.addRequiredDecryptPart(WSSDecryption.BODY_CONTENT);

// Set the part in the SOAP Header specified by QName (step: e)
    dec.addRequiredDecryptHeader(new 
       QName("http://www.w3.org/2005/08/addressing", 
       "MessageID"));

// Set the part specified by WSSVerification  (step: e)
   X509ConsumeCallbackHandler verifyCallbackHandler = 
      getCallbackHandler();
   WSSVerification ver = factory.newWSSVerification(X509Token.class, 
                                                    verifyCallbackHandler);
      dec.addRequiredDecryptPart(ver);

// Set the part specified by XPath expression (step: 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']");
      dec.addRequiredDecryptPartByXPath(sb.toString());

// Set the part in the SOAP header to be decrypted specified by QName (step: e)
      dec.addRequiredDecryptHeader(new 
          QName("http://www.w3.org/2005/08/addressing", 
          "MessageID"));

// Set the candidates for the data encryption method (step: f)
// DEFAULT : WSSDecryption.AES128
      dec.addAllowedEncryptionMethod(WSSDecryption.AES128);
      dec.addAllowedEncryptionMethod(WSSDecryption.AES192);

// Set the candidates for the key encryption method (step: g)
// DEFAULT : WSSDecryption.KW_RSA_OAEP
      dec.addAllowedKeyEncryptionMethod(WSSDecryption.KW_TRIPLE_DES);

// Set the candidate security token to used for the decryption (step: h)
   X509ConsumeCallbackHandler callbackHandler2 = getCallbackHandler2();
      dec.addToken(X509Token.class, callbackHandler2);

// Set whether or not the key should be encrypted in the incoming SOAP message (step: i) 
// DEFAULT: true
      dec.encryptKey(true);

// Add the WSSDecryption to the WSSConsumingContext (step: j)
   concont.add(dec);

// Validate the WS-Security header (step: k)
concont.process(msgcontext);

Nächste Schritte

Verwenden Sie die API "WSSDecryptPart" oder konfigurieren Sie Richtliniensätze über die Administrationskonsole, um entschlüsselte Abschnitte für die Konsumentennachricht hinzuzufügen.