Criterio HMAC

Stai visualizzando la documentazione di Apigee X.
Visualizza la documentazione di Apigee Edge.

icona delle norme

Calcola e verifica un codice HMAC (Hash-based Message Authentication Code). Talvolta noto come Keyed Message Authentication Code o Keyed hash, HMAC utilizza una funzione di crittografia crittografica come SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 o MD-5, applicata a un messaggio "quot;message" e una chiave segreta, per produrre una firma o un codice di autenticazione dei messaggi per quel messaggio. Il termine "messaggio" qui si riferisce a qualsiasi flusso di byte. Il mittente di un messaggio può anche inviare un HMAC a un destinatario, che può utilizzarlo per autenticare il messaggio.

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

Esempi

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

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

Il calcolo di una firma e la verifica di tale firma seguono esattamente la stessa procedura. Il criterio HMAC calcola un HMAC e, facoltativamente, può verificare la firma calcolata in base a un valore previsto. L'elemento facoltativo VerificationValue (se presente) indica al criterio di confrontare il valore calcolato con un valore noto o specificato.

Riferimento elemento per HMAC

Il riferimento del criterio descrive gli elementi e gli attributi del criterio 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 delle norme.

Attributo Descrizione Predefinito Presenza
name 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 restrizioni, come la rimozione automatica dei caratteri non alfanumerici.

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

 N/A Obbligatorie
continueOnError Imposta su false in modo che restituisca un errore quando un criterio non va a buon fine. Si tratta di un comportamento previsto per la maggior parte dei criteri.

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

 falso Facoltativo
attiva Imposta true per applicare il criterio.

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

 true Facoltativo
asinc Questo attributo è obsoleto. falso Deprecato

<Algoritmo&GT;

<Algorithm>algorithm-name</Algorithm>

Specifica l'algoritmo hash per calcolare l'HMAC.

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

La configurazione dei criteri accetta nomi di 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&GT;

<DisplayName>Policy Display Name</DisplayName>

Utilizzalo 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 del nome del criterio.
Presenza Facoltativo
Tipo Stringa

<Messaggio>

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

Specifica il payload del messaggio da firmare. L'input di questo elemento supporta i modelli di messaggi (sostituzione variabile) per consentire l'inclusione di elementi aggiuntivi in fase di runtime, ad esempio timestamp, valori 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. Lo spazio vuoto è significativo.

Predefinito N/A
Presenza Obbligatorie
Tipo Stringa
Valori validi Sono valide tutte le stringhe per il valore di testo. Se fornisci un attributo ref, avrà la precedenza sul valore del testo. Il criterio valuta il valore di testo o la variabile di riferimento come modello di messaggio.

<Output&GT;

<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 per l'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 testuale 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 è previsto alcun valore predefinito per la variabile di riferimento; l'attributo ref è obbligatorio.

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

Per encoding, i valori validi sono hex, base16, base64, utf8. L'impostazione predefinita è 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. Supponi, ad esempio, che la configurazione dei criteri includa quanto segue: 


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

Supponiamo inoltre che private.encodedsecretkey contenga la stringa 536563726574313233.

In questo caso, i byte della chiave vengono decodificati: [53 65 63 72 65 74 31 32 33] (ogni byte rappresentato in esadecimale). Un altro esempio: se encoding='base64', e private.encodedsecretkey contengono la stringa U2VjcmV0MTIz, restituirà la stessa serie di byte per la chiave. Senza un attributo di codifica o con un attributo di codifica UTF8, il valore della stringa Secret123 genererebbe lo stesso insieme di byte.

<VerificationValue&GT;

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

(Facoltativo) Specifica il valore di verifica e l'algoritmo di codifica utilizzato per codificare il valore di verifica. Il criterio utilizzerà questo algoritmo per decodificare il valore.

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

I valori validi per l'attributo di 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 identica a quella utilizzata per l'elemento Output.

<IgnoraUnredVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

Il valore booleano IgnoreUnresolvedVariables interessa soltanto le variabili a cui viene fatto riferimento dal modello di messaggio. SecretKey e VerificationValue possono fare riferimento a una variabile, ma entrambi devono essere risolvibili, pertanto l'impostazione ignore non si applica a tali variabili.

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 Visualizza il nome della codifica dell'output. hmac.HMAC-Policy.outputencoding = base64

Messaggi di errore

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

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Codice di errore Stato HTTP Si verifica quando
steps.hmac.UnresolvedVariable 401

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

  • Fuori ambito (non disponibile nel flusso specifico in cui viene eseguito il criterio)

    o

  • Non può essere risolto (non è definito)
steps.hmac.HmacVerificationFailed 401 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 secret è vuoto.
steps.hmac.EmptyVerificationValue 401 La variabile che contiene il valore di verifica è vuota.

Errori di deployment

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

Nome 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 dell'algoritmo non è uno dei seguenti valori: SHA-1, SHA-224, SHA-256, SHA-512 o MD-5.
steps.hmac.InvalidSecretInConfig 401 Questo errore si verifica se viene fornito esplicitamente un valore di testo 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 maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome dell'errore è l'ultima parte del codice di 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 prevede il trap della parte errorcode della risposta di errore. Non fare affidamento sul testo nel 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>