Skip to main content

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.

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.

Parameter Name Parameter Value
communityCode COMCODE
supplierBusinessCode SUPP
principalAmount 10.00
customParam A custom parameter with special characters &.
hmac dce3bc3945ca4d33151fb4c6a69971d86c35556cc2becafb3cb451f080af3d49

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

Parameter Name Parameter Value
communityCode COMCODE
customParam A custom parameter with special characters &.
principalAmount 10.00
supplierBusinessCode SUPP

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

Parameter Name Parameter Value
communityCode COMCODE
customParam this+is+a+custom+param+with+special+characters+%26
principalAmount 10.00
supplierBusinessCode SUPP

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.

Disclaimer

The information contained in this publication is provided for learning purposes only and is subject to change. Revisions may be issued from time to time that encompass changes or additions to this module.

This is a guide only and it is not comprehensive. It does not impinge on or overrule any formal arrangement you may enter into with the Bank. The Bank and its officers shall not have any liability for any losses of any kind incurred in connection with any action, inaction or decision taken in reliance on the information herein or for any inaccuracies, errors or omissions. In this publication references to the "Bank" are to Westpac Banking Corporation ABN 33 007 457 141 and to any of its operating Divisions, including BankSA and St.George.