Hash verification

Summary

After a resource owner allows a client to access their account, the client must verify that the resource owner provided their consent. The client verifies consent by calculating the hash issued by the authorization server.

After a resource owner accepts an interaction at the identity provider (IdP), the authorization server responds to the IdP with an interact.finish URL. To secure the communication and verify that the URL came from the authorization server, the authorization server also provides a unique hash as a query parameter in the URL. The IdP redirects the client to the URL and provides the hash to the client, which the client must verify.

Hashing method

The hash base is generated by concatenating 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.