docs: 466/hash-verification #512

hajjimo · 2024-10-21T15:37:55Z

Changes proposed in this pull request

Context

changeset-bot · 2024-10-21T15:38:00Z

⚠️ No Changeset found

Latest commit: 0040ace

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

netlify · 2024-10-21T15:38:18Z

✅ Deploy Preview for openpayments-preview ready!

Name	Link
🔨 Latest commit	`0040ace`
🔍 Latest deploy log	https://app.netlify.com/sites/openpayments-preview/deploys/67618585bccfed0008c066b6
😎 Deploy Preview	https://deploy-preview-512--openpayments-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

melissahenderson · 2024-10-22T10:42:31Z

docs/src/content/docs/introduction/hash-verification.mdx

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


Typo "redeirect"

Change "identify provider" to identity provider

melissahenderson · 2024-10-22T10:42:36Z

docs/src/content/docs/introduction/hash-verification.mdx

+
+</CodeBlock>
+
+For more information refer to the <LinkOut href='https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol-20#name-calculating-the-interaction'> "Calculating the interaction hash"</LinkOut> section of the GNAP specification.


Can you remove the quotation marks around the link name?

raducristianpopa · 2024-11-07T12:21:53Z

docs/src/content/docs/introduction/hash-verification.mdx

+
+## Hashing method
+
+The hash base is generated by concatentating the following values in sequence using a single newline (0x0A) character to separate them:


Suggested change

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:

raducristianpopa · 2024-11-07T12:26:32Z

docs/src/content/docs/introduction/hash-verification.mdx

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


The interact nonce is returned after making the initial grant request (interaction instructions):

{ "interact": { "redirect": "https://auth.rafiki.money/4CF492MLVMSW9MKMXKHQ", "finish": "4105340a-05eb-4290-8739-f9e2b463bfa7" // <- nonce }, "continue": { "access_token": { "value": "33OMUKMKSKU80UPRY5NM" }, "uri": "https://auth.rafiki.money/continue/4CF492MLVMSW9MKMXKHQ", "wait": 30 } }

raducristianpopa · 2024-11-07T12:49:05Z

docs/src/content/docs/introduction/hash-verification.mdx

+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 <LinkOut href='https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg'>IANA Named Information Hash Algorithm Registry</LinkOut>.


@mkurapov are we planning to support other hashing methods as well? If not I think we should only mention sha-256.

I don't think so, we can just mention sha-256

raducristianpopa · 2024-11-07T12:52:39Z

docs/src/content/docs/introduction/hash-verification.mdx

+
+</CodeBlock>
+
+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.


In Rafiki we are doing only doing base64 encoding not base64url.

CC @mkurapov

Yes, base64 is correct

- edit hash verification page for changes suggested by Radu - replace custom Disclosure components with details component - remove Disclosure references from Import statements

mkurapov · 2024-11-25T20:50:33Z

docs/src/content/docs/introduction/hash-verification.mdx

+
+import { CodeBlock, LinkOut } 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.


the authorization server (AS) will redirect

even though its probably the most common use case, the AS will redirect only if the client provided an interact.finish object.

I think we need to add a small section about how the client actually would do verification: by generating the hash using the components below, and comparing it to the provided value in the final redirect

mkurapov · 2024-11-25T20:52:44Z

docs/src/content/docs/introduction/hash-verification.mdx

+
+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 <LinkOut href='https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg'>IANA Named Information Hash Algorithm Registry</LinkOut>.


We can say that Open Payments uses sha-256 only (even though GNAP is more flexible)

mkurapov · 2024-11-25T21:07:59Z

docs/src/content/docs/introduction/idp.mdx

+:::tip[Reference implementation]
+Rafiki provides a reference <LinkOut href='https://github.com/interledger/rafiki/tree/main/packages/auth'>authorization service</LinkOut> implementation that includes support for integration with an IdP.
+:::


Let's link to the Rafiki docs?

mkurapov

hash verification doc looks good. I'm wondering if you need to merge in main given we have the other file changes

mkurapov · 2024-12-17T13:05:33Z

docs/src/content/docs/introduction/hash-verification.mdx

+## 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.


If you think its valuable, we can also add a JS 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 }

docs: 466/hash-verification

063471f

hajjimo requested a review from sabineschaller October 21, 2024 15:37

hajjimo requested a review from melissahenderson as a code owner October 21, 2024 15:37

docs: fixed broken links in op-flow and glossary

1bbb999

melissahenderson reviewed Oct 22, 2024

View reviewed changes

Update hash-verification.mdx

6797435

hajjimo linked an issue Nov 4, 2024 that may be closed by this pull request

Add hash verification documentation #466

Open

mkurapov self-requested a review November 5, 2024 14:21

hajjimo requested review from raducristianpopa and removed request for sabineschaller November 7, 2024 08:13

raducristianpopa reviewed Nov 7, 2024

View reviewed changes

hajjimo added 3 commits November 15, 2024 12:26

Merge branch 'main' into mi/466/hash-verification

a296fcc

docs: mi/466/050/hash-verification/starlight-details

b32911b

- edit hash verification page for changes suggested by Radu - replace custom Disclosure components with details component - remove Disclosure references from Import statements

Merge branch 'main' into mi/466/hash-verification

9984d2a

mkurapov reviewed Nov 25, 2024

View reviewed changes

mkurapov added the type: documentation Improvements or additions to documentation label Dec 3, 2024

hajjimo added 3 commits December 10, 2024 15:07

Merge branch 'main' into mi/466/hash-verification

e490101

docs: mi/466/hash-verification

8377884

docs: mi/466/hash-verification

221c328

mkurapov self-requested a review December 10, 2024 14:42

mkurapov reviewed Dec 17, 2024

View reviewed changes

Merge branch 'main' into mi/466/hash-verification

0040ace

mkurapov approved these changes Dec 17, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: 466/hash-verification #512

docs: 466/hash-verification #512

hajjimo commented Oct 21, 2024

changeset-bot bot commented Oct 21, 2024 •

edited

Loading

netlify bot commented Oct 21, 2024 •

edited

Loading

melissahenderson Oct 22, 2024

melissahenderson Oct 22, 2024

raducristianpopa Nov 7, 2024

raducristianpopa Nov 7, 2024

raducristianpopa Nov 7, 2024

mkurapov Nov 19, 2024

raducristianpopa Nov 7, 2024

mkurapov Nov 19, 2024

mkurapov Nov 25, 2024

mkurapov Nov 25, 2024

mkurapov Nov 25, 2024

mkurapov Nov 25, 2024

mkurapov left a comment

mkurapov Dec 17, 2024


		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.


		</CodeBlock>

		For more information refer to the <LinkOut href='https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol-20#name-calculating-the-interaction'> "Calculating the interaction hash"</LinkOut> section of the GNAP specification.


		## Hashing method

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

		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 <LinkOut href='https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg'>IANA Named Information Hash Algorithm Registry</LinkOut>.

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

docs: 466/hash-verification #512

Are you sure you want to change the base?

docs: 466/hash-verification #512

Conversation

hajjimo commented Oct 21, 2024

Changes proposed in this pull request

Context

changeset-bot bot commented Oct 21, 2024 • edited Loading

⚠️ No Changeset found

netlify bot commented Oct 21, 2024 • edited Loading

✅ Deploy Preview for openpayments-preview ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mkurapov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

changeset-bot bot commented Oct 21, 2024 •

edited

Loading

netlify bot commented Oct 21, 2024 •

edited

Loading