Norme HMAC

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Questo criterio calcola e, facoltativamente, verifica un codice HMAC (Hash-based Message Authentication Code). A volte noto come Keyed Message Authentication Code o Keyed hash, 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 stream di byte. Nell'utilizzo tipico dell'HMAC, un mittente invia un messaggio e il relativo HMAC a un destinatario, che può utilizzare l'HMAC insieme alla chiave segreta condivisa per autenticare il messaggio.

Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla loro disponibilità in base a ciascun tipo di ambiente, consulta Tipi di criteri.

Per scoprire di più su HMAC, consulta HMAC: hashing con chiave per l'autenticazione dei messaggi (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 e la verifica di una firma seguono esattamente la stessa procedura. Il criterio HMAC calcola un HMAC e può facoltativamente verificare la firma calcolata rispetto a un valore previsto. L'elemento facoltativo VerificationValue (se presente) indica al criterio di verificare il valore calcolato rispetto a un valore conosciuto o fornito.

Riferimento 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 del criterio. I caratteri che puoi utilizzare nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, l'interfaccia utente di Apigee applica ulteriori limitazioni, ad esempio la rimozione automatica dei caratteri non alfanumerici.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di Apigee con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri.

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

 falso Facoltativo
abilitato Imposta su true per applicare il criterio.

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

 true Facoltativo
asinc Questo attributo è stato ritirato. falso Ritirato

<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 dei criteri accetta i nomi degli algoritmi senza distinguere tra lettere 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>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di 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 di variabili) per consentire l'inclusione di elementi aggiuntivi in fase di esecuzione, ad esempio 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 righe nuove 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 del testo. Se fornisci un attributo ref, avrà la precedenza sul valore del testo. Il criterio valuta il valore del 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 codificato in 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 di riferimento, decodificata in base alla codifica specifica.

Predefinito

Non esiste un valore predefinito per la variabile a cui si fa 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 sono irrilevanti. Base16 è uguale a base-16 e bAse16. Base16 e Hex sono sinonimi.

L'utilizzo di un attributo di codifica 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). Un altro esempio: se utilizzi encoding='base64' e private.encodedsecretkey contiene la stringa U2VjcmV0MTIz, verrà generato lo stesso insieme di byte per la chiave. Senza attributo di codifica o con un attributo di codifica UTF8, il valore di stringa Secret123 produrrebbe lo stesso insieme di byte. Vengono mostrati tre diversi modi 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, il criterio utilizza una codifica predefinita di base64
Presenza Facoltativo
Tipo Stringa
Valori validi

I valori validi per l'attributo codifica 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 necessariamente la stessa utilizzata per l'elemento Output.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

L'attributo 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, pertanto l'impostazione ignore non si applica a queste.

Predefinito Falso
Presenza Facoltativo
Tipo Booleano
Valori validi true o false

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, ovvero il risultato della valutazione del modello di messaggio specificato nell'elemento Message. hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output Recupera 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 livello, il criterio HMAC sembra essere 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 di messaggio e chiave nota. In questa sezione vengono spiegate alcune note di utilizzo per risolvere questi problemi.

Esistono due errori comuni che comportano una mancata corrispondenza degli HMAC durante la verifica: spazi vuoti nel messaggio e differenze di codifica e decodifica. Quest'ultimo vale sia per l'elemento SecretKey sia per l'elemento Output.

Differenze negli spazi vuoti

Le differenze che potrebbero sembrare non importanti per un essere umano influiscono sul valore HMAC in uscita. 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 comportano valori HMAC molto diversi. Si tratta del comportamento previsto. Si tratta di un comportamento intenzionale e desiderato di HMAC.

Il messaggio: è importante assicurarsi che il corpo del messaggio utilizzato per calcolare il codice HMAC originale e il corpo del messaggio utilizzato per verificare il codice 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 i contenuti del messaggio. Probabilmente non è ciò che intendi. Una configurazione migliore è la seguente: 

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

Differenze nella codifica

Decodificazioni diverse dello stesso materiale della chiave generano chiavi diverse. Supponiamo una chiave segreta che può essere rappresentata come "U2VjcmV0S2V5MTIz". Con la decodifica UTF-8, i byte della chiave 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]. Se decodifichi il materiale di origine in modo diverso, otterrai chiavi diverse e, di conseguenza, valori HMAC diversi.

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

Prendi in considerazione anche le codifiche in uscita. Un HMAC-SHA256 espresso in codifica esadecimale o base 16 come 27f17e11c8ece93844c5eb5e55161d993368628a214f9a51c25d0185e8ea06e2 è uguale a un HMAC-SHA256 espresso in formato codificato Base64 come J/F+Ecjs6ThExeteVRYdmTNoYoohT5pRwl0BhejqBuI=. Sembrano diverse, ma queste due stringhe rappresentano lo stesso valore. Assicurati di utilizzare la stessa codifica per codificare l'HMAC calcolato inizialmente e l'HMAC di verifica. Nel criterio HMAC, puoi utilizzare l'attributo encoding nell'elemento Output per specificare la codifica di output che preferisci e lo stesso attributo nell'elemento VerificationValue per specificare come decodificare il verificatore.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Si verifica quando
steps.hmac.UnresolvedVariable 401

Questo errore si verifica se una variabile specificata nel criterio HMAC è:

  • Al di fuori dell'ambito (non disponibile nel flusso specifico in cui viene eseguito il criterio)

    o

  • Non può essere risolto (non è definito)
steps.hmac.HmacVerificationFailed 401 La verifica HMAC non è riuscita; il valore di verifica fornito non corrisponde al valore calcolato.
steps.hmac.HmacCalculationFailed 401 Il criterio non è stato in grado di calcolare l'HMAC.
steps.hmac.EmptySecretKey 401 Il valore della variabile della chiave segreta è vuoto.
steps.hmac.EmptyVerificationValue 401 La variabile contenente il valore di verifica è vuota.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome dell'errore Stato HTTP Si verifica quando
steps.hmac.MissingConfigurationElement 401 Questo errore si verifica quando manca un elemento o un attributo obbligatorio.
steps.hmac.InvalidValueForElement 401 Questo errore si verifica se il valore specificato nell'elemento Algorithm non è uno dei seguenti: SHA-1, SHA-224, SHA-256, SHA-512 o MD-5.
steps.hmac.InvalidSecretInConfig 401 Questo errore si verifica se è stato fornito un valore di testo esplicito per SecretKey.
steps.hmac.InvalidVariableName 401 Questo errore si verifica se la variabile SecretKey non contiene il prefisso private (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>