diff --git a/index.html b/index.html
index 3136c23d0..f7c47ee90 100644
--- a/index.html
+++ b/index.html
@@ -180,7 +180,7 @@
Web Authentication: A Web API for accessing scoped credentials
- Editor’s Draft,
+ Editor’s Draft,
User goes to example.com in the browser, and signs in using whatever method they have been using (possibly a legacy -method such as a password).
+User goes to example.com in the browser and signs in to an existing account using whatever method they have been using +(possibly a legacy method such as a password), or creates a new account.
The phone prompts, "Do you want to register this device with example.com?"
The AlgorithmIdentifier#dictdef-algorithmidentifierReferenced in:3. Web Authentication API3.8.3. Cryptographic Algorithm Identifier (type AlgorithmIdentifier)4.2.1. Client data used in WebAuthn signatures (dictionary ClientData) type and the method for normalizing an algorithm are defined in Web Cryptography API §algorithm-dictionary.
The JsonWebKey#jsonwebkeyReferenced in:4.2.1. Client data used in WebAuthn signatures (dictionary ClientData)4.3.2.3.1. Signature interface for representing cryptographic keys is defined in Web Cryptography API §JsonWebKey-dictionary.
+The JsonWebKey#dictdef-jsonwebkeyReferenced in:4.2.1. Client data used in WebAuthn signatures (dictionary ClientData)4.3.2.3.1. Signature dictionary for representing cryptographic keys is defined in Web Cryptography API §JsonWebKey-dictionary.
Base64url encoding
This section normatively specifies the API for creating and using scoped credentials. Support for deleting credentials is -deliberately omitted; this is expected to be done through platform-specific user interfaces rather than from a script. The basic -idea is that the credentials belong to the user and are managed by the browser and underlying platform. Scripts can (with the -user’s consent) request the browser to create a new credential for future use by the script’s origin. Scripts can also request -the user’s permission to perform authentication operations with an existing credential held by the platform. However, all such -operations are mediated by the browser and/or platform on the user’s behalf. At no point does the script get access to the -credentials themselves; it only gets information about the credentials in the form of objects.
-User agents SHOULD only expose this API to callers in secure contexts, as defined in [powerful-features].
+deliberately omitted; this is expected to be done through platform-specific user interfaces rather than from a script. The basic +idea is that the credentials belong to the user and are managed by an authenticator, with which the WebAuthn Relying Party interacts through the +client (consisting of the browser and underlying OS platform). Scripts can (with the user’s consent) request the browser to +create a new credential for future use by the WebAuthn Relying Party. Scripts can also request the user’s permission to perform authentication +operations with an existing credential. All such operations are performed in the authenticator and are mediated by the browser +and/or platform on the user’s behalf. At no point does the script get access to the credentials themselves; it only gets +information about the credentials in the form of objects. +The security properties of this API are provided by the client and the authenticator working together. The authenticator, which +holds and manages credentials, ensures that all operations are scoped to a particular web origin, and cannot be replayed against +a different origin, by incorporating the origin in its responses. Specifically, as defined in §4.2 Signature Format, the full +origin of the requester is included, and signed over, in the attestation statement produced when a new credential is created as +well as in all assertions produced by WebAuthn credentials.
+Additionally, to maintain user privacy and prevent malicious WebAuthn Relying Parties from probing for the presence of credentials belonging to +other WebAuthn Relying Parties, each credential is also associated with a Relying Party Identifier, or RP ID. This RP ID is provided by the client +to the authenticator for all operations, and the authenticator ensures that credentials created by a WebAuthn Relying Party can only be used in +operations requested by the same RP ID. Separating the origin from the RP ID in this way allows the API to be used in cases +where a single WebAuthn Relying Party maintains multiple web origins.
+The client facilitates these security measures by providing correct web origins and RP IDs to the authenticator for each +operation. Since this is an integral part of the WebAuthn security model, user agents SHOULD only expose this API to callers in secure contexts, as defined in [powerful-features].
The API is defined by the following Web IDL fragment.
partial interface Window { readonly attribute WebAuthentication webauthn; @@ -574,7 +586,7 @@3.
3.1. WebAuthentication#webauthenticationReferenced in:3. Web Authentication API (2) Interface
This interface has two methods, which are described in the following subsections.
-3.1.1. Create a new credential (makeCredential()#dom-webauthentication-makecredentialReferenced in:3. Web Authentication API4.1.1. The authenticatorMakeCredential operation4.3.2.3.2. Verifying AndroidClientData specific contextual bindings5. WebAuthn Extensions (2)5.2. Defining extensions5.3. Extending request parameters (2)6.2. Authenticator Selection Extension method)
+3.1.1. Create a new credential (makeCredential()#dom-webauthentication-makecredentialReferenced in:3. Web Authentication API4.3.2.3.2. Verifying AndroidClientData specific contextual bindings5. WebAuthn Extensions (2)5.2. Defining extensions5.3. Extending request parameters (2)6.2. Authenticator Selection Extension method)
With this method, a script can request the User Agent to create a new credential of a given type and persist it to the underlying platform, which may involve data storage managed by the browser or the OS. The user agent will prompt the user to approve this operation. On success, the promise will be resolved with a
ScopedCredentialInfo
object describing the newly @@ -621,16 +633,18 @@
Initialize issuedRequests to an empty list.
- -
Process each element of cryptoParameters using the following steps:
+Process each element of cryptoParameters using the following steps, to produce a new sequence
normalizedParameters
:
Let current be the currently selected element of cryptoParameters.
If
current.type
does not contain aCredentialType
supported by this implementation, then stop processing current and move on to the next element in cryptoParameters.- -
Let normalizedAlgorithm be the result of normalizing an algorithm using the procedure defined in [WebCryptoAPI], +
Let
+normalizedAlgorithm
be the result of normalizing an algorithm using the procedure defined in [WebCryptoAPI], with alg set tocurrent.algorithm
and op set to 'generateKey'. If an error occurs during this procedure, then stop processing current and move on to the next element in cryptoParameters.- +
Add a new object of type
ScopedCredentialParameters
tonormalizedParameters
, with type set tocurrent.type
and algorithm set tonormalizedAlgorithm
.If blacklist is undefined, set it to the empty list.
@@ -638,8 +652,8 @@credentialExtensions was specified, process any extensions supported by this client platform, to produce the extension data that needs to be sent to the authenticator. Call this data clientExtensions.
- -
For each embedded or external authenticator currently available on this platform: asynchronously invoke the authenticatorMakeCredential operation on that authenticator with callerOrigin, rpId, accountInformation,
+current.type
, normalizedAlgorithm, blacklist, attestationChallenge and clientExtensions as parameters. -Add a corresponding entry to issuedRequests.For each embedded or external authenticator currently available on this platform: asynchronously invoke the authenticatorMakeCredential operation on that authenticator with callerOrigin, rpId, accountInformation,
normalizedParameters
, blacklist, attestationChallenge and clientExtensions as parameters. Add a +corresponding entry to issuedRequests.While issuedRequests is not empty, perform the following actions depending upon the adjustedTimeout timer and responses from the authenticators:
@@ -660,7 +674,7 @@+
3.1.2. Use an existing credential (getAssertion()#dom-webauthentication-getassertionReferenced in:3. Web Authentication API3.6. WebAuthn Assertion Extensions (dictionary WebAuthnExtensions)5. WebAuthn Extensions (2)5.2. Defining extensions5.3. Extending request parameters (2) method)
This method is used to discover and use an existing scoped credential, with the user’s consent. The script optionally specifies some criteria to indicate what credentials are acceptable to it. The user agent and/or platform locates credentials matching the specified criteria, and guides the user to pick one that the script should be allowed to use. The user may choose not to provide @@ -744,7 +758,7 @@
The type member specifies the type of credential to be created.
@@ -800,24 +814,25 @@The scoped credential type uses certain data structures that are specified in supporting specifications. These are as follows.
-Currently one credential type is defined, namely "ScopedCred".
This interface contains the attributes that are returned to the caller when a new credential is created, and can be used later by the caller to select a credential for use.
CredentialType
, indicating the specification and version that
+ this credential conforms to.
The id attribute contains an identifier for the credential, chosen by the platform with help from the authenticator. This identifier is used to look up credentials for use, and is therefore expected to be globally unique with - high probability across all credentials of the same type. This API does not constrain the format or length of this - identifier, except that it must be sufficient for the platform to uniquely select a key. For example, an authenticator - without on-board storage may create identifiers that consist of the key material wrapped with a key that is burned into the - authenticator.
+ high probability across all credentials of the same type, across all authenticators. This API does not constrain the format + or length of this identifier, except that it must be sufficient for the platform to uniquely select a key. For example, an + authenticator without on-board storage may create identifiers that consist of the key material wrapped with a key that is + burned into the authenticator.AlgorithmIdentifier
)A string or dictionary identifying a cryptographic algorithm and optionally a set of parameters for that algorithm. This type is @@ -843,13 +858,25 @@
The RP ID corresponding to the above web origin, as determined by the user agent and the client.
All input parameters accepted by the makeCredential()
method.
The Account
information provided by the WebAuthn Relying Party.
The CredentialType
requested by the WebAuthn Relying Party.
The cryptographic parameters requested by the WebAuthn Relying Party, with the cryptographic algorithms normalized as per the procedure in Web Cryptography API §algorithm-normalization-normalize-an-algorithm.
+A list of Credential
objects provided by the WebAuthn Relying Party with the intention that, if any of these are known to the authenticator,
+it should not create a new credential.
A challenge provided by the WebAuthn Relying Party to assure freshness of the attestation statement of the new credential.
+Extension data created by the client based on the extensions requested by the WebAuthn Relying Party.
When this operation is invoked, the authenticator obtains user consent for creating a new credential. The prompt for obtaining -this consent is shown by the authenticator if it has its own output capability, or by the user agent otherwise. Once user -consent is obtained, the authenticator generates the appropriate cryptographic keys and creates a new credential. It then -associates the credential with the specified RP ID such that it will be able to retrieve the RP ID later, given the credential -ID.
+this consent is shown by the authenticator if it has its own output capability, or by the user agent otherwise. Once user +consent is obtained, the authenticator generates the appropriate cryptographic keys and creates a new credential. It also +generates an identifier for the credential, such that this identifier is globally unique with high probability across all +credentials with the same type across all authenticators. It then associates the credential with the specified RP ID such that +it will be able to retrieve the RP ID later, given the credential ID.On successful completion of this operation, the authenticator returns the type and unique identifier of this new credential to the user agent.
If the user refuses consent, the authenticator returns an appropriate error status to the client.
@@ -862,7 +889,11 @@The RP ID corresponding to the above web origin, as determined by the user agent and the client.
All input parameters accepted by the getAssertion()
method, specified below.
A challenge provided by the WebAuthn Relying Party to assure freshness of the assertion produced.
+A list of credentials acceptable to the WebAuthn Relying Party (possibly filtered by the client).
+Extension data created by the client based on the extensions requested by the WebAuthn Relying Party.
When this method is invoked, the authenticator allows the user to select a credential from among the credentials associated with that WebAuthn Relying Party and matching the specified criteria, then obtains user consent for using that credential. The prompt for obtaining @@ -885,18 +916,17 @@
The WebAuthn Relying Party (RP), which uses the WebAuthn services. The RP may, for example, be a web-application running in a browser, -or a native application that runs directly on the OS platform.
+The WebAuthn Relying Party (RP), which uses the WebAuthn services. The RP consists of a server component and a web-application running +in a browser.
The WebAuthn Client platform, which consists of the user’s OS and device used to host the RP’s client-side app. For -web-applications, the browser also belongs to this layer.
+The WebAuthn Client platform, which consists of the User Agent and the OS and device on which it executes.
The Authenticator itself, which provides key management and cryptographic signatures.
+The Authenticator itself, which provides key management and cryptographic signatures. This may be embedded in the +WebAuthn client, or houesd in a separate device entirely. In the latter case, the interface between the WebAuthn client and +the authenticator is a separately-defined protocol.
-When the WebAuthn Relying Party client-side application is a web-application, the interface between 1 and 2 is the §3 Web Authentication API, but is platform -specific for native applications. In cases where the authenticator is not tightly integrated with the platform, the interface -between 2 and 3 is a separately-defined protocol. This specification defines the common signature format shared by all layers. -This includes how the different contextual bindings are encoded, signed over, and delivered to the RP.
+This specification defines the common signature format shared by all the above layers. This includes how the different +contextual bindings are encoded, signed over, and delivered to the RP.
The goals of this design can be summarized as follows.
The facet member contains a string value describing the RP identifier facet. When the WebAuthn Relying Party client-side app is a - website, this is its fully qualified web origin, using the syntax defined by [RFC6454]. When the client-side app is a - native application, this string is a platform specific identifier.
+The facet member contains the fully qualified web origin of the requester, as provided to the authenticator by + the client, in the syntax defined by [RFC6454].
The hashAlg#clientdata-hashalgReferenced in:4.2.3. Generating a signature (2) member specifies the hash algorithm used to compute clientDataHash (see §4.2.3 Generating a signature). Use "S256" for SHA-256, "S384" for SHA384, "S512" for SHA512, and "SM3" for SM3 (see §7 IANA Considerations).
The tokenBinding member contains a JsonWebKey object as defined by Web Cryptography API §JsonWebKey-dictionary describing the public key that this client uses for the Token Binding protocol when communicating with the WebAuthn Relying Party. This can be omitted if no Token Binding has been negotiated between the client and the WebAuthn Relying Party.
@@ -941,7 +970,7 @@The encoding of authenticator data is a byte array Web Cryptography API §JsonWebKey-dictionary of 5 bytes or more, as follows.
+The encoding of authenticator data is a byte array of 5 bytes or more, as follows.
Extension-defined authenticator data. This is a CBOR [RFC7049] map with extension identifiers as keys, and extension authenticator data values as values. See §5 WebAuthn Extensions for a description of the extension mechanism. - See §6 Standard extensions for pre-defined extensions. + See §6 Pre-defined extensions for pre-defined extensions. |
The TUP
flag SHALL be set if and only if the authenticator detected a user through an authenticator-specific gesture.
The RFU
bits in the flags byte SHALL be cleared (i.e., zeroed).
For this attestation type, the ClientData dictionary is extended in the following way:
dictionary AndroidAttestationClientData : ClientData { - JsonWebKey publicKey; + JsonWebKey publicKey; boolean isInsideSecureHardware; DOMString userAuthentication; unsigned long userAuthenticationValidityDurationSeconds; // optional @@ -1308,7 +1340,7 @@§4.3.3 Verifying an Attestation Statement) as follows:
-
- -
Check that
+AndroidAttestationClientData.challenge
equals the attestationChallenge that was passed into themakeCredential()
call.Check that
AndroidAttestationClientData.challenge
equals the attestationChallenge that was passed into themakeCredential()
call.Check that the
facet
andtokenBinding
parameters in theAndroidAttestationClientData
match the WebAuthn Relying Party App.- @@ -1441,22 +1473,26 @@
5 signature extension. Extensions can define additions to the following steps and data:
- -
+
makeCredential()
request parameters for registration extension.
makeCredential()
request parameters for registration extension.- -
+
getAssertion()
request parameters for signature extensions.
getAssertion()
request parameters for signature extensions.Client processing, and the
ClientData
structure, for registration extensions and signature extensions.Authenticator processing, and the authenticatorData structure, for signature extensions.
When requesting an assertion for a scoped credential, a WebAuthn Relying Party can list a set of extensions to be used, if they are supported by -the client and/or the authenticator. It sends the request parameters for each extension in the
getAssertion()
call (for -signature extensions) ormakeCredential()
call (for registration extensions) to the client platform. The client platform +the client and/or the authenticator. It sends the request parameters for each extension in thegetAssertion()
call (for +signature extensions) ormakeCredential()
call (for registration extensions) to the client platform. The client platform performs additional processing for each extension that it supports, and augmentsClientData
as required by the extension. For extensions that the client platform does not support, it passes the request parameters on to the authenticator when possible (criteria defined below). This allows one to define extensions that affect the authenticator only.Similarly, the authenticator performs additional processing for the extensions that it supports, and augments authenticatorData as specified by the extension.
Extensions that are not supported are ignored.
+All WebAuthn extensions are optional for both clients and authenticators. Thus, any extensions requested by a WebAuthn Relying Party may be +ignored by the client browser or OS and not passed to the authenticator at all, or they may be ignored by the authenticator. +Ignoring an extension is never considered a failure in the WebAuthn API, so when WebAuthn Relying Parties include extensions with any API calls, +they must be prepared to handle cases where some or all of those extensions are ignored.
5.1. Extension identifiers
Extensions are identified by a string, chosen by the extension author. Extension identifiers should aim to be globally unique, e.g., by using reverse domain-name of the defining entity such as
@@ -1465,17 +1501,17 @@com.example.webauthn.myextension
.5.2. Defining extensions
-A definition of an extension must specify, at minimum, an extension identifier and an extension client argument sent via the
+getAssertion()
ormakeCredential()
call (see below). Additionally, extensions may specify additional values inClientData
,authenticatorData
(in the case of signature extensions), or both.A definition of an extension must specify, at minimum, an extension identifier and an extension client argument sent via the
getAssertion()
ormakeCredential()
call (see below). Additionally, extensions may specify additional values inClientData
,authenticatorData
(in the case of signature extensions), or both.Note: An extension that does not define additions to
ClientData
norauthenticatorData
is possible, but should be avoided. In such cases, the WebAuthn Relying Party would have no indication whether the extension was supported or processed by the client and/or authenticator.5.3. Extending request parameters
-An extension defines two request arguments. The client argument#client-argumentReferenced in:5.3. Extending request parameters is passed from the WebAuthn Relying Party to the client in the
getAssertion()
ormakeCredential()
call, while the authenticator argument is passed from the client to the +An extension defines two request arguments. The client argument#client-argumentReferenced in:5.3. Extending request parameters is passed from the WebAuthn Relying Party to the client in the
getAssertion()
ormakeCredential()
call, while the authenticator argument is passed from the client to the authenticator during the processing of these calls.Extension definitions MUST specify the valid values for their client argument. Clients are free to ignore extensions with an invalid client argument. Specifying an authenticator argument is optional, since some extensions may only affect client processing.
-A WebAuthn Relying Party simultaneously requests the use of an extension and sets its client argument by including an entry in the credentialExtensions or assertionExtensions dictionary parameters to the
+makeCredential()
orgetAssertion()
call. The entry key MUST be the extension identifier, and the value MUST be the client argument.A WebAuthn Relying Party simultaneously requests the use of an extension and sets its client argument by including an entry in the credentialExtensions or assertionExtensions dictionary parameters to the
makeCredential()
orgetAssertion()
call. The entry key MUST be the extension identifier, and the value MUST be the client argument.var assertionPromise = credentials.getAssertion(..., /* extensions */ { "com.example.webauthn.foobar": 42 }); @@ -1545,8 +1581,8 @@-
6. Standard extensions
-This section defines standard extensions defined by the W3C.
+6. Pre-defined extensions
+This section defines an initial set of extensions.
6.1. Transaction authorization
This signature extension allows for a simple form of transaction authorization. A WebAuthn Relying Party can specify a prompt string, intended for display on a trusted device on the authenticator.
@@ -1635,7 +1671,7 @@
Client processing
- -
This extension can only be used during
makeCredential()
. If the client supports the Authenticator Selection Extension, it +This extension can only be used during
@@ -2255,7 +2291,7 @@makeCredential()
. If the client supports the Authenticator Selection Extension, it MUST use the first available authenticator whose AAGUID is present in the AuthenticatorSelectionList. If none of the available authenticators match a provided AAGUID, the client MUST select an authenticator from among the available authenticators to generate the credential.dict-member for AndroidAttestationClientData, in §4.3.2.3.1
- dfn for AndroidAttestationClientData, in §4.3.2.3.1