Validating the hmac

The HMAC is included in the parameters returned in the passback from QuickWeb, QuickConnect, QuickVault Web and QuickVault Connect. Use this to validate the parameters in the passback were not tampered.

• The parameters in the passback are signed using the HMAC_SHA256 algorithm.
• Your secure token request password is used as the secret in the HMAC_SHA256 calculation.
• Find the password by viewing your connection details in QuickStream.

To validate the hmac parameter:

1. Remove hmac from the list of parameters returned and order the parameters ASCIIbetically by name.
2. URL encode each parameter with UTF-8 character encoding.
3. Join the parameter names and values with = and each pair with & (as per a query string).
4. Generate the HMAC from this string using secure token request password.
5. Hexadecimal encode the resulting string.
6. Compare the HMAC string you generated to the hmac parameter in the passback.

HMAC validation example

This example illustrates a simple validation of the hmac parameter in the passback.

Step 1: Get the list of parameters returned in the passback.

Step 2: Remove hmac and order the parameters ASCIIbetically by name.

Step 3: URL encode each parameter with UTF-8 character encoding

Ensure the encoded characters are lowercase and not uppercase (for example, %3A not %3a.)

Step 4: Join the parameter names and values with = and each pair with &.

communityCode=COMCODE&customParam=this+is+a+custom+param+with+special+characters+%26&principalAmount=10.00&supplierBusinessCode=SUPP

Step 5: Generate the HMAC from this string using secure token password.

Example hash function in Java

public static String hash( final String password, final String queryString )
{
    final Mac mac = Mac.getInstance( "HmacSHA256" );
    mac.init( new SecretKeySpec( password.getBytes( "UTF-8" ), "HmacSHA256" ) );
    return Hex.encodeHexString( mac.doFinal( queryString.getBytes() ) );
}

Finally, compare the HMAC string you generated to the hmac parameter in the passback. If the strings do not match, there has likely been tampering of the parameters and their values and should not be considered accurate.