Skip to content

Commit

Permalink
WIP: Replace definitions with use case descriptions
Browse files Browse the repository at this point in the history
  • Loading branch information
@emlun
emlun committed Mar 15, 2018
1 parent b9917b2 commit 2f980e7
Showing 1 changed file with 69 additions and 76 deletions.
145 changes: 69 additions & 76 deletions index.bs
View file
Expand Up @@ -415,13 +415,16 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S

: <dfn>Client-side-resident Credential Private Key</dfn>
:: 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
<dfn>client-side credential private key storage</dfn> 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.

: <dfn>Conforming User Agent</dfn>
:: A user agent implementing, in conjunction with the underlying platform, the [=Web Authentication API=] and algorithms
Expand All @@ -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.

: <dfn>First-Factor Authenticator</dfn>
:: 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=].

: <dfn>First-Factor Credential</dfn>
:: 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.

: <dfn>Human Palatability</dfn>
:: 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]].
Expand Down Expand Up @@ -578,21 +555,6 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
[=document.domain=]'s setter provides.
</div>

: <dfn>Second-Factor Authenticator</dfn>
:: 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=].

: <dfn>Second-Factor Credential</dfn>
:: 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.

: <dfn>Test of User Presence</dfn>
:: 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
Expand Down Expand Up @@ -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.

: <dfn id=concept-user-present>User Present</dfn>
: <dfn>UP</dfn>
:: Upon successful completion of a [=test of user presence|user presence test=], the user is said to be
Expand Down Expand Up @@ -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=].

<figure id="fig-authenticator-taxonomy">
<img src="images/authenticator-taxonomy.svg"/>
<figcaption>Relationships between [=authenticator=] properties and use cases.</figcaption>
</figure>

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


### <dfn>Authentication ceremony structures</dfn> ### {#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 <dfn>second-factor use case</dfn> 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 <dfn>second-factor platform authenticator</dfn> 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 <dfn>second-factor roaming authenticator</dfn> 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 <dfn>first-factor use case</dfn> 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 <dfn>first-factor platform authenticator</dfn> 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 <dfn>first-factor roaming authenticator</dfn> 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 <dfn>username-less use case</dfn>, 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 <dfn>single-step use case</dfn>, 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=].


### <dfn>Attachment Modality</dfn> ### {#sctn-authenticator-attachment-modality}
Expand All @@ -2351,20 +2349,15 @@ to as <dfn>roaming authenticators</dfn>.
<dfn>roaming credential</dfn>.
</ul>

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=].


### <dfn>First-Factor Capability</dfn> ### {#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.


## <dfn>Authenticator operations</dfn> ## {#authenticator-ops}
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 2f980e7

Please sign in to comment.