HMAC policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Computes and verifies a Hash-based Message Authentication Code (HMAC). Sometimes known as Keyed Message Authentication Code or Keyed hash, HMAC uses a cryptographic hash function like SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 or MD-5, applied to a "message," along with a secret key, to produce a signature or message authentication code on that message. The term "message" here refers to any stream of bytes. A sender of a message can also send an HMAC to a receiver, and the receiver can use the HMAC to authenticate the message.

To learn more about HMAC, see HMAC: Keyed-Hashing for Message Authentication (rfc2104).

Samples

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

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

Element reference for HMAC

The policy reference describes the elements and attributes of the HMAC policy.

Attributes that apply to the top-level element

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

The following attributes are common to all policy parent elements.

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

Specifies the hash algorithm to compute the HMAC.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use in addition to the name attribute to label the policy in the Apigee UI proxy editor with a different, natural-language name.

<Message>

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

Specifies the message payload to sign. This element's input supports message templates (variable substitution) to allow additional items to be included at runtime, such as timestamps, nonces, lists of headers, or other information. For example:

<Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
</Message>

The message template can include fixed and variable parts, including newlines and static functions. Whitespace is significant.

<Output>

<Output encoding='encoding_name'>variable_name</Output>

Specifies the name of the variable that the policy should set with the computed HMAC value. Also specifies the encoding to use for the output.

<SecretKey>

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

Specifies the secret key used to compute the HMAC. The key is obtained from the referenced variable, decoded according to the specific encoding.

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

<VerificationValue>

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

(Optional) Specifies the verification value, as well as the encoding algorithm that was used to encode the verification value. The policy will use this algorithm to decode the value.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Set to false if you want the policy to throw an error when any referenced variable specified in the policy is unresolvable. Set to true to treat any unresolvable variable as an empty string (null).

The IgnoreUnresolvedVariables boolean affects only variables that are referenced by the message template. While SecretKey and VerificationValue can reference a variable, both of those need to be resolvable, so the ignore setting does not apply to those.

Flow variables

The policy can set these variables during execution.

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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

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

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>