<ph type="x-smartling-placeholder"></ph>
Vous consultez la documentation Apigee Edge.
Accédez à la page
Documentation sur 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).
Exemples
Générer le 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> <!-- default encoding is base64 --> <Output encoding='base16'>name_of_variable</Output> </HMAC>
Vérifier le 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>
Le calcul d'une signature et la vérification de cette signature suit exactement le même processus. La règle HMAC calcule un HMAC et peut éventuellement vérifier la signature calculée par rapport à une valeur attendue. L'élément facultatif VerificationValue (le cas échéant) demande à la règle de vérifier la valeur calculée par rapport à une valeur connue ou donnée.
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.
Attribut | Description | Par défaut | Présence |
---|---|---|---|
nom |
Nom interne de la stratégie. Les caractères que vous pouvez utiliser dans le nom se limitent à : A-Z0-9._\-$ % . L'interface utilisateur Apigee applique cependant des restrictions supplémentaires, telles que la suppression automatique des caractères qui ne sont pas alphanumériques.
Vous pouvez également utiliser l'élément |
N/A | Requis |
continueOnError |
Définissez sur false pour afficher une erreur en cas d'échec d'une stratégie. Il s'agit du comportement attendu pour la plupart des règles.
Définissez sur |
faux | Facultatif |
activé | Définissez la valeur sur true pour appliquer la stratégie.Définissez la valeur sur |
vrai | Facultatif |
async | Cet attribut est obsolète. | faux | Obsolète |
<Algorithm>
<Algorithm>algorithm-name</Algorithm>
Spécifie l'algorithme de hachage pour calculer le HMAC.
Par défaut | N/A |
Présence | Requis |
Type | Chaîne |
Valeurs valides | SHA-1 , SHA-224 , SHA-256 , SHA-384 ,
SHA-512 , et MD-5
La configuration de la règle accepte les noms d'algorithme sans distinction de casse, et
avec ou sans le tiret entre les lettres et les chiffres . Par exemple, |
<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.
Par défaut | Si vous omettez cet élément, la valeur de l'attribut de nom de la stratégie est utilisée. |
Présence | Facultatif |
Type | Chaîne |
<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.
Par défaut | N/A |
Présence | Requis |
Type | Chaîne |
Valeurs valides | Toute chaîne est valide pour la valeur de texte. Si vous fournissez un attribut ref ,
il est prioritaire sur la valeur de texte. La règle évalue la valeur
textuelle ou la variable référencée en tant que modèle de message. |
<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.
Par défaut |
La variable de sortie par défaut est La valeur par défaut de l'attribut |
Présence | Facultatif. Si cet élément est absent, la règle définit la variable de flux
hmac.POLICYNAME.output avec une valeur encodée en base64. |
Type | Chaîne |
Valeurs valides | Pour l'encodage, Les valeurs ne sont pas sensibles à la casse. La valeur textuelle de l'élément |
<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.
Par défaut |
Il n'existe pas de valeur par défaut pour la variable référencée.
L'attribut En l'absence d'attribut |
Présence | Requis |
Type | Chaîne |
Valeurs valides | Pour L'utilisation d'un attribut d'encodage vous permet de spécifier une clé qui inclut des octets en dehors de la plage de caractères imprimables UTF-8. Par exemple, supposons que la configuration de la règle inclut ce qui suit : <SecretKey encoding='hex' ref='private.encodedsecretkey'/>
Et supposons que
Dans ce cas, les octets de clés sont décodés comme : [53 65 63 72 65 74 31 32 33]
(chaque octet représenté eau format hexadécimal). Autre exemple, si |
<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.
Par défaut | Il n'existe aucune valeur de validation par défaut. Si l'élément est présent, mais que l'attribut
encoding est absent, la règle utilise l'encodage par défaut base64 |
Présence | Facultatif |
Type | Chaîne |
Valeurs valides |
Voici des valeurs valides pour l'attribut d'encodage : L'encodage de |
<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.
Par défaut | Faux |
Présence | Facultatif |
Type | Booléen |
Valeurs valides | True ou False |
Variables de flux
La règle peut définir ces variables lors de l'exécution.
Variable | Description | Exemple |
---|---|---|
hmac.policy_name.message |
La règle définit cette variable avec le message effectif,
c'est-à-dire le résultat de l'évaluation du modèle de message spécifié dans l'élément
Message . |
hmac.HMAC-Policy.message = "Hello, World" |
hmac.policy_name.output |
Récupère le résultat du
calcul HMAC lorsque l'élément Output ne spécifie pas
de nom de variable. |
hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4= |
hmac.policy_name.outputencoding |
Récupère le nom de l'encodage de sortie. | hmac.HMAC-Policy.outputencoding = base64 |
Error reference
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Occurs when |
---|---|---|
steps.hmac.UnresolvedVariable |
401 | This error occurs if a variable specified in the HMAC policy is either:
|
steps.hmac.HmacVerificationFailed |
401 | The HMAC verification failed; the verification value provided does not match the calculated value. |
steps.hmac.HmacCalculationFailed |
401 | The policy was unable to calculate the HMAC. |
steps.hmac.EmptySecretKey |
401 | The value of the secret key variable is empty. |
steps.hmac.EmptyVerificationValue |
401 | The variable holding the verification value is empty. |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | HTTP status | Occurs when |
---|---|---|
steps.hmac.MissingConfigurationElement |
401 | This error occurs when a required element or attribute is missing. |
steps.hmac.InvalidValueForElement |
401 | This error occurs if the value specified in the Algorithm element is not
one of the following values: SHA-1 , SHA-224 , SHA-256 ,
SHA-512 , or MD-5 . |
steps.hmac.InvalidSecretInConfig |
401 | This error occurs if there is a text value explicitly provided for SecretKey . |
steps.hmac.InvalidVariableName |
401 | This error occurs if the SecretKey variable does not contain the
private prefix (private. ). |
Fault variables
These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "UnresolvedVariable" |
hmac.policy_name.failed |
The policy sets this variable in the case of a failure. | hmac.HMAC-Policy.failed = true |
Example error response
For error handling, the best practice is to trap the errorcode
part of the error
response. Do not rely on the text in the faultstring
, because it could change.
Example fault rule
<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>