From f9b5e82a29772e4eaadbb061c99f3b02f68ea447 Mon Sep 17 00:00:00 2001 From: Greg Hale Date: Mon, 30 Oct 2023 16:49:07 -0700 Subject: [PATCH 1/5] WIP documentation of the WebAuthn signature payload --- docs/en/pact-reference.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/en/pact-reference.md b/docs/en/pact-reference.md index 86e2f70cc..812667adc 100644 --- a/docs/en/pact-reference.md +++ b/docs/en/pact-reference.md @@ -243,6 +243,30 @@ signers: type: exec ``` +### WebAuthn Signature Format + +The Pact REST API can accept transactions signed by the WebAuthn protocol. + +A web client can make use of this scheme to allow users to authenticate and +sign pact transactions without managing thing own private keys. The client must: + + - Modify the `Signer`, it must have `scheme` set to `WebAuthn`. + - Construct the challenge: base64( blake2b ( CommandPayload )) + - Issue a JavaScript `navigator.credentials.get` with this challenge. + - Construct a `Signature` from the credentials response. + +The signature we pass to Pact (in the `sigs` field) is a sringified JSON object +composed of pieces taken from the browser's credential response. Some of them must +be converted from the Base64URL alphabet to Base64: + +``` +{ + "signature": toBase64(response.signature), + "authenticatorData": toBase64(response.authenticatorData), + "clientDataJSON": toBase64URL(response.clientDataJSON) +} +``` + Concepts {#concepts} ======== From 104516afc6f773de19961caaddf49c8cfe47ac76 Mon Sep 17 00:00:00 2001 From: Greg Hale Date: Mon, 30 Oct 2023 16:53:10 -0700 Subject: [PATCH 2/5] typos --- docs/en/pact-reference.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/en/pact-reference.md b/docs/en/pact-reference.md index 812667adc..2ecc2bc62 100644 --- a/docs/en/pact-reference.md +++ b/docs/en/pact-reference.md @@ -248,16 +248,16 @@ type: exec The Pact REST API can accept transactions signed by the WebAuthn protocol. A web client can make use of this scheme to allow users to authenticate and -sign pact transactions without managing thing own private keys. The client must: +sign pact transactions without manually managing private keys. The client must: - - Modify the `Signer`, it must have `scheme` set to `WebAuthn`. - - Construct the challenge: base64( blake2b ( CommandPayload )) + - Modify the `Signer`, it must have `scheme` set to `"WebAuthn"`. + - Construct the challenge as: `base64( blake2b ( CommandPayload ))` - Issue a JavaScript `navigator.credentials.get` with this challenge. - Construct a `Signature` from the credentials response. -The signature we pass to Pact (in the `sigs` field) is a sringified JSON object -composed of pieces taken from the browser's credential response. Some of them must -be converted from the Base64URL alphabet to Base64: +The "signature" to pass to Pact (in the `sigs` field) is a sringified JSON +object composed of pieces taken from the browser's credential response. Some of +the response fields must be converted from the Base64URL alphabet to Base64: ``` { From d4e8cf1d5425b6c0acd2fe34ee00e41c018ca0a5 Mon Sep 17 00:00:00 2001 From: Greg Hale Date: Tue, 5 Dec 2023 16:33:19 -0800 Subject: [PATCH 3/5] mention WEBAUTHN- pubkey prefix --- docs/en/pact-reference.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/en/pact-reference.md b/docs/en/pact-reference.md index 2ecc2bc62..72635161e 100644 --- a/docs/en/pact-reference.md +++ b/docs/en/pact-reference.md @@ -254,6 +254,8 @@ sign pact transactions without manually managing private keys. The client must: - Construct the challenge as: `base64( blake2b ( CommandPayload ))` - Issue a JavaScript `navigator.credentials.get` with this challenge. - Construct a `Signature` from the credentials response. + - Prefix any public keys generated by the WebAuthn client with "WEBAUTHN-", + both in the `signers` field and in any keys supplied via env data. The "signature" to pass to Pact (in the `sigs` field) is a sringified JSON object composed of pieces taken from the browser's credential response. Some of From 400c4524e6b8e798e477113b81fb1ae3e0df1c4d Mon Sep 17 00:00:00 2001 From: Greg Hale Date: Tue, 12 Dec 2023 14:16:43 -0800 Subject: [PATCH 4/5] Update docs/en/pact-reference.md Co-authored-by: 0xd34df00d <0xd34df00d@gmail.com> --- docs/en/pact-reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/pact-reference.md b/docs/en/pact-reference.md index 72635161e..52f7c015f 100644 --- a/docs/en/pact-reference.md +++ b/docs/en/pact-reference.md @@ -247,8 +247,8 @@ type: exec The Pact REST API can accept transactions signed by the WebAuthn protocol. -A web client can make use of this scheme to allow users to authenticate and -sign pact transactions without manually managing private keys. The client must: +A web client can use this scheme for authenticating and +signing pact transactions without manually managing private keys. The client must: - Modify the `Signer`, it must have `scheme` set to `"WebAuthn"`. - Construct the challenge as: `base64( blake2b ( CommandPayload ))` From 4a528acc24fd45663d9ceec74ab4f03cb060fb5a Mon Sep 17 00:00:00 2001 From: Greg Hale Date: Tue, 12 Dec 2023 14:21:09 -0800 Subject: [PATCH 5/5] Address feedback in webauthn signature docs --- docs/en/pact-reference.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/en/pact-reference.md b/docs/en/pact-reference.md index 52f7c015f..acc274c4e 100644 --- a/docs/en/pact-reference.md +++ b/docs/en/pact-reference.md @@ -248,18 +248,19 @@ type: exec The Pact REST API can accept transactions signed by the WebAuthn protocol. A web client can use this scheme for authenticating and -signing pact transactions without manually managing private keys. The client must: +signing Pact transactions without manually managing private keys. The client must: - Modify the `Signer`, it must have `scheme` set to `"WebAuthn"`. - Construct the challenge as: `base64( blake2b ( CommandPayload ))` - Issue a JavaScript `navigator.credentials.get` with this challenge. - Construct a `Signature` from the credentials response. - - Prefix any public keys generated by the WebAuthn client with "WEBAUTHN-", + - Prefix any public keys generated by the WebAuthn client with `"WEBAUTHN-"`, both in the `signers` field and in any keys supplied via env data. -The "signature" to pass to Pact (in the `sigs` field) is a sringified JSON -object composed of pieces taken from the browser's credential response. Some of -the response fields must be converted from the Base64URL alphabet to Base64: +The `"signature"` to pass to Pact (in the `"sigs"` field) is a stringified JSON +object composed of pieces taken from the browser's credential response, (the +`response` object, below). Some of the response fields must be converted from +the Base64URL alphabet to Base64: ``` {