Política HMAC

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Esta política calcula e, opcionalmente, verifica um código de autenticação de mensagens baseado em hash (HMAC, na sigla em inglês). Também conhecido como código de autenticação de mensagens com chave ou hash com chave, o HMAC usa uma função de hash criptográfico como SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 ou MD-5, aplicada a uma "mensagem", com uma chave secreta, para produzir um código de autenticação de assinatura ou mensagem nela. O termo "mensagem" refere-se a qualquer streaming de bytes. No uso típico de HMAC, um remetente de uma mensagem envia uma mensagem e o respectivo HMAC para um destinatário, e o destinatário pode usar o HMAC com a chave secreta compartilhada para autenticar a mensagem.

Esta é uma política padrão e pode ser implantada em qualquer tipo de ambiente. Para informações sobre os tipos de políticas e a disponibilidade de cada tipo de ambiente, consulte Tipos de políticas.

Para saber mais sobre o HMAC, consulte HMAC: Keyed-Hashing for Message Authentication (rfc2104).

Amostras

<HMAC name='HMAC-1'>

  <Algorithm>SHA256</Algorithm>

  <!-- the default encoding of the SecretKey is UTF-8 -->
  <SecretKey encoding='base64' ref='private.secretkey'/>

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

  <!--
    The Message element accepts a template, which means the "message" the policy operates
    on can include fixed and multiple variable parts, including newlines and static functions.
    Whitespace, such as newlines and space characters, 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>

  <!-- the default encoding of the SecretKey is UTF-8 -->
  <SecretKey encoding='base16' ref='private.secretkey'/>

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

  <!--
     The Message element accepts a template. This policy verifies an HMAC on the request content.
   -->
  <Message>{request.content}</Message>

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

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

</HMAC>

Referência de elementos para HMAC

A referência de política descreve os elementos e atributos da política HMAC.

Atributos que se aplicam ao elemento de nível superior

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

Os seguintes atributos são comuns a todos os elementos pai de política.

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

Especifica o algoritmo de hash a ser usado ao calcular o HMAC.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU da Apigee com um nome de linguagem natural diferente.

<Message>

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

Especifica o payload da mensagem a ser assinado. A entrada desse elemento é compatível com os modelos de mensagem (substituição de variáveis) para permitir que outros itens sejam incluídos no ambiente de execução, como carimbos de data/hora, valores de uso único, listas de cabeçalhos ou outras informações. Exemplo:

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

O modelo de mensagem pode incluir partes fixas e variáveis, incluindo novas linhas e funções estáticas. O espaço em branco, como novas linhas e caracteres, é importante.

<Output>

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

Especifica o nome da variável que a política precisa definir com o valor calculado HMAC. Também especifica a codificação a ser usada para a saída.

<SecretKey>

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

Especifica a chave secreta usada para calcular o HMAC. A chave é obtida da variável referenciada, decodificada de acordo com a codificação específica.

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

<VerificationValue>

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

(Opcional) Especifica o valor da verificação e a codificação usados para codificar o valor de verificação. A política usará esse algoritmo para decodificar o valor.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Defina como false se quiser que a política gere um erro quando qualquer variável referenciada especificada na política não for resolvível. Defina como true para tratar qualquer variável não resolvida como uma string vazia (null).

O booleano IgnoreUnresolvedVariables afeta apenas as variáveis referenciadas pelo modelo de mensagem. Embora SecretKey e VerificationValue possam fazer referência a uma variável, ambos precisam ser resolvidos, portanto, a configuração ignore não se aplica a eles.

Variáveis de fluxo

A política pode configurar essas variáveis durante a execução.

Problemas comuns

A política de HMAC parece simples: forneça uma chave e uma mensagem, e receba um HMAC calculado em resposta. Pode ser frustrante usar a política se você receber um valor HMAC inesperado para uma combinação conhecida de mensagem e chave. Esta seção explica algumas notas de uso para solucionar esses problemas.

Há duas armadilhas comuns que resultam em HMACs incompatíveis durante a verificação: diferenças de espaços em branco na mensagem e diferenças na codificação e na decodificação. Este último se aplica ao elemento SecretKey, bem como ao elemento Output.

Diferenças de espaços em branco

Diferenças que podem parecer não relevantes para um humano afetam o valor de HMAC de saída. Por exemplo, suponha que uma chave secreta seja representada como "Secret123". Com a decodificação UTF-8, os bytes de chave serão: [53 65 63 72 65 74 31 32 33]. O uso dessa chave para calcular um HMAC-SHA256 na mensagem abc resulta em a7938720fe5749d31076e6961360364c0cd271443f1b580779932c244293bc94. A adição de um único espaço à mensagem para que seja abc<SPACE>, em que <SPACE> implica um ASCII 32, resulta em um HMAC-SHA256 de 274669b2a85d2532da48e2ce3d8e52ee17346d1bcd1a606d87db1934b5ab294b.

Da mesma forma, se a mensagem for abc<NEWLINE>, em que <NEWLINE> implica um ASCII 10, o HMAC será 0780370844ca07f896066837e8230d3b6a775f678a4ae03e6b5e864c674831f5. Pequenas mudanças na mensagem resultam em valores HMAC muito diferentes. Isso ocorre por design. Esse é um comportamento esperado e desejado do HMAC.

Atenção: é importante garantir que o corpo da mensagem usado para calcular o HMAC original e o corpo da mensagem usados para verificar o HMAC sejam exatamente os mesmos. Se o verificador de um HMAC mudar o payload da mensagem de alguma forma, adicionando qualquer espaço em branco ou reformatando o texto, o HMAC calculado mudará.

Tome cuidado especial ao usar um modelo de mensagem na configuração da política. Por exemplo, este fragmento de configuração de política mostra um possível problema:

<HMAC name='HMAC-1'>
    ...
    <!-- the result of this message template will include surrounding whitespace -->
    <Message>
        {request.content}
    </Message>
    ...
       
</HMAC>

O resultado da avaliação do modelo de mensagem no elemento <Message> incluirá novas linhas e espaços ao redor do conteúdo da mensagem. Isso não é exatamente o que você quer. Uma configuração melhor parecia como esta:

<HMAC name='HMAC-1'>
    ...
    <Message>{request.content}</Message>
    ...
         
</HMAC>

Diferenças na codificação

As diferentes decodificações do mesmo material da chave resultam em chaves diferentes. Suponha que uma chave secreta possa ser representada como "U2VjcmV0S2V5MTIz". Com a decodificação UTF-8, os bytes de chave representados em base16 serão: [55 32 56 6a 63 6d 56 30 53 32 56 35 4d 54 49 7a]. Com a decodificação em base64, os bytes da chave serão [53 65 63 72 65 74 4b 65 79 31 32 33]. A decodificação do material de origem resulta em chaves diferentes, e isso resultará em valores de HMAC distintos.

Atenção: é importante garantir que o material da chave usado para calcular o HMAC original e a chave usada para verificar o HMAC sejam exatamente os mesmos. Isso provavelmente significa garantir que a mesma codificação da chave seja usada em ambas as extremidades. Na política de HMAC, é possível usar o atributo encoding no elemento SecretKey para especificar a codificação da chave.

Considere também as codificações na saída. Um HMAC-SHA256 expresso em base16 ou codificação hexadecimal como 27f17e11c8ece93844c5eb5e55161d993368628a214f9a51c25d0185e8ea06e2 é igual a um HMAC-SHA256 expresso em formato codificado em Base64 como J/F+Ecjs6ThExeteVRYdmTNoYoohT5pRwl0BhejqBuI=. Eles parecem diferentes, mas essas duas strings representam o mesmo valor. Verifique se a mesma codificação é usada para codificar o HMAC calculado originalmente e o HMAC de verificação. Na política de HMAC, é possível usar o atributo encoding no elemento Output para especificar a codificação de saída desejada e o mesmo atributo no elemento VerificationValue para especificar como decodificar o verificador.

Referência de erros

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Variáveis de falha

Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Exemplo de resposta de erro

Para gerenciar erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto em faultstring, porque ele pode mudar.

Exemplo de regra de falha

<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>