Política HMAC

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

Calcula e verifica um código de autenticação de mensagem baseado em hash (HMAC, na sigla em inglês). Ás vezes conhecido como código de autenticação de mensagens com chave ou o 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, aplicado 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 fluxo de bytes. Um remetente de uma mensagem também pode enviar um HMAC para um receptor, e ele pode usar o HMAC para autenticar a mensagem.

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

Amostras

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

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

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 computado 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
nome 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></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.

 falso Opcional
ativado 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.

 verdadeiro Opcional
async Esse atributo está obsoleto. falso Obsoleto

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

Especifica o algoritmo hash para 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.

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

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). Como outro exemplo, se encoding='base64' e private.encodedsecretkey manterem a string U2VjcmV0MTIz, ela resultará no 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.

<VerificationValue>

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

(Opcional) Especifica o valor da verificação e o algoritmo de codificação usado 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 Booleano
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

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 HMAC for:

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