HMAC policy

This page applies to Apigeeand Apigee hybrid.

View Apigee Edge documentation.

This policy computes and optionally 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. In the typical use of HMAC, a sender of a message sends a message and its HMAC to a receiver, and the receiver can use the HMAC along with the shared secret key to authenticate the message.

This policy is a Standard policy and can be deployed to any environment type. For information on policy types and availability with each environment type, see Policy types .

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

Samples

< HMAC 
  
 name 
 = 
 'HMAC-1' 
>  
< Algorithm>SHA256 
< / 
 Algorithm 
>  
< !-- 
  
 the 
  
 default 
  
 encoding 
  
 of 
  
 the 
  
 SecretKey 
  
 is 
  
 UTF 
 - 
 8 
  
 -- 
>  
< SecretKey 
  
 encoding 
 = 
 'base64' 
  
 ref 
 = 
 'private.secretkey' 
 / 
>  
< IgnoreUnresolvedVariables>true 
 | 
 false 
< / 
 IgnoreUnresolvedVariables 
>  
< !-- 
  
 optional 
  
 -- 
>  
< !-- 
  
 The 
  
 Message 
  
 element 
  
 accepts 
  
 a 
  
 template 
 , 
  
 which 
  
 means 
  
 the 
  
 "message" 
  
 the 
  
 policy 
  
 operates 
  
 on 
  
 can 
  
 include 
  
 fixed 
  
 and 
  
 multiple 
  
 variable 
  
 parts 
 , 
  
 including 
  
 newlines 
  
 and 
  
 static 
  
 functions 
 . 
  
 Whitespace 
 , 
  
 such 
  
 as 
  
 newlines 
  
 and 
  
 space 
  
 characters 
 , 
  
 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 
>  
< !-- 
  
 the 
  
 default 
  
 encoding 
  
 of 
  
 the 
  
 SecretKey 
  
 is 
  
 UTF 
 - 
 8 
  
 -- 
>  
< SecretKey 
  
 encoding 
 = 
 'base16' 
  
 ref 
 = 
 'private.secretkey' 
 / 
>  
< IgnoreUnresolvedVariables>true 
 | 
 false 
< / 
 IgnoreUnresolvedVariables 
>  
< !-- 
  
 optional 
  
 -- 
>  
< !-- 
  
 The 
  
 Message 
  
 element 
  
 accepts 
  
 a 
  
 template 
 . 
  
 This 
  
 policy 
  
 verifies 
  
 an 
  
 HMAC 
  
 on 
  
 the 
  
 request 
  
 content 
 . 
  
 -- 
>  
< Message 
> { 
 request 
 . 
 content 
 } 
< / 
 Message 
>  
< !-- 
  
 VerificationValue 
  
 is 
  
 optional 
 . 
  
 Include 
  
 it 
  
 to 
  
 perform 
  
 an 
  
 HMAC 
  
 check 
 . 
  
 -- 
>  
< VerificationValue 
  
 encoding 
 = 
 'base16' 
  
 ref 
 = 
 'expected_hmac_value' 
 / 
>  
< !-- 
  
 default 
  
 encoding 
  
 of 
  
 the 
  
 output 
  
 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 use when computing 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, such as newlines and space characters, 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 that was used to encode the verification value. The policy will use this encoding 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.

Common Issues

At one level, the HMAC policy seems to be straightforward: provide a key and a message, and get a computed HMAC in response. It can be frustrating when using the policy if you obtain an unexpected HMAC value for a known message and key combination. This section will explain some usage notes to work through such problems.

There are two common pitfalls that result in mismatched HMACs during verification: whitespace differences in the message, and differences in encoding and decoding. The latter applies to both the SecretKey element as well as the Output element .

Whitespace Differences

Differences that may seem unimportant to a human, affect the output HMAC value. For example, suppose a secret key that can be represented as "Secret123". With UTF-8 decoding, the key bytes will be: [53 65 63 72 65 74 31 32 33] . Using that key to compute an HMAC-SHA256 on the message abc results in a7938720fe5749d31076e6961360364c0cd271443f1b580779932c244293bc94 . Adding a single space to the message, so that it is abc<SPACE> , where <SPACE> implies an ASCII 32, results in an HMAC-SHA256 of 274669b2a85d2532da48e2ce3d8e52ee17346d1bcd1a606d87db1934b5ab294b .

Similarly, if the message is abc<NEWLINE> , where <NEWLINE> implies an ASCII 10, the HMAC is 0780370844ca07f896066837e8230d3b6a775f678a4ae03e6b5e864c674831f5 . Slight changes in the message result in very different HMAC values. This is by design. This is an intended and desired behavior of HMAC.

The takeaway: It's important to ensure that the message body used to calculate the original HMAC and the message body used to verify the HMAC are exactly the same. If the verifier of an HMAC changes the message payload in any way, by adding any whitespace or reformatting the text, the calculated HMAC will change.

Take special care when using a message template in the policy configuration. For example, this policy configuration fragment shows a potential problem:

<HMAC name='HMAC-1'>
    ...
    <!-- the result of this message template will include surrounding whitespace -->
    <Message>
        {request.content}
    </Message>
    ...
       
</HMAC>

The result of evaluating the message template within the <Message> element will include newlines and spaces surrounding the message content. This is probably not what is intended. A better configuration would look like this:

<HMAC name='HMAC-1'>
    ...
    <Message>{request.content}</Message>
    ...
         
</HMAC>

Differences in Encoding

Different decodings of the same key material, results in different keys. Suppose a secret key that can be represented as "U2VjcmV0S2V5MTIz". With UTF-8 decoding, the key bytes as representated in base16 will be: [55 32 56 6a 63 6d 56 30 53 32 56 35 4d 54 49 7a] . With base64-decoding, the key bytes will be [53 65 63 72 65 74 4b 65 79 31 32 33] . Decoding the source material differently results in different keys, and that will result in different HMAC values.

The takeaway: It's important to ensure that the key material used to calculate the original HMAC and the key used to verify the HMAC are exactly the same. This probably means ensuring that the same encoding of the key is used on both ends. In the HMAC policy, you can use the encoding attribute on the SecretKey element to specify the key encoding.

Also consider encodings on the output. An HMAC-SHA256 expressed in base16 or hex encoding as 27f17e11c8ece93844c5eb5e55161d993368628a214f9a51c25d0185e8ea06e2 is the same as an HMAC-SHA256 expressed in base64 encoded form as J/F+Ecjs6ThExeteVRYdmTNoYoohT5pRwl0BhejqBuI= . They look different, but these two strings represent the same value. Ensure that the same encoding is used to encode the originally calculated HMAC, and the verifying HMAC. In the HMAC policy, you can use the encoding attribute on the Output element to specify your desired output encoding, and the same attribute on the VerificationValue element to specify how to decode the verifier.

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>