From c112c9621bdffacb022d57d6b59cecf2a671dc5b Mon Sep 17 00:00:00 2001 From: Vijay Bharadwaj Date: Sat, 7 May 2016 00:52:13 -0700 Subject: [PATCH] Clarify security model and remove vestiges of "native API" language Fixes #58 by adding verbiage in the API section about the two layers in the WebAuthn security model. This discussion is ongoing with the TAG, so we will open a new issue if there are follow-ups. Fixes #20, #21, #23 by removing mentions of native apps and APIs, as these are out of scope for this specification. --- index.src.html | 57 +++++++++++++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 22 deletions(-) diff --git a/index.src.html b/index.src.html index 6fd5ac69c..8b62ecb09 100644 --- a/index.src.html +++ b/index.src.html @@ -140,15 +140,30 @@ # Web Authentication API # {#api} -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]]. +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 an authenticator, with which the [RP] 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 [RP]. 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 [[#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 [RPS] from probing for the presence of credentials belonging to +other [RPS], 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 [RP] 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 [RP] 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. @@ -617,18 +632,17 @@ The components of a system using WebAuthn can be divided into three layers: -1. The [RP] (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. - -2. 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. +1. The [RP] (RP), which uses the WebAuthn services. The RP consists of a server component and a web-application running + in a browser. -3. The Authenticator itself, which provides key management and cryptographic signatures. +2. The WebAuthn Client platform, which consists of the User Agent and the OS and device on which it executes. -When the [RP] client-side application is a web-application, the interface between 1 and 2 is the [[#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. +3. 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. + +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. @@ -667,9 +681,8 @@
The challenge member contains the base64url encoding of the challenge provided by the RP. - The facet member contains a string value describing the RP identifier facet. When the [RP] 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 member specifies the hash algorithm used to compute clientDataHash (see [[#authenticator-signature]]). Use "S256" for SHA-256, "S384" for SHA384, "S512" for SHA512, and "SM3" for SM3 (see