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 |
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 |
falso | Facoltativo |
abilitata |
Imposta il valore su true per applicare il criterio.
Imposta su |
true | Facoltativo |
asinc | Questo attributo è obsoleto. | falso | Deprecato |
<Algorithm>
<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, |
<DisplayName>
<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 |
<Message>
<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. |
<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.
Predefinita |
La variabile di output predefinita è Il valore predefinito per l'attributo |
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, I valori non fanno distinzione tra maiuscole e minuscole. Il valore testuale dell'elemento |
<SecretKey>
<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 In assenza di un attributo |
Presenza | Obbligatorio |
Tipo | Stringa |
Valori validi | Per 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
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 |
<VerificationValue>
<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: La codifica di |
<IgnoreUnresolvedVariables>
<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:
|
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>