Norme HMAC

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X.
Informazioni

Calcola e verifica un codice HMAC (Hash-based Message Authentication Code). A volte noto come Keyed Message Authentication Code o hash con chiave, HMAC utilizza un hash crittografico funzione 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. Termine "messaggio" qui si riferisce a qualsiasi flusso di byte. Il mittente di un messaggio può anche inviare un HMAC a un destinatario, e il destinatario può utilizzare HMAC per autenticare il messaggio.

Per scoprire di più su HMAC, consulta HMAC: Keyed-Hashing per l'autenticazione dei messaggi (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 e la verifica della firma seguono esattamente le stesse e il processo di sviluppo. Il criterio HMAC calcola un HMAC e, facoltativamente, può verificare il valore calcolato in base a un valore previsto. L'elemento facoltativo VerificationValue (se presente) indica al criterio di verificare il valore calcolato a fronte di un valore valore.


Riferimento elemento per HMAC

La guida di riferimento al criterio descrive gli elementi e gli attributi del criterio HMAC.

Attributi che applica all'elemento di primo livello

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

I seguenti attributi sono comuni a tutti gli elementi principali del criterio.

Attributo Descrizione Predefinita Presenza
nome Il nome interno del criterio. I caratteri utilizzabili nel nome sono limitati a: A-Z0-9._\-$ %. Tuttavia, la UI di Apigee applica come la rimozione automatica di caratteri non alfanumerici.

Se vuoi, puoi usare l'elemento <displayname></displayname> per etichetta il criterio nell'editor proxy della UI di Apigee con una lingua diversa, nome.

N/D Obbligatorio
continueOnError Imposta il valore su false per restituire un errore quando un criterio non viene eseguito. Si tratta di un comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche dopo un criterio non riesce.

falso Facoltativo
abilitata Imposta il valore su true per applicare il criterio.

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

true Facoltativo
asinc Questo attributo è obsoleto. falso Deprecato

&lt;Algorithm&gt;

<Algorithm>algorithm-name</Algorithm>

Specifica l'algoritmo hash per calcolare l'HMAC.

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

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

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

Da utilizzare in aggiunta all'attributo name per etichettare il criterio nell'editor proxy della UI di Apigee con un nome diverso in linguaggio naturale.

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

&lt;Message&gt;

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

Specifica il payload dei messaggi da firmare. L'input di questo elemento supporta modelli di messaggi (sostituzione di 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. Lo spazio vuoto è significativo.

Predefinita 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 testo o la variabile di riferimento come modello di messaggio.

&lt;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.

Predefinita

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 codificato base64.
Tipo Stringa
Valori validi

Per la codifica, hex, base16, base64 e 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.

&lt;SecretKey&gt;

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

Specifica la chiave segreta utilizzata per calcolare l'HMAC. La chiave viene ottenuta dall'oggetto decodificata in base alla codifica specifica.

Predefinita

Non esiste un 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 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, mentre i trattini sono non significativo. Base16 è uguale a base-16 e bAse16. Base16 e Hex sono sinonimi.

L'utilizzo di un attributo di codifica consente di specificare una chiave include byte che non rientrano nell'intervallo di caratteri stampabili UTF-8. Ad esempio, supponiamo che la configurazione dei criteri includa quanto segue:

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

Supponiamo che private.encodedsecretkey contenga la stringa 536563726574313233.

In questo caso, i byte della chiave saranno decodificati come: [53 65 63 72 65 74 31 32 33] (ogni byte rappresentato in esadecimale). Come ulteriore esempio, se encoding='base64', e private.encodedsecretkey contiene la stringa U2VjcmV0MTIz, lo stesso set di byte per la chiave. Senza attributo di codifica, o con un attributo di codifica UTF8, il valore della stringa Secret123 genererà lo stesso insieme di byte.

&lt;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 che era utilizzato per codificare il valore di verifica. Il criterio utilizzerà questo algoritmo per decodificare il valore.

Predefinita Non è presente alcun 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 necessariamente la stessa della codifica utilizzata per l'elemento Output.

&lt;IgnoreUnresolvedVariables&gt;

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Imposta su false se vuoi che il criterio generi un errore quando viene specificata una variabile di riferimento del criterio non è risolvibile. Imposta su true per trattare le variabili non risolvibili come stringhe vuote (nullo).

Il valore booleano IgnoraUnresolvedVariables influisce solo sulle variabili a cui viene fatto riferimento nel di messaggistica di Google. Sebbene SecretKey e VerificationValue possano fare riferimento a una variabile, di queste devono essere risolvibili, quindi l'impostazione ignore non si applica a queste ultime.

Predefinita 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, il risultato della valutazione del modello di messaggio specificato in Message . hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output Restituisce il risultato di il calcolo HMAC, quando l'elemento Output non specificare un nome per la variabile. hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding Restituisce il nome della codifica di output. hmac.HMAC-Policy.outputencoding = base64

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

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

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed The policy sets this variable in the case of a failure. hmac.HMAC-Policy.failed = true

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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