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.

Once a resource owner authorizes a client software, the authorization server will redirect the resource owner’s identity provider (IdP) to the finish URI if the client had provided an interact.finish object in the initial request. In order to secure this communication and verify that the redirect indeed emanated from the authorization server, the authorization server 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 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 authorization server after the initial grant request.
3. interact_ref returned from the authorization server 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 authorization server, the authorization server 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 authorization server, then the client can be certain the redirect emanated from the authorization server.

The example below demonstrates how to verify the hash received from the authorization server 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.