device public key extension

index.bs

@@ -1068,8 +1068,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 : <dfn>Credential Private Key</dfn>
 : <dfn>Credential Public Key</dfn>
 : <dfn>User Public Key</dfn>
+: <dfn>User Credential</dfn>
 :: A [=credential key pair=] is a pair of asymmetric cryptographic keys generated by an [=authenticator=]
-    and [=scoped=] to a specific [=[WRP]=]. It is the central part of a [=public key credential=].
+    and [=scoped=] to a specific [=[WRP]=]. It thus forms the central part of a [=public key credential source=].
 
     A [=credential public key=] is the public key portion of a [=credential key pair=].
     The [=credential public key=] is returned to the [=[RP]=] during a [=registration ceremony=].
@@ -1078,17 +1079,26 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
     The [=credential private key=] is bound to a particular [=authenticator=] - its [=managing authenticator=] -
     and is expected to never be exposed to any other party, not even to the owner of the [=authenticator=].
 
-    Note that in the case of [=self
-    attestation=], the [=credential key pair=] is also used as the [=attestation key pair=], see [=self attestation=]
-    for details.
+    Note: In the case of [=self attestation=], the [=credential key pair=] is also used as the [=attestation key pair=], see [=self attestation=] for details.
 
     Note: The [=credential public key=] is referred to as the [=user public key=] in FIDO UAF [[UAFProtocol]], and in FIDO U2F
-    [[FIDO-U2F-Message-Formats]] and some parts of this specification that relate to it.
+    [[FIDO-U2F-Message-Formats]] and some parts of this specification that relate to it. Also, the term [=user credential=] is occasionally used to synonymously refer to [=credential public key=] and [=user public key=].
 
 : <dfn>Credential Properties</dfn>
 :: A [=credential property=] is some characteristic property of a [=public key credential source=], such as whether it is a
     [=client-side discoverable credential=] or a [=server-side credential=].
 
+: <dfn>Hardware-bound Device Key Pair</dfn>
+: <dfn>Device-bound Key</dfn>
+: <dfn>Device Private Key</dfn>
+: <dfn>Device Public Key</dfn>
+: <dfn>Device Key</dfn>
+: <dfn>Secondary Key</dfn>
+:: A [=hardware-bound device key pair=], also known as a [=device-bound key=], is a [=[RP]=]-specific and [=user credential=]-specific public key pair created upon a [=[RP]=]'s request via the [=devicePubKey=] [=WebAuthn extension=].
+    The [=[RP]=] may supply this extension during both [=registration=] and [=authentication=].
+    The [=authenticator=] that a [=hardware-bound device key pair=] is created upon guarantees that the [=device private key=] is securely stored in hardware, i.e., it is unextractable. The [=device public key=] is returned only to the [=[RP]=] that created the [=hardware-bound device key pair=]. See [[#sctn-device-publickey-extension]].
+
+
 : <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]].
@@ -5952,6 +5962,142 @@ However, [=authenticators=] that do not utilize [[!FIDO-CTAP]] do not necessaril
 :: [=largeblob|This extension=] directs the user-agent to cause the large blob to be stored on, or retrieved from, the authenticator. It thus does not specify any direct authenticator interaction for [=[RPS]=].
 
 
+## Device-bound public key extension (<dfn>devicePubKey</dfn>) ## {#sctn-device-publickey-extension}
+
+This [=client extension|client=] [=registration extension=] and [=authentication extension=] provides a [=[RP]=] with a "device continuity" signal. This is done by creating a [=[RP]=]-specific [=hardware-bound device key pair=] on the [=client device=], if such a key pair does not already exist for the [=user credential=] being created or exercised, and returning the attested [=device public key=] along with a signature by the [=device private key=] to the [=[RP]=]. This is done each time this [=devicePubKey=] extension is included with either a <code>{{CredentialsContainer/create()|navigator.credentials.create()}}</code> or <code>{{CredentialsContainer/create()|navigator.credentials.get()}}</code> call.
+
+If the [=client device=] is incapable of generating a [=hardware-bound device key pair=], or the registration or authentication operation fails for any reason, this extension is ignored and no [=hardware-bound device key pair=] is created. In this case, there is no [=devicePubKey=] extension output generated.
+
+
+<div class="note">
+    Note 1: This extension is intended for use by those [=[RPS]=] employing risk-analysis systems informing their sign-in decisions. This extension provides a "device continuity" signal when used consistently with both <code>{{CredentialsContainer/get()|navigator.credentials.create()}}</code> and <code>{{CredentialsContainer/get()|navigator.credentials.get()}}</code> operations. When a user's credential is synced to a new device, the [=[RP]=] will receive a new [=device public key=] on the initial <code>{{CredentialsContainer/get()|navigator.credentials.get()}}</code> invocation on the new device. Note that a synced credential will be exercised for authentication on a new device without a <code>{{CredentialsContainer/get()|navigator.credentials.create()}}</code> having been performed on that new device).
+
+    A usage example is thus:
+
+    Say that a sign-in request appears along with some geolocation signal that has not been seen for this [=user account=] before, and is outside of the typical working hours observed for the account. The risk may be deemed high enough not to allow the request, even with a synced credential. But if a device-bound signature can also be presented and it's a [=device-bound key=] that is well established for this user, then that may tip the balance.
+
+    Note 2: A [=[RP]=] utilizing this extension will only need to perform thorough verification of the [=device public key=]'s `attObjForDevicePublicKey` once: i.e., the first time a new [=device public key=] is received. "Thorough verification" means verifying the attestation statement `$$attStmtType` (per the [= attestation statement format=]'s signing procedure, see [[#sctn-generating-an-attestation-object]]) as well as the `sig` value. Upon successful verification, the [=[RP]=] SHOULD cache the `aaguid`, `dpk`, `scope`, and `$$attStmtType` values. Upon receiving subsequent `devicePubKey` extension output values, the [=[RP]=] can, along with verifying the `sig` value of each extension output occurrance, do binary equality checks against the cached `aaguid`, `dpk`, `scope`, and `$$attStmtType` values against those returned in the extension output.
+</div>
+
+Issue: TODO: write an explicit subsection wrt "how to verify a `attObjForDevicePublicKey`" ?  (i.e., analogous to the "verification procedue" steps provided in [[#sctn-defined-attestation-formats|attestation statement format definitions]], and also steps 7 through 19 in [[#sctn-verifying-assertion]])
+
+: Extension identifier
+:: `devicePubKey`
+
+: Operation applicability
+:: [=registration extension|Registration=] and [=authentication extension|authentication=]
+
+: Client extension input
+:: The Boolean value [TRUE] to indicate that this extension is requested by the [=[RP]=].
+    <xmp class="idl">
+    partial dictionary AuthenticationExtensionsClientInputs {
+        boolean devicePubKey;  // Explicitly set this to \`true\`!
+    };
+    </xmp>
+
+: Client extension processing
+:: If {{AuthenticationExtensionsClientInputs/devicePubKey}} is [TRUE], the client creates the authenticator extension input from the client extension input. If {{AuthenticationExtensionsClientInputs/devicePubKey}} is [FALSE], the client ignores this extension.
+
+: Client extension output
+:: An ArrayBuffer containing the [=device public key attestation object=] that was returned in the authenticator extension output.
+    <xmp class="idl">
+    partial dictionary AuthenticationExtensionsClientOutputs {
+        ArrayBuffer devicePubKey;
+    };
+    </xmp>
+
+
+: Authenticator extension input
+:: The Boolean value [TRUE], encoded in CBOR (major type 7, value 21).
+
+    ```
+    $$extensionInput //= (
+      devicePubKey: true
+    )
+    ```
+
+: Authenticator extension output
+:: The <dfn>device public key attestation object</dfn>, defined by the `attObjForDevicePublicKey` type:
+
+    ```
+    $$extensionOutput //= (
+        devicePubKey: attObjForDevicePublicKey,
+    )
+
+    attObjForDevicePublicKey = { ; Note: This object conveys an attested
+                                 ; device public key and is analogous to \`attObj\`.
+
+        sig:     bstr,  ; Result of sign((clientDataHash || userCredentialId), devicePrivateKey)
+                        ; Note that this signature value is unique per-response
+                        ; because the client data contains the per-request challenge.
+
+        aaguid:  bstr,  ; Authenticator's AAGUID (16 bytes fixed-length)
+                        ; https://www.w3.org/TR/webauthn/#aaguid
+
+        dpk:     bstr,  ; The Device Public Key (self-describing variable length,
+                        ; COSE_Key format, CBOR-encoded)).
+
+        ; Whether this key is scoped to the entire device, or a loosely-defined,
+        ; narrower scope called "app". For example, a "device"-scoped key is expected
+        ; to be the same between an app and a browser on the same device, while
+        ; an "app"-scoped key would probably not be.
+        ;
+        ; Whatever the scope, a device key is still specific to a given credential
+        ; and does not provide any ability to link credentials.
+        ;
+        ; Whether device-scoped or not, keys are still device-bound. I.e. an
+        ; app-scoped key does not enjoy lesser protection from extraction.
+
+        scope: uint .size 1, ; a value of 0x00 means "entire device" ("all apps") scope.
+                             ; 0x01 means "per-app" scope.
+                             ; Values other than 0x00 or 0x01 are reserved for future use.
+
+        ; See https://www.w3.org/TR/webauthn/#sctn-generating-an-attestation-object
+        ;
+        ; Attestation statement formats define the \`fmt\` and \`attStmt\` members of
+        ; $$attStmtType.
+        ;
+        ; In summary, the \`attStmt\` will (typically) contain:
+        ;   (1) a SIGNATURE value calculated (using the attestation private key)
+        ;       over (aaguid || dpk).
+        ;   (2) the attestation certificate or public key, and supporting certificates,
+        ;       if any.
+        ;
+        ; Note that there are details dependent upon the particular attestation
+        ; statement format.
+        ; See https://www.w3.org/TR/webauthn/#sctn-defined-attestation-formats.
+
+        $$attStmtType,
+    }
+
+    ```
+
+: Authenticator extension processing
+:: For both [=authenticatorMakeCredential=] and [=authenticatorGetAssertion=] operations:
+    1. Create or select the [=user credential=] as usual, and let `userCredentialId` be its <code>[=credentialId=]</code>.
+
+    1. If a [=hardware-bound device key pair=] does not already exist for this [=user credential=] on the [=authenticator=], create it using the same public key algorithm as that used by the [=user credential=]'s [=credential key pair=], otherwise locate the existing [=device-bound key=].
+
+    1. Let `dpk` be the newly created or existing [=device public key=], in COSE_Key format [=credentialPublicKey|in the same fashion as for the user credential's credentialPublicKey=] when the latter is conveyed in [=attested credential data=].
+
+    1. Let `devicePrivateKey` be the newly created or existing [=device private key=].
+
+    1. Let `clientDataHash` be the [=hash of the serialized client data=].
+
+    1. Let `sig` be the result of signing the concatenation of `clientDataHash` and `userCredentialId` using the `devicePrivateKey` and the signature algorithm appropriate for the `devicePrivateKey`'s public key algorithm: `sign((clientDataHash || userCredentialId), devicePrivateKey)`.
+
+    1. Let `scope` have the value zero (0x00) if this is an "entrie-device" [=device public key=]. Otherwise, let `scope` have the value one (0x01), indicating a more narrow per-app scope.
+
+    1. Let the `$$attStmtType` values be the result of generating an attestation statement in the [=attestation statement format=] appropriate for the [=user credential=], although substituting the authenticator's <code>[=aaguid=]</code> for |authenticatorData|, and substituting `userCredentialId` for |clientDataHash| in the [=attestation statement format=]'s signing procedure (see [[#sctn-generating-an-attestation-object]]). Attestation statement formats define the `fmt` and `attStmt` members of the `$$attStmtType` expansion.
+
+        In summary, the `$$attStmtType` values typically contain a signature value calculated over the bytes of `(clientDataHash || userCredentialId)`, the attestation certificate or public key, and supporting certificates, if any.
+
+        Note: The details of the `$$attStmtType` values are dependent upon the particular [=attestation statement=] format. See [[#sctn-attestation-formats]].
+
+    1. Let the `devicePubKey` [=authenticator extension output=] be a [=CBOR=] map as defined by `attObjForDevicePublicKey` above, whose values for its `sig`, `aaguid`, `dpk`, `scope`, and `$$attStmtType` members are as calculated in the prior steps.
+
+
+
 # User Agent Automation # {#sctn-automation}
 
 For the purposes of user agent automation and [=web application=] testing, this document defines a number of [[WebDriver]] [=extension commands=].