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. 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 criteri e sulla disponibilità per ogni tipo di ambiente, consulta Tipi di criteri.

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 al criterio 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 del criterio. 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 la norma nell'editor proxy dell'interfaccia utente Apigee con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError Imposta questo valore su false per restituire un errore quando un criterio non viene rispettato. 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 true per applicare la policy.

Imposta false per "disattivare" la policy. Il criterio non verrà applicato anche se rimane allegato 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 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 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 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 utilizzata per l'elemento Output.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta false se vuoi che la policy generi un errore quando una variabile a cui viene fatto riferimento specificata nella policy 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 Le norme impostano 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 Recupera 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 di messaggio e chiave nota. 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 restituisce 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 bianchi 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à nuove righe e spazi che circondano il contenuto del messaggio. Probabilmente non è quello che si intende. Una configurazione migliore avrebbe il seguente aspetto: 

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

Differenze nella codifica

Decodifiche diverse dello stesso materiale della chiave danno origine a 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. Probabilmente significa assicurarsi che venga utilizzata la stessa codifica della chiave su entrambe le estremità. Nel criterio 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 codificato 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. Nelle norme 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.

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 I criteri non sono riusciti a 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>