diff --git a/index.bs b/index.bs index 198ae8393..b5d8d2f7c 100644 --- a/index.bs +++ b/index.bs @@ -161,6 +161,12 @@ spec: RFC4949; urlPrefix: https://tools.ietf.org/html/rfc4949 text: leap of faith; url: page-182 text: man-in-the-middle attack; url: page-186 +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 @@ -219,11 +225,11 @@ infrastructure which allows those credentials to be used with {{CredentialsConta 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 +[=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 computing device in conjunction with some means +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 computing device running the user agent, and be accessed over a transport such +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). @@ -266,9 +272,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. @@ -427,7 +433,8 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S attestation=] for details. : Authentication -:: The [=ceremony=] where a user, and the user's computing device(s) (containing at least one [=authenticator=]) work in +: 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 previously-registered [=public key credential=] (see [=Registration=]). Note that this includes a [=test of user presence=] or [=user verification=]. @@ -465,10 +472,10 @@ 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 +:: 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 @@ -574,11 +581,12 @@ 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 -:: The [=ceremony=] where a user, a [=[RP]=], and the user's computing device(s) (containing at least one +: 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=]. @@ -638,6 +646,8 @@ 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=] 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 @@ -650,6 +660,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]=]. + : [WRP] :: The entity whose web application utilizes the [=Web Authentication API=] to register and authenticate users. See [=Registration=] and [=Authentication=], respectively. @@ -955,7 +976,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=]. @@ -1819,6 +1840,21 @@ attributes. }; +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 :: This value indicates [=platform attachment=]. @@ -1827,35 +1863,10 @@ attributes. :: This value indicates [=cross-platform attachment=].
-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 attachment|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. - - -- An [=authenticator=] with platform attachment is attached using a platform-specific transport. 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. - -- An [=authenticator=] with cross-platform attachment is attached using a cross-platform transport. 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 [=[WRP]=], 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. - 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)}} +authenticating on another [=client device=]; or to specifically register a [=platform credential=] for easier reauthentication using a +particular [=client device=]. 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. @@ -2416,6 +2427,47 @@ This is because the first 37 bytes of the signed data in a FIDO U2F authenticati the same procedure as other [=assertion signatures=] generated by the [=authenticatorMakeCredential=] operation. +## Authenticator taxonomy ## {#sctn-authenticator-taxonomy} + +[=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. + +Issue: Expand this section with further discussion about the other dimensions mentioned above. + + +### 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 [=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 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, 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, 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. + +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 recognize it only as a [=roaming authenticator=], and not as a [=platform +authenticator=]. + +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. + +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. + + ## Authenticator operations ## {#authenticator-ops} A [=[WAC]=] MUST connect to an authenticator in order to invoke any of the operations of that authenticator. This connection @@ -2989,7 +3041,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 @@ -3066,7 +3118,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 @@ -3076,7 +3128,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 @@ -3092,9 +3144,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}}. @@ -3176,12 +3228,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} @@ -4385,7 +4437,7 @@ This extension enables use of a user verification method. ## Biometric Authenticator Performance Bounds Extension (biometricPerfBounds) ## {#sctn-authenticator-biometric-criteria-extension} This extension allows [=[WRPS]=] 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` @@ -4536,7 +4588,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 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 [=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 @@ -5099,7 +5151,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. @@ -5190,6 +5242,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",