Règle HMAC

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Calcule et valide un code d'authentification d'une empreinte cryptographique de message (HMAC, Hash-based Message Authentication Code). Parfois appelé "code d'authentification de message avec clé" ou "hachage avec clé", le HMAC utilise une fonction d'empreinte cryptographique telle que SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 ou MD-5 appliquée à un "message", avec une clé secrète pour produire une signature ou un code d'authentification de message sur ce message. Le terme "message" désigne ici un flux d'octets. L'expéditeur d'un message peut également envoyer un HMAC à un destinataire, qui peut l'utiliser pour authentifier le message.

Pour en savoir plus sur HMAC, consultez la page HMAC : Keyed-Hashing for Message Authentication (rfc2104).

Samples

<HMAC name='HMAC-1'>

  <Algorithm>SHA256</Algorithm>

  <SecretKey ref='private.secretkey'/>

  <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional -->

  <!--
    The "message" can include fixed and multiple variable parts,
    including newlines and static functions.
    Whitespace is significant.
   -->
  <Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
  </Message>

  <!-- default encoding is base64 -->
  <Output encoding='base16'>name_of_variable</Output>

</HMAC>

<HMAC name='HMAC-1'>

  <Algorithm>SHA256</Algorithm>

  <SecretKey ref='private.secretkey'/>

  <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional -->

  <!--
    The "message" can include fixed and multiple variable parts,
    including newlines and static functions.
    Whitespace is significant.
   -->
  <Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
  </Message>

  <!--
    VerificationValue is optional.
    Include it to perform an HMAC check.
  -->
  <VerificationValue encoding='base16' ref='expected_hmac_value'/>

  <!-- default encoding is base64 -->
  <Output encoding='base16'>name_of_variable</Output>

</HMAC>

Référence d'élément pour HMAC

La référence de la règle décrit les éléments et les attributs de la règle HMAC.

Attributs qui s'appliquent à l'élément de premier niveau

<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">

Les attributs suivants sont communs à tous les éléments parents de la stratégie.

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

Spécifie l'algorithme de hachage pour calculer le HMAC.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

À utiliser, en plus de l'attribut, pour appliquer un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur d'Apigee en utilisant un nom différent, en langage naturel.

<Message>

<Message>message_template_here</Message>
or
<Message ref='variable_here'/>

Spécifie la charge utile du message à signer. L'entrée de cet élément est compatible avec les modèles de message (substitution de variable) pour permettre l'inclusion d'éléments supplémentaires lors de l'exécution, tels que l'horodatage, les nonces, les listes d'en-têtes ou d'autres informations. Exemple :

<Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
</Message>

Le modèle de message peut inclure des parties fixes et variables, y compris des nouvelles lignes et des fonctions statiques. Les espaces blancs sont importants.

<Output>

<Output encoding='encoding_name'>variable_name</Output>

Spécifie le nom de la variable que la règle doit définir avec la valeur HMAC calculée. Spécifie également l'encodage à utiliser pour la sortie.

<SecretKey>

<SecretKey encoding='encoding_name' ref='private.secretkey'/>

Spécifie la clé secrète utilisée pour calculer le HMAC. La clé est obtenue à partir de la variable référencée, décodée en fonction de l'encodage spécifique.

 <SecretKey encoding='hex' ref='private.encodedsecretkey'/>

<VerificationValue>

<VerificationValue encoding='encoding_name' ref='variable_name'/>
or
<VerificationValue encoding='encoding_name'>string_value</VerificationValue>

(Facultatif) Spécifie la valeur de validation, ainsi que l'algorithme d'encodage utilisé pour encoder la valeur de validation. La règle utilise cet algorithme pour décoder la valeur.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Définissez la valeur sur false si vous souhaitez que la règle génère une erreur lorsqu'une variable référencée spécifiée dans la stratégie est irrésolue. Définissez la valeur sur true pour traiter toute variable irrésolue comme une chaîne vide (null).

La valeur booléenne IgnoreUnresolvedVariables n'affecte que les variables référencées par le modèle de message. Si SecretKey et VerificationValue peuvent faire référence à une variable, chacune d'entre elles doit être résolue, le paramètre ignore ne s'applique donc pas à ces variables.

Variables de flux

La règle peut définir ces variables lors de l'exécution.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés et les variables d'erreur définies par Apigee lorsque cette règle déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour en savoir plus, consultez la section Ce que vous devez savoir sur les erreurs liées aux règles.

Exemple de réponse d'erreur

Pour le traitement des erreurs, la meilleur pratique consiste à intercepter la partie errorcode de la réponse. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

Exemple de règle de défaillance

<FaultRules>
    <FaultRule name="HMAC Policy Errors">
        <Step>
            <Name>AM-Unauthorized</Name>
            <Condition>(fault.name Matches "HmacVerificationFailed")</Condition>
        </Step>
        <Condition>hmac.HMAC-1.failed = true</Condition>
    </FaultRule>
</FaultRules>