Estás consultando la documentación de Apigee Edge.
Consulta la
documentación de Apigee X. Información
![](https://docs.apigee.com/static/api-platform/images/icon_policy_security.jpg?authuser=0000&hl=es)
Calcula y verifica un código de autenticación de mensajes basado en hash (HMAC). HMAC también se denomina código de autenticación de mensajes con clave o hash con clave y usa una función de hash criptográfica, como SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 o MD-5, aplicada a un "mensaje" junto con una clave secreta para producir una firma o un código de autenticación para ese mensaje. El término “mensaje” aquí se refiere a cualquier transmisión de bytes. El remitente de un mensaje también puede enviar un HMAC a un receptor, y este puede usar el HMAC para autenticar el mensaje.
Si deseas obtener más información sobre HMAC, consulta HMAC: hash con clave para la autenticación de mensajes (rfc2104).
Ejemplos
Genera 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>
Verifica 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>
El cálculo de una firma y la verificación de ella siguen el mismo proceso. La política de HMAC calcula un HMAC y, de forma opcional, puede verificar la firma calculada con un valor esperado. El elemento opcional VerificationValue (si está presente) dirige la política para verificar el valor calculado con un valor conocido o determinado.
Referencia de elementos para HMAC
La referencia de política describe los elementos y atributos de la política HMAC.
Atributos que se aplican al elemento de nivel superior
<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">
Los siguientes atributos son comunes a todos los elementos superiores de la política.
Atributo | Descripción | Valor predeterminado | Presencia |
---|---|---|---|
name |
El nombre interno de la política. Los caracteres que puede usar en el nombre están restringidos a:
A-Z0-9._\-$ % . Sin embargo, la IU de Apigee aplica restricciones adicionales, como quitar automáticamente los caracteres que no son alfanuméricos.
De forma opcional, usa el elemento |
No disponible | Obligatorias |
continueOnError |
Configúralo como false para devolver un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas.
Configúralo como |
false | Opcional |
habilitado |
Configúralo como true para aplicar la política.
Configúralo como |
true | Opcional |
async | Este atributo dejó de estar disponible. | false | Funciones obsoletas |
<Algorithm>
<Algorithm>algorithm-name</Algorithm>
Especifica el algoritmo hash para calcular el HMAC.
Valor predeterminado | No disponible |
Presencia | Obligatorias |
Tipo | Cadena |
Valores válidos | SHA-1 , SHA-224 , SHA-256 , SHA-384 ,
SHA-512 y MD-5
La configuración de la política acepta nombres de algoritmos sin distinción entre mayúsculas y minúsculas, y con o sin el guion entre las letras y los números . Por ejemplo, |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Además de usar el atributo de nombre para etiquetar la política en el editor de proxy de IU de Apigee con un nombre diferente y con lenguaje natural.
Configuración predeterminada | Si omites este elemento, se usa el valor del atributo de nombre de la política. |
Presencia | Opcional |
Tipo | Cadena |
<Message>
<Message>message_template_here</Message> or <Message ref='variable_here'/>
Especifica la carga útil del mensaje que se firmará. La entrada de este elemento admite plantillas de mensajes (sustitución de variables) para permitir que se incluyan elementos adicionales en el entorno de ejecución, como marcas de tiempo, nonces, listas de encabezados o alguna otra información. Por ejemplo:
<Message>Fixed Part {a_variable} {timeFormatUTCMs(timeFormatString1,system.timestamp)} {nonce} </Message>
La plantilla de mensajes puede incluir partes fijas y variables, incluidas las líneas nuevas y las funciones estáticas. El espacio en blanco es importante.
Predeterminada | No disponible |
Presencia | Obligatorias |
Tipo | Cadena |
Valores válidos | Cualquier string es válida para el valor de texto. Si proporcionas un atributo ref , tendrá prioridad sobre el valor de texto. La política evalúa el valor de texto o la variable a la que se hace referencia como una plantilla de mensaje. |
<Output>
<Output encoding='encoding_name'>variable_name</Output>
Especifica el nombre de la variable que la política debe establecer con el valor HMAC calculado. También especifica la codificación que se usará para la salida.
Configuración predeterminada |
La variable de resultado predeterminada es El valor predeterminado para el atributo |
Presencia | Opcional. Si este elemento no está presente, la política establece la variable de flujo hmac.POLICYNAME.output , con un valor codificado en base64. |
Tipo | Cadena |
Valores válidos | Para la codificación, Los valores no distinguen mayúsculas de minúsculas, El valor de texto del elemento |
<SecretKey>
<SecretKey encoding='encoding_name' ref='private.secretkey'/>
Especifica la clave secreta utilizada para calcular el HMAC. La clave se obtiene de la variable a la que se hace referencia, que se decodifica según la codificación específica.
Configuración predeterminada |
No hay un valor predeterminado para la variable a la que se hace referencia; el atributo Si no se encuentra un atributo |
Presencia | Obligatorias |
Tipo | Cadena |
Valores válidos | Para El uso de un atributo de codificación te permite especificar una clave que incluye bytes fuera del rango de caracteres UTF-8 imprimibles. Por ejemplo, supongamos que la configuración de la política incluye lo siguiente: <SecretKey encoding='hex' ref='private.encodedsecretkey'/>
Supongamos que
En este caso, los bytes clave se decodificarán como: [53 65 63 72 65 74 31 32 33] (cada byte representado en formato hexadecimal). Otro ejemplo: si |
<VerificationValue>
<VerificationValue encoding='encoding_name' ref='variable_name'/> or <VerificationValue encoding='encoding_name'>string_value</VerificationValue>
Especifica el valor de verificación, así como el algoritmo de codificación que se usó para codificar el valor de verificación (opcional). La política usará este algoritmo para decodificar el valor.
Predeterminada | No hay un valor de verificación predeterminado. Si el elemento está presente, pero el atributo encoding está ausente, la política usa una codificación predeterminada de base64 . |
Presencia | Opcional |
Tipo | Cadena |
Valores válidos |
Los valores válidos para el atributo de codificación son: No es necesario que la codificación de |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Configúralo como false
si deseas que la política muestre un error cuando no se pueda resolver cualquier variable a la que se especifica en la política. Se establece como true
para tratar cualquier variable no recuperable como una string vacía (null).
El valor booleano IgnoreUnresolvedVariables afecta solo a las variables a las que se hace referencia en la plantilla de mensaje. Si bien SecretKey
y VerificationValue
pueden hacer referencia a una variable, ambas se deben poder resolver, por lo que la configuración ignore
no se aplica a ellas.
Configuración predeterminada | Falso |
Presencia | Opcional |
Tipo | Booleano |
Valores válidos | True o False |
Variables de flujo
La política puede establecer estas variables durante la ejecución.
Variable | Descripción | Ejemplo |
---|---|---|
hmac.policy_name.message |
La política establece esta variable con el mensaje real, que es el resultado de la evaluación de la plantilla de mensajes especificada en el elemento Message . |
hmac.HMAC-Policy.message = "Hello, World" |
hmac.policy_name.output |
Obtiene el resultado del cálculo HMAC cuando el elemento Output no especifica un nombre de variable. |
hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4= |
hmac.policy_name.outputencoding |
Obtiene el nombre de la codificación de salida. | 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>