Configuration des informations de signature à l'aide de l'API WSSSignature

Vous pouvez sécuriser les messages SOAP, sans utiliser d'ensemble de règles de configuration, en utilisant les API Web Services Security (WSS API). Pour configurer les informations de signature pour la liaison du générateur concernant les demandes côté client, utilisez l'API WSSSignature. L'API WSSSignature se trouve dans le package com.ibm.websphere.wssecurity.wssapi.signature.

Avant de commencer

Vous pouvez utiliser l'API WSS ou configurer des ensembles de règles à l'aide de la console d'administration pour activer les informations de signature. Pour sécuriser des messages SOAP, procédez comme suit :

  • Configurez les informations de signature.
  • Choisissez les méthodes de signature.
  • Ajoutez ou modifiez des portions signées, si besoin est.

Pourquoi et quand exécuter cette tâche

WebSphere Application Server utilise les informations de signature du générateur par défaut pour signer les portions de message, et la signature numérique XML avec les algorithmes existants tels que RSA-SHA1 et HMAC-SHA1.

La signature XML définit un grand nombre de méthodes de description des informations clé et active la définition d'une nouvelle méthode. La canonisation XML (C14N) est souvent nécessaire lorsque vous utilisez la signature XML. Les informations peuvent être représentées de différentes manières dans les documents XML sérialisés. Le processus C14N sert à canoniser les informations XML. Sélectionnez un algorithme C14N approprié, sachant que les informations canonisées dépendent de cet algorithme.

Les informations de signature définissent les contraintes d'intégrité appliquées aux messages générés. Ces contraintes incluent l'indication des portions des messages générés qui doivent être signées de façon numérique, ainsi que celles auxquelles associer des éléments nonce et d'horodatage signés numériquement. Les informations suivantes sur la signature et les portions signées sont configurées :

Tableau 1. Informations sur les portions signées. Utilisation des portions signées pour la sécurisation des messages.
Portions signées Description
keyword
Ajoute, à l'aide de mots clés, une portion signée. Définissez les portions signées à l'aide des mots clés suivants :
  • ADDRESSING_HEADERS
  • BODY
  • TIMESTAMP
Les en-têtes WS-Addressing ne sont pas chiffrés mais peuvent être signés.
xpath Ajoute une portion signée à l'aide d'une expression XPath.
part Ajoute un objet WSSSignPart comme cible de la portion signée.
timestamp Ajoute un objet WSSTimestamp comme cible de la portion signée. Lorsqu'elles sont fournies, les informations sur l'horodatage indiquent également à quel moment le message est généré et expire.
header Ajoute l'en-tête, indiqué par QName, comme cible de la portion signée.
securityToken Ajoute un objet SecurityToken comme cible de la portion signée.

Certains comportements par défaut s'appliquent aux informations de signature. La façon la plus simple d'utiliser l'API WSSSignature est d'appliquer les comportements par défaut (voir l'exemple de code). Les valeurs par défaut sont définies par l'API WSS pour la méthode de signature, la méthode de canonisation, les références de jeton de sécurité et les portions signées.

Tableau 2. Comportements par défaut des portions signées. Certaines caractéristiques des portions signées sont configurées par défaut.
Choix de signature Comportement par défaut
Mots clés à employer Définit les mots clés. Par défaut, WebSphere Application Server prend en charge les mots clés suivants :
  • ADDRESSING_HEADERS
  • BODY
  • TIMESTAMP
Méthode de signature à utiliser Définit l'algorithme de signature. La méthode de signature par défaut est RSA SHA1. WebSphere Application Server prend en charge les méthodes de signature préconfigurées suivantes :
  • WSSSignature.RSA_SHA1 : http://www.w3.org/2000/09/xmldsig#rsa-sha1
  • WSSSignature.HMAC_SHA1 : http://www.w3.org/2000/09/xmldsig#hmac-sha1
La méthode de signature numérique DSA-SHA1 (http://www.w3.org/2000/09/xmldsig#dsa-sha1) n'est pas prise en charge.
Méthode de canonisation à utiliser Définit l'algorithme de canonisation. La méthode de canonisation par défaut est EXC C14N. WebSphere Application Server prend en charge les méthodes de canonisation préconfigurées suivantes :
  • WSSSignature.EXC_C14N : http://www.w3.org/2001/10/xml-exc-c14n#
  • WSSSignature.C14N : http://www.w3.org/2001/10/xml-c14n#
Indique si la confirmation de signature est requise. Détermine si la confirmation de signature doit être demandée. La valeur par défaut est false. La confirmation de signature est définie dans la spécification OASIS Web Services Security version 1.1. Si elle est obligatoire, la valeur de confirmation de signature est stockée pour valider la confirmation après la réception du message qui a généré cette confirmation dans le message de réponse. Cette méthode concerne le côté demandeur.
Jeton de sécurité à utiliser

Détermine l'objet SecurityToken. Il s'agit du type de jeton à utiliser pour signer et valider des messages. Le jeton X.509 est le type par défaut.

WebSphere Application Server fournit les types de jeton de destinataire préconfigurés suivants :

  • Jeton de clé dérivée
  • Jetons X509

Vous pouvez aussi créer des types de jeton personnalisés, si besoin est.

Référence de jeton à définir Détermine l'objet refType. SecurityToken.REF_STR est la valeur par défaut pour le type de référence de jeton. WebSphere Application Server prend en charge les types de références de jeton préconfigurés suivants :
  • SecurityToken.REF_STR
  • SecurityToken.REF_KEYID
  • SecurityToken.REF_EMBEDDED
  • SecurityToken.REF_THUMBPRINT

En cas d'appel de WSSSignature.requireSignatureConfirmation(), l'API WSSSignature attend que le message de réponse inclue la confirmation de signature.

Procédure

  1. Pour configurer les informations de signature dans un message SOAP à l'aide de l'API WSS, assurez-vous d'abord que le serveur d'application est installé.
  2. Utilisez l'API WSSSignature pour signer les parties du message et indiquez les algorithmes dans un message SOAP. L'API WSS pour la signature suit la procédure ci-après :
    1. Utilise WSSFactory.getInstance() pour obtenir l'instance d'implémentation d'API WSS.
    2. Crée l'instance WSSGenerationContext à partir de l'instance WSSFactory. WSSGenerationContext doit être appelée dans une application client JAX-WS.
    3. Création de l'objet SecurityToken à partir de WSSFactory pour configurer la clé pour la signature.
    4. Création de WSSSignature à partir de l'instance WSSFactory à l'aide de SecurityToken. Par défaut, WSSSignature signe ces portions : BODY, ADDRESSING_HEADERS et TIMESTAMP.
    5. Ajout de la partie à signer si celle par défaut n'est pas appropriée. Si la méthode de synthèse (digest) ou de transformation est modifiée, elle crée WSSSignPart et l'ajoute à WSSSignature.
    6. Création de WSSSignaturePart dans WSSSignature. Appel de la méthode requiredSignatureConfirmation() si la confirmation de signature doit être appliquée.
    7. Définition de la méthode de canonisation si celle par défaut n'est pas appropriée.
    8. Définition de la méthode de signature si celle par défaut n'est pas appropriée.
    9. Définition de la référence de jeton si celle par défaut n'est pas appropriée.
    10. Ajout de WSSSignature à WSSGenerationContext.
    11. Appelle WSSGenerationContext.process() avec le contexte SOAPMessageContext.

Résultats

Vous avez terminé la procédure de configuration de la signature pour les liaisons de générateur. En cas d'erreur lors de la signature des portions de message, l'exception WSSException est lancée. Si l'opération aboutit, la méthode WSSGenerationContext.process() est appelée et la sécurité des services Web est appliquée au message SOAP.

Exemple

L'exemple suivant fournit un code utilisant des méthodes définies dans l'API WSSignature.

// Obtenir le contexte de message
   Object msgcontext = getMessageContext();

// Générer l'instance com.ibm.websphere.wssecurity.wssapi.WSSFactory (step: a)
   WSSFactory factory = com.ibm.websphere.wssecurity.wssapi.WSSFactory.getInstance();

// Générer l'instance WSSGenerationContext (étape : b)
   WSSGenerationContext gencont = factory.newWSSGenerationContext();

// Générer le gestionnaire d'appel
   X509GenerateCallbackHandler callbackHandler = new 
       X509GenerateCallbackHandler(
       "",
       "dsig-sender.ks",
       "jks", 
       "client".toCharArray(), 
       "soaprequester", 
       "client".toCharArray(), 
       "CN=SOAPRequester, OU=TRL, O=IBM, ST=Kanagawa, C=JP", null);

// Générer le jeton de sécurité à utiliser pour la signature (étape : c)
   SecurityToken token = factory.newSecurityToken(X509Token.class, 
        callbackHandler);

// Générer l'instance WSSSignature (étape : d)
   WSSSignature sig = factory.newWSSSignature(token);

// Définir la partie à signer (étape : e)
// PAR DEFAUT : WSSSignature.BODY, WSSSignature.ADDRESSING_HEADERS 
//          et WSSSignature.TIMESTAMP.

// Définir la partie dans l'en-tête SOAP indiquée par QName (étape : e)
      sig.addSignHeader(new 
                        QName("http://www.w3.org/2005/08/addressing", 
                        "MessageID"));

// Définir la partie indiquée par le mot clé (étape : e)
      sig.addSignPart(WSSSignature.BODY);

// Définir la partie indiquée par SecurityToken (étape : e)
   UNTGenerateCallbackHandler untCallbackHandler = new 
      UNTGenerateCallbackHandler("Chris", "sirhC");
      SecurityToken unt = factory.newSecurityToken(UsernameToken.class, 
         untCallbackHandler);
      sig.addSignPart(unt);

// Définir la partie indiquée par WSSSignPart (étape : e)
   WSSSignPart sigPart = factory.newWSSSignPart();
      sigPart.setSignPart(WSSSignature.TIMESTAMP);
      sigPart.setDigestMethod(WSSSignPart.SHA256);
      sig.addSignPart(sigPart);

// Définir la partie indiquée par WSSTimestamp (étape : e)
   WSSTimestamp timestamp = factory.newWSSTimestamp();
      sig.addSignPart(timestamp);

// Définir la partie indiquée par l'expression XPath (étape : 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());

// Définir l'option pour appliquer la confirmation de signature (étape : f)
      sig.requireSignatureConfirmation();

// Définir la méthode de canonisation (étape : g)
// DEFAULT: WSSSignature.EXC_C14N
      sig.setCanonicalizationMethod(WSSSignature.C14N);

// Définir la méthode de signature (étape : h)
// DEFAULT: WSSSignature.RSA_SHA1
      sig.setSignatureMethod(WSSSignature.HMAC_SHA1);

// Définir la référence de jeton (étape : i)
// PAR DEFAUT : SecurityToken.REF_STR
      sig.setTokenReference(SecurityToken.REF_KEYID);
	
// Ajouter WSSSignature à  WSSGenerationContext (étape : j)
   gencont.add(sig);

// Générer l'en-tête WS-Security (étape : k)
gencont.process(msgctx);
Remarque : X509GenerationCallbackHandler a besoin du mot de passe de clé car la clé privée est utilisée pour la signature.

Que faire ensuite

Choisissez ensuite les méthodes d'algorithme si vous souhaitez une méthode autre que les valeurs par défaut. Si les méthodes d'algorithme ne doivent pas être modifiées, utilisez l'API WSSVerification pour vérifier la signature et indiquer les méthodes d'algorithme dans la liaison de destinataire. L'API WSSVerification est uniquement prise en charge sur le destinataire de la réponse (côté client).


Icône indiquant le type de rubrique Rubrique de tâche



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_confsignaturegen
Nom du fichier : twbs_confsignaturegen.html