HMAC policy

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

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

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

Computation of a signature and verification of that signature follow exactly the same process. The HMAC policy computes an HMAC, and can optionally verify the computed signature against an expected value. The optional VerificationValue element (if present) directs the policy to check the computed value against a known or given value.


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.

Attribute Description Default Presence
name The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Apigee UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <displayname></displayname> element to label the policy in the Apigee UI proxy editor with a different, natural-language name.

N/A Required
continueOnError Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async This attribute is deprecated. false Deprecated

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

Specifies the hash algorithm to compute the HMAC.

Default N/A
Presence Required
Type String
Valid values SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, and MD-5

The policy configuration accepts algorithm names without distinguishing case, and with or without the dash between the letters and numbers . For example, SHA256 and SHA-256 and sha256 are equivalent.

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

Default If you omit this element, the value of the policy's name attribute is used.
Presence Optional
Type String

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

Default N/A
Presence Required
Type String
Valid values Any string is valid for the text value. If you provide a ref attribute, it will take precedence over the text value. The policy evaluates either the text value or the referenced variable as a message template.

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

Default

The default output variable is hmac.POLICYNAME.output.

The default value for the encoding attribute is base64.

Presence Optional. If this element is not present, the policy sets the flow variable hmac.POLICYNAME.output, with a base64-encoded value.
Type String
Valid values

For encoding, hex, base16, base64, base64url.

The values are case insensitive; hex and base16 are synonyms.

The text value of the Output element can be any valid flow variable name.

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

Default

There is no default value for the referenced variable; the ref attribute is required.

In the absence of an encoding attribute, by default the policy decodes the secret key string with UTF-8 to obtain the key bytes.

Presence Required
Type String
Valid values

For encoding, valid values are hex, base16, base64, utf8. The default is UTF8. The values are case-insensitive, and dashes are insignificant. Base16 is the same as base-16 and bAse16. Base16 and Hex are synonyms.

Using an encoding attribute allows you to specify a key that includes bytes outside the range of UTF-8 printable characters. For example, suppose the policy configuration includes this:

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

And suppose private.encodedsecretkey holds the string 536563726574313233.

In this case, the key bytes will be decoded as: [53 65 63 72 65 74 31 32 33] (each byte represented in hex). As another example, if encoding='base64', and private.encodedsecretkey holds the string U2VjcmV0MTIz, it will result in the same set of bytes for the key. With no encoding attribute, or with an encoding attribute of UTF8, the string value Secret123 would result in the same set of bytes.

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

Default There is no default verification value. If the element is present but the encoding attribute is absent, the policy uses a default encoding of base64
Presence Optional
Type String
Valid values

Valid values for the encoding attribute are: hex, base16, base64, base64url. The values are case insensitive; hex and base16 are synonyms.

The encoding of the VerificationValue need not be the same as the encoding used for the Output element.

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

Default False
Presence Optional
Type Boolean
Valid values true or false

Flow variables

The policy can set these variables during execution.

Variable Description Example
hmac.policy_name.message The policy sets this variable with the effective message, the result of evaluating the message template specified in the Message element. hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output Gets the result of the HMAC computation, when the Output element does not specify a variable name. hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding Gets the name of the output encoding. 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 emtpy.

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>