From 1e3241503b08069d7eaa58733c86f6968be68f63 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Wed, 14 Mar 2018 13:13:54 +0100 Subject: [PATCH 01/27] Add link to "attachment modality" reference --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 46d33455e..18e4fa42f 100644 --- a/index.bs +++ b/index.bs @@ -854,7 +854,7 @@ When this method is invoked, the user agent MUST execute the following algorithm 1. If |options|.{{PublicKeyCredentialCreationOptions/authenticatorSelection}} is [=present=]: 1. If |options|.{{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{authenticatorAttachment}} is - [=present|present=] and its value is not equal to |authenticator|'s attachment modality, [=iteration/continue=]. + [=present|present=] and its value is not equal to |authenticator|'s [=attachment modality=], [=iteration/continue=]. 1. If |options|.{{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{requireResidentKey}} is set to `true` and the |authenticator| is not capable of storing a [=Client-Side-Resident Credential Private Key=], [=iteration/continue=]. From 2c01f6f98eeedf4297d9fd1cdad2dadc0ad5b735 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Wed, 14 Mar 2018 15:57:39 +0100 Subject: [PATCH 02/27] Define Authentication Ceremony as alias of Authentication --- index.bs | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/index.bs b/index.bs index 18e4fa42f..63ec54e57 100644 --- a/index.bs +++ b/index.bs @@ -353,6 +353,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S attestation=] for details. : Authentication +: Authentication Ceremony :: The [=ceremony=] where a user, and the user's computing device(s) (containing at least one [=authenticator=]) work in concert to cryptographically prove to a [=[RP]=] that the user controls the [=credential private key=] associated with a previously-registered [=public key credential=] (see [=Registration=]). Note that this includes a [=test of user presence=] or @@ -514,7 +515,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S : Relying Party Identifier : RP ID :: A [=valid domain string=] that identifies the [=[RP]=] on whose behalf a given [=registration=] or - [=authentication|authentication ceremony=] is being performed. A [=public key credential=] can only be used for + [=authentication ceremony=] is being performed. A [=public key credential=] can only be used for [=authentication=] with the same entity (as identified by [=RP ID=]) it was registered with. By default, the [=RP ID=] for a WebAuthn operation is set to the caller's [=environment settings object/origin=]'s [=effective domain=]. This default MAY be overridden by the caller, as long as the caller-specified [=RP ID=] value [=is a registrable domain suffix of or is equal @@ -2952,9 +2953,9 @@ provide this chain in the attestation information. ## Verifying an authentication assertion ## {#verifying-assertion} When verifying a given {{PublicKeyCredential}} structure (|credential|) and an {{AuthenticationExtensionsClientOutputs}} structure -|clientExtensionResults|, as part of an [=authentication=] [=ceremony=], the [=[RP]=] MUST proceed as follows: +|clientExtensionResults|, as part of an [=authentication ceremony=], the [=[RP]=] MUST proceed as follows: -1. If the {{PublicKeyCredentialRequestOptions/allowCredentials}} option was given when this [=authentication=] [=ceremony=] was +1. If the {{PublicKeyCredentialRequestOptions/allowCredentials}} option was given when this [=authentication ceremony=] was initiated, verify that |credential|.{{Credential/id}} identifies one of the [=public key credentials=] that were listed in {{PublicKeyCredentialRequestOptions/allowCredentials}}. @@ -3034,12 +3035,12 @@ When verifying a given {{PublicKeyCredential}} structure (|credential|) and an { being used in parallel. [=[RPS]=] should incorporate this information into their risk scoring. Whether the [=[RP]=] updates the stored [=signature counter=] value in this case, or not, or fails the - [=authentication|authentication ceremony=] or not, is + [=authentication ceremony=] or not, is [=[RP]=]-specific. -1. If all the above steps are successful, continue with the authentication ceremony as appropriate. Otherwise, fail the - [=authentication|authentication ceremony=]. +1. If all the above steps are successful, continue with the [=authentication ceremony=] as appropriate. Otherwise, fail the + [=authentication ceremony=]. # Defined Attestation Statement Formats # {#defined-attestation-formats} @@ -4820,7 +4821,7 @@ key credential|credential=] is listed by the [=[RP]=] in {{PublicKeyCredentialRe If the above cases are distinguishable, information is leaked by which a malicious [=[RP]=] could identify the user by probing for which [=public key credential|credentials=] are available. For example, one such information leak is if the client returns a -failure response as soon as the user denies [=user consent|consent=] to proceed with an [=authentication=] [=ceremony=]. In this +failure response as soon as the user denies [=user consent|consent=] to proceed with an [=authentication ceremony=]. In this case the [=[RP]=] could detect that the [=ceremony=] was canceled by the user and not the timeout, and thus conclude that at least one of the [=public key credential|credentials=] listed in the {{PublicKeyCredentialRequestOptions/allowCredentials}} parameter is available to the user. From 77f814b0f45c246447863db3efd21423fb05c155 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Wed, 14 Mar 2018 15:57:54 +0100 Subject: [PATCH 03/27] Define Registration Ceremony as alias of Registration --- index.bs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index 63ec54e57..4202f7907 100644 --- a/index.bs +++ b/index.bs @@ -501,6 +501,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S aspect of [=user verification=]. : Registration +: Registration Ceremony :: The [=ceremony=] where a user, a [=[RP]=], and the user's computing device(s) (containing at least one [=authenticator=]) work in concert to create a [=public key credential=] and associate it with the user's [=[RP]=] account. Note that this includes employing a [=test of user presence=] or [=user verification=]. @@ -2849,7 +2850,7 @@ structures. ## Registering a new credential ## {#registering-a-new-credential} When registering a new credential, represented by an {{AuthenticatorAttestationResponse}} structure |response| and an -{{AuthenticationExtensionsClientOutputs}} structure |clientExtensionResults|, as part of a [=registration=] [=ceremony=], a +{{AuthenticationExtensionsClientOutputs}} structure |clientExtensionResults|, as part of a [=registration ceremony=], a [=[RP]=] MUST proceed as follows: 1. Let |JSONtext| be the result of @@ -2927,7 +2928,7 @@ When registering a new credential, represented by an {{AuthenticatorAttestationR 1. Check that the [=credentialId=] is not yet registered to any other user. If registration is requested for a credential that is already registered to a different user, the [=[RP]=] SHOULD - fail this [=registration=] ceremony, or it MAY decide to accept the registration, e.g. while deleting the older registration. + fail this [=registration ceremony=], or it MAY decide to accept the registration, e.g. while deleting the older registration. 1. If the attestation statement |attStmt| verified successfully and is found to be trustworthy, then register the new credential with the account that was denoted in the @@ -2937,7 +2938,7 @@ When registering a new credential, represented by an {{AuthenticatorAttestationR [=[RP]=]'s system. 1. If the attestation statement |attStmt| successfully verified but is not trustworthy per step 16 above, the [=[RP]=] SHOULD fail - the [=registration=] [=ceremony=]. + the [=registration ceremony=]. NOTE: However, if permitted by policy, the [=[RP]=] MAY register the [=credential ID=] and credential public key but treat the credential as one with [=self attestation=] (see [[#sctn-attestation-types]]). If doing so, the [=[RP]=] is asserting there @@ -4220,7 +4221,7 @@ This [=registration extension=] and [=authentication extension=] enables use of ## Biometric Authenticator Performance Bounds Extension (biometricPerfBounds) ## {#sctn-authenticator-biometric-criteria-extension} This [=registration extension=] allows [=[RPS]=] to specify the desired performance bounds for selecting [=biometric authenticators=] -as candidates to be employed in a [=registration=] ceremony. +as candidates to be employed in a [=registration ceremony=]. : Extension identifier :: `biometricPerfBounds` From f6b5bcc8cf51c6dd18e15173671a5ddc4919d74c Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Thu, 15 Mar 2018 17:04:23 +0100 Subject: [PATCH 04/27] Add authenticator taxonomy diagram --- images/authenticator-taxonomy.svg | 207 ++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 images/authenticator-taxonomy.svg diff --git a/images/authenticator-taxonomy.svg b/images/authenticator-taxonomy.svg new file mode 100644 index 000000000..703d869d6 --- /dev/null +++ b/images/authenticator-taxonomy.svg @@ -0,0 +1,207 @@ + + + +image/svg+xmlFirst-Factor +Platform +Roaming +Single-Step +Client-side-resident c.p.k. +User Verification +Username-Less +Italic: Authenticator properties +Normal: Use cases + \ No newline at end of file From 2ea108580a3b5d8adbecf02b831bff0c38c3f0ac Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Thu, 15 Mar 2018 17:05:18 +0100 Subject: [PATCH 05/27] WIP: Extract Authenticator Taxonomy section and define 1st/2nd factor authnr/cred --- index.bs | 144 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 111 insertions(+), 33 deletions(-) diff --git a/index.bs b/index.bs index 4202f7907..6b3ecf798 100644 --- a/index.bs +++ b/index.bs @@ -400,12 +400,13 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S : Client-side-resident Credential Private Key :: A [=Client-side-resident Credential Private Key=] is stored either on the client platform, or in some cases on the - authenticator itself, e.g., in the case of a discrete first-factor roaming authenticator. Such client-side credential - private key storage has the property that the authenticator is able to select the [=credential private key=] given - only an [=RP ID=], possibly with user assistance (e.g., by providing the user a pick list of credentials associated with the RP - ID). By definition, the private key is always exclusively controlled by the Authenticator. In the case of a - [=Client-side-resident Credential Private Key=], the Authenticator might offload storage of wrapped key material to the - client platform, but the client platform is not expected to offload the key storage to remote entities (e.g. RP Server). + authenticator itself, e.g., in the case of a discrete [=first-factor authenticator|first-factor=] [=roaming authenticator=]. + By definition, the private key is always exclusively controlled by the Authenticator. + In the case of a [=Client-side-resident Credential Private Key=], the Authenticator might offload storage of wrapped key + material to the client platform, but the client platform is not expected to offload the key storage to remote entities (e.g. + RP Server). + + A [=client-side-resident credential private key=] is the defining characteristic of a [=first-factor credential=]. : Conforming User Agent :: A user agent implementing, in conjunction with the underlying platform, the [=Web Authentication API=] and algorithms @@ -431,6 +432,32 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S attestation=], the [=credential key pair=] is also used as the [=attestation key pair=], see [=self attestation=] for details. +: First-Factor Authenticator +:: A [=first-factor authenticator=] is an [=authenticator=] that is capable of creating [=first-factor credentials=]. An + [=authenticator=] has this capability if and only if it satisfies all of the following criteria: + + - It is capable of [=user verification=]. + - It can store and retrieve the [=user handles=] associated with its [=public key credential|credentials=]. + - It is capable of generating an [=assertion=] given only an [=RP ID=]. In particular, this means it is capable of creating + [=client-side-resident credential private keys=]. + + A [=first-factor authenticator=] might also be capable of creating [=second-factor credentials=]. + +: First-Factor Credential +:: A [=first-factor credential=] is a [=public key credential source=] created by a [=first-factor authenticator=], and whose + [=credential private key=] is a [=client-side-resident credential private key=]. A [=first-factor credential=] therefore has + the property that the [=authenticator=] is able to select the [=credential private key=] given only an [=RP ID=], possibly + with user assistance (e.g., by providing the user a pick list of credentials associated with the [=RP ID=]). + + [=First-factor credentials=] enable an [=authentication=] scenario where the [=first-factor credential=] is used to both + identify and authenticate the user in a single step, possibly without other user input. For this reason, use of a + [=first-factor credential=] always requires [=user verification=] so that mere possession of the [=authenticator=] is not + sufficient to complete an [=authentication ceremony=]. + + Because each [=first-factor credential=] requires a [=client-side-resident credential private key=], [=first-factor + authenticators=] might have limited storage capacity for [=first-factor credentials=]. Management of such storage is beyond + the scope of this specification. + : Human Palatability :: An identifier that is [=human palatability|human-palatable=] is intended to be rememberable and reproducible by typical human users, in contrast to identifiers that are, for example, randomly generated sequences of bits [[EduPersonObjectClassSpec]]. @@ -536,6 +563,21 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S [=document.domain=]'s setter provides. +: Second-Factor Authenticator +:: A [=second-factor authenticator=] is an [=authenticator=] that is not a [=first-factor authenticator=], and therefore can only + create [=second-factor credentials=]. In particular, a [=second-factor authenticator=] typically requires being given a + [=credential ID=] in order to generate an [=assertion=]. + +: Second-Factor Credential +:: In contrast to [=first-factor credentials=], a [=second-factor credential=] can only be used if the [=authenticator=] is also + given the [=credential ID=] for the requested [=second-factor credential=]. This is the case when the [=authenticator=] + implements [=credential=] storage by using the encrypted [=public key credential source=] as the [=credential ID=], which also + means that such an [=authenticator=] has unlimited storage capacity for [=second-factor credentials=]. + + Because a [=second-factor credential=] requires a [=credential ID=] to be used, the [=authentication ceremony=] needs to be + done in two steps: the user first needs to provide some identification, such as a [=username=] and/or password, and only then + can the [=[RP]=] look up the user's [=credential IDs=] and request an [=assertion=] proving the claimed identity. + : Test of User Presence :: A [=test of user presence=] is a simple form of [=authorization gesture=] and technical process where a user interacts with an [=authenticator=] by (typically) simply touching it (other modalities may also exist), yielding a boolean result. Note @@ -1745,32 +1787,8 @@ attributes. }; -Clients can communicate with authenticators using a variety of mechanisms. For example, a client MAY use a platform-specific -API to communicate with an authenticator which is physically bound to a platform. On the other hand, a client can use a -variety of standardized cross-platform transport protocols such as Bluetooth (see [[#transport]]) to discover and -communicate with [=cross-platform attached=] authenticators. Therefore, we use {{AuthenticatorAttachment}} to describe an -[=authenticator=]'s attachment modality. We define authenticators that are part of the client's -platform as having a [=platform attachment=], and refer to them as platform authenticators. While those that -are reachable via cross-platform transport protocols are defined as having [=cross-platform attachment=], and refer to -them as roaming authenticators. - -
    -
  • platform attachment - the respective authenticator is attached - using platform-specific transports. Usually, authenticators of - this class are non-removable from the platform. A [=public key credential=] bound to a [=platform authenticator=] is - called a platform credential. -
  • cross-platform attachment - the respective - authenticator is attached using cross-platform transports. Authenticators of this class are removable from, and can - "roam" among, client platforms. A [=public key credential=] bound to a [=roaming authenticator=] is called a roaming - credential. -
- -This distinction is important because there are use-cases where only [=platform authenticators=] are acceptable to a [=[RP]=], and -conversely ones where only [=roaming authenticators=] are employed. As a concrete example of the former, a [=platform credential=] -may be used by [=[RPS]=] to quickly and conveniently reauthenticate the user with a minimum of friction, e.g., the user will not -have to dig around in their pocket for their key fob or phone. As a concrete example of the latter, when the user is accessing the -[=[RP]=] from a given client for the first time, they may be asked to use a [=roaming credential=] which was originally -registered with the [=[RP]=] using a different client. +This enumeration is used to describe the [=[RP]=]'s preferred [=attachment modality=] of the [=authenticator=] to use to create a +[=public key credential|credential=]. Note: An [=attachment modality=] selection option is available only in the {{PublicKeyCredential/[[Create]](origin, options, sameOriginWithAncestors)}} operation. The [=[RP]=] may use it to, for example, ensure the user has a [=roaming credential=] for @@ -2274,6 +2292,66 @@ Authenticators: - should ensure that the [=signature counter=] value does not accidentally decrease (e.g., due to hardware failures). + +## Authenticator taxonomy ## {#sctn-authenticator-taxonomy} + +[=Authenticators=] are divided into four primary categories based on two independent primary characteristics: the [=attachment +modality=], and the [=first-factor capability=]. The combinations of these characteristics enable different kinds of use cases. + +- A second-factor platform authenticator is a [=platform authenticator=] that is also a [=second-factor authenticator=]. + This enables use cases where a particular device, such as a laptop computer or smartphone, is registered as a "trusted device" + and available for use as a second authentication factor in future [=authentication ceremonies=]. The authentication factors in + these use cases are typically a password (something you know) and the registered device (something you have). + +- A second-factor roaming authenticator is a [=roaming authenticator=] that is also a [=second-factor authenticator=]. + This enables use cases where the [=authenticator=] can be used with any [=client=] on any device, for example for the first + login with a particular [=client=]. The authentication factors in this use case are typically a password (something you know) + and the [=authenticator=] (something you have). + +- A first-factor platform authenticator is a [=platform authenticator=] that is also a [=first-factor authenticator=]. + In combination with the use cases of a [=second-factor platform authenticator=], this enables "passwordless login" use cases + where the user does not need to provide a [=username=] or password. The user might instead only need to enter a PIN, or scan a + fingerprint on a smartphone or laptop computer. + +- A first-factor roaming authenticator is a [=roaming authenticator=] that is also a [=first-factor authenticator=]. + In combination with the use cases of a [=second-factor roaming authenticator=], this enables "passwordless login" use cases + where the user does not need to provide a [=username=] or password. The user might instead only need to connect the + [=authenticator=] and enter a PIN, or scan a fingerprint on a sensor integrated into the [=authenticator=]. + + +### Attachment Modality ### {#sctn-authenticator-attachment-modality} + +[=Clients=] can communicate with [=authenticators=] using a variety of mechanisms. For example, a [=client=] MAY use a +platform-specific API to communicate with an [=authenticator=] which is physically bound to a platform. On the other hand, a +[=client=] can use a variety of standardized cross-platform transport protocols such as Bluetooth (see [[#transport]]) to discover +and communicate with cross-platform attached [=authenticators=]. We refer to [=authenticators=] that are part of the [=client=]'s +platform as platform authenticators, while those that are reachable via cross-platform transport protocols are referred +to as roaming authenticators. + +
    +
  • A [=platform authenticator=] is attached using a platform-specific transport, and is usually not removable from the + platform. A [=public key credential=] bound to a [=platform authenticator=] is called a platform credential. +
  • A [=roaming authenticator=] is attached using cross-platform transports. Authenticators of this class are removable from, + and can "roam" among, client platforms. A [=public key credential=] bound to a [=roaming authenticator=] is called a + roaming credential. +
+ +This distinction is important because there are use-cases where [=platform authenticators=] are preferred by a [=[RP]=], and +conversely ones where only [=roaming authenticators=] are employed. As a concrete example of the former, a [=platform credential=] +may be used by [=[RPS]=] to quickly and conveniently reauthenticate the user with a minimum of friction, e.g., the user will not +have to dig around in their pocket for their key fob or phone. As a concrete example of the latter, when the user is accessing the +[=[RP]=] from a given [=client=] for the first time, they may be asked to use a [=roaming credential=] which was originally +registered with the [=[RP]=] using a different [=client=]. + + +### First-Factor Capability ### {#sctn-authenticator-first-factor-capability} + +The [=first-factor capability=] of an [=authenticator=] is determined by whether the [=authenticator=] is a [=first-factor +authenticator=] or a [=second-factor authenticator=]. A [=first-factor authenticator=] is capable of creating [=first-factor +credentials=] and MAY be capable of creating [=second-factor credentials=], while a [=second-factor authenticator=] is capable of +creating [=second-factor credentials=] only. + + ## Authenticator operations ## {#authenticator-ops} A [=[WAC]=] MUST connect to an authenticator in order to invoke any of the operations of that authenticator. This connection @@ -4391,7 +4469,7 @@ It also registers identifiers for ECDAA algorithms. In this section, we walk through some events in the lifecycle of a [=public key credential=], along with the corresponding sample code for using this API. Note that this is an example flow and does not limit the scope of how the API can be used. -As was the case in earlier sections, this flow focuses on a use case involving an external first-factor [=authenticator=] +As was the case in earlier sections, this flow focuses on a use case involving an external [=first-factor authenticator=] with its own display. One example of such an authenticator would be a smart phone. Other authenticator types are also supported by this API, subject to implementation by the platform. For instance, this flow also works without modification for the case of an authenticator that is embedded in the client platform. The flow also works for the case of an authenticator without From b9917b28bad6a9743cc3f15d749bbe66efb60cb4 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Thu, 15 Mar 2018 14:36:59 +0100 Subject: [PATCH 06/27] Define Authentication Factor --- index.bs | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 6b3ecf798..6463e4327 100644 --- a/index.bs +++ b/index.bs @@ -366,6 +366,21 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S This corresponds to the [[CREDENTIAL-MANAGEMENT-1]] specification's single-use credentials. +: Authentication Factor +:: An [=authentication factor=] is something used as a proof of authenticity. Authentication factors are typically divided into + three main categories: + + - Known Factor: Something you know, for example a password or PIN. + - Possessed Factor: Something you have, for example a key or hardware token. + - Biometric Factor: Something you are, for example a fingerprint. + + Multi-factor authentication means employing at least two of the above kinds of factors. A Web Authentication + [=authenticator=] is a kind of [=possessed factor=]. An [=authenticator=] that supports [=user verification=] can also work as + an "all-in-one multi-factor" by preventing the [=possessed factor=] from being used without first unlocking it with a [=known + factor=] and/or a [=biometric factor=]. An advantage of this approach is that the [=known factor=] or [=biometric factor=] can + be used without sharing it with the [=[RP]=], but instead the [=[RP]=] needs to trust the [=authenticator=]'s [=attestation=] + of its security guarantees. + : Authenticator :: A cryptographic entity used by a [=[WAC]=] to (i) generate a [=public key credential=] and register it with a [=[RP]=], and (ii) [=authentication|authenticate=] by potentially [=user verification|verifying the user=], and then @@ -524,7 +539,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S :: The process (also known as throttling) by which an authenticator implements controls against brute force attacks by limiting the number of consecutive failed authentication attempts within a given period of time. If the limit is reached, the authenticator should impose a delay that increases exponentially with each successive attempt, or disable the current - authentication modality and offer a different authentication factor if available. Rate limiting is often implemented as an + authentication modality and offer a different [=authentication factor=] if available. Rate limiting is often implemented as an aspect of [=user verification=]. : Registration From 2f980e7da765fac1071b388af06b0fd5fa81501a Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Thu, 15 Mar 2018 17:40:28 +0100 Subject: [PATCH 07/27] WIP: Replace definitions with use case descriptions --- index.bs | 145 ++++++++++++++++++++++++++----------------------------- 1 file changed, 69 insertions(+), 76 deletions(-) diff --git a/index.bs b/index.bs index 6463e4327..548d7dc12 100644 --- a/index.bs +++ b/index.bs @@ -415,13 +415,16 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S : Client-side-resident Credential Private Key :: A [=Client-side-resident Credential Private Key=] is stored either on the client platform, or in some cases on the - authenticator itself, e.g., in the case of a discrete [=first-factor authenticator|first-factor=] [=roaming authenticator=]. - By definition, the private key is always exclusively controlled by the Authenticator. + authenticator itself, e.g., in the case of a discrete [=first-factor use case|first-factor=] [=roaming authenticator=]. Such + client-side credential private key storage has the property that the authenticator is able to select the + [=credential private key=] given only an [=RP ID=], possibly with user assistance (e.g., by providing the user a pick list of + credentials associated with the RP ID). By definition, the private key is always exclusively controlled by the Authenticator. In the case of a [=Client-side-resident Credential Private Key=], the Authenticator might offload storage of wrapped key material to the client platform, but the client platform is not expected to offload the key storage to remote entities (e.g. RP Server). - A [=client-side-resident credential private key=] is the defining characteristic of a [=first-factor credential=]. + [=Client-side-resident credential private keys=] is a defining characteristic of the [=username-less use case|username-less=] + and [=single-step use case|single-step=] use cases. : Conforming User Agent :: A user agent implementing, in conjunction with the underlying platform, the [=Web Authentication API=] and algorithms @@ -447,32 +450,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S attestation=], the [=credential key pair=] is also used as the [=attestation key pair=], see [=self attestation=] for details. -: First-Factor Authenticator -:: A [=first-factor authenticator=] is an [=authenticator=] that is capable of creating [=first-factor credentials=]. An - [=authenticator=] has this capability if and only if it satisfies all of the following criteria: - - - It is capable of [=user verification=]. - - It can store and retrieve the [=user handles=] associated with its [=public key credential|credentials=]. - - It is capable of generating an [=assertion=] given only an [=RP ID=]. In particular, this means it is capable of creating - [=client-side-resident credential private keys=]. - - A [=first-factor authenticator=] might also be capable of creating [=second-factor credentials=]. - -: First-Factor Credential -:: A [=first-factor credential=] is a [=public key credential source=] created by a [=first-factor authenticator=], and whose - [=credential private key=] is a [=client-side-resident credential private key=]. A [=first-factor credential=] therefore has - the property that the [=authenticator=] is able to select the [=credential private key=] given only an [=RP ID=], possibly - with user assistance (e.g., by providing the user a pick list of credentials associated with the [=RP ID=]). - - [=First-factor credentials=] enable an [=authentication=] scenario where the [=first-factor credential=] is used to both - identify and authenticate the user in a single step, possibly without other user input. For this reason, use of a - [=first-factor credential=] always requires [=user verification=] so that mere possession of the [=authenticator=] is not - sufficient to complete an [=authentication ceremony=]. - - Because each [=first-factor credential=] requires a [=client-side-resident credential private key=], [=first-factor - authenticators=] might have limited storage capacity for [=first-factor credentials=]. Management of such storage is beyond - the scope of this specification. - : Human Palatability :: An identifier that is [=human palatability|human-palatable=] is intended to be rememberable and reproducible by typical human users, in contrast to identifiers that are, for example, randomly generated sequences of bits [[EduPersonObjectClassSpec]]. @@ -578,21 +555,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S [=document.domain=]'s setter provides. -: Second-Factor Authenticator -:: A [=second-factor authenticator=] is an [=authenticator=] that is not a [=first-factor authenticator=], and therefore can only - create [=second-factor credentials=]. In particular, a [=second-factor authenticator=] typically requires being given a - [=credential ID=] in order to generate an [=assertion=]. - -: Second-Factor Credential -:: In contrast to [=first-factor credentials=], a [=second-factor credential=] can only be used if the [=authenticator=] is also - given the [=credential ID=] for the requested [=second-factor credential=]. This is the case when the [=authenticator=] - implements [=credential=] storage by using the encrypted [=public key credential source=] as the [=credential ID=], which also - means that such an [=authenticator=] has unlimited storage capacity for [=second-factor credentials=]. - - Because a [=second-factor credential=] requires a [=credential ID=] to be used, the [=authentication ceremony=] needs to be - done in two steps: the user first needs to provide some identification, such as a [=username=] and/or password, and only then - can the [=[RP]=] look up the user's [=credential IDs=] and request an [=assertion=] proving the claimed identity. - : Test of User Presence :: A [=test of user presence=] is a simple form of [=authorization gesture=] and technical process where a user interacts with an [=authenticator=] by (typically) simply touching it (other modalities may also exist), yielding a boolean result. Note @@ -620,6 +582,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S operations implies use of key material managed by the authenticator. Note that for security, [=user verification=] and use of [=credential private keys=] must occur within a single logical security boundary defining the [=authenticator=]. + [=User verification=] is a defining characteristic of the [=first-factor use case|first-factor=] and [=single-step use + case|single-step=] use cases. + : User Present : UP :: Upon successful completion of a [=test of user presence|user presence test=], the user is said to be @@ -2310,28 +2275,61 @@ Authenticators: ## Authenticator taxonomy ## {#sctn-authenticator-taxonomy} -[=Authenticators=] are divided into four primary categories based on two independent primary characteristics: the [=attachment -modality=], and the [=first-factor capability=]. The combinations of these characteristics enable different kinds of use cases. +Different kinds of [=authenticators=] enable different use cases along two independent dimensions: the [=authentication ceremony +structure=] and the [=authenticator=]'s [=attachment modality=]. The [figure below](#fig-authData) illustrates how the use cases +relate to different kinds of [=authenticators=]. + +
+ +
Relationships between [=authenticator=] properties and use cases.
+
+ +The terms [=second-factor use case|second-factor=], [=first-factor use case|first-factor=], [=single-step use case|single-step=] +and [=username-less use case|username-less=] referenced in the figure refer to the use cases defined in +[[#sctn-authentication-ceremony-structures]]. The terms [=platform authenticator|platform=] and [=roaming authenticator|roaming=] +are defined in [[#sctn-authenticator-attachment-modality]]. The terms [=user verification=] and [=client-side-resident credential +private key=] are defined in [[#terminology]]. + + +### Authentication ceremony structures ### {#sctn-authentication-ceremony-structures} + +The [=authentication ceremony structure=] is defined by the [=authentication factors=] used in the [=authentication +ceremony|ceremony=]. Different [=authentication ceremony structures=] provide different benefits for security and usability. + +- In the second-factor use case the user initiates an [=authentication ceremony=] by entering their [=username=] and + password. The [=[RP]=] then looks up the [=credential IDs=] registered for this user, requests an [=assertion=] by one of + those [=public key credential|credentials=], and the user confirms [=user consent|consent=] to use the [=public key + credential|credential=]. -- A second-factor platform authenticator is a [=platform authenticator=] that is also a [=second-factor authenticator=]. - This enables use cases where a particular device, such as a laptop computer or smartphone, is registered as a "trusted device" - and available for use as a second authentication factor in future [=authentication ceremonies=]. The authentication factors in - these use cases are typically a password (something you know) and the registered device (something you have). + In this use case the password is a [=known factor=] and the [=authenticator=] is a [=possessed factor=]. This use case is + available with any [=authenticator=]. -- A second-factor roaming authenticator is a [=roaming authenticator=] that is also a [=second-factor authenticator=]. - This enables use cases where the [=authenticator=] can be used with any [=client=] on any device, for example for the first - login with a particular [=client=]. The authentication factors in this use case are typically a password (something you know) - and the [=authenticator=] (something you have). +- In the first-factor use case the user initiates an [=authentication ceremony=] by entering only their [=username=]. + The [=[RP]=] then looks up the [=credential IDs=] registered for this user, and requests an [=assertion=] with [=user + verification=] by one of those [=public key credential|credentials=]. Finally the user performs [=user verification=], e.g., + by entering a PIN or scanning a fingerprint. -- A first-factor platform authenticator is a [=platform authenticator=] that is also a [=first-factor authenticator=]. - In combination with the use cases of a [=second-factor platform authenticator=], this enables "passwordless login" use cases - where the user does not need to provide a [=username=] or password. The user might instead only need to enter a PIN, or scan a - fingerprint on a smartphone or laptop computer. + In this use case the [=authenticator=] is both a [=possessed factor=] and, depending on the particular [=authenticator=], a + [=known factor=] and/or a [=biometric factor=]. This use case is only available with [=authenticators=] that support [=user + verification=]. -- A first-factor roaming authenticator is a [=roaming authenticator=] that is also a [=first-factor authenticator=]. - In combination with the use cases of a [=second-factor roaming authenticator=], this enables "passwordless login" use cases - where the user does not need to provide a [=username=] or password. The user might instead only need to connect the - [=authenticator=] and enter a PIN, or scan a fingerprint on a sensor integrated into the [=authenticator=]. +- In the username-less use case, the user initiates an [=authentication ceremony=] without any initial input. The + [=[RP]=] then asks for an [=assertion=] by any [=public key credential|credential=]. The user picks a [=public key + credential|credential=] from those stored in the [=authenticator=], and the [=user handle=] returned in the [=assertion=] is + used to identify the user. The [=[RP]=] might then ask the user for a password, or log the user in using only the verified + [=assertion=]. + + In this use case the [=authenticator=] is a [=possessed factor=] and the password, if used, is a [=known factor=]. This use + case is only available with [=authenticators=] that support [=client-side-resident credential private keys=]. + +- In the single-step use case, the user initiates an [=authentication ceremony=] without any initial input. The + [=[RP]=] then asks for an [=assertion=] with [=user verification=] by any [=public key credential|credential=]. The user picks + a [=public key credential|credential=] from those stored in the [=authenticator=] and performs [=user verification=], e.g., by + entering a PIN or scanning a fingerprint, and the [=user handle=] returned in the [=assertion=] is used to identify the user. + + In this use case the authenticator is both a [=possessed factor=] and, depending on the particular [=authenticator=], a + [=known factor=] and/or a [=biometric factor=]. This use case is only available with [=authenticators=] that support both + [=user verification=] and [=client-side-resident credential private keys=]. ### Attachment Modality ### {#sctn-authenticator-attachment-modality} @@ -2351,20 +2349,15 @@ to as roaming authenticators. roaming credential. -This distinction is important because there are use-cases where [=platform authenticators=] are preferred by a [=[RP]=], and -conversely ones where only [=roaming authenticators=] are employed. As a concrete example of the former, a [=platform credential=] -may be used by [=[RPS]=] to quickly and conveniently reauthenticate the user with a minimum of friction, e.g., the user will not -have to dig around in their pocket for their key fob or phone. As a concrete example of the latter, when the user is accessing the -[=[RP]=] from a given [=client=] for the first time, they may be asked to use a [=roaming credential=] which was originally -registered with the [=[RP]=] using a different [=client=]. - - -### First-Factor Capability ### {#sctn-authenticator-first-factor-capability} +The primary use case for [=platform authenticators=] is to register a particular device as a "trusted device" available as a +[=possessed factor|possessed authentication factor=] for future [=authentication=]. This gives the user the convenience benefit of +not needing a [=roaming authenticator=] for future [=authentication ceremonies=], e.g., the user will not have to dig around in +their pocket for their key fob or phone. -The [=first-factor capability=] of an [=authenticator=] is determined by whether the [=authenticator=] is a [=first-factor -authenticator=] or a [=second-factor authenticator=]. A [=first-factor authenticator=] is capable of creating [=first-factor -credentials=] and MAY be capable of creating [=second-factor credentials=], while a [=second-factor authenticator=] is capable of -creating [=second-factor credentials=] only. +The primary use case for [=roaming authenticators=] is for initial [=authentication=] on a new device, or on devices that are +rarely used or do not include a [=platform authenticator=]; or when policy or preference dictates that the [=authenticator=] be +kept separate from the [=clients=] it is used with. A [=roaming authenticator=] can also be used to hold backup [=public key +credential|credentials=] in case another [=authenticator=] is lost. ## Authenticator operations ## {#authenticator-ops} @@ -4484,7 +4477,7 @@ It also registers identifiers for ECDAA algorithms. In this section, we walk through some events in the lifecycle of a [=public key credential=], along with the corresponding sample code for using this API. Note that this is an example flow and does not limit the scope of how the API can be used. -As was the case in earlier sections, this flow focuses on a use case involving an external [=first-factor authenticator=] +As was the case in earlier sections, this flow focuses on a use case involving a [=roaming authenticator|roaming=] [=first-factor use case|first-factor=] [=authenticator=] with its own display. One example of such an authenticator would be a smart phone. Other authenticator types are also supported by this API, subject to implementation by the platform. For instance, this flow also works without modification for the case of an authenticator that is embedded in the client platform. The flow also works for the case of an authenticator without From ecc950c16c3f7316e7c26c5fba4c54193c379e01 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Fri, 16 Mar 2018 12:26:54 +0100 Subject: [PATCH 08/27] Link authentication factor terms to NIST SP 800-63r3 --- index.bs | 62 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 35 insertions(+), 27 deletions(-) diff --git a/index.bs b/index.bs index 548d7dc12..ce608adb8 100644 --- a/index.bs +++ b/index.bs @@ -131,6 +131,13 @@ spec: FIDO-APPID; urlPrefix: https://fidoalliance.org/specs/fido-u2f-v1.2-ps-201 text: determining the FacetID of a calling application; url: determining-the-facetid-of-a-calling-application text: determining if a caller's FacetID is authorized for an AppID; url: determining-if-a-caller-s-facetid-is-authorized-for-an-appid +spec: SP800-800-63r3; urlPrefix: https://pages.nist.gov/800-63-3/sp800-63-3.html + type: dfn + text: authentication factor; url: af + text: something you know; url: af + text: something you have; url: af + text: something you are; url: af + @@ -366,21 +373,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S This corresponds to the [[CREDENTIAL-MANAGEMENT-1]] specification's single-use credentials. -: Authentication Factor -:: An [=authentication factor=] is something used as a proof of authenticity. Authentication factors are typically divided into - three main categories: - - - Known Factor: Something you know, for example a password or PIN. - - Possessed Factor: Something you have, for example a key or hardware token. - - Biometric Factor: Something you are, for example a fingerprint. - - Multi-factor authentication means employing at least two of the above kinds of factors. A Web Authentication - [=authenticator=] is a kind of [=possessed factor=]. An [=authenticator=] that supports [=user verification=] can also work as - an "all-in-one multi-factor" by preventing the [=possessed factor=] from being used without first unlocking it with a [=known - factor=] and/or a [=biometric factor=]. An advantage of this approach is that the [=known factor=] or [=biometric factor=] can - be used without sharing it with the [=[RP]=], but instead the [=[RP]=] needs to trust the [=authenticator=]'s [=attestation=] - of its security guarantees. - : Authenticator :: A cryptographic entity used by a [=[WAC]=] to (i) generate a [=public key credential=] and register it with a [=[RP]=], and (ii) [=authentication|authenticate=] by potentially [=user verification|verifying the user=], and then @@ -2296,12 +2288,21 @@ private key=] are defined in [[#terminology]]. The [=authentication ceremony structure=] is defined by the [=authentication factors=] used in the [=authentication ceremony|ceremony=]. Different [=authentication ceremony structures=] provide different benefits for security and usability. +The following discussion assumes that the [=[RP]=] can verify the security guarantees of the [=authenticator=] by inspecting +[=attestation statements=] generated by the [=authenticator=]. In particular, the [=[RP]=] cannot trust that the [=authenticator=] +can verify [=something you know=] or [=something you are=] unless these properties can be derived from the [=attestation +statement=]. Thus, an [=authenticator=] that cannot provide such an [=attestation statement=] can only enable the [=second-factor +use case=]. + +Issue: Add "See also 'Ignoring attestation'" to the preceding paragraph if/when PR +[#829](https://github.com/w3c/webauthn/pull/829) is merged. Delete this issue if PR #829 is closed. + - In the second-factor use case the user initiates an [=authentication ceremony=] by entering their [=username=] and password. The [=[RP]=] then looks up the [=credential IDs=] registered for this user, requests an [=assertion=] by one of those [=public key credential|credentials=], and the user confirms [=user consent|consent=] to use the [=public key credential|credential=]. - In this use case the password is a [=known factor=] and the [=authenticator=] is a [=possessed factor=]. This use case is + In this use case the password is [=something you know=] and the [=authenticator=] is [=something you have=]. This use case is available with any [=authenticator=]. - In the first-factor use case the user initiates an [=authentication ceremony=] by entering only their [=username=]. @@ -2309,9 +2310,9 @@ ceremony|ceremony=]. Different [=authentication ceremony structures=] provide di verification=] by one of those [=public key credential|credentials=]. Finally the user performs [=user verification=], e.g., by entering a PIN or scanning a fingerprint. - In this use case the [=authenticator=] is both a [=possessed factor=] and, depending on the particular [=authenticator=], a - [=known factor=] and/or a [=biometric factor=]. This use case is only available with [=authenticators=] that support [=user - verification=]. + In this use case the [=authenticator=] is [=something you have=] which also verifies [=something you know=] and/or [=something + you are=], depending on the particular [=authenticator=]. This use case is only available with [=authenticators=] that support + [=user verification=]. - In the username-less use case, the user initiates an [=authentication ceremony=] without any initial input. The [=[RP]=] then asks for an [=assertion=] by any [=public key credential|credential=]. The user picks a [=public key @@ -2319,17 +2320,17 @@ ceremony|ceremony=]. Different [=authentication ceremony structures=] provide di used to identify the user. The [=[RP]=] might then ask the user for a password, or log the user in using only the verified [=assertion=]. - In this use case the [=authenticator=] is a [=possessed factor=] and the password, if used, is a [=known factor=]. This use - case is only available with [=authenticators=] that support [=client-side-resident credential private keys=]. + In this use case the [=authenticator=] is [=something you have=] and the password, if used, is [=something you know=]. This + use case is only available with [=authenticators=] that support [=client-side-resident credential private keys=]. - In the single-step use case, the user initiates an [=authentication ceremony=] without any initial input. The [=[RP]=] then asks for an [=assertion=] with [=user verification=] by any [=public key credential|credential=]. The user picks a [=public key credential|credential=] from those stored in the [=authenticator=] and performs [=user verification=], e.g., by entering a PIN or scanning a fingerprint, and the [=user handle=] returned in the [=assertion=] is used to identify the user. - In this use case the authenticator is both a [=possessed factor=] and, depending on the particular [=authenticator=], a - [=known factor=] and/or a [=biometric factor=]. This use case is only available with [=authenticators=] that support both - [=user verification=] and [=client-side-resident credential private keys=]. + In this use case the authenticator is [=something you have=] which also verifies [=something you know=] and/or [=something you + are=], depending on the particular [=authenticator=]. This use case is only available with [=authenticators=] that support + both [=user verification=] and [=client-side-resident credential private keys=]. ### Attachment Modality ### {#sctn-authenticator-attachment-modality} @@ -2350,9 +2351,9 @@ to as roaming authenticators. The primary use case for [=platform authenticators=] is to register a particular device as a "trusted device" available as a -[=possessed factor|possessed authentication factor=] for future [=authentication=]. This gives the user the convenience benefit of -not needing a [=roaming authenticator=] for future [=authentication ceremonies=], e.g., the user will not have to dig around in -their pocket for their key fob or phone. +[=something you have=] [=authentication factor=] for future [=authentication=]. This gives the user the convenience benefit of not +needing a [=roaming authenticator=] for future [=authentication ceremonies=], e.g., the user will not have to dig around in their +pocket for their key fob or phone. The primary use case for [=roaming authenticators=] is for initial [=authentication=] on a new device, or on devices that are rarely used or do not include a [=platform authenticator=]; or when policy or preference dictates that the [=authenticator=] be @@ -4987,6 +4988,13 @@ for their contributions as our W3C Team Contacts. "date": "August 2012" }, + "SP800-800-63r3": { + "title": "NIST Special Publication 800-63: Digital Identity Guidelines", + "href": "https://pages.nist.gov/800-63-3/sp800-63-3.html", + "authors": ["Paul A. Grassi", "Michael E. Garcia", "James L. Fenton"], + "date": "June 2017" + }, + "OSCCA-SM3": { "title": "SM3 Cryptographic Hash Algorithm", "href": "http://www.oscca.gov.cn/UpFile/20101222141857786.pdf", From fabf85e049906dc9b6e4fe1301be61ed57986627 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Wed, 11 Apr 2018 18:53:45 +0200 Subject: [PATCH 09/27] Add note about platform authnrs as roaming authnrs --- index.bs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/index.bs b/index.bs index ce608adb8..5a602ef71 100644 --- a/index.bs +++ b/index.bs @@ -2350,6 +2350,11 @@ to as roaming authenticators. roaming credential. +Some [=platform authenticators=] could possibly also act as [=roaming authenticators=] depending on context. For example, a +[=platform authenticator=] integrated into a mobile device could make itself available as a [=roaming authenticator=] via +Bluetooth. In this case the [=client=] would identify it only as a [=roaming authenticator=], and not as a [=platform +authenticator=]. + The primary use case for [=platform authenticators=] is to register a particular device as a "trusted device" available as a [=something you have=] [=authentication factor=] for future [=authentication=]. This gives the user the convenience benefit of not needing a [=roaming authenticator=] for future [=authentication ceremonies=], e.g., the user will not have to dig around in their From 68825d1bf896ad4024ab19770da736dee232039e Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Wed, 11 Apr 2018 18:58:57 +0200 Subject: [PATCH 10/27] Remove some authenticator property labels from authnr taxonomy diagram --- images/authenticator-taxonomy.svg | 88 ++++++++++++------------------- 1 file changed, 35 insertions(+), 53 deletions(-) diff --git a/images/authenticator-taxonomy.svg b/images/authenticator-taxonomy.svg index 703d869d6..7fe477196 100644 --- a/images/authenticator-taxonomy.svg +++ b/images/authenticator-taxonomy.svg @@ -11,8 +11,8 @@ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" width="9.3327789cm" - height="7.6045218cm" - viewBox="0 0 264.55121 215.56126" + height="6.6045198cm" + viewBox="0 0 264.55121 187.21475" xml:space="preserve" class="st13" version="1.1" @@ -32,18 +32,18 @@ guidetolerance="10" inkscape:pageopacity="0" inkscape:pageshadow="2" - inkscape:window-width="1276" - inkscape:window-height="1383" + inkscape:window-width="2556" + inkscape:window-height="1401" id="namedview4698" showgrid="false" inkscape:snap-to-guides="false" inkscape:snap-grids="false" showguides="false" - inkscape:zoom="2" - inkscape:cx="179.05839" - inkscape:cy="143.58035" + inkscape:zoom="2.8284271" + inkscape:cx="102.2727" + inkscape:cy="101.89234" inkscape:window-x="1600" - inkscape:window-y="55" + inkscape:window-y="37" inkscape:window-maximized="0" inkscape:current-layer="svg4696" inkscape:snap-text-baseline="true" @@ -79,129 +79,111 @@ First-Factor Platform Roaming Single-Step -Client-side-resident c.p.k. User Verification -Username-Less Italic: Authenticator properties Normal: Use cases \ No newline at end of file From f2b40dbf7c77a745e7a5124f8e11eb912b16837d Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 19 Jun 2018 18:49:02 +0200 Subject: [PATCH 11/27] Use [WAC] text macro in Client definition --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index a322a7597..8e6ef55bf 100644 --- a/index.bs +++ b/index.bs @@ -468,7 +468,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S those [=ceremonies=]. : Client -:: See [=WebAuthn Client=], [=Conforming User Agent=]. +:: See [=[WAC]=], [=Conforming User Agent=]. : Client-Side :: This refers in general to the combination of the user's platform device, user agent, authenticators, and everything gluing From 2ef1db886a87173d8d6a44d5cfe46b0d665eea11 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 19 Jun 2018 19:03:02 +0200 Subject: [PATCH 12/27] Introduce WebAuthn Client Device term --- index.bs | 68 +++++++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 28 deletions(-) diff --git a/index.bs b/index.bs index 8e6ef55bf..4481cf178 100644 --- a/index.bs +++ b/index.bs @@ -220,12 +220,12 @@ infrastructure which allows those credentials to be used with {{CredentialsConta {{CredentialsContainer/get()|navigator.credentials.get()}}. The former is used during [=Registration=], and the latter during [=Authentication=]. -Broadly, compliant [=authenticators=] protect [=public key credentials=], and interact with user agents to implement the -[=Web Authentication API=]. Some authenticators MAY run on the same computing device (e.g., smart phone, tablet, desktop PC) as -the user agent is running on. For instance, such an authenticator might consist of a Trusted Execution Environment (TEE) applet, -a Trusted Platform Module (TPM), or a Secure Element (SE) integrated into the computing device in conjunction with some means -for [=user verification=], along with appropriate platform software to mediate access to these components' functionality. Other -authenticators MAY operate autonomously from the computing device running the user agent, and be accessed over a transport such +Broadly, compliant [=authenticators=] protect [=public key credentials=], and interact with user agents to implement the [=Web +Authentication API=]. Some authenticators MAY run on the same [=client device=] (e.g., smart phone, tablet, desktop PC) as the +user agent is running on. For instance, such an authenticator might consist of a Trusted Execution Environment (TEE) applet, a +Trusted Platform Module (TPM), or a Secure Element (SE) integrated into the [=client device=] in conjunction with some means for +[=user verification=], along with appropriate platform software to mediate access to these components' functionality. Other +authenticators MAY operate autonomously from the [=client device=] running the user agent, and be accessed over a transport such as Universal Serial Bus (USB), Bluetooth Low Energy (BLE) or Near Field Communications (NFC). @@ -268,9 +268,9 @@ scenarios. Additional scenarios, including sample code, are given later in [[#sa This use case scenario illustrates how a [=[RP]=] can leverage a combination of a [=roaming authenticator=] (e.g., a USB security key fob) and a [=platform authenticator=] (e.g., a built-in fingerprint sensor) such that the user has: - - a "primary" [=roaming authenticator=] that they use to authenticate on new-to-them devices (e.g., laptops, desktops) or on - such devices that lack a [=platform authenticator=], and - - a low-friction means to strongly re-authenticate on devices having [=platform authenticators=]. + - a "primary" [=roaming authenticator=] that they use to authenticate on new-to-them [=client devices=] (e.g., laptops, + desktops) or on such [=client devices=] that lack a [=platform authenticator=], and + - a low-friction means to strongly re-authenticate on [=client devices=] having [=platform authenticators=]. Note: This approach of registering multiple [=authenticators=] for an account is also useful in account recovery use cases. @@ -430,8 +430,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S : Authentication : Authentication Ceremony -:: The [=ceremony=] where a user, and the user's computing device(s) (containing at least one [=authenticator=]) work in - concert to cryptographically prove to a [=[RP]=] that the user controls the [=credential private key=] associated with a +:: The [=ceremony=] where a user, and the user's [=client=] (containing at least one [=authenticator=]) work in concert to + cryptographically prove to a [=[RP]=] that the user controls the [=credential private key=] associated with a previously-registered [=public key credential=] (see [=Registration=]). Note that this includes a [=test of user presence=] or [=user verification=]. @@ -471,8 +471,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S :: See [=[WAC]=], [=Conforming User Agent=]. : Client-Side -:: This refers in general to the combination of the user's platform device, user agent, authenticators, and everything gluing - it all together. +:: This refers in general to the combination of the user's [=client device=], user agent, [=authenticators=], and everything + gluing it all together. : Client-side-resident Credential Private Key :: A [=Client-side-resident Credential Private Key=] is stored either on the client platform, or in some cases on the @@ -586,9 +586,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S : Registration : Registration Ceremony -:: The [=ceremony=] where a user, a [=[RP]=], and the user's computing device(s) (containing at least one - [=authenticator=]) work in concert to create a [=public key credential=] and associate it with the user's [=[RP]=] account. - Note that this includes employing a [=test of user presence=] or [=user verification=]. +:: The [=ceremony=] where a user, a [=[RP]=], and the user's [=client=] (containing at least one [=authenticator=]) work in + concert to create a [=public key credential=] and associate it with the user's [=[RP]=] account. Note that this includes + employing a [=test of user presence=] or [=user verification=]. : [RP] :: The entity whose web application utilizes the [=Web Authentication API=] to register and authenticate users. See @@ -662,6 +662,17 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S : [WAC] :: Also referred to herein as simply a [=client=]. See also [=Conforming User Agent=]. A [=[WAC]=] is an intermediary entity typically implemented in the user agent (in whole, or in part). Conceptually, it underlies the [=Web Authentication API=] and embodies the implementation of the {{PublicKeyCredential/[[Create]](origin, options, sameOriginWithAncestors)}} and {{PublicKeyCredential/[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)}} [=internal methods=]. It is responsible for both marshalling the inputs for the underlying [=authenticator operations=], and for returning the results of the latter operations to the [=Web Authentication API=]'s callers. + The [=[WAC]=] runs on, and is distinct from, a [=[WAC] Device=]. + +: Client Device +: [WAC] Device +:: The hardware device on which the [=[WAC]=] runs, for example a smartphone, a laptop computer or a desktop computer. Also + referred to herein as the "platform" or "client platform". + + The distinction between this and the [=client=] is that multiple [=clients=], i.e., browser implementations, may run on the + same [=client device=] and have access to the same [=authenticators=] available on that [=client device=]; and that [=platform + authenticators=] are bound to a [=[WAC] Device=] rather than a [=[WAC]=]. + # Web Authentication API # {#api} @@ -1850,10 +1861,11 @@ the [=attachment modality=] of an [=authenticator=] that was used. Note: An [=attachment modality=] selection option is available only in the {{PublicKeyCredential/[[Create]](origin, options, sameOriginWithAncestors)}} operation. The [=[RP]=] may use it to, for example, ensure the user has a [=roaming credential=] for -authenticating using other [=clients=]; or to specifically register a [=platform credential=] for easier reauthentication using a -particular [=client=]. The {{PublicKeyCredential/[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors)}} -operation has no [=attachment modality=] selection option, so the [=[RP]=] should accept any of the user's registered [=public key -credential|credentials=]. The [=client=] and user will then use whichever is available and convenient at the time. +authenticating on another [=client device=]; or to specifically register a [=platform credential=] for easier reauthentication +using a particular [=client=]. The {{PublicKeyCredential/[[DiscoverFromExternalSource]](origin, options, +sameOriginWithAncestors)}} operation has no [=attachment modality=] selection option, so the [=[RP]=] should accept any of the +user's registered [=public key credential|credentials=]. The [=client=] and user will then use whichever is available and +convenient at the time. ### Attestation Conveyance Preference enumeration (enum AttestationConveyancePreference) ### {#attestation-convey} @@ -2504,15 +2516,15 @@ Some [=platform authenticators=] could possibly also act as [=roaming authentica Bluetooth. In this case the [=client=] would identify it only as a [=roaming authenticator=], and not as a [=platform authenticator=]. -The primary use case for [=platform authenticators=] is to register a particular device as a "trusted device" available as a -[=something you have=] [=authentication factor=] for future [=authentication=]. This gives the user the convenience benefit of not -needing a [=roaming authenticator=] for future [=authentication ceremonies=], e.g., the user will not have to dig around in their -pocket for their key fob or phone. +The primary use case for [=platform authenticators=] is to register a particular [=client device=] as a "trusted device" available +as a [=something you have=] [=authentication factor=] for future [=authentication=]. This gives the user the convenience benefit +of not needing a [=roaming authenticator=] for future [=authentication ceremonies=], e.g., the user will not have to dig around in +their pocket for their key fob or phone. -The primary use case for [=roaming authenticators=] is for initial [=authentication=] on a new device, or on devices that are -rarely used or do not include a [=platform authenticator=]; or when policy or preference dictates that the [=authenticator=] be -kept separate from the [=clients=] it is used with. A [=roaming authenticator=] can also be used to hold backup [=public key -credential|credentials=] in case another [=authenticator=] is lost. +The primary use case for [=roaming authenticators=] is for initial [=authentication=] on a new [=client device=], or on [=client +devices=] that are rarely used or do not include a [=platform authenticator=]; or when policy or preference dictates that the +[=authenticator=] be kept separate from the [=clients=] it is used with. A [=roaming authenticator=] can also be used to hold +backup [=public key credential|credentials=] in case another [=authenticator=] is lost. ## Authenticator operations ## {#authenticator-ops} From fc385a05d4b7294bd1468627bfe342d63f0ab352 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 19 Jun 2018 19:17:02 +0200 Subject: [PATCH 13/27] Link Rate limiting --- index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 8e6ef55bf..413b8219f 100644 --- a/index.bs +++ b/index.bs @@ -581,8 +581,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S :: The process (also known as throttling) by which an authenticator implements controls against brute force attacks by limiting the number of consecutive failed authentication attempts within a given period of time. If the limit is reached, the authenticator should impose a delay that increases exponentially with each successive attempt, or disable the current - authentication modality and offer a different [=authentication factor=] if available. Rate limiting is often implemented as an - aspect of [=user verification=]. + authentication modality and offer a different [=authentication factor=] if available. [=Rate limiting=] is often implemented + as an aspect of [=user verification=]. : Registration : Registration Ceremony From a6ab65d01d9fb6305229e1821c338bd573c3f6d4 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 19 Jun 2018 19:18:47 +0200 Subject: [PATCH 14/27] Mention rate limiting in UV definition --- index.bs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/index.bs b/index.bs index 413b8219f..4bf74e18d 100644 --- a/index.bs +++ b/index.bs @@ -650,6 +650,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S [=User verification=] is a defining characteristic of the [=first-factor use case|first-factor=] and [=single-step use case|single-step=] use cases. + [=User verification=] procedures MAY implement [=rate limiting=] as a protection against brute force attacks. + : User Present : UP :: Upon successful completion of a [=test of user presence|user presence test=], the user is said to be From 946007b7675f90bf0ffa9be048f6dfc9d02a76a5 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 19 Jun 2018 19:36:23 +0200 Subject: [PATCH 15/27] Address review comment See https://github.com/w3c/webauthn/pull/842#discussion_r195565487 --- index.bs | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 413b8219f..70af895ed 100644 --- a/index.bs +++ b/index.bs @@ -1836,9 +1836,20 @@ attributes. }; -This enumeration is used to describe the [=attachment modality=] of an [=authenticator=] used to create a [=public key -credential|credential=] - either by the [=[RP]=] to express a preferred [=attachment modality=], or by the [=client=] to report -the [=attachment modality=] of an [=authenticator=] that was used. +This enumeration's values describe [=authenticators=]' [=attachment modalities=]. [=[RPS]=] use this for two purposes: + +- to express a preferred [=authenticator=] [=attachment modality=] when calling + {{CredentialsContainer/create()|navigator.credentials.create()}} to [[#createCredential|create a credential]], and + +- to inform the [=client=] of the [=[RP]=]'s best belief about how to locate the [=managing authenticators=] of the + [=credentials=] listed in {{PublicKeyCredentialRequestOptions/allowCredentials}} when calling + {{CredentialsContainer/get()|navigator.credentials.get()}}. + +
: platform From 5c04f8b795c6f669ffd839ebf83752ce43314e17 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 19 Jun 2018 19:55:17 +0200 Subject: [PATCH 16/27] Resolve inline issue 2 --- index.bs | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/index.bs b/index.bs index 413b8219f..10e509bd9 100644 --- a/index.bs +++ b/index.bs @@ -2442,10 +2442,7 @@ The following discussion assumes that the [=[RP]=] can verify the security guara [=attestation statements=] generated by the [=authenticator=]. In particular, the [=[RP]=] cannot trust that the [=authenticator=] can verify [=something you know=] or [=something you are=] unless these properties can be derived from the [=attestation statement=]. Thus, an [=authenticator=] that cannot provide such an [=attestation statement=] can only enable the [=second-factor -use case=]. - -Issue: Add "See also 'Ignoring attestation'" to the preceding paragraph if/when PR -[#829](https://github.com/w3c/webauthn/pull/829) is merged. Delete this issue if PR #829 is closed. +use case=]. See also [[#sctn-no-attestation-security-attestation]]. - In the second-factor use case the user initiates an [=authentication ceremony=] by entering their [=username=] and password. The [=[RP]=] then looks up the [=credential IDs=] registered for this user, requests an [=assertion=] by one of From 5945017a25332720f232eb2cfc83f104df1768a9 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 19 Jun 2018 20:08:20 +0200 Subject: [PATCH 17/27] Address review comment See https://github.com/w3c/webauthn/pull/842#discussion_r195582774 --- index.bs | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 10e509bd9..872a77d24 100644 --- a/index.bs +++ b/index.bs @@ -2417,9 +2417,10 @@ the same procedure as other [=assertion signatures=] generated by the [=authenti ## Authenticator taxonomy ## {#sctn-authenticator-taxonomy} -Different kinds of [=authenticators=] enable different use cases along two independent dimensions: the [=authentication ceremony -structure=] and the [=authenticator=]'s [=attachment modality=]. The [figure below](#fig-authData) illustrates how the use cases -relate to different kinds of [=authenticators=]. +[=Authenticator=] types vary along several different dimensions: [=attachment modality=], employed [=transport=](s), whether they +are [=user verification=]-capable or only [=test of user presence|detect any user's presence=], and whether they support +[=client-side-resident credential private keys=] or not. These dimensions enable various use cases known as [=authentication +ceremony structures=].
From b5810be37daaea39e7951cc0db9d6e0089fa1344 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 19 Jun 2018 20:15:35 +0200 Subject: [PATCH 18/27] Tone back trust assumption in authn ceremony structures section --- index.bs | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index 872a77d24..238948934 100644 --- a/index.bs +++ b/index.bs @@ -2439,11 +2439,9 @@ private key=] are defined in [[#terminology]]. The [=authentication ceremony structure=] is defined by the [=authentication factors=] used in the [=authentication ceremony|ceremony=]. Different [=authentication ceremony structures=] provide different benefits for security and usability. -The following discussion assumes that the [=[RP]=] can verify the security guarantees of the [=authenticator=] by inspecting -[=attestation statements=] generated by the [=authenticator=]. In particular, the [=[RP]=] cannot trust that the [=authenticator=] -can verify [=something you know=] or [=something you are=] unless these properties can be derived from the [=attestation -statement=]. Thus, an [=authenticator=] that cannot provide such an [=attestation statement=] can only enable the [=second-factor -use case=]. See also [[#sctn-no-attestation-security-attestation]]. +The following discussion assumes that the [=[RP]=] to some degree trusts the [=authenticator=] to perform [=user verification=]. +For example, the [=[RP]=] may derive this trust from the [=authenticator=]'s [=attestation statement=], and/or perform some risk +based trust assessment. See also [[#sctn-no-attestation-security-attestation]]. - In the second-factor use case the user initiates an [=authentication ceremony=] by entering their [=username=] and password. The [=[RP]=] then looks up the [=credential IDs=] registered for this user, requests an [=assertion=] by one of From 40896e5920bf7d8ffcc7ce53475819795c0a009a Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 26 Jun 2018 17:42:03 +0200 Subject: [PATCH 19/27] Incorporate @equalsJeffH's suggested wording --- index.bs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 238948934..7da684382 100644 --- a/index.bs +++ b/index.bs @@ -2439,9 +2439,8 @@ private key=] are defined in [[#terminology]]. The [=authentication ceremony structure=] is defined by the [=authentication factors=] used in the [=authentication ceremony|ceremony=]. Different [=authentication ceremony structures=] provide different benefits for security and usability. -The following discussion assumes that the [=[RP]=] to some degree trusts the [=authenticator=] to perform [=user verification=]. -For example, the [=[RP]=] may derive this trust from the [=authenticator=]'s [=attestation statement=], and/or perform some risk -based trust assessment. See also [[#sctn-no-attestation-security-attestation]]. +The following discussion is based on the notion that the degree of trust an [=[RP]=] has in an [=authenticator=] to satisfactorily +perform [=user verification=] is established and assessed by the [=[RP]=]. - In the second-factor use case the user initiates an [=authentication ceremony=] by entering their [=username=] and password. The [=[RP]=] then looks up the [=credential IDs=] registered for this user, requests an [=assertion=] by one of From 3f3ace91c92e230ceab545bd7f3bdade264fb485 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 26 Jun 2018 19:49:51 +0200 Subject: [PATCH 20/27] Use [=client device=] term in Attachment Modality section --- index.bs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index 4f5c84d06..61dd1377b 100644 --- a/index.bs +++ b/index.bs @@ -2509,17 +2509,17 @@ use case=]. See also [[#sctn-no-attestation-security-attestation]]. ### Attachment Modality ### {#sctn-authenticator-attachment-modality} [=Clients=] can communicate with [=authenticators=] using a variety of mechanisms. For example, a [=client=] MAY use a -platform-specific API to communicate with an [=authenticator=] which is physically bound to a platform. On the other hand, a +platform-specific API to communicate with an [=authenticator=] which is physically bound to a [=client device=]. On the other hand, a [=client=] can use a variety of standardized cross-platform transport protocols such as Bluetooth (see [[#transport]]) to discover and communicate with [=cross-platform attachment|cross-platform attached=] [=authenticators=]. We refer to [=authenticators=] that -are part of the [=client=]'s platform as platform authenticators, while those that are reachable via cross-platform +are part of the [=client device=] as platform authenticators, while those that are reachable via cross-platform transport protocols are referred to as roaming authenticators. -- A [=platform authenticator=] is attached using a platform-specific transport, and is usually not removable from the platform. A - [=public key credential=] bound to a [=platform authenticator=] is called a platform credential. +- A [=platform authenticator=] is attached using a platform-specific transport, and is usually not removable from the [=client + device=]. A [=public key credential=] bound to a [=platform authenticator=] is called a platform credential. - A [=roaming authenticator=] is attached using cross-platform transports. Authenticators of this class are removable from, and - can "roam" among, client platforms. A [=public key credential=] bound to a [=roaming authenticator=] is called a roaming + can "roam" among, [=client devices=]. A [=public key credential=] bound to a [=roaming authenticator=] is called a roaming credential. Some [=platform authenticators=] could possibly also act as [=roaming authenticators=] depending on context. For example, a From d26ecf4ac70da2ef8266b3279e66e3db6baff04d Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 26 Jun 2018 19:58:08 +0200 Subject: [PATCH 21/27] Re-introduce missing definitions of [cross-]platform attachment --- index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 61dd1377b..32c28835c 100644 --- a/index.bs +++ b/index.bs @@ -2515,10 +2515,10 @@ and communicate with [=cross-platform attachment|cross-platform attached=] [=aut are part of the [=client device=] as platform authenticators, while those that are reachable via cross-platform transport protocols are referred to as roaming authenticators. -- A [=platform authenticator=] is attached using a platform-specific transport, and is usually not removable from the [=client +- A [=platform authenticator=] is attached using a platform-specific transport, called platform attachment, and is usually not removable from the [=client device=]. A [=public key credential=] bound to a [=platform authenticator=] is called a platform credential. -- A [=roaming authenticator=] is attached using cross-platform transports. Authenticators of this class are removable from, and +- A [=roaming authenticator=] is attached using cross-platform transports, called cross-platform attachment. Authenticators of this class are removable from, and can "roam" among, [=client devices=]. A [=public key credential=] bound to a [=roaming authenticator=] is called a roaming credential. From f937d21beedfafc2f69318d60a79b22e574bd31c Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Tue, 26 Jun 2018 20:42:33 +0200 Subject: [PATCH 22/27] Fix reference to undefined [=transport=] --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 9bbacbc81..e66e2f52c 100644 --- a/index.bs +++ b/index.bs @@ -2422,7 +2422,7 @@ the same procedure as other [=assertion signatures=] generated by the [=authenti ## Authenticator taxonomy ## {#sctn-authenticator-taxonomy} -[=Authenticator=] types vary along several different dimensions: [=attachment modality=], employed [=transport=](s), whether they +[=Authenticator=] types vary along several different dimensions: [=attachment modality=], employed [[#transport|transport(s)]], whether they are [=user verification=]-capable or only [=test of user presence|detect any user's presence=], and whether they support [=client-side-resident credential private keys=] or not. These dimensions enable various use cases known as [=authentication ceremony structures=]. From 265fd3d1bc3dbf192cfc3fd7269e9f85606a1de2 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Mon, 2 Jul 2018 18:16:42 +0200 Subject: [PATCH 23/27] Remove draft of use case descriptions --- index.bs | 68 +++----------------------------------------------------- 1 file changed, 3 insertions(+), 65 deletions(-) diff --git a/index.bs b/index.bs index bc778fe2f..26dbec126 100644 --- a/index.bs +++ b/index.bs @@ -476,7 +476,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S : Client-side-resident Credential Private Key :: A [=Client-side-resident Credential Private Key=] is stored either on the client platform, or in some cases on the - authenticator itself, e.g., in the case of a discrete [=first-factor use case|first-factor=] [=roaming authenticator=]. Such + authenticator itself, e.g., in the case of a discrete first-factor [=roaming authenticator=]. Such client-side credential private key storage has the property that the authenticator is able to select the [=credential private key=] given only an [=RP ID=], possibly with user assistance (e.g., by providing the user a pick list of credentials associated with the RP ID). By definition, the private key is always exclusively controlled by the @@ -484,9 +484,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S storage of wrapped key material to the client platform, but the client platform is not expected to offload the key storage to remote entities (e.g. RP Server). - [=Client-side-resident credential private keys=] is a defining characteristic of the [=username-less use case|username-less=] - and [=single-step use case|single-step=] use cases. - : Conforming User Agent :: A user agent implementing, in conjunction with the underlying platform, the [=Web Authentication API=] and algorithms given in this specification, and handling communication between [=authenticators=] and [=[RPS]=]. @@ -647,9 +644,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S operations implies use of key material managed by the authenticator. Note that for security, [=user verification=] and use of [=credential private keys=] must occur within a single logical security boundary defining the [=authenticator=]. - [=User verification=] is a defining characteristic of the [=first-factor use case|first-factor=] and [=single-step use - case|single-step=] use cases. - [=User verification=] procedures MAY implement [=rate limiting=] as a protection against brute force attacks. : User Present @@ -2424,63 +2418,7 @@ the same procedure as other [=assertion signatures=] generated by the [=authenti [=Authenticator=] types vary along several different dimensions: [=attachment modality=], employed [[#transport|transport(s)]], whether they are [=user verification=]-capable or only [=test of user presence|detect any user's presence=], and whether they support -[=client-side-resident credential private keys=] or not. These dimensions enable various use cases known as [=authentication -ceremony structures=]. - -
- -
Relationships between [=authenticator=] properties and use cases.
-
- -The terms [=second-factor use case|second-factor=], [=first-factor use case|first-factor=], [=single-step use case|single-step=] -and [=username-less use case|username-less=] referenced in the figure refer to the use cases defined in -[[#sctn-authentication-ceremony-structures]]. The terms [=platform authenticator|platform=] and [=roaming authenticator|roaming=] -are defined in [[#sctn-authenticator-attachment-modality]]. The terms [=user verification=] and [=client-side-resident credential -private key=] are defined in [[#terminology]]. - - -### Authentication ceremony structures ### {#sctn-authentication-ceremony-structures} - -The [=authentication ceremony structure=] is defined by the [=authentication factors=] used in the [=authentication -ceremony|ceremony=]. Different [=authentication ceremony structures=] provide different benefits for security and usability. - -The following discussion is based on the notion that the degree of trust an [=[RP]=] has in an [=authenticator=] to satisfactorily -perform [=user verification=] is established and assessed by the [=[RP]=]. - -- In the second-factor use case the user initiates an [=authentication ceremony=] by entering their [=username=] and - password. The [=[RP]=] then looks up the [=credential IDs=] registered for this user, requests an [=assertion=] by one of - those [=public key credential|credentials=], and the user confirms [=user consent|consent=] to use the [=public key - credential|credential=]. - - In this use case the password is [=something you know=] and the [=authenticator=] is [=something you have=]. This use case is - available with any [=authenticator=]. - -- In the first-factor use case the user initiates an [=authentication ceremony=] by entering only their [=username=]. - The [=[RP]=] then looks up the [=credential IDs=] registered for this user, and requests an [=assertion=] with [=user - verification=] by one of those [=public key credential|credentials=]. Finally the user performs [=user verification=], e.g., - by entering a PIN or scanning a fingerprint. - - In this use case the [=authenticator=] is [=something you have=] which also verifies [=something you know=] and/or [=something - you are=], depending on the particular [=authenticator=]. This use case is only available with [=authenticators=] that support - [=user verification=]. - -- In the username-less use case, the user initiates an [=authentication ceremony=] without any initial input. The - [=[RP]=] then asks for an [=assertion=] by any [=public key credential|credential=]. The user picks a [=public key - credential|credential=] from those stored in the [=authenticator=], and the [=user handle=] returned in the [=assertion=] is - used to identify the user. The [=[RP]=] might then ask the user for a password, or log the user in using only the verified - [=assertion=]. - - In this use case the [=authenticator=] is [=something you have=] and the password, if used, is [=something you know=]. This - use case is only available with [=authenticators=] that support [=client-side-resident credential private keys=]. - -- In the single-step use case, the user initiates an [=authentication ceremony=] without any initial input. The - [=[RP]=] then asks for an [=assertion=] with [=user verification=] by any [=public key credential|credential=]. The user picks - a [=public key credential|credential=] from those stored in the [=authenticator=] and performs [=user verification=], e.g., by - entering a PIN or scanning a fingerprint, and the [=user handle=] returned in the [=assertion=] is used to identify the user. - - In this use case the authenticator is [=something you have=] which also verifies [=something you know=] and/or [=something you - are=], depending on the particular [=authenticator=]. This use case is only available with [=authenticators=] that support - both [=user verification=] and [=client-side-resident credential private keys=]. +[=client-side-resident credential private keys=] or not. ### Attachment Modality ### {#sctn-authenticator-attachment-modality} @@ -4632,7 +4570,7 @@ such as registering -257 for "RS256". In this section, we walk through some events in the lifecycle of a [=public key credential=], along with the corresponding sample code for using this API. Note that this is an example flow and does not limit the scope of how the API can be used. -As was the case in earlier sections, this flow focuses on a use case involving a [=roaming authenticator|roaming=] [=first-factor use case|first-factor=] [=authenticator=] +As was the case in earlier sections, this flow focuses on a use case involving a [=roaming authenticator|roaming=] first-factor [=authenticator=] with its own display. One example of such an authenticator would be a smart phone. Other authenticator types are also supported by this API, subject to implementation by the platform. For instance, this flow also works without modification for the case of an authenticator that is embedded in the client platform. The flow also works for the case of an authenticator without From 0366f515be6c3d79c88cc6e95ee43cdb608e5e65 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Mon, 2 Jul 2018 22:29:18 +0200 Subject: [PATCH 24/27] Add Issue: pointing out that Authenticator Taxonomy section is not complete --- index.bs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/index.bs b/index.bs index 26dbec126..395dd7004 100644 --- a/index.bs +++ b/index.bs @@ -2420,6 +2420,8 @@ the same procedure as other [=assertion signatures=] generated by the [=authenti are [=user verification=]-capable or only [=test of user presence|detect any user's presence=], and whether they support [=client-side-resident credential private keys=] or not. +Issue: Expand this section with further discussion about the other dimensions mentioned above. + ### Attachment Modality ### {#sctn-authenticator-attachment-modality} From 46d1fd96ade2e7af5c0f2033a1187f35a7d6e176 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Mon, 2 Jul 2018 23:03:00 +0200 Subject: [PATCH 25/27] Remove now unused image file --- images/authenticator-taxonomy.svg | 189 ------------------------------ 1 file changed, 189 deletions(-) delete mode 100644 images/authenticator-taxonomy.svg diff --git a/images/authenticator-taxonomy.svg b/images/authenticator-taxonomy.svg deleted file mode 100644 index 7fe477196..000000000 --- a/images/authenticator-taxonomy.svg +++ /dev/null @@ -1,189 +0,0 @@ - - - -image/svg+xmlFirst-Factor -Platform -Roaming -Single-Step -Username-Less -Italic: Authenticator properties -Normal: Use cases - \ No newline at end of file From 57c2b8f03f44c8febd8d50bd49a80bb935306058 Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Mon, 2 Jul 2018 23:20:36 +0200 Subject: [PATCH 26/27] Un-rewrap lines This should make @selfissued happy. :) --- index.bs | 41 ++++++++++++++++++++--------------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/index.bs b/index.bs index 5ebbdd742..ad832876f 100644 --- a/index.bs +++ b/index.bs @@ -222,11 +222,11 @@ infrastructure which allows those credentials to be used with {{CredentialsConta {{CredentialsContainer/get()|navigator.credentials.get()}}. The former is used during [=Registration=], and the latter during [=Authentication=]. -Broadly, compliant [=authenticators=] protect [=public key credentials=], and interact with user agents to implement the [=Web -Authentication API=]. Some authenticators MAY run on the same [=client device=] (e.g., smart phone, tablet, desktop PC) as the -user agent is running on. For instance, such an authenticator might consist of a Trusted Execution Environment (TEE) applet, a -Trusted Platform Module (TPM), or a Secure Element (SE) integrated into the [=client device=] in conjunction with some means for -[=user verification=], along with appropriate platform software to mediate access to these components' functionality. Other +Broadly, compliant [=authenticators=] protect [=public key credentials=], and interact with user agents to implement the +[=Web Authentication API=]. Some authenticators MAY run on the same [=client device=] (e.g., smart phone, tablet, desktop PC) as +the user agent is running on. For instance, such an authenticator might consist of a Trusted Execution Environment (TEE) applet, +a Trusted Platform Module (TPM), or a Secure Element (SE) integrated into the [=client device=] in conjunction with some means +for [=user verification=], along with appropriate platform software to mediate access to these components' functionality. Other authenticators MAY operate autonomously from the [=client device=] running the user agent, and be accessed over a transport such as Universal Serial Bus (USB), Bluetooth Low Energy (BLE) or Near Field Communications (NFC). @@ -432,8 +432,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S : Authentication : Authentication Ceremony -:: The [=ceremony=] where a user, and the user's [=client=] (containing at least one [=authenticator=]) work in concert to - cryptographically prove to a [=[RP]=] that the user controls the [=credential private key=] associated with a +:: The [=ceremony=] where a user, and the user's [=client=] (containing at least one [=authenticator=]) work in + concert to cryptographically prove to a [=[RP]=] that the user controls the [=credential private key=] associated with a previously-registered [=public key credential=] (see [=Registration=]). Note that this includes a [=test of user presence=] or [=user verification=]. @@ -473,18 +473,17 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S :: See [=[WAC]=], [=Conforming User Agent=]. : Client-Side -:: This refers in general to the combination of the user's [=client device=], user agent, [=authenticators=], and everything - gluing it all together. +:: This refers in general to the combination of the user's [=client device=], user agent, [=authenticators=], and everything gluing + it all together. : Client-side-resident Credential Private Key :: A [=Client-side-resident Credential Private Key=] is stored either on the client platform, or in some cases on the - authenticator itself, e.g., in the case of a discrete first-factor [=roaming authenticator=]. Such - client-side credential private key storage has the property that the authenticator is able to select the - [=credential private key=] given only an [=RP ID=], possibly with user assistance (e.g., by providing the user a pick list of - credentials associated with the RP ID). By definition, the private key is always exclusively controlled by the - [=authenticator=]. In the case of a [=Client-side-resident Credential Private Key=], the [=authenticator=] might offload - storage of wrapped key material to the client platform, but the client platform is not expected to offload the key storage to - remote entities (e.g. RP Server). + authenticator itself, e.g., in the case of a discrete first-factor [=roaming authenticator=]. Such client-side credential + private key storage has the property that the authenticator is able to select the [=credential private key=] given + only an [=RP ID=], possibly with user assistance (e.g., by providing the user a pick list of credentials associated with the RP + ID). By definition, the private key is always exclusively controlled by the [=authenticator=]. In the case of a + [=Client-side-resident Credential Private Key=], the [=authenticator=] might offload storage of wrapped key material to the + client platform, but the client platform is not expected to offload the key storage to remote entities (e.g. RP Server). : Conforming User Agent :: A user agent implementing, in conjunction with the underlying platform, the [=Web Authentication API=] and algorithms @@ -580,14 +579,14 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S :: The process (also known as throttling) by which an authenticator implements controls against brute force attacks by limiting the number of consecutive failed authentication attempts within a given period of time. If the limit is reached, the authenticator should impose a delay that increases exponentially with each successive attempt, or disable the current - authentication modality and offer a different [=authentication factor=] if available. [=Rate limiting=] is often implemented - as an aspect of [=user verification=]. + authentication modality and offer a different [=authentication factor=] if available. [=Rate limiting=] is often implemented as an + aspect of [=user verification=]. : Registration : Registration Ceremony -:: The [=ceremony=] where a user, a [=[RP]=], and the user's [=client=] (containing at least one [=authenticator=]) work in - concert to create a [=public key credential=] and associate it with the user's [=[RP]=] account. Note that this includes - employing a [=test of user presence=] or [=user verification=]. +:: The [=ceremony=] where a user, a [=[RP]=], and the user's [=client=] (containing at least one + [=authenticator=]) work in concert to create a [=public key credential=] and associate it with the user's [=[RP]=] account. + Note that this includes employing a [=test of user presence=] or [=user verification=]. : [RP] :: The entity whose web application utilizes the [=Web Authentication API=] to register and authenticate users. See From d95918495ceffe6044c70adf8b672f81d24bdf4a Mon Sep 17 00:00:00 2001 From: Emil Lundberg Date: Wed, 11 Jul 2018 17:34:54 +0200 Subject: [PATCH 27/27] Address review comments See https://github.com/w3c/webauthn/pull/956#pullrequestreview-136032383 --- index.bs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index e3c7ba917..b5d8d2f7c 100644 --- a/index.bs +++ b/index.bs @@ -2454,15 +2454,15 @@ transport protocols are referred to as roaming authenticators. Some [=platform authenticators=] could possibly also act as [=roaming authenticators=] depending on context. For example, a [=platform authenticator=] integrated into a mobile device could make itself available as a [=roaming authenticator=] via -Bluetooth. In this case the [=client=] would identify it only as a [=roaming authenticator=], and not as a [=platform +Bluetooth. In this case the [=client=] would recognize it only as a [=roaming authenticator=], and not as a [=platform authenticator=]. -The primary use case for [=platform authenticators=] is to register a particular [=client device=] as a "trusted device" available +A primary use case for [=platform authenticators=] is to register a particular [=client device=] as a "trusted device" available as a [=something you have=] [=authentication factor=] for future [=authentication=]. This gives the user the convenience benefit of not needing a [=roaming authenticator=] for future [=authentication ceremonies=], e.g., the user will not have to dig around in their pocket for their key fob or phone. -The primary use case for [=roaming authenticators=] is for initial [=authentication=] on a new [=client device=], or on [=client +A primary use case for [=roaming authenticators=] is for initial [=authentication=] on a new [=client device=], or on [=client devices=] that are rarely used or do not include a [=platform authenticator=]; or when policy or preference dictates that the [=authenticator=] be kept separate from the [=clients=] it is used with. A [=roaming authenticator=] can also be used to hold backup [=public key credential|credentials=] in case another [=authenticator=] is lost.