Hash verification

Once a resource owner (RO) authorizes a client software, the authorization server (AS) will redirect the RO’s identity provider (IdP) to the finish URI if the client had provided an interact.finish object in the intial request. In order to secure this communication and verify that the redirect indeed emanated from the AS, the AS will provide a hash parameter in the request to the client’s callback URI. The client must verify this hash.

Hashing method

The hash base is generated by concatentating the following values in sequence using a single newline (/n) character to separate them:

1. nonce value sent by the client in the initial request.
2. nonce value returned from the AS after the initial grant request.
3. interact_ref returned from the AS in the interaction finish method.
4. The grant endpoint uri the client used to make its initial request.

The following example shows the four aforementioned components that make up the hash base. There is no padding or whitespace before or after each line and no trailing newline character.

Example hash base

VJLO6A4CATR0KRO
MBDOFXG4Y5CVJCX821LH
4IFWWIKYB2PQ6U56NL1
https://server.example.com/tx

The ASCII encoding of this string is hashed with the sha-256 algorithm, which is the only hashing algorithm currently supported by Open Payments. The byte array from the hash function is then encoded using Base64 with no padding. The resultant string is the hash value.

Using our hash base string example above, the following is the sha-256 encoded hash that uses the 256-bit SHA2 algorithm.

SHA2 256-bit hash example

x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY

Verifying hash

When the client receives a redirect from the AS, the AS will include the hash parameter in the response. The client must calculate this exact value by concatenating the fields referenced above and then applying the sha-256 hashing algorithm. If the hash value matches the parameter sent by the AS, then the client can be certain the redirect emanated from the AS.

The example below demonstrates how to verify the hash received from the AS using a function in Javascript.

JavaScript example

function verifyHash(
  clientNonce,
  interactNonce,
  interactRef,
  authServerUrl,
  receivedHash
) {
  const data = `${clientNonce}\n${interactNonce}\n${interactRef}\n${authServerUrl}/`
  const hash = createHash('sha-256').update(data).digest('base64')

  return hash === receivedHash
}

Further reading

For more information refer to the Calculating the interaction hash section of the GNAP specification.