Skip to content

Commit a61ad90

Browse files
pascoejpascoej
authored
Merge pull request #2298 from w3c/issue-2285-clarify-prf-hmac-secret
Generalize PRF extension processing to non-CTAP authenticators
2 parents c591bcb + e75c208 commit a61ad90

File tree

1 file changed

+73
-15
lines changed

1 file changed

+73
-15
lines changed

‎index.bs

Lines changed: 73 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7440,11 +7440,23 @@ This [=client extension|client=] [=registration extension=] and [=authentication
74407440

74417441
As a motivating example, PRF outputs could be used as symmetric keys to encrypt user data. Such encrypted data would be inaccessible without the ability to get assertions from the associated [=credential=]. By using the provision below to evaluate the PRF at two inputs in a single [=assertion=] operation, the encryption key could be periodically rotated during [=assertions=] by choosing a fresh, random input and reencrypting under the new output. If the evaluation inputs are unpredictable then even an attacker who could satisfy [=user verification=], and who had time-limited access to the authenticator, could not learn the encryption key without also knowing the correct PRF input.
74427442

7443-
This extension is implemented on top of the [[FIDO-CTAP]] `hmac-secret` extension. It is a separate [=client extension=] because `hmac-secret` requires that inputs and outputs be encrypted in a manner that only the user agent can perform, and to provide separation between uses by WebAuthn and any uses by the underlying platform. This separation is achieved by hashing the provided PRF inputs with a context string to prevent evaluation of the PRFs for arbitrary inputs.
7443+
This extension is modeled on top of the [[FIDO-CTAP]] `hmac-secret` extension, but can also be implemented by other means.
7444+
It is a separate [=client extension=] because `hmac-secret` requires that inputs and outputs be encrypted
7445+
in a manner that only the user agent can perform,
7446+
and to provide separation between uses by WebAuthn and any uses by the underlying platform.
7447+
This separation is achieved by hashing the provided PRF inputs with a context string
7448+
to prevent evaluation of the PRFs for arbitrary inputs.
74447449

7445-
The `hmac-secret` extension provides two PRFs per credential: one which is used for requests where [=user verification=] is performed and another for all other requests. This extension only exposes a single PRF per credential and, when implementing on top of `hmac-secret`, that PRF MUST be the one used for when [=user verification=] is performed. This overrides the {{UserVerificationRequirement}} if neccessary.
7450+
The `hmac-secret` extension provides two PRFs per credential: one which is used for requests where [=user verification=] is performed and another for all other requests. This extension only exposes a single PRF per credential and, when implementing on top of `hmac-secret`, that PRF MUST be the one used for when [=user verification=] is performed. This overrides the {{UserVerificationRequirement}} if necessary.
7451+
7452+
This extension MAY be implemented for [=authenticators=] that do not use [[FIDO-CTAP]].
7453+
The interface for this between [=client=] and [=authenticator=],
7454+
and the construction of the PRF by the authenticator, is only abstractly specified.
7455+
7456+
Note: Implementing on top of `hmac-secret` causes [=authenticator extension outputs=] that are not present otherwise.
7457+
These outputs are encrypted and cannot be used by the [=[RP]=],
7458+
but also cannot be deleted by the client since the [=authenticator data=] is signed.
74467459

7447-
Note: This extension may be implemented for [=authenticators=] that do not use [[FIDO-CTAP]] so long as the behavior observed by a [=[RP]=] is identical.
74487460

74497461
: Extension identifier
74507462
:: `prf`
@@ -7491,12 +7503,25 @@ Note: This extension may be implemented for [=authenticators=] that do not use [
74917503
: Client extension processing ([=registration extension|registration=])
74927504
::
74937505
1. If {{AuthenticationExtensionsPRFInputs/evalByCredential}} is present, return a {{DOMException}} whose name is “{{NotSupportedError}}”.
7494-
1. Set `hmac-secret` to [TRUE] in the authenticator extensions input.
7495-
1. If {{AuthenticationExtensionsPRFInputs/eval}} is present and a future extension to [[FIDO-CTAP]] permits evaluation of the PRF at creation time, configure `hmac-secret` inputs accordingly:
7496-
* Let `salt1` be the value of <code>SHA-256(UTF8Encode("WebAuthn PRF") || 0x00 || {{AuthenticationExtensionsPRFInputs/eval}}.{{AuthenticationExtensionsPRFValues/first}})</code>.
7497-
* If <code>{{AuthenticationExtensionsPRFInputs/eval}}.{{AuthenticationExtensionsPRFValues/second}}</code> is present, let `salt2` be the value of <code>SHA-256(UTF8Encode("WebAuthn PRF") || 0x00 || {{AuthenticationExtensionsPRFInputs/eval}}.{{AuthenticationExtensionsPRFValues/second}})</code>.
7498-
1. Set {{AuthenticationExtensionsPRFOutputs/enabled}} to the value of `hmac-secret` in the authenticator extensions output. If not present, set {{AuthenticationExtensionsPRFOutputs/enabled}} to [FALSE].
7499-
1. Set {{AuthenticationExtensionsPRFOutputs/results}} to the decrypted PRF result(s), if any.
7506+
1. If {{AuthenticationExtensionsPRFInputs/eval}} is present:
7507+
- Let |salt1| be the value of <code>SHA-256(UTF8Encode("WebAuthn PRF") || 0x00 || {{AuthenticationExtensionsPRFInputs/eval}}.{{AuthenticationExtensionsPRFValues/first}})</code>.
7508+
- If <code>{{AuthenticationExtensionsPRFInputs/eval}}.{{AuthenticationExtensionsPRFValues/second}}</code> is present,
7509+
let |salt2| be the value of <code>SHA-256(UTF8Encode("WebAuthn PRF") || 0x00 || {{AuthenticationExtensionsPRFInputs/eval}}.{{AuthenticationExtensionsPRFValues/second}})</code>.
7510+
7511+
1. If the authenticator supports the CTAP2 `hmac-secret` extension [[FIDO-CTAP]]:
7512+
1. Set `hmac-secret` to [TRUE] in the authenticator extensions input.
7513+
1. If |salt1| is defined and a future extension to [[FIDO-CTAP]] permits evaluation of the PRF at creation time,
7514+
configure `hmac-secret` inputs accordingly using the values of |salt1| and, if defined, |salt2|.
7515+
1. Set {{AuthenticationExtensionsPRFOutputs/enabled}} to the value of `hmac-secret` in the authenticator extensions output. If not present, set {{AuthenticationExtensionsPRFOutputs/enabled}} to [FALSE].
7516+
1. Set {{AuthenticationExtensionsPRFOutputs/results}} to the decrypted PRF result(s), if any.
7517+
7518+
1. If the authenticator does not support the CTAP2 `hmac-secret` extension [[FIDO-CTAP]],
7519+
but does support some other implementation compatible with the abstract authenticator processing defined below:
7520+
1. Set {{AuthenticationExtensionsPRFOutputs/enabled}} to [TRUE].
7521+
1. If |salt1| is defined, use some unspecified mechanism to convey |salt1| and,
7522+
if defined, |salt2| to the authenticator as PRF inputs, in that order.
7523+
1. Use some unspecified mechanism to receive the PRF outputs from the authenticator.
7524+
Set <code>{{AuthenticationExtensionsPRFOutputs/results}}</code> to the evaluation results, if any.
75007525

75017526
: Client extension processing ([=authentication extension|authentication=])
75027527
::
@@ -7507,13 +7532,46 @@ Note: This extension may be implemented for [=authenticators=] that do not use [
75077532
1. If {{AuthenticationExtensionsPRFInputs/evalByCredential}} is present and [=map/exists|contains=] an [=map/entry=] whose [=map/key=] is the [=base64url encoding=] of the [=credential ID=] that will be returned, let |ev| be the [=map/value=] of that entry.
75087533
1. If |ev| is null and {{AuthenticationExtensionsPRFInputs/eval}} is present, then let |ev| be the value of {{AuthenticationExtensionsPRFInputs/eval}}.
75097534
1. If |ev| is not null:
7510-
1. Let `salt1` be the value of <code>SHA-256(UTF8Encode("WebAuthn PRF") || 0x00 || |ev|.{{AuthenticationExtensionsPRFValues/first}})</code>.
7511-
1. If <code>|ev|.{{AuthenticationExtensionsPRFValues/second}}</code> is present, let `salt2` be the value of <code>SHA-256(UTF8Encode("WebAuthn PRF") || 0x00 || |ev|.{{AuthenticationExtensionsPRFValues/second}})</code>.
7512-
1. Send an `hmac-secret` extension to the [=authenticator=] using the values of `salt1` and, if set, `salt2` as the parameters of the same name in that process.
7513-
1. Decrypt the extension result and set {{AuthenticationExtensionsPRFOutputs/results}} to the PRF result(s), if any.
7535+
1. Let |salt1| be the value of <code>SHA-256(UTF8Encode("WebAuthn PRF") || 0x00 || |ev|.{{AuthenticationExtensionsPRFValues/first}})</code>.
7536+
1. If <code>|ev|.{{AuthenticationExtensionsPRFValues/second}}</code> is present, let |salt2| be the value of <code>SHA-256(UTF8Encode("WebAuthn PRF") || 0x00 || |ev|.{{AuthenticationExtensionsPRFValues/second}})</code>.
7537+
1. If the authenticator supports the CTAP2 `hmac-secret` extension [[FIDO-CTAP]]:
7538+
1. Send an `hmac-secret` extension to the [=authenticator=] using the values of |salt1| and, if set, |salt2| as the parameters of the same name in that process.
7539+
1. Decrypt the extension result and set {{AuthenticationExtensionsPRFOutputs/results}} to the PRF result(s), if any.
7540+
1. If the authenticator does not support the CTAP2 `hmac-secret` extension [[FIDO-CTAP]],
7541+
but does support some other implementation compatible with the abstract authenticator processing defined below:
7542+
1. Use some unspecified mechanism to convey |salt1| and, if defined, |salt2| to the authenticator as PRF inputs, in that order.
7543+
1. Use some unspecified mechanism to receive the PRF outputs from the authenticator as an {{AuthenticationExtensionsPRFValues}} value |results|.
7544+
Set <code>{{AuthenticationExtensionsPRFOutputs/results}}</code> to |results|.
7545+
7546+
: Authenticator extension input / output
7547+
:: [=prf|This extension=] is abstract over the authenticator implementation,
7548+
using either the [[FIDO-CTAP]] `hmac-secret` extension or an unspecified interface for communication between the client and authenticator.
7549+
It thus does not specify a CBOR interface for inputs and outputs.
7550+
7551+
: Authenticator extension processing
7552+
:: [=Authenticators=] that support the [[FIDO-CTAP]] `hmac-secret` extension implement authenticator processing as defined in that extension.
7553+
7554+
[=Authenticators=] that do not support the [[FIDO-CTAP]] `hmac-secret` extension
7555+
MAY instead implement the following abstract procedure:
7556+
7557+
1. Let |PRF| be the pseudo-random function associated with the current [=credential=],
7558+
or initialize the association if uninitialized:
7559+
7560+
Let |PRF| be a pseudo-random function whose outputs are exactly 32 bytes long,
7561+
selected uniformly at random from a set of at least 2<sup>256</sup> such functions.
7562+
The choice of |PRF| MUST be independent of the state of [=user verification=].
7563+
The selected |PRF| SHOULD NOT be used for other purposes than implementing this extension.
7564+
Associate |PRF| with the current [=credential=] for the lifetime of the credential.
7565+
7566+
1. Use some unspecified mechanism to receive PRF inputs |salt1| and, optionally, |salt2| from the [=client=], in that order.
7567+
If none are received, let |salt1| and |salt2| be undefined.
75147568

7515-
: Authenticator extension input / processing / output
7516-
:: [=prf|This extension=] uses the [[FIDO-CTAP]] `hmac-secret` extension when communicating with the authenticator. It thus does not specify any direct authenticator interaction for [=[RPS]=].
7569+
1. If |salt1| is defined:
7570+
1. Let |results| be an {{AuthenticationExtensionsPRFValues}} structure containing the evaluations of |PRF| at the given inputs:
7571+
- Set <code>|results|.{{AuthenticationExtensionsPRFValues/first}}</code> to <code>PRF(|salt1|)</code>.
7572+
- If |salt2| is defined,
7573+
set <code>|results|.{{AuthenticationExtensionsPRFValues/second}}</code> to <code>PRF(|salt2|)</code>.
7574+
1. Use some unspecified mechanism to convey |results| to the [=client=] as the PRF outputs.
75177575

75187576
: Client extension output
75197577
:: <xmp class="idl">

0 commit comments

Comments
 (0)