Estás viendo la documentación de Apigee Edge.
Ve a la
Documentación de Apigee X. información
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).
Muestras
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 |
N/A | Obligatorio |
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 |
falso | Opcional |
habilitado | Configúralo como true para aplicar la política.Configúralo como |
true | Opcional |
async | Este atributo dejó de estar disponible. | falso | Obsoleta |
<Algorithm>
<Algorithm>algorithm-name</Algorithm>
Especifica el algoritmo hash para calcular el HMAC.
Predeterminada | N/A |
Presencia | Obligatorio |
Tipo | String |
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 | String |
<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 | N/A |
Presencia | Obligatorio |
Tipo | String |
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 | String |
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 | Obligatorio |
Tipo | String |
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 | String |
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 |
Referencia de errores
En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo solucionar fallas.
Errores de entorno de ejecución
Estos errores pueden producirse cuando se ejecuta la política.
Código de falla | Estado de HTTP | Ocurre cuando |
---|---|---|
steps.hmac.UnresolvedVariable |
401 | Este error se produce si una variable especificada en la política HMAC tiene las siguientes características:
|
steps.hmac.HmacVerificationFailed |
401 | Falló la verificación de HMAC. El valor de verificación proporcionado no coincide con el valor calculado. |
steps.hmac.HmacCalculationFailed |
401 | La política no pudo calcular el HMAC. |
steps.hmac.EmptySecretKey |
401 | El valor de la variable de clave secreta está vacío. |
steps.hmac.EmptyVerificationValue |
401 | La variable que contiene el valor de verificación está vacía. |
Errores en la implementación
Estos errores pueden generarse cuando implementas un proxy que contiene esta política.
Nombre del error | Estado de HTTP | Ocurre cuando |
---|---|---|
steps.hmac.MissingConfigurationElement |
401 | Este error ocurre cuando falta un elemento o un atributo obligatorio. |
steps.hmac.InvalidValueForElement |
401 | Este error se produce si el valor especificado en el elemento Algoritmo no es uno de los siguientes valores: SHA-1 , SHA-224 , SHA-256 , SHA-512 o MD-5 . |
steps.hmac.InvalidSecretInConfig |
401 | Este error se produce si hay un valor de texto proporcionado de forma explícita para SecretKey . |
steps.hmac.InvalidVariableName |
401 | Este error se produce si la variable SecretKey no contiene el prefijo private (private. ). |
Variables con fallas
Estas variables se configuran cuando se genera un error de entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.
Variables | Donde | Ejemplo |
---|---|---|
fault.name="fault_name" |
fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla. | fault.name Matches "UnresolvedVariable" |
hmac.policy_name.failed |
La política establece esta variable en caso de falla. | hmac.HMAC-Policy.failed = true |
Ejemplo de respuesta de error
Para controlar errores, se recomienda capturar la parte errorcode
de la respuesta de error. No dependas del texto en la faultstring
, ya que podría cambiar.
Ejemplo de regla de falla
<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>