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. Nem todos os usuários têm necessidade de saber sobre os tipos de política e 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

Gerar HMAC

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

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

A computação de uma assinatura e a verificação dessa assinatura seguem exatamente o mesmo processo. A política HMAC calcula um HMAC e, opcionalmente, pode verificar a assinatura calculada com um valor esperado. O elemento VerificationValue opcional (se presente) direciona a política para verificar o valor calculado em relação a um valor conhecido ou fornecido.

---

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.

Atributo	Descrição	Padrão	Presença
name	O nome interno da política. Os caracteres que podem ser usados no nome são restritos a: A-Z0-9._\-$ %. No entanto, a IU da Apigee impõe outras restrições, como a remoção automática de caracteres que não são alfanuméricos. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU da Apigee com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	falso	Opcional
ativada	Defina como true para aplicar a política. Defina como false para "desativar" a política. A política não será aplicada mesmo se permanecer anexada a um fluxo.	true	Opcional
async	Esse atributo está obsoleto.	falso	Obsoleto

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

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

Padrão	N/A
Presença	Obrigatório
Tipo	String
Valores válidos	SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, e MD-5 A configuração da política aceita nomes de algoritmo sem distinção entre maiúsculas e minúsculas e com ou sem o traço entre as letras e os números. Por exemplo, SHA256 e SHA-256 e sha256 são equivalentes. Observação de segurança: SHA-1 e MD-5 estão incluídos aqui para fins de abrangência, mas o Google não recomenda o uso desses hashes. O Google demonstrou pela primeira vez os ataques de colisão contra o SHA-1 em 2017 e recomenda não usá-lo. O NIST também recomenda que as pessoas parem de usar o SHA-1. O instituto de engenharia de software da CMU, recomendou evitar o uso do algoritmo MD5 em todas as capacidade em 2008.

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

Padrão	Se você omitir esse elemento, o valor do atributo name da política será usado.
Presença	Opcional
Tipo	String

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

Padrão	N/A
Presença	Obrigatório
Tipo	String
Valores válidos	Qualquer string é válida para o valor de texto. Se você fornecer um atributo ref, ele terá precedência sobre o valor do texto. A política avalia o valor do texto ou a variável referenciada como um modelo de mensagem.

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

Padrão	A variável de saída padrão é hmac.POLICYNAME.output. O valor padrão para o atributo encoding é base64.
Presença	Opcional. Se esse elemento não estiver presente, a política definirá a variável de fluxo hmac.POLICYNAME.output com um valor codificado em base64.
Tipo	String
Valores válidos	Para codificação, hex, base16, base64, base64url. Os valores não diferenciam maiúsculas de minúsculas. Portanto, hex e base16 são sinônimos. O valor de texto do elemento Output pode ser qualquer nome de variável de fluxo válido.

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

Padrão	Não há valor padrão para a variável referenciada. O atributo ref é obrigatório. Na ausência de um atributo encoding, a política decodifica a string da chave secreta com UTF-8 por padrão para receber os bytes da chave.
Presença	Obrigatório
Tipo	String
Valores válidos	Para encoding, os valores válidos são hex, base16, base64 e utf8. O padrão é UTF-8. Os valores não diferenciam maiúsculas de minúsculas, e os traços são insignificantes. Base16 é igual a base-16 e bAse16. Base16 e Hex são sinônimos. O uso de um atributo de codificação permite que você especifique uma chave que inclua bytes fora do intervalo de caracteres imprimíveis em UTF-8. Por exemplo, suponha que a configuração da política inclua isto: <SecretKey encoding='hex' ref='private.encodedsecretkey'/> E suponha que private.encodedsecretkey mantenha a string 536563726574313233. Nesse caso, os bytes da chave serão decodificados como: [53 65 63 72 65 74 31 32 33] (cada byte representado em hexadecimal). Outro exemplo: se encoding='base64' for usado, e se private.encodedsecretkey mantiver a string U2VjcmV0MTIz, o resultado será o mesmo conjunto de bytes da chave. Sem um atributo de codificação ou com um atributo de codificação UTF8, o valor da string Secret123 resultaria no mesmo conjunto de bytes. Isso mostra três maneiras diferentes de representar a mesma chave.

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

Padrão	Não há valor de verificação padrão. Se o elemento estiver presente, mas o atributo encoding estiver ausente, a política usará uma codificação padrão de base64
Presença	Opcional
Tipo	String
Valores válidos	Os valores válidos para o atributo de codificação são: hex, base16, base64 e base64url. Os valores não diferenciam maiúsculas de minúsculas. Portanto, hex e base16 são sinônimos. A codificação de VerificationValue não precisa ser a mesma usada para o elemento Output.

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

Padrão	Falso
Presença	Opcional
Tipo	Booleanos
Valores válidos	verdadeiro ou falso

Variáveis de fluxo

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

Variável	Descrição	Exemplo
hmac.policy_name.message	A política define essa variável com a mensagem efetiva, o resultado da avaliação do modelo de mensagem especificado no elemento Message.	hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output	Recebe o resultado do cálculo HMAC, quando o elemento Output não especifica um nome de variável.	hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding	Recebe o nome da codificação de saída.	hmac.HMAC-Policy.outputencoding = base64

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.

Código de falha	Status HTTP	Ocorre quando
steps.hmac.UnresolvedVariable	401	Esse erro ocorrerá se uma variável especificada na política de código de autenticação de mensagem baseado em hash (HMAC, na sigla em inglês): Fora do escopo (não disponível no fluxo específico em que a política está sendo executada) ou Não é possível resolver (não está definida)
steps.hmac.HmacVerificationFailed	401	A verificação de HMAC falhou. O valor de verificação fornecido não corresponde ao valor calculado.
steps.hmac.HmacCalculationFailed	401	A política não conseguiu calcular o HMAC.
steps.hmac.EmptySecretKey	401	O valor da variável da chave secreta está vazio.
steps.hmac.EmptyVerificationValue	401	A variável que contém o valor de verificação está vazia.

Erros na implantação

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

Nome do erro	Status HTTP	Ocorre quando
steps.hmac.MissingConfigurationElement	401	Esse erro ocorre quando um elemento ou atributo obrigatório está ausente.
steps.hmac.InvalidValueForElement	401	Esse erro ocorrerá se o valor especificado no elemento algoritmo não for um dos seguintes valores: SHA-1, SHA-224, SHA-256, SHA-512 ou MD-5.
steps.hmac.InvalidSecretInConfig	401	Esse erro ocorre quando há um valor de texto explicitamente fornecido para SecretKey.
steps.hmac.InvalidVariableName	401	Esse erro ocorre se a variável SecretKey não contiver o prefixo private (private.).

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.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed	A política define essa variável em caso de falha.	hmac.HMAC-Policy.failed = true

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>