From 063471fd518c22e4f66a28a6d6ae52ae6bc90ec6 Mon Sep 17 00:00:00 2001 From: Mohammed Islam Date: Mon, 21 Oct 2024 16:36:19 +0100 Subject: [PATCH 1/7] docs: 466/hash-verification --- docs/astro.config.mjs | 33 ++++++++++---- docs/src/content/docs/introduction/grants.mdx | 12 ----- .../docs/introduction/hash-verification.mdx | 45 +++++++++++++++++++ docs/src/content/docs/introduction/idp.mdx | 22 +++++++++ 4 files changed, 91 insertions(+), 21 deletions(-) create mode 100644 docs/src/content/docs/introduction/hash-verification.mdx create mode 100644 docs/src/content/docs/introduction/idp.mdx diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index dbc49faa..7da8039b 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -69,15 +69,30 @@ export default defineConfig({ }, { label: 'Grant negotiation and authorization', - link: '/introduction/grants/' - }, - { - label: 'Client keys', - link: '/introduction/client-keys/' - }, - { - label: 'HTTP message signatures', - link: '/introduction/http-signatures/' + collapsed: true, + + items: [ + { + label: 'Overview', + link: '/introduction/grants/' + }, + { + label: 'Identity providers', + link: '/introduction/idp/' + }, + { + label: 'Client keys', + link: '/introduction/client-keys/' + }, + { + label: 'HTTP message signatures', + link: '/introduction/http-signatures/' + }, + { + label: 'Hash verification', + link: '/introduction/hash-verification/' + } + ] } ] }, diff --git a/docs/src/content/docs/introduction/grants.mdx b/docs/src/content/docs/introduction/grants.mdx index ac2e8f4c..6ddd854c 100644 --- a/docs/src/content/docs/introduction/grants.mdx +++ b/docs/src/content/docs/introduction/grants.mdx @@ -93,15 +93,3 @@ Operations on the APIs by a client require the client to have a valid access tok :::note An open-source implementation of an Open Payments resource server, called Rafiki, is currently in development. ::: - -## Identity providers - -An identity provider (IdP) is a system or service that manages user authentication, identity information, and consent. Open Payments requires any AS that issues interactive grants be integrated with an IdP. - -After an interactive grant request is initiated and the AS sets the session, the AS provides the client with the IdP URI to redirect the end-user to. - - - -:::tip[Reference implementation] -Rafiki provides a reference authorization service implementation that includes support for integration with an IdP. -::: diff --git a/docs/src/content/docs/introduction/hash-verification.mdx b/docs/src/content/docs/introduction/hash-verification.mdx new file mode 100644 index 00000000..73a29d1b --- /dev/null +++ b/docs/src/content/docs/introduction/hash-verification.mdx @@ -0,0 +1,45 @@ +--- +title: Hash verification +--- + +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' + +Once a resource owner (RO) authorizes a client software, the authorization server (AS) will redeirect the RO's [identify provider (IdP)](/introduction/idp/) to the finish URI. 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 (0x0A) character to separate them: + +1. `nonce` value sent by the client in the initial request. +2. `nonce` value sent by the AS from the interaction finish response. +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. + + + +```http +VJLO6A4CATR0KRO +MBDOFXG4Y5CVJCX821LH +4IFWWIKYB2PQ6U56NL1 +https://server.example.com/tx +``` + + + +The ASCII encoding of this string is hashed with the algorithm specified in the `hash_method` parameter under the `finish` key of the interaction finish request. The byte array from the hash function is then encoded using URL-Safe Base64 with no padding. The resultant string is the hash value. + +Unless specified by the client in the initial request, the `hash_method` will default to `sha-256`. If the client specifies the `hash_method`, the `hash_method` **_must_** be one of the hash name strings defined in the IANA Named Information Hash Algorithm Registry. + +Using our hash base string example above, the following is the `sha-256` encoded hash that uses the 256-bit SHA2 algorithm. + + + +```http +x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY +``` + + + +For more information refer to the "Calculating the interaction hash" section of the GNAP specification. diff --git a/docs/src/content/docs/introduction/idp.mdx b/docs/src/content/docs/introduction/idp.mdx new file mode 100644 index 00000000..8c7e9240 --- /dev/null +++ b/docs/src/content/docs/introduction/idp.mdx @@ -0,0 +1,22 @@ +--- +title: Identity providers +--- + +import { + CodeBlock, + LinkOut, + Tooltip, + Mermaid, + MermaidWrapper +} from '@interledger/docs-design-system' +import Interactive from '/src/partials/diagram-interactive-grant.mdx' + +An identity provider (IdP) is a system or service that manages user authentication, identity information, and consent. Open Payments requires any authorization server (AS) that issues interactive grants be integrated with an IdP. + +After an interactive grant request is initiated and the AS sets the session, the AS provides the client with the IdP URI to redirect the end-user to. + + + +:::tip[Reference implementation] +Rafiki provides a reference authorization service implementation that includes support for integration with an IdP. +::: From 1bbb99941fc40cb0a5a3000bfdf98903f298b66d Mon Sep 17 00:00:00 2001 From: Mohammed Islam Date: Mon, 21 Oct 2024 17:31:53 +0100 Subject: [PATCH 2/7] docs: fixed broken links in op-flow and glossary --- docs/src/content/docs/introduction/op-flow.mdx | 2 +- docs/src/content/docs/resources/glossary.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/introduction/op-flow.mdx b/docs/src/content/docs/introduction/op-flow.mdx index 4509cfb9..8ed0a10a 100644 --- a/docs/src/content/docs/introduction/op-flow.mdx +++ b/docs/src/content/docs/introduction/op-flow.mdx @@ -149,7 +149,7 @@ Similarly, the client can provide the end-user with details about a specific
  • Date: Tue, 22 Oct 2024 12:22:59 +0100 Subject: [PATCH 3/7] Update hash-verification.mdx --- docs/src/content/docs/introduction/hash-verification.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/introduction/hash-verification.mdx b/docs/src/content/docs/introduction/hash-verification.mdx index 73a29d1b..43511534 100644 --- a/docs/src/content/docs/introduction/hash-verification.mdx +++ b/docs/src/content/docs/introduction/hash-verification.mdx @@ -4,7 +4,7 @@ title: Hash verification import { CodeBlock, LinkOut } from '@interledger/docs-design-system' -Once a resource owner (RO) authorizes a client software, the authorization server (AS) will redeirect the RO's [identify provider (IdP)](/introduction/idp/) to the finish URI. 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. +Once a resource owner (RO) authorizes a client software, the authorization server (AS) will redirect the RO's [identity provider (IdP)](/introduction/idp/) to the finish URI. 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 @@ -42,4 +42,4 @@ x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY -For more information refer to the "Calculating the interaction hash" section of the GNAP specification. +For more information refer to the Calculating the interaction hash section of the GNAP specification. From b32911bdac9139e5bd98125e22c31959d2a1c52c Mon Sep 17 00:00:00 2001 From: Mohammed Islam Date: Tue, 19 Nov 2024 14:22:09 +0100 Subject: [PATCH 4/7] docs: mi/466/050/hash-verification/starlight-details - edit hash verification page for changes suggested by Radu - replace custom Disclosure components with details component - remove Disclosure references from Import statements --- docs/README.md | 5 ++--- .../docs/introduction/hash-verification.mdx | 6 +++--- docs/src/content/docs/snippets/grant-continue.mdx | 2 +- docs/src/content/docs/snippets/grant-create.mdx | 2 +- .../src/content/docs/snippets/incoming-create.mdx | 2 +- docs/src/content/docs/snippets/incoming-list.mdx | 2 +- .../src/content/docs/snippets/outgoing-create.mdx | 2 +- docs/src/content/docs/snippets/outgoing-get.mdx | 2 +- docs/src/content/docs/snippets/outgoing-list.mdx | 2 +- docs/src/content/docs/snippets/quote-create.mdx | 2 +- docs/src/content/docs/snippets/quote-get.mdx | 2 +- docs/src/content/docs/snippets/token-revoke.mdx | 2 +- docs/src/content/docs/snippets/token-rotate.mdx | 2 +- .../src/content/docs/snippets/wallet-get-keys.mdx | 2 +- docs/src/partials/code-snippets-template.mdx | 15 +-------------- docs/src/partials/js-prerequisites.mdx | 6 +++--- docs/src/partials/ts-prerequisites.mdx | 8 ++++---- 17 files changed, 25 insertions(+), 39 deletions(-) diff --git a/docs/README.md b/docs/README.md index b59926ca..e068969b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,7 +61,6 @@ Refer to the Starlight documentation on [authoring content](https://starlight.as We have extracted some of the commonly repeated patterns within the documentation pages into custom docs components that can be reused. There are components which are shared across all our Starlight documentation sites and those which are specific to this project only. This will determine what the import path is. - CodeBlock (Shared) -- Disclosure (Shared) - Hidden (Shared) - LargeImg (Shared) - LinkOut (Shared) @@ -72,10 +71,10 @@ We have extracted some of the commonly repeated patterns within the documentatio - [FullSnippet](#fullsnippet-component) (Project-specific) - [ChunkedSnippet](#chunkedsnippet-component) (Project-specific) -For the shared components, if you are using both `CodeBlock` and `Disclosure` on the same page, you can import them both like so: +For the shared components, if you are using both `CodeBlock` and `Hidden` on the same page, you can import them both like so: ```jsx -import { CodeBlock, Disclosure } from '@interledger/docs-design-system' +import { CodeBlock, Hidden } from '@interledger/docs-design-system' ``` For more information about importing things in Javascript, please refer to [import on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). diff --git a/docs/src/content/docs/introduction/hash-verification.mdx b/docs/src/content/docs/introduction/hash-verification.mdx index 43511534..ea2b87ac 100644 --- a/docs/src/content/docs/introduction/hash-verification.mdx +++ b/docs/src/content/docs/introduction/hash-verification.mdx @@ -8,10 +8,10 @@ Once a resource owner (RO) authorizes a client software, the authorization serve ## Hashing method -The hash base is generated by concatentating the following values in sequence using a single newline (0x0A) character to separate them: +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 sent by the AS from the interaction finish response. +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. @@ -28,7 +28,7 @@ https://server.example.com/tx -The ASCII encoding of this string is hashed with the algorithm specified in the `hash_method` parameter under the `finish` key of the interaction finish request. The byte array from the hash function is then encoded using URL-Safe Base64 with no padding. The resultant string is the hash value. +The ASCII encoding of this string is hashed with the algorithm specified in the `hash_method` parameter under the `finish` key of the interaction finish request. The byte array from the hash function is then encoded using Base64 with no padding. The resultant string is the hash value. Unless specified by the client in the initial request, the `hash_method` will default to `sha-256`. If the client specifies the `hash_method`, the `hash_method` **_must_** be one of the hash name strings defined in the IANA Named Information Hash Algorithm Registry. diff --git a/docs/src/content/docs/snippets/grant-continue.mdx b/docs/src/content/docs/snippets/grant-continue.mdx index b3702a19..220d7327 100644 --- a/docs/src/content/docs/snippets/grant-continue.mdx +++ b/docs/src/content/docs/snippets/grant-continue.mdx @@ -2,7 +2,7 @@ title: Continue a grant request --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/grant-create.mdx b/docs/src/content/docs/snippets/grant-create.mdx index 36bad820..0993efde 100644 --- a/docs/src/content/docs/snippets/grant-create.mdx +++ b/docs/src/content/docs/snippets/grant-create.mdx @@ -2,7 +2,7 @@ title: Create a grant request --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/incoming-create.mdx b/docs/src/content/docs/snippets/incoming-create.mdx index 612950d7..d71bc76a 100644 --- a/docs/src/content/docs/snippets/incoming-create.mdx +++ b/docs/src/content/docs/snippets/incoming-create.mdx @@ -2,7 +2,7 @@ title: Create an incoming payment --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/incoming-list.mdx b/docs/src/content/docs/snippets/incoming-list.mdx index c31651ac..42082b76 100644 --- a/docs/src/content/docs/snippets/incoming-list.mdx +++ b/docs/src/content/docs/snippets/incoming-list.mdx @@ -2,7 +2,7 @@ title: List incoming payments --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/outgoing-create.mdx b/docs/src/content/docs/snippets/outgoing-create.mdx index 0871f5e9..ca80b1a0 100644 --- a/docs/src/content/docs/snippets/outgoing-create.mdx +++ b/docs/src/content/docs/snippets/outgoing-create.mdx @@ -2,7 +2,7 @@ title: Create an outgoing payment --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/outgoing-get.mdx b/docs/src/content/docs/snippets/outgoing-get.mdx index 595858d0..9222c4e1 100644 --- a/docs/src/content/docs/snippets/outgoing-get.mdx +++ b/docs/src/content/docs/snippets/outgoing-get.mdx @@ -2,7 +2,7 @@ title: Get an outgoing payment --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/outgoing-list.mdx b/docs/src/content/docs/snippets/outgoing-list.mdx index c8518955..9f46f120 100644 --- a/docs/src/content/docs/snippets/outgoing-list.mdx +++ b/docs/src/content/docs/snippets/outgoing-list.mdx @@ -2,7 +2,7 @@ title: List outgoing payments --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/quote-create.mdx b/docs/src/content/docs/snippets/quote-create.mdx index 474e0f32..2c07af20 100644 --- a/docs/src/content/docs/snippets/quote-create.mdx +++ b/docs/src/content/docs/snippets/quote-create.mdx @@ -2,7 +2,7 @@ title: Create a quote --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/quote-get.mdx b/docs/src/content/docs/snippets/quote-get.mdx index 01ae66f2..821c2399 100644 --- a/docs/src/content/docs/snippets/quote-get.mdx +++ b/docs/src/content/docs/snippets/quote-get.mdx @@ -2,7 +2,7 @@ title: Get a quote --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/token-revoke.mdx b/docs/src/content/docs/snippets/token-revoke.mdx index f7d5067b..825036d9 100644 --- a/docs/src/content/docs/snippets/token-revoke.mdx +++ b/docs/src/content/docs/snippets/token-revoke.mdx @@ -2,7 +2,7 @@ title: Revoke an access token --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/token-rotate.mdx b/docs/src/content/docs/snippets/token-rotate.mdx index ccc53367..3336846a 100644 --- a/docs/src/content/docs/snippets/token-rotate.mdx +++ b/docs/src/content/docs/snippets/token-rotate.mdx @@ -2,7 +2,7 @@ title: Rotate an access token --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/content/docs/snippets/wallet-get-keys.mdx b/docs/src/content/docs/snippets/wallet-get-keys.mdx index 51d73d78..3c768c7c 100644 --- a/docs/src/content/docs/snippets/wallet-get-keys.mdx +++ b/docs/src/content/docs/snippets/wallet-get-keys.mdx @@ -2,7 +2,7 @@ title: Get keys bound to a wallet address --- -import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' import Begin from '/src/partials/before-you-begin.mdx' diff --git a/docs/src/partials/code-snippets-template.mdx b/docs/src/partials/code-snippets-template.mdx index 43679300..024111cf 100644 --- a/docs/src/partials/code-snippets-template.mdx +++ b/docs/src/partials/code-snippets-template.mdx @@ -2,7 +2,7 @@ title: Change this title --- -import { Disclosure, CodeBlock } from '@interledger/docs-design-system' +import { CodeBlock } from '@interledger/docs-design-system' import { Tabs, TabItem } from '@astrojs/starlight/components' import FullSnippet from '/src/components/FullSnippet.astro' import ChunkedSnippet from '/src/components/ChunkedSnippet.astro' @@ -30,19 +30,6 @@ import Ts from '/src/partials/ts-prerequisites.mdx' - - -Delete the contents of this disclosure and replace it with a link to the raw source -file like so: - -```html - -``` - - - ## References - [Link to concept page(s)]() diff --git a/docs/src/partials/js-prerequisites.mdx b/docs/src/partials/js-prerequisites.mdx index 106685f1..ba6c3808 100644 --- a/docs/src/partials/js-prerequisites.mdx +++ b/docs/src/partials/js-prerequisites.mdx @@ -1,7 +1,7 @@ import { LinkOut, Disclosure } from '@interledger/docs-design-system' - - +
    +Prerequisites - Node 18 or higher - A package manager such as NPM or PNPM - @@ -12,4 +12,4 @@ import { LinkOut, Disclosure } from '@interledger/docs-design-system' Add `"type": "module"` to `package.json` - +
    diff --git a/docs/src/partials/ts-prerequisites.mdx b/docs/src/partials/ts-prerequisites.mdx index 75e95c7f..76dc2554 100644 --- a/docs/src/partials/ts-prerequisites.mdx +++ b/docs/src/partials/ts-prerequisites.mdx @@ -1,7 +1,7 @@ -import { LinkOut, Disclosure } from '@interledger/docs-design-system' - - +import { LinkOut } from '@interledger/docs-design-system' +
    +Prerequisites - Node 18 - A package manager such as NPM or PNPM - @@ -24,4 +24,4 @@ Add the following to `tsconfig.json` } ``` - +
    From 8377884625d071362e89ca2fe3a49eb05c4bf439 Mon Sep 17 00:00:00 2001 From: Mohammed Islam Date: Tue, 10 Dec 2024 15:07:30 +0100 Subject: [PATCH 5/7] docs: mi/466/hash-verification --- .../docs/introduction/hash-verification.mdx | 14 +++++++++----- docs/src/content/docs/introduction/idp.mdx | 2 +- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/src/content/docs/introduction/hash-verification.mdx b/docs/src/content/docs/introduction/hash-verification.mdx index ea2b87ac..fff3b432 100644 --- a/docs/src/content/docs/introduction/hash-verification.mdx +++ b/docs/src/content/docs/introduction/hash-verification.mdx @@ -2,9 +2,9 @@ title: Hash verification --- -import { CodeBlock, LinkOut } from '@interledger/docs-design-system' +import { CodeBlock, LinkOut, Tooltip } from '@interledger/docs-design-system' -Once a resource owner (RO) authorizes a client software, the authorization server (AS) will redirect the RO's [identity provider (IdP)](/introduction/idp/) to the finish URI. 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. +Once a resource owner (RO) authorizes a client software, the authorization server (AS) will redirect the RO's [identity provider (IdP)](/introduction/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 @@ -28,9 +28,7 @@ https://server.example.com/tx -The ASCII encoding of this string is hashed with the algorithm specified in the `hash_method` parameter under the `finish` key of the interaction finish request. The byte array from the hash function is then encoded using Base64 with no padding. The resultant string is the hash value. - -Unless specified by the client in the initial request, the `hash_method` will default to `sha-256`. If the client specifies the `hash_method`, the `hash_method` **_must_** be one of the hash name strings defined in the IANA Named Information Hash Algorithm Registry. +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. @@ -42,4 +40,10 @@ 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. + +## Further reading + For more information refer to the Calculating the interaction hash section of the GNAP specification. diff --git a/docs/src/content/docs/introduction/idp.mdx b/docs/src/content/docs/introduction/idp.mdx index 8c7e9240..fa72caff 100644 --- a/docs/src/content/docs/introduction/idp.mdx +++ b/docs/src/content/docs/introduction/idp.mdx @@ -18,5 +18,5 @@ After an interactive grant request is initiated and the AS sets the session, the :::tip[Reference implementation] -Rafiki provides a reference authorization service implementation that includes support for integration with an IdP. +Rafiki provides a reference authorization service implementation that includes support for integration with an IdP. ::: From 221c32840f215061bd957e3d482fa7a57e26b0ef Mon Sep 17 00:00:00 2001 From: Mohammed Islam Date: Tue, 10 Dec 2024 15:08:49 +0100 Subject: [PATCH 6/7] docs: mi/466/hash-verification --- docs/src/content/docs/introduction/hash-verification.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/introduction/hash-verification.mdx b/docs/src/content/docs/introduction/hash-verification.mdx index fff3b432..31ebc3f9 100644 --- a/docs/src/content/docs/introduction/hash-verification.mdx +++ b/docs/src/content/docs/introduction/hash-verification.mdx @@ -28,7 +28,7 @@ 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. +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. @@ -42,7 +42,7 @@ 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. +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. ## Further reading From 48bcf4e6f70d1355dafdc91ce9a9cfaa8cb290e0 Mon Sep 17 00:00:00 2001 From: Mohammed Islam Date: Thu, 19 Dec 2024 11:59:39 +0100 Subject: [PATCH 7/7] docs: mi/466/hash-verification Added Max's JS example for verifying the hash --- .../docs/introduction/hash-verification.mdx | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/src/content/docs/introduction/hash-verification.mdx b/docs/src/content/docs/introduction/hash-verification.mdx index 31ebc3f9..141aca26 100644 --- a/docs/src/content/docs/introduction/hash-verification.mdx +++ b/docs/src/content/docs/introduction/hash-verification.mdx @@ -44,6 +44,27 @@ x-gguKWTj8rQf7d7i3w3UhzvuJ5bpOlKyAlVpLxBffY 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 +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.