Protection des services Web avec un jeton X.509

Liberty prend en charge la spécification Oasis Web Services Security X.509 Certificate Token Profile 1.1. Un jeton X.509 peut être utilisé pour assurer l'intégrité et la confidentialité des messages en les signant et en les chiffrant.

Règle de sécurité de services Web

Pour protéger un message XML avec un jeton X.509, vous devez d'abord créer un contrat spécifié dans un fichier WSDL (Web Services Description Language). Le service Web doit être associé à un règle de sécurité de services Web incluse dans le fichier WSDL. La règle de sécurité de services Web peut contenir des assertions AsymmetricBinding ou SymmetricBinding.

Le besoin d'un jeton X.509 est exprimé sous forme de type d'assertion X509Token dans la règle de sécurité de services Web. L'exemple suivant illustre une assertion X509Token :
<sp:X509Token sp:IncludeToken=
  "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
  <wsp:Policy>
    <sp:WssX509V3Token10 />
  </wsp:Policy>
</sp:X509Token>
Dans une assertion AsymmetricBinding :
  • L'initiateur X509Token est utilisé pour la signature du message du demandeur au fournisseur et le chiffrement du message du fournisseur au demandeur.
  • Le destinataire X509Token est utilisé pour la signature du message du fournisseur au demandeur et le chiffrement du message du demandeur au fournisseur.
Le tableau suivant explique comment les jetons d'initiateur et de destinataire sont utilisés pour chaque composant de la chaîne de demande/réponse :
Tableau 1. Utilisation du jeton d'initiateur et de destinataire pour chaque composant de la chaîne de demande/réponse
* Jeton d'initiateur Jeton de destinataire
envoi de la demande (demandeur) signer chiffrer
réception de la demande (fournisseur) vérifier la signature déchiffrer
envoi de la réponse (fournisseur) chiffrer signer
réception de la réponse (demandeur) déchiffrer vérifier la signature
Les clés privées sont utilisées pour signer et déchiffrer des messages. Les certificats publics sont utilisés pour chiffrer les messages et vérifier les signatures. Les clés privées appartiennent à l'utilisateur de la clé (le signataire ou le déchiffreur).

Dans une assertion SymmetricBinding, une clé confidentielle ou une clé provisoire protégée par un jeton X.509 est partagée par l'initiateur et le destinataire. La clé est utilisée à la fois pour le chiffrement et le déchiffrement.

L'exemple ci-dessous illustre une règle de sécurité de services Web avec un jeton X.509 dans une assertion AsymmetricBinding. Cette règle permet de signer et de chiffrer le corps de la demande et celui de la réponse avec un horodatage.
<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>
L'exemple ci-dessous illustre une règle de sécurité de services Web avec un jeton X.509 dans une assertion SymmetricBinding. Cette règle permet de signer le corps de la demande et celui de la réponse avec un horodatage.
<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>

Référence de jeton et inclusion de jeton

Une assertion de jeton peut être associée à un attribut sp:IncludeToken qui requiert l'inclusion du jeton dans le message. Plusieurs assertions de jeton prennent en charge les mécanismes de référence des jetons, en plus des références directes. Si une assertion de jeton contient plusieurs assertions de référence, les références à ce jeton doivent contenir tous les types de référence spécifiés. Par exemple, si une assertion de jeton possède un attribut sp:IncludeToken dont la valeur est ../Always ainsi qu'une assertion sp:RequireIssuerSerialReference imbriquée, le jeton doit être inclus deux fois dans le message. Bien que ce genre de combinaisons ne constitue pas une erreur, il est recommandé de les éviter pour une meilleure efficacité.

L'assertion IncludeToken est appliquée dans Liberty, mais est ignorée dans l'environnement d'exécution de sécurité de services Web de WebSphere Application Server Traditional.

La règle de sécurité de services Web prend en charge les mécanismes de référence de jeton suivants :
  • KeyIdentifier: <sp:RequireKeyIdentifierReference... />
  • IssuerSerial: <sp:RequireIssuerSerialReference ... />
  • Thumbprint: <sp:RequireThumbprintReference ... />

Ces références sont utilisées lorsque vous générez un jeton X.509 côté client/générateur et elles ne sont pas appliquées côté serveur/consommateur.

Configuration de l'exécution

L'environnement d'exécution de la fonction de sécurité de services Web fournit des options de configuration supplémentaires pour la protection des messages avec un jeton X.509 par rapport à celles proposées par la règle de sécurité de services Web. La configuration de l'environnement d'exécution est définie dans le fichier server.xml. Elle inclut des propriétés de chiffrement, comme signatureProperties et encryptionProperties, une clé et des fichiers de clés.

L'exemple suivant illustre une configuration client pour une assertion X509Token :
<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>
L'exemple suivant illustre une configuration de serveur pour une assertion X509Token :
<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>

Dans la configuration de l'environnement d'exécution, les propriétés signatureProperties et encryptionProperties sont équivalentes aux propriétés de chiffrement dans la configuration WSS4J. Pour plus d'informations, voir WSS4J configuration. La plupart des propriétés de chiffrement sont associées à des valeurs par défaut valides et il n'est donc pas nécessaire de les spécifier. Toutefois, d'autres propriétés, notamment les propriétés relatives au fichier de clés et aux clés, doivent être spécifiées.

Pour plus d'informations sur ces propriétés, voir Configuration par défaut de la sécurité de services Web.

Fichiers de clés, clés et certificats

Pour la signature et le chiffrement des messages, l'utilisation de certificats publics et de clés privées est nécessaire. Ces certificats publics et ces clés privées sont stockés dans des fichiers de clés. Les fichiers de clés sont requis lorsque vous utilisez des assertions X509Token. Le fichier de clés côté client contient la clé privée du client et une chaîne de certificats correspondant à la clé publique du serveur. Le fichier de clés côté serveur contient la clé privée du serveur et une chaîne de certificats correspondant à la clé publique du client.

Lorsqu'un message SOAP est signé et chiffré, les propriétés signatureProperties et encryptionProperties sont interprétées par l'environnement d'exécution de la sécurité de services Web comme suit :
  • Assertion AsymmetricBinding

    La clé qui est spécifiée par la propriété signatureProperties est utilisée en tant que clé privée pour signer le message sortant et elle est également utilisée pour déchiffrer le message entrant.

    La clé spécifiée par la propriété encryptionProperties est utilisée en tant que clé publique pour chiffrer le message sortant et elle est également utilisée pour vérifier la signature dans le message entrant.

  • Assertion SymmetricBinding

    La clé spécifiée par les propriétés encryptionProperties est utilisée alors que la propriété signatureProperties est ignorée.

Gestionnaire d'appel de mot de passe de clé privée

Vous devez connaître deux mots de passe différents pour accéder à une clé privée dans un fichier de clés. Le premier mot de passe concerne le fichier de clés dans lequel la clé privée est stockée. Le deuxième mot de passe concerne la clé privée elle-même. Alors que le mot de passe du fichier de clés est spécifié dans l'une des propriétés de chiffrement, signatureProperties ou encryptionProperties, la classe CallbackHandler est normalement utilisée par la sécurité de services Web pour accéder à la clé privée dans un fichier de clés. Dans Liberty, cette classe CallbackHandler doit être packagée en tant que fonction Liberty et son nom de classe doit être spécifié en tant que valeur de la propriété personnalisée ws-security.callback-handler dans le fichier security.xml.

Cette classe CallbackHandler est requise par la sécurité de services Web pour accéder à la clé privée dans un fichier de clés.

Pour plus d'informations sur la classe CallbackHandler de mot de passe, voir Développement d'un gestionnaire d'appel de mot de passe pour la sécurité de services Web.

Si la classe CallbackHandler ne fournit pas le mot de passe de la clé privée, l'environnement d'exécution ws-security essaie d'abord avec CallbackHandler (et il doit donc être fourni), puis le mot de passe spécifié dans les propriétés crypto est utilisé comme mot de passe par défaut de la clé privée. Cette propriété est org.apache.ws.security.crypto.merlin.keystore.private.password.

Etant donné qu'une seule propriété personnalisée ws-security.callback-handler est prise en charge dans chacune des sections wsSecurityClient et wsSecurityProvider du fichier security.xml, un gestionnaire d'appel de mot de passe unique doit prendre en charge tous les mots de passe requis pour chaque type d'application (client ou serveur) utilisant la configuration par défaut. Toutes les applications de fournisseur doivent utiliser le gestionnaire d'appel de mot de passe par défaut. Les applications client peuvent remplacer le gestionnaire d'appel de mot de passe par défaut en spécifiant la propriété personnalisée ws-security.callback-handler dans le contexte de la demande pour l'appel de service Web du client.

Si vous devez indiquer des mots de passe pour une clé privée X.509 et un jeton de nom d'utilisateur pour un appel de service Web unique, vous ne pouvez pas fournir des gestionnaires d'appel distincts pour chaque utilisation. Dans ce cas, vous devez implémenter un gestionnaire d'appel unique qui gère les deux types de mot de passe. Comme illustré dans l'exemple précédent, vous devez utiliser la méthode WSPasswordCallback.getUsage() pour déterminer le type de mot de passe renvoyé. Reportez-vous à la documentation de l'API WSPasswordCallback pour connaître les codes d'utilisation pris en charge (http://ws.apache.org/wss4j/apidocs/org/apache/wss4j/common/ext/WSPasswordCallback.html).

Liste de révocation des certificat

Une liste de révocation des certificats (CRL) est une liste des numéros de série des certificats révoqués. Il peut s'agir d'un fichier autonome ou conditionné dans un encapsuleur PKCS#7. Vous pouvez utiliser une CRL avec un magasin de clés de confiance pour contrôler l'accès à un service.

Deux étapes sont requises pour configurer la fonction WS-Security dans Liberty afin d'effectuer la vérification de révocation avec un fichier CRL. Pour activer la vérification de révocation de certificat avec un fichier de liste de révocation de certificat, vous devez modifier la configuration de l'environnement d'exécution de la sécurité de services Web dans le fichier server.xml.
  1. Dans l'élément wsSecurityProvider ou wsSecurityClient, ajoutez la propriété suivante :
    ws-security.enableRevocation="true"
  2. Dans l'élément signatureProperties, ajoutez la propriété suivante et définissez un fichier de liste de révocation de certificat comme valeur :
    org.apache.ws.security.crypto.merlin.x509crl.file
L'exemple suivant illustre une configuration de fournisseur de sécurité de services Web qui permet la vérification de révocation de certificat avec un fichier de liste de révocation de certificat :
<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>

Icône indiquant le type de rubrique Rubrique de concept



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