Norme HMAC

Norme standard

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio HMAC calcola e verifica facoltativamente un codice HMAC (Hash-based Message Authentication Code). A volte noto come codice di autenticazione del messaggio con chiave o hash con chiave, HMAC utilizza una funzione di hash crittografica come SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 o MD-5, applicata a un "messaggio", insieme a una chiave segreta, per produrre una firma o un codice di autenticazione del messaggio su quel messaggio. Il termine "messaggio" qui si riferisce a qualsiasi flusso di byte. Nel tipico utilizzo di HMAC, il mittente di un messaggio invia un messaggio e il relativo HMAC a un destinatario, che può utilizzare l'HMAC insieme alla chiave segreta condivisa per autenticare il messaggio.

Questa policy è una policy standard e può essere implementata in qualsiasi tipo di ambiente. Per informazioni sui tipi di policy e sulla disponibilità con ogni tipo di ambiente, consulta Tipi di policy.

Per scoprire di più su HMAC, consulta HMAC: Keyed-Hashing for Message Authentication (rfc2104).

Esempi

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

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

Il calcolo di una firma e la verifica di questa firma seguono esattamente la stessa procedura. La policy HMAC calcola un HMAC e, facoltativamente, può verificare la firma calcolata rispetto a un valore previsto. L'elemento facoltativo VerificationValue (se presente) indica alla policy di confrontare il valore calcolato con un valore noto o fornito.

Riferimento all'elemento per HMAC

Il riferimento alle norme descrive gli elementi e gli attributi delle norme HMAC.

Attributi che si applicano all'elemento di primo livello

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

I seguenti attributi sono comuni a tutti gli elementi principali dei criteri.

Attributo Descrizione Predefinito Presenza
nome Il nome interno della policy. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, la UI di Apigee applica ulteriori limitazioni, ad esempio la rimozione automatica dei caratteri non alfanumerici.

(Facoltativo) Utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente Apigee con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError Imposta false per restituire un errore quando una policy non va a buon fine. Questo è il comportamento previsto per la maggior parte delle norme.

Imposta su true per continuare l'esecuzione del flusso anche dopo l'esito negativo di un criterio. Vedi anche:

 falso Facoltativo
abilitato Imposta su true per applicare la policy.

Imposta false per "disattivare" la policy. Il criterio non verrà applicato anche se rimane collegato a un flusso.

 true Facoltativo
asinc Questo attributo è stato ritirato. falso Deprecato

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

Specifica l'algoritmo hash da utilizzare per il calcolo dell'HMAC.

Predefinito N/D
Presenza Obbligatorio
Tipo Stringa
Valori validi SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 e MD-5

La configurazione del criterio accetta i nomi degli algoritmi senza distinzione tra maiuscole e minuscole e con o senza il trattino tra lettere e numeri. Ad esempio, SHA256, SHA-256 e sha256 sono equivalenti.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Utilizza questo attributo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente Apigee con un nome diverso in linguaggio naturale.

Predefinito Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presenza Facoltativo
Tipo Stringa

<Message>

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

Specifica il payload del messaggio da firmare. L'input di questo elemento supporta modelli di messaggi (sostituzione delle variabili) per consentire l'inclusione di elementi aggiuntivi in fase di runtime, come timestamp, nonce, elenchi di intestazioni o altre informazioni. Ad esempio: 

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

Il modello di messaggio può includere parti fisse e variabili, tra cui nuove righe e funzioni statiche. Gli spazi vuoti, come i caratteri di fine riga e gli spazi, sono significativi.

Predefinito N/D
Presenza Obbligatorio
Tipo Stringa
Valori validi Qualsiasi stringa è valida per il valore di testo. Se fornisci un attributo ref, avrà la precedenza sul valore di testo. Il criterio valuta il valore di testo o la variabile a cui viene fatto riferimento come modello di messaggio.

<Output>

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

Specifica il nome della variabile che il criterio deve impostare con il valore HMAC calcolato. Specifica anche la codifica da utilizzare per l'output.

Predefinito

La variabile di output predefinita è hmac.POLICYNAME.output.

Il valore predefinito dell'attributo encoding è base64.
Presenza Facoltativo. Se questo elemento non è presente, il criterio imposta la variabile di flusso hmac.POLICYNAME.output, con un valore con codifica Base64.
Tipo Stringa
Valori validi

Per la codifica, hex, base16, base64, base64url.

I valori non fanno distinzione tra maiuscole e minuscole; hex e base16 sono sinonimi.

Il valore di testo dell'elemento Output può essere qualsiasi nome di variabile di flusso valido.

<SecretKey>

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

Specifica la chiave segreta utilizzata per calcolare l'HMAC. La chiave viene ottenuta dalla variabile a cui viene fatto riferimento, decodificata in base alla codifica specifica.

Predefinito

Non esiste un valore predefinito per la variabile a cui viene fatto riferimento; l'attributo ref è obbligatorio.

In assenza di un attributo encoding, per impostazione predefinita il criterio decodifica la stringa della chiave segreta con UTF-8 per ottenere i byte della chiave.
Presenza Obbligatorio
Tipo Stringa
Valori validi

Per encoding, i valori validi sono hex, base16, base64, utf8. Il valore predefinito è UTF8. I valori non fanno distinzione tra maiuscole e minuscole e i trattini non sono significativi. Base16 è uguale a base-16 e bAse16. Base16 e Hex sono sinonimi.

L'utilizzo di un attributo di codifica ti consente di specificare una chiave che include byte al di fuori dell'intervallo di caratteri stampabili UTF-8. Ad esempio, supponiamo che la configurazione delle norme includa quanto segue: 

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

Supponiamo che private.encodedsecretkey contenga la stringa 536563726574313233.

In questo caso, i byte della chiave verranno decodificati come: [53 65 63 72 65 74 31 32 33] (ogni byte rappresentato in esadecimale). Come altro esempio, se utilizzi encoding='base64', e se private.encodedsecretkey contiene la stringa U2VjcmV0MTIz, il risultato sarà lo stesso insieme di byte per la chiave. Senza attributo di codifica o con un attributo di codifica UTF8, il valore della stringa Secret123 produrrebbe lo stesso insieme di byte. Mostra tre modi diversi per rappresentare la stessa chiave.

<VerificationValue>

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

(Facoltativo) Specifica il valore di verifica, nonché la codifica utilizzata per codificare il valore di verifica. Il criterio utilizzerà questa codifica per decodificare il valore.

Predefinito Non esiste un valore di verifica predefinito. Se l'elemento è presente, ma l'attributo encoding è assente, la norma utilizza una codifica predefinita di base64
Presenza Facoltativo
Tipo Stringa
Valori validi

I valori validi per l'attributo encoding sono: hex, base16, base64, base64url. I valori non fanno distinzione tra maiuscole e minuscole; hex e base16 sono sinonimi.

La codifica di VerificationValue non deve essere la stessa di quella utilizzata per l'elemento Output.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta false se vuoi che il criterio generi un errore quando qualsiasi variabile a cui viene fatto riferimento specificata nel criterio non è risolvibile. Imposta questa opzione su true per trattare qualsiasi variabile non risolvibile come stringa vuota (null).

Il valore booleano IgnoreUnresolvedVariables influisce solo sulle variabili a cui fa riferimento il modello di messaggio. Sebbene SecretKey e VerificationValue possano fare riferimento a una variabile, entrambe devono essere risolvibili, quindi l'impostazione ignore non si applica.

Predefinito Falso
Presenza Facoltativo
Tipo Booleano
Valori validi vero o falso

Variabili di flusso

Il criterio può impostare queste variabili durante l'esecuzione.

Variabile Descrizione Esempio
hmac.policy_name.message Il criterio imposta questa variabile con il messaggio effettivo, il risultato della valutazione del modello di messaggio specificato nell'elemento Message. hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output Restituisce il risultato del calcolo HMAC quando l'elemento Output non specifica un nome di variabile. hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding Restituisce il nome della codifica di output. hmac.HMAC-Policy.outputencoding = base64

Problemi comuni

A un primo livello, la norma HMAC sembra semplice: fornisci una chiave e un messaggio e ricevi un HMAC calcolato in risposta. L'utilizzo del criterio può essere frustrante se ottieni un valore HMAC imprevisto per una combinazione nota di messaggio e chiave. Questa sezione illustra alcune note sull'utilizzo per risolvere questi problemi.

Esistono due insidie comuni che comportano HMAC non corrispondenti durante la verifica: differenze di spazi bianchi nel messaggio e differenze di codifica e decodifica. Quest'ultimo si applica sia all'SecretKey sia all'Output.

Differenze di spazi vuoti

Le differenze che possono sembrare irrilevanti per un essere umano influiscono sul valore HMAC di output. Ad esempio, supponiamo una chiave segreta che può essere rappresentata come "Secret123". Con la decodifica UTF-8, i byte della chiave saranno: [53 65 63 72 65 74 31 32 33]. L'utilizzo di questa chiave per calcolare un HMAC-SHA256 sul messaggio abc genera a7938720fe5749d31076e6961360364c0cd271443f1b580779932c244293bc94. L'aggiunta di un singolo spazio al messaggio, in modo che sia abc<SPACE>, dove <SPACE> implica un ASCII 32, genera un HMAC-SHA256 di 274669b2a85d2532da48e2ce3d8e52ee17346d1bcd1a606d87db1934b5ab294b.

Analogamente, se il messaggio è abc<NEWLINE>, dove <NEWLINE> implica un ASCII 10, l'HMAC è 0780370844ca07f896066837e8230d3b6a775f678a4ae03e6b5e864c674831f5. Piccole modifiche al messaggio generano valori HMAC molto diversi. Si tratta del comportamento previsto. Questo è un comportamento previsto e desiderato di HMAC.

Il punto chiave è che è importante assicurarsi che il corpo del messaggio utilizzato per calcolare l'HMAC originale e il corpo del messaggio utilizzato per verificare l'HMAC siano esattamente gli stessi. Se il verificatore di un HMAC modifica il payload del messaggio in qualsiasi modo, aggiungendo spazi vuoti o riformattando il testo, l'HMAC calcolato cambierà.

Presta particolare attenzione quando utilizzi un modello di messaggio nella configurazione delle norme. Ad esempio, questo frammento di configurazione dei criteri mostra un potenziale problema: 

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

</HMAC>

Il risultato della valutazione del modello di messaggio all'interno dell'elemento <Message> includerà i ritorni a capo e gli spazi che circondano il contenuto del messaggio. Probabilmente non è quello che si intende. Una configurazione migliore sarebbe simile a questa: 

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

</HMAC>

Differenze nella codifica

Decodifiche diverse dello stesso materiale della chiave comportano chiavi diverse. Supponiamo una chiave segreta che può essere rappresentata come "U2VjcmV0S2V5MTIz". Con la decodifica UTF-8, i byte della chiave come rappresentati in base16 saranno: [55 32 56 6a 63 6d 56 30 53 32 56 35 4d 54 49 7a]. Con la decodifica Base64, i byte della chiave saranno [53 65 63 72 65 74 4b 65 79 31 32 33]. La decodifica del materiale di origine in modo diverso genera chiavi diverse, che a loro volta generano valori HMAC diversi.

Il punto chiave è che è importante assicurarsi che il materiale della chiave utilizzato per calcolare l'HMAC originale e la chiave utilizzata per verificare l'HMAC siano esattamente gli stessi. Ciò probabilmente significa assicurarsi che venga utilizzata la stessa codifica della chiave su entrambe le estremità. Nella policy HMAC, puoi utilizzare l'attributo encoding nell'elemento SecretKey per specificare la codifica della chiave.

Considera anche le codifiche nell'output. Un HMAC-SHA256 espresso in codifica esadecimale o base16 come 27f17e11c8ece93844c5eb5e55161d993368628a214f9a51c25d0185e8ea06e2 è uguale a un HMAC-SHA256 espresso in formato con codifica base64 come J/F+Ecjs6ThExeteVRYdmTNoYoohT5pRwl0BhejqBuI=. Hanno un aspetto diverso, ma queste due stringhe rappresentano lo stesso valore. Assicurati che venga utilizzata la stessa codifica per codificare l'HMAC calcolato originariamente e l'HMAC di verifica. Nella policy HMAC, puoi utilizzare l'attributo encoding nell'elementoOutput per specificare la codifica di output desiderata e lo stesso attributo nell'elementoVerificationValue per specificare come decodificare il verificatore.

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:

  • Out of scope (not available in the specific flow where the policy is being executed)

    or

  • Can't be resolved (is not defined)
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 emtpy.

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

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed Il criterio imposta questa variabile in caso di errore. hmac.HMAC-Policy.failed = true

Esempio di risposta di errore

Per la gestione degli errori, la best practice è intercettare la parte errorcode della risposta all'errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

Esempio di regola di errore

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