Client to Authenticator Protocol (CTAP)

1. Introduction

This section is not normative.

This protocol is intended to be used in scenarios where a user interacts with a Relying Party (a website or native app) on some platform (e.g., a PC) which prompts the user to interact with a roaming authenticator (e.g., a smartphone).

In order to provide evidence of user interaction, a roaming authenticator implementing this protocol may have a built-in mechanism to obtain a "user gesture", allowing the platform to collect a PIN on behalf of the authenticator.

1.1. Relationship to Other Specifications

This specification is part of the FIDO2 project, which includes this specification and is related to the W3C [WebAuthn] specification. This specification refers to two CTAP protocol versions:

1. The CTAP1/U2F protocol, which is defined by the U2F Raw Messages specification [U2FRawMsgs]. CTAP1/U2F messages are recognizable by their APDU-like binary structure. CTAP1/U2F may also be referred to as CTAP 1.2 or U2F 1.2. The latter was the U2F specification version used as the basis for several portions of this specification. Authenticators implementing CTAP1/U2F are typically referred to as U2F authenticators or CTAP1 authenticators.

2. The CTAP2 protocol, whose messages are encoded in the CTAP2 canonical CBOR encoding form. Authenticators implementing CTAP2 are referred to as CTAP2 authenticators, FIDO2 authenticators, or WebAuthn authenticators.

Both CTAP1 and CTAP2 share the same underlying transports: USB Human Interface Device (USB HID), Near Field Communication (NFC), and Bluetooth Smart / Bluetooth Low Energy Technology (BLE).

Whole documents or specific features may be superseded by this document. A superseded document or feature MAY be implemented if optional, but it exists purely for backwards compatibility with older platforms or authenticators. Thus a superseded document or feature SHOULD NOT be used unless the replacement is not implemented by the counterparty. (Superseded features are not automatically optional, e.g. a CTAP 2.1 authenticator MUST still support authenticatorClientPIN's getPinToken subcommand if it supports clientPIN and CTAP 2.0.)

The [U2FUsbHid], [U2FNfc], [U2FBle], and [U2FRawMsgs] specifications, specifically, are superseded by this specification.

CTAP2 authenticators SHOULD also implement CTAP1/U2F. See § 10 Interoperating with CTAP1/U2F authenticators for details on how these protocols interoperate from the perspective of authenticators, platforms, and RPs.

Occasionally, the term "CTAP" may be used without clarifying whether it is referring to CTAP1 or CTAP2. In such cases, it should be understood to be referring to the entirety of this specification or portions of this specification that are not specific to either CTAP1 or CTAP2. For example, some error messages begin with the term "CTAP" without clarifying whether they are CTAP1- or CTAP2-specific because they are applicable to both CTAP protocol versions. CTAP protocol-specific error messages are prefixed with either "CTAP1" or "CTAP2" as appropriate.

1.2. Data Elements Referenced by Other Specifications

The following data elements might be referenced by other specifications and hence should not be changed in their fundamental data type or high-level semantics without liaising with the other specifications:

1. aaguid, data type byte string and identifying the authenticator model, i.e. identical values mean that they refer to the same authenticator model and different values mean they refer to different authenticator models.

2. RP ID, data type string representing the Relying party identifier, i.e. identical values mean that they refer to the same Relying Party.

3. credentialID, data type byte string identifying a specific public key credential source, i.e. identical values mean that they refer to the same credential and different values mean they refer to different credentials. Note that there might be a very small probability that different credentials get assigned the same credentialID.

4. up and uv, data type boolean indicating whether user presence (up) or user verification (uv) was performed by the authenticator.

Note: Some of the data elements might have an internal structure that might change. Other specifications shall not rely on such internal structure.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC2119].

Authenticators and Platforms may implement additional constraints on these specifications to meet the certification requirements of programs like [CMVP], [CSPN], and [CommonCriteria].

3. Protocol Structure

This protocol is specified in three parts:

• Authenticator API: At this level of abstraction, each authenticator operation is defined similarly to an API call - it accepts input parameters and returns either an output or error code. Note that this API level is conceptual and does not represent actual APIs. The actual APIs will be provided by each implementing platform.

• Message Encoding: In order to invoke a method in the authenticator API, the host must construct and encode a request and send it to the authenticator over the chosen transport protocol. The authenticator will then process the request and return an encoded response.

• Transport-specific Binding: Requests and responses are conveyed to roaming authenticators over specific transports (e.g., USB, NFC, Bluetooth). For each transport technology, message bindings are specified for this protocol.

This document specifies all three of the above pieces for roaming FIDO2 authenticators.

4. Protocol Overview

The general protocol between a Relying Party application, a client platform, and an authenticator is as follows:

1. In Relying Party-oriented use cases involving credential registration or user authentication, a Relying Party application calls navigator.credentials.create() or navigator.credentials.get() if it is a website, or the client platform’s equivalent API methods if it is a native application. Other use cases, such as credential management, PIN establishment/maintenance, or biometric enrollment, are typically initiated by the client platform itself.

2. The platform establishes a connection with a nominally appropriate available authenticator, having used criteria passed in by the Relying Party application and possibly other information it has to select the authenticator.

3. The platform gets information about the authenticator using the authenticatorGetInfo command, which helps it determine the authenticator’s capabilities.

4. Depending upon the operation the Relying Party application, or the platform itself, initiated (in step 1), the options it supplied, and the authenticator’s capabilities, the platform will invoke one or more further Authenticator API commands.

5. Terminology

Built-in User Verification method

The authenticator supports a built-in on-device user verification method like fingerprint or has a input UI with secure communication to the authenticator.

Note: clientPin is not a built-in user verification method.

Evidence of user interaction

Collection of evidence of user interaction establishes a state of user presence. Also, if it is collected along with displaying a particular prompt to a user it may be considered collecting user consent. The general notion is that the user interacts with the authenticator in some fashion, also known as supplying a "user gesture"—e.g., touches a consent button, enters a password or a PIN, or supplies a biometric—in order to at least confirm their presence and possibly consent to some proposed action. Some "user gesture" approaches provide user verification in addition to establishing user presence, e.g., a fingerprint-based built-in user verification method.

Platform-mediated user interactions such as clientPin may provide user verification but are not considered to assert user presence. Thus, there are transport-based affordances affecting when and for how long user presence is established on a per-transport basis:

NFC

For authenticators without a method to collect a user gesture inside the authenticator boundary other than through a power on gesture, the act of a user placing an NFC authenticator into the NFC reader’s field is considered a user gesture that establishes user presence and provides evidence of user interaction. This powers-up the authenticator, who then starts an NFC powered-up timer, and sets an NFC userPresent flag to true. There is an associated NFC user presence maximum time limit of two minutes (120 seconds).

Upon the platform subsequently invoking either authenticatorMakeCredential or authenticatorGetAssertion (e.g., with the "up" option key set to 'true'):

1. If evidence of user interaction is requested then:

   1. If the platform sends a zero length pinUvAuthParam then return either CTAP2_ERR_PIN_NOT_SET if PIN is not set or CTAP2_ERR_PIN_INVALID if PIN has been set.

      Note: This is done for backwards compatibility with CTAP2.0 platforms in the case where multiple authenticators are attached to the platform. In this case the authenticator must not consume the NFC userPresent flag or it will prevent authentication with some CTAP2.0 platforms.

   2. If the NFC userPresent flag's value is true, then consider the user as having granted permission, and set the NFC userPresent flag to false.

   3. Otherwise, do not consider the user as having granted permission. End the operation by returning CTAP2_ERR_UP_REQUIRED.

Upon expiry of the NFC user presence maximum time limit, the NFC userPresent flag is set to false if it is not already false.

Note: This notion of user presence establishment is distinct due to the physical proximity and user action characteristics of devices employing NFC to communicate, i.e., the user placing the authenticator in the NFC field, also known as the "NFC tap". Thus, user presence is asserted even if the platform and authenticator then use a form of user verification that does not itself provide user presence, such as clientPin-based user verification (clientPin does not assert user presence when used over other transports).

For example, in an authentication scenario, the user places an NFC authenticator on an NFC reading device having a keyboard and display, and is prompted to enter a PIN. If PIN entry is completed (e.g., by pressing Enter) before the NFC user presence maximum time limit expires, the authenticator will return an assertion with the "UP" bit in authenticator data set to true and the NFC userPresent flag is then set to false.

If a user lays an NFC authenticator on an NFC reader and for whatever reason ignores it for greater than the NFC user presence maximum time limit they will need to remove the authenticator from the NFC field and re-insert it and start over to complete any interaction requiring user presence.

All other transports

If evidence of user interaction is explicitly requested (i.e., even if a pinUvAuthToken is in use) it is interactively collected at that time in an authenticator-specific manner.

pre-flight

In order to determine whether authenticatorMakeCredential's excludeList or authenticatorGetAssertion's allowList contain credential IDs that are already present on an authenticator, a platform typically invokes authenticatorGetAssertion with the "up" option key set to false and optionally pinUvAuthParam one or more times. If a credential is found an assertion is returned. If a valid pinUvAuthParam was also provided, the response will contain "up"=0 and "uv"=1 within the "flags bits" of the authenticator data structure, otherwise the "flag bits" will contain "up"=0 and "uv"=0.

Protected by some form of User Verification

Either or both clientPin or built-in user verification methods are supported and enabled. I.e., in the authenticatorGetInfo response the pinUvAuthToken option ID is present and set to true, and either clientPin option ID is present and set to true or uv option ID is present and set to true or both.

Some form of User Verification

This term refers to either clientPin or built-in user verification methods.

User action timeout

This refers to a timeout that occurs when the authenticator is waiting for direct action from the user, like a touch. (I.e. not a command from the platform.) The duration of this timeout is chosen by the authenticator but MUST be at least 10 seconds. Thirty seconds is a reasonable value.

6. Authenticator API

Each operation in the authenticator API can be performed independently of the others, and all operations are asynchronous. The authenticator may enforce a limit on outstanding operations to limit resource usage - in this case, the authenticator is expected to return a busy status and the host is expected to retry the operation later. Additionally, this protocol does not enforce in-order or reliable delivery of requests and responses; if these properties are desired, they must be provided by the underlying transport protocol or implemented at a higher layer by applications.

Note that this API level is conceptual and does not represent actual APIs. The actual APIs will be provided by each implementing platform.

Some commands or subcommands require the authenticator to maintain state. For example, the authenticatorCredentialManagement subcommand enumerateRPsGetNextRP implicitly assumes that the authenticator remembers which RP is next to return. The following (sub)commands require such state and are called stateful commands. Each such command uses and updates state that is initialized by a corresponding state initializing command:

1. authenticatorGetNextAssertion, with state initialized by authenticatorGetAssertion.

2. authenticatorCredentialManagement/enumerateRPsGetNextRP, with state initialized by enumerateRPsBegin.

3. authenticatorCredentialManagement/enumerateCredentialsGetNextCredential, with state initialized by enumerateCredentialsBegin.

4. authenticatorLargeBlobs where the parameter set is given and the parameter offset is non-zero, with state initialized by a prior authenticatorLargeBlobs command with set given and a zero offset.

In order to accommodate authenticators with limited capacity, the following accommodations are made:

1. The state SHOULD NOT be maintained across power cycles.

2. The authenticator MAY maintain state based on the assumption that each stateful command is exclusively preceded by either another instance of the same command, or by the corresponding state initializing command, and no more than 30 seconds will elapse between such commands. If this pattern is violated then the authenticator MAY fail any stateful command with the error CTAP2_ERR_NOT_ALLOWED. Here, “exclusively preceded” means that no other authenticator operation occurs in between. An authenticator MAY assume this globally, even when the transport-specific binding provides for independent streams of platform commands (e.g. § 11.2.3 Concurrency and channels).

3. An authenticator MUST discard the state for a stateful command command if the pinUvAuthToken that authenticated the state initializing command expires since the stateful commands do not themselves always verify a pinUvAuthToken.

The authenticator API has the following methods and data structures.

6.1. authenticatorMakeCredential (0x01)

This method is invoked by the host to request generation of a new credential in the authenticator. It takes the following input parameters, several of which correspond to those defined in the authenticatorMakeCredential operation section of the Web Authentication specification:

The following option keys are defined for use in authenticatorMakeCredential's options parameter. All option keys have boolean values.

Note: For brevity, individual option keys are often referred to as simply an "option", below.

Note: For backwards compatibility, platforms must be aware that FIDO_2_0 (aka CTAP2.0) authenticators always require some form of user verification for authenticatorMakeCredential operations. If a platform attempts to create a non-discoverable credential on a CTAP2.0 authenticator without including the "uv" option key or the pinUvAuthToken parameter that authenticator will return an error. In contrast, a FIDO_2_1 (aka CTAP2.1) authenticator with the makeCredUvNotRqd option ID (set to true) in the authenticatorGetInfo response structure, will allow creation of non-discoverable credentials without requiring some form of user verification.

Note: For backwards compatibility, platforms must be aware that FIDO_2_0 (aka CTAP2.0) authenticators will return a CTAP2_ERR_INVALID_OPTION response if "up" is present. Platforms SHOULD NOT send "up" to a CTAP2.0 authenticator.

Note: The [WebAuthn] specification defines an abstract authenticatorMakeCredential operation, which corresponds to the operation described in this section. The parameters in the abstract [WebAuthn] authenticatorMakeCredential operation map to the above parameters as follows:

Note: Icon values used with authenticators can employ [RFC2397] "data" URLs so that the image data is passed by value, rather than by reference. This can enable authenticators with a display but no Internet connection to display icons.

Note: Text strings are UTF-8 encoded (CBOR major type 3).

6.1.1. Platform Actions for authenticatorMakeCredential (non-normative)

To invoke authenticatorMakeCredential, the platform performs the following steps, in general. Here, we are assuming that the platform has already queried the authenticator for its particulars using the authenticatorGetInfo command, and has determined that the authenticator’s present characteristics are likely sufficient to be able to satisfy the request(s) the platform will send it. In other words, this is only a brief sketch of plausible platform behavior.

For example, if the authenticator is not protected by some form of user verification and user verification is required for the present usage scenario, e.g., the Relying Party set options.authenticatorSelection.userVerification to "required" in the WebAuthn API, then the platform recovers in some fashion out of scope of these actions.

1. The platform marshals the necessary and appropriate input parameters given the present usage scenario, and additionally:

   1. If the authenticator is protected by some form of user verification, or the Relying Party prefers enforcing user verification (e.g., by setting options.authenticatorSelection.userVerification to "required", or "preferred" in the WebAuthn API):

      1. If the platform has already created a pinUvAuthParam parameter during this overall scenario, it uses that along with the other marshalled input parameters to invoke the authenticator operation: either authenticatorMakeCredential or possibly authenticatorGetAssertion. For example, in some situations (e.g., with CTAP2 authenticators) when an "exclude list" was provided by the Relying Party, the platform may first invoke the authenticatorGetAssertion operation multiple times to "pre-flight" the "exclude list" (i.e., to determine if any of the exclude list’s credential IDs are already present on the authenticator), prior to invoking authenticatorMakeCredential to create a new credential on this authenticator.

      2. Otherwise, the platform examines various option IDs in the authenticatorGetInfo response to determine its course of action:

         1. If the uv option ID is present and set to true:

            1. If the pinUvAuthToken option ID is present and true then plan to use getPinUvAuthTokenUsingUvWithPermissions to obtain a pinUvAuthToken, and let it be the selected operation. Go to Step 1.1.2.3.

            2. Else (implying the pinUvAuthToken option ID is set to false or absent) use the "uv" option key when invoking the authenticatorMakeCredential operation and terminate these steps. (Note that if the authenticator returns a 0x36 error code (CTAP2_ERR_PUAT_REQUIRED (aka CTAP2_ERR_PIN_REQUIRED in CTAP2.0)) then "fall back" and go to Step 1.1.2.2.2.1)

         2. Else (implying the uv option ID is present and set to false or absent):

            1. If the pinUvAuthToken option ID is present and true:

               1. To continue, ensure the clientPin option ID is present and true. Plan to use getPinUvAuthTokenUsingPinWithPermissions to obtain a pinUvAuthToken, and let it be the selected operation. Go to Step 1.1.2.3.

            2. Else (implying the pinUvAuthToken option ID is absent):

               1. To continue, ensure the clientPin option ID is present and true. Plan to use getPinToken to obtain a pinUvAuthToken, and let it be the selected operation.

         3. In preparation for obtaining pinUvAuthToken, the platform:

            1. Obtains a shared secret.

            2. Sets the pinUvAuthProtocol parameter to the value as selected when it obtained the shared secret.

         4. Then the platform obtains a pinUvAuthToken from the authenticator, with the mc (and likely also with the ga) permission (see "pre-flight", mentioned above), using the selected operation. If successful, the platform creates the pinUvAuthParam parameter by calling authenticate(pinUvAuthToken, clientDataHash), and goes to Step 1.1.1.

   2. Otherwise, implying the authenticator is not presently protected by some form of user verification, or the Relying Party wants to create a non-discoverable credential and not require user verification (e.g., by setting options.authenticatorSelection.userVerification to "discouraged" in the WebAuthn API), the platform invokes the authenticatorMakeCredential operation using the marshalled input parameters along with the "uv" option key set to false and terminate these steps.

6.1.2. authenticatorMakeCredential Algorithm

Upon receipt of an authenticatorMakeCredential request, the authenticator performs the following procedure:

1. If authenticator supports either pinUvAuthToken or clientPin features and the platform sends a zero length pinUvAuthParam:

   1. Request evidence of user interaction in an authenticator-specific way (e.g., flash the LED light).

   2. If the user declines permission, or the operation times out, then end the operation by returning CTAP2_ERR_OPERATION_DENIED.

   3. If evidence of user interaction is provided in this step then return either CTAP2_ERR_PIN_NOT_SET if PIN is not set or CTAP2_ERR_PIN_INVALID if PIN has been set.

   Note: This is done for backwards compatibility with CTAP2.0 platforms in the case where multiple authenticators are attached to the platform and the platform wants to enforce pinUvAuthToken feature semantics, but the user has to select which authenticator to get the pinUvAuthToken from. CTAP2.1 platforms SHOULD use § 6.9 authenticatorSelection (0x0B).

2. If the pinUvAuthParam parameter is present:

   1. If the pinUvAuthProtocol parameter’s value is not supported, return CTAP1_ERR_INVALID_PARAMETER error.

   2. If the pinUvAuthProtocol parameter is absent, return CTAP2_ERR_MISSING_PARAMETER error.

3. Validate pubKeyCredParams with the following steps:

   1. For each element of pubKeyCredParams:

      1. If the element is missing required members, including members that are mandatory only for the specific type, then return an error, for example CTAP2_ERR_INVALID_CBOR.

      2. If the values of any known members have the wrong type then return an error, for example CTAP2_ERR_CBOR_UNEXPECTED_TYPE.

      3. If the element specifies an algorithm that is supported by the authenticator, and no algorithm has yet been chosen by this loop, then let the algorithm specified by the current element be the chosen algorithm.

   2. If the loop completes and no algorithm was chosen then return CTAP2_ERR_UNSUPPORTED_ALGORITHM.

   Note: This loop chooses the first occurrence of an algorithm identifier supported by this authenticator but always iterates over every element of pubKeyCredParams to validate them.

4. Create a new authenticatorMakeCredential response structure and initialize both its "uv" bit and "up" bit as false.
5. If the options parameter is present, process all option keys and values present in the parameter. Treat any option keys that are not understood as absent.

   Note: As this specification defines normative behaviours for the "rk", "up", and "uv" option keys, they MUST be understood by all authenticators.

   1. If the "uv" option is absent, let the "uv" option be treated as being present with the value false. (This is the default)

   2. If the pinUvAuthParam is present, let the "uv" option be treated as being present with the value false.

      Note: pinUvAuthParam and the "uv" option are processed as mutually exclusive with pinUvAuthParam taking precedence.

   3. If the "uv" option is true then:

      1. If the authenticator does not support a built-in user verification method end the operation by returning CTAP2_ERR_INVALID_OPTION.

      2. If the built-in user verification method has not yet been enabled, end the operation by returning CTAP2_ERR_INVALID_OPTION.

   4. If the "rk" option is present then:

      1. If the rk option ID is not present in authenticatorGetInfo response, end the operation by returning CTAP2_ERR_UNSUPPORTED_OPTION.

   5. Else: (the "rk" option is absent)

      1. Let the "rk" option be treated as being present with the value false. (This is the default.)

   6. If the "up" option is present then:

      1. If the "up" option is false, end the operation by returning CTAP2_ERR_INVALID_OPTION.

   7. If the "up" option is absent, let the "up" option be treated as being present with the value true (i.e., this is the default for both CTAP2.0 and CTAP2.1 authenticators).

6. If the alwaysUv option ID is present and true then:

   1. Let the makeCredUvNotRqd option ID be treated as false.

   2. If the authenticator is not protected by some form of user verification:

      1. If the clientPin option ID is present and noMcGaPermissionsWithClientPin option ID is absent or false (clientPin is supported for the mc permission):

         1. End the operation by returning CTAP2_ERR_PUAT_REQUIRED.

      2. Else (clientPin is not supported):

         1. End the operation by returning CTAP2_ERR_OPERATION_DENIED.

   3. If the pinUvAuthParam is not present, and the uv option ID is true, let the "uv" option be treated as being present with the value true.

      Note: The above step 6.3 is for backwards compatibility with CTAP2.0 platforms who are not aware of the Always UV feature.

   4. If the pinUvAuthParam is not present, and the "uv" option is false or absent:

      1. If the clientPin option ID is present and noMcGaPermissionsWithClientPin option ID is absent or false (clientPin is supported for the mc permission):

         1. End the operation by returning CTAP2_ERR_PUAT_REQUIRED.

      2. Else (clientPin is not supported):

         1. End the operation by returning CTAP2_ERR_OPERATION_DENIED.

7. If the makeCredUvNotRqd option ID is present and set to true in the authenticatorGetInfo response:

   1. If the following statements are all true:

      Note: This step returns an error if the platform tries to create a discoverable credential without performing some form of user verification.

      1. The authenticator is protected by some form of user verification.

      2. The "uv" option is set to false.

      3. The pinUvAuthParam parameter is not present.

      4. The "rk" option is present and set to true.

      Then:

      1. If ClientPin option ID is true and the noMcGaPermissionsWithClientPin option ID is absent or false, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

      2. Otherwise, end the operation by returning CTAP2_ERR_OPERATION_DENIED.

8. Else: (the makeCredUvNotRqd option ID in authenticatorGetInfo's response is present with the value false or is absent):

   1. If the following statements are all true:

      Note: This step returns an error if the platform tries to create a credential without performing some form of user verification when the makeCredUvNotRqd option ID in authenticatorGetInfo's response is present with the value false or is absent.

      1. The authenticator is protected by some form of user verification.

      2. The "uv" option is set to false.

      3. The pinUvAuthParam parameter is not present.

      Then:

      1. If the ClientPin option ID is true and the noMcGaPermissionsWithClientPin option ID is absent or false, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

      2. Otherwise, end the operation by returning CTAP2_ERR_OPERATION_DENIED.

9. If the enterpriseAttestation parameter is present:

   1. If the authenticator is not enterprise attestation capable, or the authenticator is enterprise attestation capable but enterprise attestation is disabled, then end the operation by returning CTAP1_ERR_INVALID_PARAMETER.

   2. Else: (the authenticator is enterprise attestation capable and enterprise attestation is enabled; see also § 7.1.2 Platform Actions):

      1. If the enterpriseAttestation parameter’s value is not 1 or 2, then end the operation by returning CTAP2_ERR_INVALID_OPTION.

      2. Consider the following cases in order, until one matches, to learn whether the authenticator may return an enterprise attestation. (These substeps define when an authenticator is permitted to return an enterprise attestation. Authenticators MUST NOT do so in any other cases.)

         1. If the authenticator supports only vendor-facilitated enterprise attestation and the request’s rp.id matches an entry on the authenticator’s pre-configured RP ID list, then the authenticator MAY return an enterprise attestation.

            Note: An authenticator that only supports vendor-facilitated enterprise attestation is obliged to treat enterpriseAttestation parameter values 1 and 2 equivalently, otherwise it will yield unexpected results if used with an enterprise-managed platform (which will be setting enterpriseAttestation to 2).

         2. If the authenticator supports vendor-facilitated enterprise attestation at all, the enterpriseAttestation parameter’s value is 1, and the request’s rp.id matches an entry on the authenticator’s pre-configured RP ID list, then the authenticator MAY return an enterprise attestation.

         3. If the authenticator supports platform-managed enterprise attestation (whether or not vendor-facilitated enterprise attestation is also supported), and the enterpriseAttestation parameter’s value is 2, then the platform MUST have performed the necessary vetting of the request’s rp.id (e.g., via local policy lookup), and the authenticator MAY return an enterprise attestation without checking whether the request’s rp.id matches an entry on the authenticator’s pre-configured RP ID list (if any).

      3. If, by considering the substeps of the previous step, the authenticator did not conclude that it may return an enterprise attestation then let the enterpriseAttestation parameter be treated as absent, terminate these steps, and go to Step 10. A non-enterprise attestation will be returned with the credential.

      4. Apply any additional constraints that may prohibit returning an enterprise attestation. An authenticator has unlimited discretion to apply additional constraints which can further limit the contexts in which enterprise attestation is returned. They may be based on other parameters from the request or, indeed, on any other factor the authenticator wishes. It is the job of enterprise Relying Party to know the authenticators that it has deployed and thus to arrange the request so as to get its desired result.

      5. If, by considering any additional constraints in the previous step, the authenticator concluded that it did not wish to return an enterprise attestation then let the enterpriseAttestation parameter be treated as absent, terminate these steps, and go to Step 10. A non-enterprise attestation will be returned with the credential.

      6. If the authenticator has a display, then the authenticator SHOULD display an explicit warning to the user, including the rp.id, notifying the user that they are being uniquely identified to this Relying Party.

      7. Let epAtt in the authenticatorMakeCredential response structure be set to true and return an enterprise attestation.

10. If the following statements are all true:

    Note: This step allows the authenticator to create a non-discoverable credential without requiring some form of user verification under the below specific criteria.

    1. "rk" and "uv" options are both set to false or omitted.

    2. the makeCredUvNotRqd option ID in authenticatorGetInfo's response is present with the value true.

    3. the pinUvAuthParam parameter is not present.

    Then go to Step 12.

    Note: Step 4 has already ensured that the "uv" bit is false in the response.

11. If the authenticator is protected by some form of user verification, then:

    1. If pinUvAuthParam parameter is present (implying the "uv" option is false (see Step 5)):

       1. Call verify(pinUvAuthToken, clientDataHash, pinUvAuthParam).

          1. If the verification returns error, then end the operation by returning CTAP2_ERR_PIN_AUTH_INVALID error.

       2. Verify that the pinUvAuthToken has the mc permission, if not, then end the operation by returning CTAP2_ERR_PIN_AUTH_INVALID.

       3. If the pinUvAuthToken has a permissions RP ID associated:

          1. If the permissions RP ID does not match the rp.id in this request, then end the operation by returning CTAP2_ERR_PIN_AUTH_INVALID.

       4. Let userVerifiedFlagValue be the result of calling getUserVerifiedFlagValue().

       5. If userVerifiedFlagValue is false then end the operation by returning CTAP2_ERR_PIN_AUTH_INVALID.

       6. If userVerifiedFlagValue is true then set the "uv" bit to true in the response.

       7. If the pinUvAuthToken does not have a permissions RP ID associated:

          1. Associate the request’s rp.id parameter value with the pinUvAuthToken as its permissions RP ID.

       8. Go to Step 12.

    2. If the "uv" option is present and set to true (implying the pinUvAuthParam parameter is not present, and that the authenticator supports an enabled built-in user verification method, see Step 5):

       Note: This step provides backwards compatibility for CTAP2.0 platforms.

       1. Let internalRetry be true.

       2. Let uvState be the result of calling performBuiltInUv(internalRetry)

       3. If uvState is error:

          1. If the error reason is a user action timeout, then return CTAP2_ERR_USER_ACTION_TIMEOUT.

          2. If the ClientPin option ID is true and the noMcGaPermissionsWithClientPin option ID is absent or false, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

          3. If the uvRetries counter is <= 0, return CTAP2_ERR_PIN_BLOCKED.

          4. Otherwise, end the operation by returning CTAP2_ERR_OPERATION_DENIED.

       4. If uvState is success:

          1. Set the "uv" bit to true in the response.

    Note: If Step 11 was skipped, then the authenticator is NOT protected by some form of user verification, and Step 4 has already ensured that the "uv" bit is false in the response.

12. If the excludeList parameter is present and contains a credential ID created by this authenticator, that is bound to the specified rp.id:

    1. If the credential’s credProtect value is not userVerificationRequired, then:

       1. Let userPresentFlagValue be false.

       2. If the pinUvAuthParam parameter is present then let userPresentFlagValue be the result of calling getUserPresentFlagValue().

       3. Else, if evidence of user interaction was provided as part of Step 11 let userPresentFlagValue be true.

       4. If userPresentFlagValue is false, then:

          1. Wait for user presence.

          2. Regardless of whether user presence is obtained or the authenticator times out, terminate this procedure and return CTAP2_ERR_CREDENTIAL_EXCLUDED.

       5. Else, (implying userPresentFlagValue is true) terminate this procedure and return CTAP2_ERR_CREDENTIAL_EXCLUDED.

          Note: A user presence test is required for CTAP2 authenticators, before the RP is told that the authenticator is already registered, to behave similarly to CTAP1/U2F authenticators.

    2. Else (implying the credential’s credProtect value is userVerificationRequired):

       1. If the "uv" bit is true in the response:

          1. Let userPresentFlagValue be false.

          2. If the pinUvAuthParam parameter is present then let userPresentFlagValue be the result of calling getUserPresentFlagValue().

          3. Else, if evidence of user interaction was provided as part of Step 11 let userPresentFlagValue be true.

          4. If userPresentFlagValue is false, then:

             1. Wait for user presence.

             2. Regardless of whether user presence is obtained or the authenticator times out, terminate this procedure and return CTAP2_ERR_CREDENTIAL_EXCLUDED.

          5. Else, (implying userPresentFlagValue is true) terminate this procedure and return CTAP2_ERR_CREDENTIAL_EXCLUDED.

       2. Else (implying user verification was not collected in Step 11), remove the credential from the excludeList and continue parsing the rest of the list.

13. If evidence of user interaction was provided as part of Step 11 (i.e., by invoking performBuiltInUv()):

    Note: This step’s criteria implies that the "uv" option is present and set to true and the pinUvAuthParam parameter is not present. I.e., the pinUvAuthToken feature is not in use.

    1. Set the "up" bit to true in the response.

    2. Go to Step 15

14. If the "up" option is set to true:

    1. If the pinUvAuthParam parameter is present then:

       1. Let userPresentFlagValue be the result of calling getUserPresentFlagValue().

       2. If userPresentFlagValue is false:

          Note: An authenticator may be configured to collect user presence whenever the "up" option is true by setting the default user present time limit to zero.

          1. Request evidence of user interaction in an authenticator-specific way (e.g., flash the LED light). If the authenticator has a display, show the items contained within the user and rp parameter structures to the user, and request permission to create a credential.

          2. If the user declines permission, or the operation times out, then end the operation by returning CTAP2_ERR_OPERATION_DENIED.

    2. Else (implying the pinUvAuthParam parameter is not present):

       1. If the "up" bit is false in the response :

          1. Request evidence of user interaction in an authenticator-specific way (e.g., flash the LED light). If the authenticator has a display, show the items contained within the user and rp parameter structures to the user, and request permission to create a credential.

          2. If the user declines permission, or the operation times out, then end the operation by returning CTAP2_ERR_OPERATION_DENIED.

    3. Set the "up" bit to true in the response.

    4. Call clearUserPresentFlag(), clearUserVerifiedFlag(), and clearPinUvAuthTokenPermissionsExceptLbw().

       Note: This consumes both the "user present state", sometimes referred to as the "cached UP", and the "user verified state", sometimes referred to as "cached UV". These functions are no-ops if there is not an in-use pinUvAuthToken.

15. If the extensions parameter is present:

    1. Process any extensions that this authenticator supports, ignoring any that it does not support.

    2. Authenticator extension outputs generated by the authenticator extension processing are returned in the authenticator data. The set of keys in the authenticator extension outputs map MUST be equal to, or a subset of, the keys of the authenticator extension inputs map.

    Note: Some extensions may produce different output depending on the state of the "uv" bit and/or "up" bit in the response.

16. Generate a new credential key pair for the algorithm chosen in step 3.

17. If the "rk" option is set to true:

    1. The authenticator MUST create a discoverable credential.

    2. If a credential for the same rp.id and account ID already exists on the authenticator:

       1. If the existing credential contains a largeBlobKey, an authenticator MAY erase any associated large-blob data. Platforms MUST NOT assume that authenticators will do this. Platforms can later garbage collect any orphaned large-blobs.

       2. Overwrite that credential.

    3. Store the user parameter along with the newly-created key pair.

    4. If authenticator does not have enough internal storage to persist the new credential, return CTAP2_ERR_KEY_STORE_FULL.

18. Otherwise, if the "rk" option is false: the authenticator MUST create a non-discoverable credential.

    Note: This step is a change from CTAP2.0 where if the "rk" option is false the authenticator could optionally create a discoverable credential.

19. Generate an attestation statement for the newly-created credential using clientDataHash, taking into account the value of the enterpriseAttestation parameter, if present, as described above in Step 9.

On success, the authenticator returns the following authenticatorMakeCredential response structure which contains an attestation object plus additional information.

6.1.3. Discoverable credentials

A credential may, or may not, be discoverable. A discoverable credential [WebAuthn] has the property that, in response to an authenticatorGetAssertion request where the allowList parameter is omitted, the authenticator is able to discover the appropriate public key credential source given only an RP ID, possibly with user assistance.

Each credential has a credential protection policy. For backwards compatibility with CTAP2.0 platforms, the default credential creation policy is userVerificationOptional (0x01). If a credential was created with credential protection values of userVerificationOptionalWithCredentialIDList (0x02) or userVerificationRequired (0x03) it will not be discoverable unless the platform invokes authenticatorGetAssertion with a valid pinUvAuthParam or the "uv" option key with a value of true.

Note: Regarding user assistance, for example, the authenticator may provide the user a pick-list of credentials scoped to the RP ID.

In contrast, server-side credentials (also known as non-discoverable credentials) have the property that their credential IDs MUST be supplied by the Relying Party in authenticatorGetAssertion's allowList parameter in order for the authenticator to discover and employ them.

Note that this definition does not speak to whether a credential is statefully maintained or not.

An authenticator may choose to keep state, such as the private key, whether a credential is discoverable or not (see also public key credential source). A discoverable credential, however, always involves maintaining some state because it must be discoverable using only the RP ID and the user id (also known as the user handle) must always be returned.

All state that is kept for a discoverable credential MUST be stored client side—i.e., such that the authenticator working together with the client platform, if necessary, can satisfy requested authenticator operations.

An authenticator specifies whether it is capable of creating discoverable credentials via the rk option ID in the authenticatorGetInfo response. A discoverable credential will be created if, and only if, the rk option key of the options parameter of an authenticatorMakeCredential request is true.

If the authenticatorCredentialManagement command is supported by an authenticator then it can be used to manage discoverable credentials.

If a discoverable credential's state is deleted, e.g., by the authenticatorCredentialManagement command or overwritten by authenticatorMakeCredential, the associated credentialID MUST no longer yield a public key credential source, e.g., when processed by the authenticator’s equivalent of the Lookup Credential Source by Credential ID Algorithm including cases where the credential source is encoded within the credentialID. This means, for example, that any such deleted credentials whose credentialIDs may have been stored server-side and subsequently are provided in an allowList to authenticatorGetAssertion, will no longer be "located" in the latter’s Step 7 when the allowList is processed.

Note: Historically discoverable credentials have been called "resident keys", and this terminology can still be found in aspects of the protocol. (For example the name of the rk option key comes from the term “resident key”.) However, the word “resident” conflated the concepts of being discoverable and being statefully maintained by the authenticator, when it’s only the former that is externally observable and thus important.

6.2. authenticatorGetAssertion (0x02)

This method is used by a host to request cryptographic proof of user authentication as well as user consent to a given transaction, using a previously generated credential that is bound to the authenticator and relying party identifier. It takes the following input parameters, several of which correspond to those defined in the authenticatorGetAssertion operation section of the Web Authentication specification:

The following option keys are defined for use in authenticatorGetAssertion's options parameter. All option keys have boolean values.

Note: For brevity, individual option keys are often referred to as simply an "option", below.

Note: Platforms MUST NOT send the "rk" option key.

Note: For backwards compatibility with CTAP2.0 platforms, the authenticator MAY perform a built-in user verification method even if not requested to enhance its security offering. Thus, platforms SHOULD be prepared to receive a CTAP2_ERR_PUAT_REQUIRED error even if the platform did not include the "uv" option key, or did include it and set it to false. CTAP2.1 authenticators SHOULD use the authenticator always requires some form of user verification feature to signal this behaviour.

Note: The [WebAuthn] specification defines an abstract authenticatorGetAssertion operation, which corresponds to the operation described in this section. The parameters in the abstract [WebAuthn] authenticatorGetAssertion operation map to the above parameters as follows:

6.2.1. Platform Actions for authenticatorGetAssertion (non-normative)

To invoke authenticatorGetAssertion, the platform performs the following steps, in general. Here, we are assuming that the platform has already queried the authenticator for its particulars using the authenticatorGetInfo command, and has determined that the authenticator’s present characteristics are likely sufficient to be able to satisfy the request(s) the platform will send it. In other words, this is only a brief sketch of plausible platform behavior.

For example, if the authenticator is not protected by some form of user verification and user verification is required for the present usage scenario, e.g., the Relying Party set options.userVerification to "required" in the WebAuthn API, then the platform recovers in some fashion out of scope of these actions.

1. The platform marshals the necessary and appropriate input parameters given the present usage scenario, and additionally:

   1. If the authenticator is protected by some form of user verification or the Relying Party prefers enforcing user verification (e.g., by setting options.userVerification to "required", or "preferred" in the WebAuthn API):

      1. If the platform has already created a pinUvAuthParam parameter during this overall scenario, it uses that along with the other marshalled input parameters to invoke the authenticatorGetAssertion. Or, in some situations (e.g., with CTAP2 authenticators) the platform may invoke the authenticatorGetAssertion operation multiple times using the pinUvAuthParam parameter to "pre-flight" an "allow list" (i.e., to determine if any of the allow list’s credential IDs are already present on the authenticator), prior to invoking authenticatorGetAssertion to have this authenticator issue an assertion using the selected credential.

      2. Otherwise, the platform examines various option IDs in the authenticatorGetInfo response to determine its course of action:

         1. If the uv option ID is present and set to true:

            1. If the pinUvAuthToken option ID is present and true then plan to use getPinUvAuthTokenUsingUvWithPermissions to obtain a pinUvAuthToken, and let it be the selected operation. Go to Step 1.1.2.3.

            2. Else (implying the pinUvAuthToken option ID is set to false or absent) use the "uv" option key when invoking the authenticatorGetAssertion operation and terminate these steps. (Note that if the authenticator returns a 0x36 error code (CTAP2_ERR_PUAT_REQUIRED (aka CTAP2_ERR_PIN_REQUIRED in CTAP2.0)) then "fall back" and go to Step 1.1.2.2.2.1)

         2. Else (implying the uv option ID is present and set to false or absent):

            1. If the pinUvAuthToken option ID is present and true:

               1. To continue, ensure the clientPin option ID is present and true. Plan to use getPinUvAuthTokenUsingPinWithPermissions to obtain a pinUvAuthToken, and let it be the selected operation. Go to Step 1.1.2.3.

            2. Else (implying the pinUvAuthToken option ID is absent):

               1. To continue, ensure the clientPin option ID is present and true. Plan to use getPinToken to obtain a pinUvAuthToken, and let it be the selected operation.

         3. In preparation for obtaining pinUvAuthToken, the platform:

            1. Obtains a shared secret.

            2. Sets the pinUvAuthProtocol parameter to the value as selected when it obtained the shared secret.

         4. Then the platform obtains a pinUvAuthToken from the authenticator, with the ga permission using the selected operation. If successful, the platform creates the pinUvAuthParam parameter by calling authenticate(pinUvAuthToken, clientDataHash), and goes to Step 1.1.1 to use it.

   2. Otherwise, implying the authenticator is not presently protected by some form of user verification, or the Relying Party does not wish to require user verification (e.g., by setting options.userVerification to "discouraged" in the WebAuthn API), the platform invokes the authenticatorGetAssertion operation using the marshalled input parameters along with an absent "uv" option key.

6.2.2. authenticatorGetAssertion Algorithm

Upon receipt of a authenticatorGetAssertion request, the authenticator performs the following procedure:

1. If authenticator supports either pinUvAuthToken or clientPin features and the platform sends a zero length pinUvAuthParam:

   1. Request evidence of user interaction in an authenticator-specific way (e.g., flash the LED light).

   2. If the user declines permission, or the operation times out, then end the operation by returning CTAP2_ERR_OPERATION_DENIED.

   3. If evidence of user interaction is provided in this step then return either CTAP2_ERR_PIN_NOT_SET if PIN is not set or CTAP2_ERR_PIN_INVALID if PIN has been set.

   Note: This is done for backwards compatibility with CTAP2.0 platforms in the case where multiple authenticators are attached to the platform and the platform wants to enforce pinUvAuthToken semantics, but the user has to select which authenticator to get the pinUvAuthToken from. CTAP2.1 platforms SHOULD use § 6.9 authenticatorSelection (0x0B).

2. If the pinUvAuthParam parameter is present:

   1. If the pinUvAuthProtocol parameter’s value is not supported, return CTAP1_ERR_INVALID_PARAMETER error.

   2. If the pinUvAuthProtocol parameter is absent, return CTAP2_ERR_MISSING_PARAMETER error.

3. Create a new authenticatorGetAssertion response structure and initialize both its "uv" bit and "up" bit as false.
4. If the options parameter is present, process all option keys and values present in the parameter. Treat any option keys that are not understood as absent.

   Note: As this specification defines normative behaviours for the "rk", "up", and "uv" option keys, they MUST be understood by all authenticators.

   1. If the "uv" option is absent, let the "uv" option be treated as being present with the value false. (This is the default)

   2. If the pinUvAuthParam is present, let the "uv" option be treated as being present with the value false.

      Note: pinUvAuthParam and the "uv" option are processed as mutually exclusive with pinUvAuthParam taking precedence.

   3. If the "uv" option is present and true then:

      1. If the authenticator does not support a built-in user verification method end the operation by returning CTAP2_ERR_INVALID_OPTION.

      2. If the built-in user verification method has not yet been enabled, end the operation by returning CTAP2_ERR_INVALID_OPTION.

   4. If the "rk" option is present then:

      1. Return CTAP2_ERR_UNSUPPORTED_OPTION.

   5. If the "up" option is not present then:

      1. Let the "up" option be treated as being present with the value true. (This is the default)

5. If the alwaysUv option ID is present and true and the "up" option is present and true then:

   1. If the authenticator is not protected by some form of user verification:

      1. If the clientPin option ID is present and noMcGaPermissionsWithClientPin option ID is absent or false (clientPin is supported for the ga permission):

         1. End the operation by returning CTAP2_ERR_PUAT_REQUIRED.

      2. Else (clientPin is not supported):

         1. End the operation by returning CTAP2_ERR_OPERATION_DENIED.

   2. If the pinUvAuthParam is present then go to Step 6.

   3. If the "uv" option is true then go to Step 6.

   4. If the "uv" option is false and the authenticator supports a built-in user verification method, and the user verification method is enabled then:

      1. Let the "uv" option be treated as being present with the value true.

      2. Go To Step 6.

   5. If the clientPin option ID is present and noMcGaPermissionsWithClientPin option ID is absent or false, then:

      Note: This is to address the case of CTAP2.0 platforms not being aware of and ignoring the alwaysUv option ID.

      1. End the operation by returning CTAP2_ERR_PUAT_REQUIRED.

   6. Else (clientPin is not supported):

      1. End the operation by returning CTAP2_ERR_OPERATION_DENIED.

6. If authenticator is protected by some form of user verification, then:

   1. If pinUvAuthParam parameter is present (implying the "uv" option is treated as false, see Step 4):

      1. Call verify(pinUvAuthToken, clientDataHash pinUvAuthParam).

         1. If the verification returns error, return CTAP2_ERR_PIN_AUTH_INVALID error.

         2. If the verification returns success, set the "uv" bit to true in the response.

      2. Let userVerifiedFlagValue be the result of calling getUserVerifiedFlagValue().

      3. If userVerifiedFlagValue is false then end the operation by returning CTAP2_ERR_PIN_AUTH_INVALID.

      4. Verify that the pinUvAuthToken has the ga permission, if not, return CTAP2_ERR_PIN_AUTH_INVALID.

      5. If the pinUvAuthToken has a permissions RP ID associated:

         1. If the permissions RP ID does not match the rpId in this request, return CTAP2_ERR_PIN_AUTH_INVALID.

      6. If the pinUvAuthToken does not have a permissions RP ID associated:

         1. Associate the request’s rpId parameter value with the pinUvAuthToken as its permissions RP ID.

      7. Go to Step 7.

   2. If the "uv" option is present and set to true (implying the pinUvAuthParam parameter is not present, and that the authenticator supports an enabled built-in user verification method, see Step 4):

      Note: This step provides backwards compatibility for CTAP2.0 platforms.

      1. Let internalRetry be true.

      2. Let uvState be the result of calling performBuiltInUv(internalRetry)

      3. If uvState is error:

         1. If the error reason is a user action timeout, then return CTAP2_ERR_USER_ACTION_TIMEOUT.

         2. If the ClientPin option ID is true and the noMcGaPermissionsWithClientPin option ID is absent or false, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

         3. If the uvRetries counter is <= 0, return CTAP2_ERR_PIN_BLOCKED.

         4. Otherwise, end the operation by returning CTAP2_ERR_OPERATION_DENIED.

      4. If uvState is success:

         1. Set the "uv" bit to true in the response.

   Note: If Step 6 was skipped, then the authenticator is NOT protected by some form of user verification, and Step 3 has already ensured that the "uv" bit is false in the response.

7. Locate all credentials that are eligible for retrieval under the specified criteria:

   1. If the allowList parameter is present and is non-empty, locate all denoted credentials created by this authenticator and bound to the specified rpId.

   2. If an allowList is not present, locate all discoverable credentials that are created by this authenticator and bound to the specified rpId.

   3. Create an applicable credentials list populated with the located credentials.

   4. Iterate through the applicable credentials list, and if credential protection for a credential is marked as userVerificationRequired, and the "uv" bit is false in the response, remove that credential from the applicable credentials list.

   5. Iterate through the applicable credentials list, and if credential protection for a credential is marked as userVerificationOptionalWithCredentialIDList and there is no allowList passed by the client and the "uv" bit is false in the response, remove that credential from the applicable credentials list.

   6. If the applicable credentials list is empty, return CTAP2_ERR_NO_CREDENTIALS.

   7. Let numberOfCredentials be the number of applicable credentials found.

8. If evidence of user interaction was provided as part of Step 6.2 (i.e., by invoking performBuiltInUv()):

   Note: This step’s criteria implies that the "uv" option is present and set to true and the pinUvAuthParam parameter is not present. I.e., the pinUvAuthToken feature is not in use.

   1. Set the "up" bit to true in the response.

   2. Go to Step 10

9. If the "up" option is set to true or not present:

   1. If the pinUvAuthParam parameter is present then:

      1. Let userPresentFlagValue be the result of calling getUserPresentFlagValue().

      2. If userPresentFlagValue is false:

         Note: An authenticator may be configured to collect user presence whenever the "up" option is true by setting the default user present time limit to zero.

         1. Request evidence of user interaction in an authenticator-specific way (e.g., flash the LED light). If the authenticator has a display, show the rpId parameter value to the user, and request permission to create an assertion.

         2. If the user declines permission, or the operation times out, then end the operation by returning CTAP2_ERR_OPERATION_DENIED.

   2. Else (implying the pinUvAuthParam parameter is not present):

      1. If the "up" bit is false in the response:

         1. Request evidence of user interaction in an authenticator-specific way (e.g., flash the LED light). If the authenticator has a display, show the rpId parameter value to the user, and request permission to create an assertion.

         2. If the user declines permission, or the operation times out, then end the operation by returning CTAP2_ERR_OPERATION_DENIED.

   3. Set the "up" bit to true in the response.

   4. Call clearUserPresentFlag(), clearUserVerifiedFlag(), and clearPinUvAuthTokenPermissionsExceptLbw().

      Note: This consumes both the "user present state", sometimes referred to as the "cached UP", and the "user verified state", sometimes referred to as "cached UV". These functions are no-ops if there is not an in-use pinUvAuthToken.

10. If the extensions parameter is present:

    1. Process any extensions that this authenticator supports, ignoring any that it does not support.

    2. Authenticator extension outputs generated by the authenticator extension processing are returned in the authenticator data. The set of keys in the authenticator extension outputs map MUST be equal to, or a subset of, the keys of the authenticator extension inputs map.

    Note: Some extensions may produce different output depending on the state of the "uv" and/or "up" bits set in the response.

11. If the allowList parameter is present:

    1. Select any credential from the applicable credentials list.

    2. Delete the numberOfCredentials member.

    3. Go to Step 13.

12. If allowList is not present:

    1. If numberOfCredentials is one:

       1. Select that credential.

    2. If numberOfCredentials is more than one:

       1. Order the credentials in the applicable credentials list by the time when they were created in reverse order. (I.e. the first credential is the most recently created.)

       2. If the authenticator does not have a display, or the authenticator does have a display and the "uv" and "up" options are false:

          1. Remember the authenticatorGetAssertion parameters.

          2. Create a credential counter (credentialCounter) and set it to 1. This counter signifies the next credential to be returned by the authenticator, assuming zero-based indexing.

          3. Start a timer. This is used during authenticatorGetNextAssertion command. This step is OPTIONAL if transport is done over NFC.

          4. Select the first credential.

       3. If authenticator has a display and at least one of the "uv" and "up" options is true:

          1. Display all the credentials in the applicable credentials list to the user, using their friendly name along with other stored account information.

          2. Also, display the rpId of the requester (specified in the request) and ask the user to select a credential.

          3. If the user declines to select a credential or takes too long (as determined by the authenticator), terminate this procedure and return the CTAP2_ERR_OPERATION_DENIED error.

          4. Update the response to set the userSelected member to true and to delete the numberOfCredentials member.

          5. Select the credential indicated by the user.

    3. Update the response to include the selected credential’s publicKeyCredentialUserEntity information. User identifiable information (name, DisplayName, icon) inside the publicKeyCredentialUserEntity MUST NOT be returned if user verification is not done by the authenticator.

13. Sign the clientDataHash along with authData with the selected credential, using the structure specified in [WebAuthn].

On success, the authenticator returns the following authenticatorGetAssertion response structure:

Within the "flags bits" of the authenticator data structure returned, the authenticator will report what was actually done within the authenticator boundary. The meanings of the combinations of the User Present (UP) and User Verified (UV) bit flags are as follows:

6.3. authenticatorGetNextAssertion (0x08)

The client calls this method when the authenticatorGetAssertion response contains the numberOfCredentials member and the number of credentials exceeds 1. This method is used to obtain the next per-credential signature for a given authenticatorGetAssertion request. It takes no arguments.

Note: this is a stateful command and the specified implementation accommodations apply to it.

When this command is received, the authenticator performs the following procedure:

1. If authenticator does not remember any authenticatorGetAssertion parameters, return CTAP2_ERR_NOT_ALLOWED.

2. If the credentialCounter is equal to or greater than numberOfCredentials, return CTAP2_ERR_NOT_ALLOWED.

3. If timer since the last call to authenticatorGetAssertion/authenticatorGetNextAssertion is greater than 30 seconds, discard the current authenticatorGetAssertion state and return CTAP2_ERR_NOT_ALLOWED. This step is OPTIONAL if transport is done over NFC.

   Note: the section on stateful commands makes this timeout OPTIONAL for any stateful command. This section supersedes that and makes it mandatory in this instance, except over NFC, where maintaining timers for that length of time can be problematic.

4. Select the credential indexed by credentialCounter. (I.e. credentials[n] assuming a zero-based array.)

5. Update the response to include the selected credential’s publicKeyCredentialUserEntity information. User identifiable information (name, DisplayName, icon) inside the publicKeyCredentialUserEntity MUST NOT be returned if user verification was not done by the authenticator in the original authenticatorGetAssertion call.

6. Sign the clientDataHash along with authData with the selected credential, using the structure specified in [WebAuthn].

7. Reset the timer. This step is OPTIONAL if transport is done over NFC.

8. Increment credentialCounter.

On success, the authenticator returns the same structure as returned by the authenticatorGetAssertion method. The numberOfCredentials member is omitted.

6.3.1. Client Logic

If client receives numberOfCredentials member value exceeding 1 in response to the authenticatorGetAssertion call:

1. Call authenticatorGetNextAssertion numberOfCredentials minus 1 times.

   • Make sure ‘rp’ member matches the current request.

   • Remember the ‘response’ member.

   • Add credential user information to the ‘credentialInfo’ list.

2. Draw a UX that displays credentialInfo list.

3. Let user select which credential to use.

4. Return the value of the ‘response’ member associated with the user choice.

5. Discard all other responses.

6.4. authenticatorGetInfo (0x04)

Using this method, platforms can request that the authenticator report a list of its supported protocol versions and extensions, its AAGUID, and other aspects of its overall capabilities. Platforms should use this information to tailor their command parameters choices.

Note: The values of various authenticatorGetInfo response structure members and option IDs may change over time depending upon the commands the platform sends to the authenticator.

This method takes no inputs.

On success, the authenticator returns the following authenticatorGetInfo response structure:

All options are in the form key-value pairs with string IDs and boolean values. When an option ID is not present, the default is applied per table below. The following table lists all defined option IDs as of CTAP version "FIDO_2_1":

6.5. authenticatorClientPIN (0x06)

This command exists so that plaintext PINs are not sent to the authenticator. Instead, a PIN/UV auth protocol (aka pinUvAuthProtocol) ensures that PINs are encrypted when sent to an authenticator and are exchanged for a pinUvAuthToken that serves to authenticate subsequent commands. Additionally, authenticators supporting built-in user verification methods can provide a pinUvAuthToken upon user verification.

The pinUvAuthToken is a randomly-generated, opaque bytestring that is large enough to be effectively unguessable. See § 6.5.2.1 pinUvAuthToken State for details.

Two PIN/UV auth protocols are defined herein:

• § 6.5.6 PIN/UV Auth Protocol One

• § 6.5.7 PIN/UV Auth Protocol Two

Each PIN/UV auth protocol:

• maintains its own pinUvAuthToken so that no unexpected, cross-protocol interactions occur, and

• is a concrete instantiation of § 6.5.4 PIN/UV Auth Protocol Abstract Definition.

Note: The platform MAY flexibly manage the lifetime of its copy of the pinUvAuthToken based on the usage scenario. However, it SHOULD erase its copy of the pinUvAuthToken as soon as possible when it is no longer needed. The authenticator can also expire the pinUvAuthToken based on certain conditions such as changing a PIN, authenticator timeouts, when returning CTAP2_ERR_OPERATION_DENIED or CTAP2_ERR_CREDENTIAL_EXCLUDED errors, the platform system waking up from a suspend state, the platform sending commands with no optional pinUvAuthParam, etc. If the pinUvAuthToken has expired, the authenticator will return CTAP2_ERR_PIN_AUTH_INVALID and the platform can act on the error accordingly, e.g., by getting a new pinUvAuthToken from the authenticator.

Note: The authenticator is only required to manage one pinUvAuthToken, though it MAY manage one per transport interface in the case that it supports multiple simultaneous transport protocols.

6.5.1. PIN Composition Requirements

Platforms MUST enforce the following, baseline, requirements on PINs used with this specification:

• Minimum PIN Length: 4 Unicode characters

• Maximum PIN Length: UTF-8 representation MUST NOT exceed 63 bytes

• PIN are in Unicode normalization form C.

• PIN MUST NOT end in a 0x00 byte

Authenticators MUST enforce the following, baseline, requirements on PINs:

• Minimum PIN Length: 4 code points.

  Note: Authenticators can enforce a greater minimum length.

• Maximum PIN Length: 63 bytes

• PIN storage on the device has to provide the same, or better, security assurances as provided for private keys.

6.5.2. PIN/UV Auth Protocol Global State

Authenticators keep the following global state, independent of any specific PIN/UV auth protocol:

6.5.2.1. pinUvAuthToken State

A pinUvAuthToken has the following associated state variables. When initially generated via resetPinUvAuthToken(), the pinUvAuthToken's state variables are set to the initial values given below. The state variables values are managed via the interface given in § 6.5.3.2 pinUvAuthToken State Maintenance Functions.

Note: The pinUvAuthToken-issuing operations call beginUsingPinUvAuthToken() to update the pinUvAuthToken's state variables' values prior to issuing the pinUvAuthToken to the platform. For example, they will use the latter function to set both or either the userVerified flag and/or the userPresent flag to true, and start the usage timer.

A pinUvAuthToken is associated with these state variables:

• A permissions RP ID, initially null.

• A permissions set whose possible values are those of pinUvAuthToken permissions. It is initially empty.

• A usage timer, initially not running.

  Note: Once running, the timer is observed by pinUvAuthTokenUsageTimerObserver().

• An in use flag, initially set to false, meaning that the pinUvAuthToken is not in use. When the in use flag is set to true, the pinUvAuthToken is said to be in use.

• A initial usage time limit, initially not set. beginUsingPinUvAuthToken() sets this value according to the transport the platform is using to communicate with it. The platform MUST invoke an authenticator operation using the pinUvAuthToken within this time limit for the pinUvAuthToken to remain valid for the full max usage time period. The default maximum per-transport initial usage time limit values are:

  • usb: 30 seconds

  • nfc: 19.8 seconds (16 bit counter with 3311hz clock: max time before overflow)

  • ble: 30 seconds

  • internal: 30 seconds

  Authenticators MAY use other values that are less than the default maximum values.

  Authenticators MAY implement a rolling timer, initialized to the per-transport initial usage time limit, where the pinUvAuthToken and its state variables remain valid as long as the platform again uses the pinUvAuthToken in an operation before the rolling timer expires. If so, the rolling timer is again initialized to the initial usage time limit. This continues until the max usage time period expires. See pinUvAuthTokenUsageTimerObserver().

  Note: Authenticators should utilize the rolling timer approach judiciously, e.g., because some features, such as authenticatorBioEnrollment and authenticatorCredentialManagement, may need to accommodate infrequent user interactions. Thus the rolling timer approach may be most applicable to authenticatorMakeCredential and authenticatorGetAssertion operations.

• A user present time limit defining the length of time the user is considered "present", as represented by the userPresent flag, after user presence is collected. The user present time limit defaults to the same default maximum per-transport values as the initial usage time limit, although authenticators MAY use other values that are less than the default maximum values, including zero.

  Note: The user present time limit value of zero accommodates the case where an authenticator does not wish to support maintaining "user present" state (i.e., "cached user presence").

• A max usage time period value, which SHOULD default to a maximum of 10 minutes (600 seconds), though authenticators MAY use other values less than the latter default, possibly depending upon the use case, e.g., which transport is in use.

• A userVerified flag, initially false.

• A userPresent flag, initially false.

6.5.2.2. PIN-Entry and User Verification Retries Counters

1. pinRetries counter:

   • pinRetries counter represents the number of attempts left before PIN is disabled.

   • Authenticators MUST allow no more than 8 retries but MAY set a lower maximum.

   • Each correct PIN entry resets the pinRetries and the uvRetries counters back to their maximum values unless the PIN is already disabled.

   • Each incorrect PIN entry decrements the pinRetries by 1.

   • Once the pinRetries counter reaches 0, both ClientPin as well as built-in user verification are disabled and can only be enabled if authenticator is reset.

2. uvRetries counter:

   • The uvRetries counter represents the number of user verification attempts left before built-in user verification is disabled.

   • maxUvRetries is a global value statically configured into an authenticator; it is the maximum number of retries that a user can experience. uvRetries is initialized to this value. Its value MUST be in the range of 1 to 25, inclusive.

     Note: This value is determined by the authenticator vendor based on the desired FIDO security certification level. This limit protects against brute force attacks. It is the total number of attempts allowed for all built-in user verification methods.

   • maxUvAttemptsForInternalRetries is a global value configured into an authenticator. It is the maximum number of times the authenticator will retry internally when internalRetry is true as part of the performBuiltInUv() algorithm. This is used for older platforms when the "uv" parameter is set as true OR when an authenticator vendor wants the platform to try calling it only once as indicated by the preferredPlatformUvAttempts value. If preferredPlatformUvAttempts is 1, maxUvAttemptsForInternalRetries value MUST be in range of 1 to maxUvRetries inclusive. If preferredPlatformUvAttempts is NOT 1, maxUvAttemptsForInternalRetries value MUST be in range of 1 to 5 inclusive.

   • Once the uvRetries counter reaches 0, built-in user verification MUST be disabled and can only be re-enabled if the authenticator is reset or the correct clientPIN is provided via the authenticatorClientPIN's getPinUvAuthTokenUsingPinWithPermissions or getPinToken subCommands.

   • internalRetry is a authenticator-internal boolean parameter. It defaults to false. It is explicitly set to true if the authenticator intends to perform multiple internal uv retries before returning an error to the platform.

6.5.3. Utility Functions

These utility functions are independent of the particular PIN/UV auth protocol in use.

6.5.3.1. Perform Built-in User Verification Algorithm

performBuiltInUv(internalRetry) → success | error:

1. If internalRetry is true then let attemptsBeforeReturning be set to maxUvAttemptsForInternalRetries.

2. Else let attemptsBeforeReturning be set to 1.

3. If clientPIN is true and pinRetries <= 0 then let the uvRetries counter be set to 0, return error.

4. If uvRetries <= 0 then return error.

5. Decrement the uvRetries counter by 1.

   Note: It is best practice to decrement the counter before performing built-in user verification. This prevents some hardware attacks that could provide an attacker with a unlimited number of presentation attempts. If the sample input times out the authenticator may re-increment the uvRetries counter to its previous value, if no matching is preformed by the authenticator. Some platforms will send authenticatorGetAssertion requests in parallel to multiple authenticators causing the ones not touched by the user to decrement uvRetries to 0 over time unless the uvRetries is re-incremented to the previous value after an input time out.

6. Decrement attemptsBeforeReturning by 1.

7. Perform built-in user verification.

8. If a user action timeout occurs, return error.

9. If built-in user verification succeeds then set the uvRetries counter to maxUvRetries and return success.

10. Else (built-in user verification failed), if attemptsBeforeReturning > 0, go to Step 4.

11. Otherwise, return error.

6.5.3.2. pinUvAuthToken State Maintenance Functions

beginUsingPinUvAuthToken(userIsPresent)

This function prepares the pinUvAuthToken for use by the platform, which has invoked one of the pinUvAuthToken-issuing operations, by setting particular pinUvAuthToken state variables to given use-case-specific values. See also § 6.5.5.7 Operations to Obtain a pinUvAuthToken.

1. Set the userPresent flag to the value of userIsPresent.

2. Set the userVerified flag to true.

3. Set the initial usage time limit to a transport-specific value, as described in § 6.5.2.1 pinUvAuthToken State.

4. Start the pinUvAuthToken usage timer, set the in use flag to true, and assign pinUvAuthTokenUsageTimerObserver() to observe the usage timer. The pinUvAuthToken is now in use.

pinUvAuthTokenUsageTimerObserver()

This function observes the pinUvAuthToken usage timer and takes appropriate action upon the specified conditions:

1. If the usage timer is not running, return.

2. While the overall usage timer has not reached the max usage time period, perform the following substeps:

   1. If the current user present time limit is reached, call clearUserPresentFlag().

   2. If the initial usage time limit is reached without the platform using the pinUvAuthToken in an authenticator operation then call stopUsingPinUvAuthToken(), and terminate these steps.

   3. If the authenticator does not utilize a rolling timer then continue.

   4. If the authenticator utilizes a rolling timer then:

      1. If the platform uses the pinUvAuthToken in an authenticator operation before the rolling timer expires then:

         1. Set the rolling timer to the applicable initial usage time limit and continue.

      2. Otherwise (implying the rolling timer expires) call stopUsingPinUvAuthToken(), and terminate these steps.

3. Call stopUsingPinUvAuthToken(), and terminate these steps.

getUserPresentFlagValue() → userPresentFlagValue

1. If the pinUvAuthToken is in use then set the userPresentFlagValue to the current value of the pinUvAuthToken's userPresent flag.

2. Otherwise (implying a pinUvAuthToken exists and is not in use, or does not exist), set userPresentFlagValue to false.

   Note: The pinUvAuthToken may not exist because the pinUvAuthToken feature is not in use or is not supported.

3. Return userPresentFlagValue.

getUserVerifiedFlagValue() → userVerifiedFlagValue

1. If the pinUvAuthToken is in use then set the userVerifiedFlagValue to the current value of the pinUvAuthToken's userVerified flag.

2. Otherwise (implying a pinUvAuthToken exists and is not in use, or does not exist), set userVerifiedFlagValue to false.

   Note: The pinUvAuthToken may not exist because the pinUvAuthToken feature is not in use or is not supported.

3. Return userVerifiedFlagValue.

clearUserPresentFlag()

1. If the pinUvAuthToken is in use then set the pinUvAuthToken's userPresent flag to false, otherwise do nothing.

clearUserVerifiedFlag()

1. If the pinUvAuthToken is in use then set the pinUvAuthToken's userVerified flag to false, otherwise do nothing.

clearPinUvAuthTokenPermissionsExceptLbw()

1. If the pinUvAuthToken is in use then clear all of the pinUvAuthToken's permissions, except for lbw, otherwise do nothing.

stopUsingPinUvAuthToken()

1. Set all of the pinUvAuthToken's state variables to their initial values as given in § 6.5.2.1 pinUvAuthToken State.

6.5.4. PIN/UV Auth Protocol Abstract Definition

A specific PIN/UV auth protocol defines an implementation of two interfaces to cryptographic services: one for the authenticator, and one for the platform.

The authenticator interface is:

initialize()

This process is run by the authenticator at power-on.

regenerate()

Generates a fresh public key.

resetPinUvAuthToken()

Generates a fresh pinUvAuthToken.

getPublicKey() → coseKey

Returns the authenticator’s public key as a COSE_Key structure.

decapsulate(peerCoseKey) → sharedSecret | error

Processes the output of encapsulate from the peer and produces a shared secret, known to both platform and authenticator.

decrypt(sharedSecret, ciphertext) → plaintext | error

Decrypts a ciphertext, using sharedSecret as a key, and returns the plaintext.

verify(key, message, signature) → success | error

Verifies that the signature is a valid MAC for the given message. If the key parameter value is the current pinUvAuthToken, it also checks whether the pinUvAuthToken is in use or not.

The platform interface is:

initialize()

This is run by the platform when starting a series of transactions with a specific authenticator.

encapsulate(peerCoseKey) → (coseKey, sharedSecret) | error

Generates an encapsulation for the authenticator’s public key and returns the message to transmit and the shared secret.

encrypt(key, demPlaintext) → ciphertext

Encrypts a plaintext to produce a ciphertext, which may be longer than the plaintext. The plaintext is restricted to being a multiple of the AES block size (16 bytes) in length.

decrypt(key, ciphertext) → plaintext | error

Decrypts a ciphertext and returns the plaintext.

authenticate(key, message) → signature

Computes a MAC of the given message.

(In the pseudocode function definitions, above, a function takes a number of arguments that are given in parentheses and yields a result that is one of the types separated by a bar (‘|’). If a function doesn’t yield any meaningful result then it implicitly yields a value of the unit type, written “success”, which carries no information.)

The following PIN/UV auth protocols, specified herein, define concrete instantiations of the above interfaces:

• § 6.5.6 PIN/UV Auth Protocol One

• § 6.5.7 PIN/UV Auth Protocol Two

6.5.5. authenticatorClientPIN (0x06) Command Definition

This authenticatorClientPIN command allows a platform to use a PIN/UV auth protocol to perform a number of actions:

• Performing key agreement to obtain the shared secret

• Setting a PIN

• Changing a PIN

• Obtaining the pinUvAuthToken

The command takes the following input parameters:

The authenticatorClientPIN subCommands are:

On success, authenticator returns the following structure in its response:

6.5.5.1. Authenticator Configuration Operations Upon Power Up

At power-up, the authenticator calls initialize for each pinUvAuthProtocol that it supports.

6.5.5.2. Platform getting PIN retries from Authenticator

PIN retries count is the number of PIN attempts remaining before PIN is disabled on the device. When the PIN retries count nears zero, the platform can optionally warn the user to be careful while entering the PIN.

Platform performs the following operations to get pinRetries:

1. Platform sends authenticatorClientPIN command with following parameters to the authenticator:

   1. subCommand: getPINRetries(0x01)

2. Authenticator responds back with pinRetries and, optionally, powerCycleState.

6.5.5.3. Platform getting UV Retries from Authenticator

UV retries count is the number of built-in UV attempts remaining before built-in UV is disabled on the device. When the UV retries count nears zero, the platform can optionally warn the user to be careful while performing user verification.

Platform performs the following operations to get uvRetries:

1. Platform sends authenticatorClientPIN command with following parameters to the authenticator:

   1. subCommand: getUVRetries(0x07)

2. Authenticator responds back with uvRetries.

6.5.5.4. Obtaining the Shared Secret

Platforms obtain a shared secret for each transaction. The authenticator does not have to keep a list of sharedSecrets for all active sessions. If there are subsequent authenticatorClientPIN transactions, a new sharedSecret is generated every time.

Platform performs the following operations to arrive at the sharedSecret:

1. The platform selects a mutually supported PIN/UV auth protocol by considering the list of protocols supported by the authenticator, as reported in the pinUvAuthProtocols member of the authenticatorGetInfo response. If there are multiple mutually supported protocols, and the platform has no preference, it SHOULD select the one listed first in pinUvAuthProtocols.

2. The platform sends authenticatorClientPIN command with following parameters to the authenticator:

   1. pinUvAuthProtocol: as chosen above

   2. subCommand: getKeyAgreement(0x02)

3. If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

4. If the authenticator does not support the selected pinUvAuthProtocol, it returns CTAP1_ERR_INVALID_PARAMETER.

5. Otherwise the authenticator sends a response with the following parameters:

   1. keyAgreement: the result of calling getPublicKey for the selected pinUvAuthProtocol.

6. The platform calls encapsulate with the public key that the authenticator returned in order to generate the platform key-agreement key and the shared secret.

6.5.5.5. Setting a New PIN

The following operations are performed to set up a new PIN:

1. The platform collects the new PIN ( newPinUnicode ) from the user as Unicode characters in Normalization Form C.

2. Let platformCollectedPinLengthInCodePoints be the length in code points of newPinUnicode after normalization is applied.

   1. If the minPINLength member of the authenticatorGetInfo response is absent, then let platformMinPINLengthInCodePoints be 4. (The default minimum value)

   2. Else let platformMinPINLengthInCodePoints be the value of the minPINLength member of the authenticatorGetInfo response.

   3. If platformCollectedPinLengthInCodePoints is less than platformMinPINLengthInCodePoints then the platform SHOULD display a "PIN too short" error message to the user.

   4. Let "newPin" be the UTF-8 representation of newPinUnicode.

   5. If the byte length of "newPin" is greater than the max UTF-8 representation limit of 63 bytes, then the platform SHOULD display a "PIN too long" error message to the user.

   Note: The platform collects the PIN before obtaining the shared secret. This prevents the shared secret from being reset if a NFC transport is used and the user removes the authenticator from the NFC reader’s field while typing the PIN.

3. The Platform obtains the shared secret from the authenticator.

4. Platform sends authenticatorClientPIN command with following parameters to the authenticator:

   1. pinUvAuthProtocol: as selected when getting the shared secret.

   2. subCommand: setPIN(0x03).

   3. keyAgreement: the platform key-agreement key.

   4. newPinEnc: the result of calling encrypt(shared secret, paddedPin) where paddedPin is newPin padded on the right with 0x00 bytes to make it 64 bytes long. (Since the maximum length of newPin is 63 bytes, there is always at least one byte of padding.)

   5. pinUvAuthParam: the result of calling authenticate(shared secret, newPinEnc).

5. Authenticator performs following operations upon receiving the request:

   1. If the authenticator does not receive mandatory parameters for this command, it returns CTAP2_ERR_MISSING_PARAMETER error.

   2. If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

   3. If a PIN has already been set, authenticator returns CTAP2_ERR_PIN_AUTH_INVALID error.

   4. The authenticator calls decapsulate on the provided platform key-agreement key to obtain the shared secret. If an error results, it returns CTAP1_ERR_INVALID_PARAMETER.

   5. The authenticator calls verify(shared secret, newPinEnc, pinUvAuthParam)

      1. If an error results, it returns CTAP2_ERR_PIN_AUTH_INVALID.

   6. The authenticator calls decrypt(shared secret, newPinEnc) to produce paddedNewPin. If an error results, it returns CTAP2_ERR_PIN_AUTH_INVALID.

   7. If paddedNewPin is NOT 64 bytes long, it returns CTAP1_ERR_INVALID_PARAMETER.

   8. The authenticator drops all trailing 0x00 bytes from paddedNewPin to produce newPin.

   9. The authenticator checks the length of newPin against the current minimum PIN length, returning CTAP2_ERR_PIN_POLICY_VIOLATION if it is too short.

   10. An authenticator MAY impose arbitrary, additional constraints on PINs. If newPin fails to satisfy such additional constraints, the authenticator returns CTAP2_ERR_PIN_POLICY_VIOLATION.

   11. Authenticator remembers newPin length internally as PINCodePointLength.

   12. Authenticator stores LEFT(SHA-256(newPin), 16) internally as CurrentStoredPIN, sets the pinRetries counter to maximum count, and returns CTAP2_OK.

6.5.5.6. Changing existing PIN

The following operations are performed to change an existing PIN:

1. The Platform collects the current PIN ( curPinUnicode ) and new PIN ( newPinUnicode ) from the user as Unicode characters in Normalization Form C.

2. Let platformCollectedNewPinLengthInCodePoints be the length in code points of newPinUnicode after applying normalization.

   1. If the minPINLength member of the authenticatorGetInfo response is absent, then let platformMinPINLengthInCodePoints be 4. (The default minimum value)

   2. Else let platformMinPINLengthInCodePoints be the value of the minPINLength member of the authenticatorGetInfo response.

   3. If platformCollectedNewPinLengthInCodePoints is less than platformMinPINLengthInCodePoints then the platform SHOULD display a "PIN too short" error message to the user.

   4. Let "newPin" be the UTF-8 representation of newPinUnicode.

      1. If the byte length of "newPin" is greater than the max UTF-8 representation limit of 63 bytes, then the platform SHOULD display a "New PIN too long" error message to the user.

   5. Let "curPin" be the UTF-8 representation of curPinUnicode.

      1. If the byte length of "curPin" is greater than the max UTF-8 representation limit of 63 bytes, then the platform SHOULD display a "Current PIN too long" error message to the user.

   Note: The platform collects the PIN before obtaining the shared secret. This prevents the shared secret from being reset if a NFC transport is used and the user removes the authenticator from the NFC reader’s field while typing the PIN.

3. Platform obtains the shared secret from the authenticator.

4. Platform sends authenticatorClientPIN command. with following parameters to the authenticator:

   1. pinUvAuthProtocol: as selected when getting the shared secret.

   2. subCommand: changePIN(0x04).

   3. keyAgreement: the platform key-agreement key.

   4. pinHashEnc: The result of calling encrypt(shared secret, LEFT(SHA-256(curPin), 16)).

   5. newPinEnc: the result of calling encrypt(shared secret, paddedPin) where paddedPin is newPin padded on the right with 0x00 bytes to make it 64 bytes long. (Since the maximum length of newPin is 63 bytes, there is always at least one byte of padding.)

   6. pinUvAuthParam: the result of calling authenticate(shared secret, newPinEnc || pinHashEnc).

5. Authenticator performs following operations upon receiving the request:

   1. If the authenticator does not receive mandatory parameters for this command, it returns CTAP2_ERR_MISSING_PARAMETER error.

   2. If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

   3. If the pinRetries counter is 0, return CTAP2_ERR_PIN_BLOCKED error.

   4. The authenticator calls decapsulate on the provided platform key-agreement key to obtain the shared secret. If an error results, it returns CTAP1_ERR_INVALID_PARAMETER.

   5. The authenticator calls verify(shared secret, newPinEnc || pinHashEnc, pinUvAuthParam)

      1. If an error results, it returns CTAP2_ERR_PIN_AUTH_INVALID.

   6. Authenticator decrements the pinRetries counter by 1.

   7. Authenticator decrypts pinHashEnc using decrypt(shared secret, pinHashEnc) and verifies against its internal stored LEFT(SHA-256(curPin), 16).

      1. If an error results, or a mismatch is detected, the authenticator performs the following operations:

         1. Calls regenerate for the selected pinUvAuthProtocol.

         2. Authenticator returns errors according to following conditions:

            1. If the pinRetries counter is 0, return CTAP2_ERR_PIN_BLOCKED error.

            2. If the authenticator sees 3 consecutive mismatches, it returns CTAP2_ERR_PIN_AUTH_BLOCKED, indicating that power cycling is needed for further operations. This is done so that malware running on the platform should not be able to block the device without user interaction.

            3. Else return CTAP2_ERR_PIN_INVALID error.

   8. Authenticator sets the pinRetries counter to maximum value.

   9. The authenticator calls decrypt(shared secret, newPinEnc) to produce paddedNewPin. If an error results, it returns CTAP2_ERR_PIN_AUTH_INVALID.

   10. If paddedNewPin is NOT 64 bytes long, it returns CTAP1_ERR_INVALID_PARAMETER.

   11. The authenticator drops all trailing 0x00 bytes from paddedNewPin to produce newPin.

   12. The authenticator checks the length of newPin against the current minimum PIN length, returning CTAP2_ERR_PIN_POLICY_VIOLATION if it is too short.

   13. If the forcePINChange member of the authenticatorGetInfo response is true and LEFT(SHA-256(newPin), 16) is equal to its internal stored LEFT(SHA-256(curPin), 16) then authenticator returns CTAP2_ERR_PIN_POLICY_VIOLATION.

   14. An authenticator MAY impose arbitrary, additional constraints on PINs. If newPin fails to satisfy such additional constraints, the authenticator returns CTAP2_ERR_PIN_POLICY_VIOLATION.

   15. Authenticator remembers newPin length internally as PINCodePointLength.

   16. Authenticator sets the value of the forcePINChange member of the authenticatorGetInfo response to false,

   17. Authenticator stores LEFT(SHA-256(newPin), 16) internally as the new value of CurrentStoredPIN.

   18. Authenticator sets the pinRetries counter to maximum count.

   19. Authenticator calls resetPinUvAuthToken() for all pinUvAuthProtocols supported by this authenticator. (I.e. all existing pinUvAuthTokens are invalidated.)

   20. Authenticator returns CTAP2_OK.

6.5.5.7. Operations to Obtain a pinUvAuthToken

Invoking one of the below operations only has to be performed once for the lifetime of the pinUvAuthToken. Obtaining a pinUvAuthToken once allows high security without any additional roundtrips each time a subsequent authenticator operation is invoked (except for the first key-agreement phase) and its overhead is minimal.

To obtain a pinUvAuthToken, the platform SHOULD first try using getPinUvAuthTokenUsingUvWithPermissions. If that fails, try using getPinUvAuthTokenUsingPinWithPermissions. Once the platform obtains a pinUvAuthToken, it can be used in subsequent authenticator operations for the length of its max usage time period (see § 6.5.2.1 pinUvAuthToken State), thereby avoiding asking the user for verification for each authenticator operation.

When obtaining a pinUvAuthToken, the platform requests permissions appropriate for the operations it intends to perform. Consequently, the pinUvAuthToken can only be used for those operations. Some permissions require the presence of the rpId parameter, known as a permissions RP ID. See also § 6.5.2.1 pinUvAuthToken State.

The following pinUvAuthToken permissions are defined:

When a pinUvAuthToken is used with an operation that tests user presence, it is updated to remove all permissions except lbw. If lbw was not originally requested then the pinUvAuthToken becomes permission-less and cannot be used for future operations. However, the platform can fetch a fresh pinUvAuthToken in order to perform any future operations.

If authenticatorClientPIN's getPinToken subcommand is invoked, default permissions of mc and ga (value 0x03) are granted for the returned pinUvAuthToken. Other pinUvAuthToken permissions can only be acquired by providing the permissions parameter to the getPinUvAuthTokenUsingPinWithPermissions (0x09) or getPinUvAuthTokenUsingUvWithPermissions (0x06) subcommands.

Following operations are performed to get pinUvAuthToken:

6.5.5.7.1. Getting pinUvAuthToken using getPinToken (superseded)

• Platform collects PIN from the user.

  Note: The platform collects the PIN before obtaining the shared secret. This prevents the shared secret from being reset if a NFC transport is used and the user removes the authenticator from the NFC reader’s field while typing the PIN.

• Platform obtains the shared secret from the authenticator.

• Platform sends authenticatorClientPIN command. with following parameters to the authenticator:

  • pinUvAuthProtocol: as selected when getting the shared secret.

  • subCommand: getPinToken (0x05).

  • keyAgreement: the platform key-agreement key.

  • pinHashEnc: the result of calling encrypt(shared secret, LEFT(SHA-256(PIN), 16)).

• Authenticator performs following operations upon receiving the request:

  • If the authenticator does not receive mandatory parameters for this command, it returns CTAP2_ERR_MISSING_PARAMETER error.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • If authenticatorClientPIN's permissions parameter is present in the getPinToken (0x05) subcommand, return CTAP1_ERR_INVALID_PARAMETER.

  • If authenticatorClientPIN's rpId parameter is present in the getPinToken (0x05) subcommand, return CTAP1_ERR_INVALID_PARAMETER.

  • If the pinRetries counter is 0, return CTAP2_ERR_PIN_BLOCKED error.

  • The authenticator calls decapsulate on the provided platform key-agreement key to obtain the shared secret. If an error results, it returns CTAP1_ERR_INVALID_PARAMETER.

  • If the authenticator has a display, request user consent for the default permissions. If this is not approved, return CTAP2_ERR_OPERATION_DENIED.

  • Authenticator decrements the pinRetries counter by 1.

  • Authenticator decrypts pinHashEnc using decrypt and verifies against its internally stored CurrentStoredPIN.

    • If an error results, or a mismatch is detected, the authenticator performs the following operations:

      • Calls regenerate for the selected pinUvAuthProtocol.

      • Authenticator returns errors according to following conditions:

        • If the pinRetries counter is 0, return CTAP2_ERR_PIN_BLOCKED error.

        • If the authenticator sees 3 consecutive mismatches, it returns CTAP2_ERR_PIN_AUTH_BLOCKED, indicating that power cycling is needed for further operations. This is done so that malware running on the platform should not be able to block the device without user interaction.

        • Else return CTAP2_ERR_PIN_INVALID error.

  • Authenticator sets the pinRetries counter to maximum value.

  • If the value of the forcePINChange member of the authenticatorGetInfo response is true, authenticator returns CTAP2_ERR_PIN_INVALID error.

    Note: The above error value is for backwards compatibility with CTAP2.0 platforms where the authenticator implements the forcePINChange feature as part of the setMinPINLength command. A pinUvAuthToken MUST NOT be returned if PINCodePointLength is less than current minimum PIN length. This is intended to force a user to change their PIN to one that conforms to the current authenticator policy. A CTAP2.1 platform will check the forcePINChange member of the authenticatorGetInfo response, and not invoke this command without forcing the user to change PIN first.

  • Create a new pinUvAuthToken by calling resetPinUvAuthToken() for all pinUvAuthProtocols supported by this authenticator. (I.e. all existing pinUvAuthTokens are invalidated.)

  • Call beginUsingPinUvAuthToken(userIsPresent: false).

  • If the noMcGaPermissionsWithClientPin option ID is present and set to false, or absent, then assign the pinUvAuthToken the default permissions.

    Note: If noMcGaPermissionsWithClientPin option ID is true, default permissions of mc and ga are not given, but the token is still used by older CTAP 2.0 platforms for userVerificationMgmtPreview and credentialMgmtPreview commands.

  • The authenticator returns the encrypted pinUvAuthToken for the specified pinUvAuthProtocol, i.e. encrypt(shared secret, pinUvAuthToken).

6.5.5.7.2. Getting pinUvAuthToken using getPinUvAuthTokenUsingPinWithPermissions (ClientPIN)

This subCommand MUST be implemented if the authenticator includes both clientPin and pinUvAuthToken Option IDs set to true in the authenticatorGetInfo response.

1. Platform collects PIN from the user.

   Note: The platform collects the PIN before obtaining the shared secret. This prevents the shared secret from being reset if a NFC transport is used and the user removes the authenticator from the NFC reader’s field while typing the PIN.

2. Platform obtains the shared secret from the authenticator.

3. Platform sends authenticatorClientPIN command. with following parameters to the authenticator:

   1. pinUvAuthProtocol: as selected when getting the shared secret.

   2. subCommand: getPinUvAuthTokenUsingPinWithPermissions (0x09).

   3. keyAgreement: the platform key-agreement key.

   4. pinHashEnc: the result of calling encrypt(shared secret, LEFT(SHA-256(PIN), 16)).

   5. permissions: mandatory, the permissions associated with this pinUvAuthToken.

      Note: The platform SHOULD request only the permissions absolutely necessary.

   6. rpId: Required for some permissions, optional for others.

4. Authenticator performs following operations upon receiving the request:

   1. If the authenticator does not receive mandatory parameters for this command, it returns CTAP2_ERR_MISSING_PARAMETER error.

   2. If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

   3. If the authenticator receives a permissions parameter with value 0, return CTAP1_ERR_INVALID_PARAMETER.

   4. The below statements each relate a pinUvAuthToken permission to a given state for a authenticatorGetInfo option ID. For each pinUvAuthToken permission present in the permissions parameter, if the statement corresponding to the permission is currently true, terminate these steps and return CTAP2_ERR_UNAUTHORIZED_PERMISSION. Undefined permissions present in the permissions parameter are ignored.

      • cm: credMgmt is false or absent.

      • be: bioEnroll is absent.

      • lbw: largeBlobs is false or absent.

      • acfg: authnrCfg is false or absent.

      • mc: noMcGaPermissionsWithClientPin is present and set to true.

      • ga: noMcGaPermissionsWithClientPin is present and set to true.

   5. If the pinRetries counter is 0, return CTAP2_ERR_PIN_BLOCKED error.

   6. The authenticator calls decapsulate on the provided platform key-agreement key to obtain the shared secret. If an error results, it returns CTAP1_ERR_INVALID_PARAMETER.

   7. If the authenticator has a display, request user consent for the requested permissions. If this is not approved, return CTAP2_ERR_OPERATION_DENIED.

   8. Authenticator decrements the pinRetries counter by 1.

   9. Authenticator decrypts pinHashEnc using decrypt and verifies against its internally stored CurrentStoredPIN.

      1. If an error results, or a mismatch is detected, the authenticator performs the following operations:

         1. Calls regenerate for the selected pinUvAuthProtocol.

         2. Authenticator returns errors according to following conditions:

            1. If the pinRetries counter is 0, return CTAP2_ERR_PIN_BLOCKED error.

            2. If the authenticator sees 3 consecutive mismatches, it returns CTAP2_ERR_PIN_AUTH_BLOCKED, indicating that power cycling is needed for further operations. This is done so that malware running on the platform should not be able to block the device without user interaction.

            3. Else return CTAP2_ERR_PIN_INVALID error.

   10. Authenticator sets the pinRetries counter to maximum value.

   11. If the value of the forcePINChange member of the authenticatorGetInfo response is true, authenticator returns CTAP2_ERR_PIN_POLICY_VIOLATION. Platform on receiving such error response SHOULD direct the user to change the PIN.

   12. Create a new pinUvAuthToken by calling resetPinUvAuthToken() for all pinUvAuthProtocols supported by this authenticator. (I.e. all existing pinUvAuthTokens are invalidated.)

   13. Call beginUsingPinUvAuthToken(userIsPresent: false).

   14. Assign the requested permissions to the pinUvAuthToken, ignoring any undefined permissions.

   15. If the rpId parameter is present, associate the permissions RP ID with the pinUvAuthToken.

   16. The authenticator returns the encrypted pinUvAuthToken for the specified pinUvAuthProtocol, i.e. encrypt(shared secret, pinUvAuthToken).

6.5.5.7.3. Getting pinUvAuthToken using getPinUvAuthTokenUsingUvWithPermissions (built-in user verification methods)

This subCommand is only applicable when the authenticator supports built-in user verification methods. This subCommand MUST be implemented if the authenticator returns both uv and pinUvAuthToken option IDs set to true in the authenticatorGetInfo response.

1. Platform obtains the shared secret from the authenticator.

2. Platform sends authenticatorClientPIN command. with following parameters to the authenticator:

   1. pinUvAuthProtocol: as selected when getting the shared secret.

   2. subCommand: getPinUvAuthTokenUsingUvWithPermissions (0x06).

   3. keyAgreement: the platform key-agreement key.

   4. permissions: mandatory, the permissions associated with this pinUvAuthToken.

      Note: The platform SHOULD request only the permissions absolutely necessary.

   5. rpId: Required for some permissions, optional for others.

3. Authenticator performs following operations upon receiving the request:

   1. If the authenticator does not receive mandatory parameters for this command, it returns CTAP2_ERR_MISSING_PARAMETER error.

   2. If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

   3. If the authenticator receives a permissions parameter with value 0, return CTAP1_ERR_INVALID_PARAMETER.

   4. The below statements each relate a pinUvAuthToken permission to a given state for a authenticatorGetInfo option ID. For each pinUvAuthToken permission present in the permissions parameter, if the statement corresponding to the permission is currently true, terminate these steps and return CTAP2_ERR_UNAUTHORIZED_PERMISSION. The mc and ga permissions are always considered authorized, thus they are not listed below. Undefined permissions present in the permissions are ignored.

      • cm: credMgmt is false or absent.

      • be: uvBioEnroll is false or absent.

      • lbw: largeBlobs is false or absent.

      • acfg: uvAcfg is false or absent.

      Note: Some authenticators with multiple built-in user verification methods may wish to support the uvBioEnroll and authnrCfg features that enable the getPinUvAuthTokenUsingUvWithPermissions subcommand to return the be and acfg permissions, allowing the platform to enroll fingerprints or perform authenticatorConfig subCommands based, e.g., on a built-in PIN or other modality.

   5. If a built-in user verification method is supported but not configured, the authenticator returns CTAP2_ERR_NOT_ALLOWED.

   6. If preferredPlatformUvAttempts > 1 then let internalRetry be false. This indicates that the platform will try invoking this sub command preferably about preferredPlatformUvAttempts times. Else let internalRetry be true.

   7. If the uvRetries counter is <= 0, return CTAP2_ERR_UV_BLOCKED error.

   8. If the authenticator has a display, request user consent for the requested permissions. If this is not approved, return CTAP2_ERR_OPERATION_DENIED.

   9. Let uvState be the result of calling performBuiltInUv(internalRetry)

   10. If uvState is error:

       1. If the error reason is a user action timeout, then return CTAP2_ERR_USER_ACTION_TIMEOUT.

       2. If the uvRetries counter is <= 0, return CTAP2_ERR_UV_BLOCKED.

       3. Otherwise, return CTAP2_ERR_UV_INVALID.

          Note: The platform, upon receipt of CTAP2_ERR_UV_INVALID, SHOULD check the uvRetries value using authenticatorClientPIN's getUVRetries subCommand. If uvRetries > 0 and preferredPlatformUvAttempts > 1, then, platforms can materialize a UI to inform the user (if appropriate) of the number of remaining retries remaining before user verification is blocked, in conjunction with retrying getPinUvAuthTokenUsingUvWithPermissions. If the platform receives CTAP2_ERR_UV_BLOCKED or uvRetries <= 0 and clientPin option ID is set to true then the platform MAY fall back to invoking getPinUvAuthTokenUsingPinWithPermissions.

   11. Create a new pinUvAuthToken by calling resetPinUvAuthToken() for all pinUvAuthProtocols supported by this authenticator. (I.e. all existing pinUvAuthTokens are invalidated.)

   12. If the employed built-in user verification method supplied evidence of user interaction, then call beginUsingPinUvAuthToken(userIsPresent: true).

       Note: Whether or not a particular built-in user verification method supplies user presence can vary between authenticators.

   13. Otherwise (implying that user presence was not collected), call beginUsingPinUvAuthToken(userIsPresent: false).

   14. Assign the requested permissions to the pinUvAuthToken, ignoring any undefined permissions.

   15. If the rpId parameter is present, use its value as the permissions RP ID and associate it with the pinUvAuthToken.

   16. The authenticator returns the encrypted pinUvAuthToken for the specified pinUvAuthProtocol, i.e. encrypt(shared secret, pinUvAuthToken).

6.5.6. PIN/UV Auth Protocol One

This section specifies a concrete instance of the abstract PIN/UV auth protocol interfaces. It is given the numeric identifier 1, and that is the value to pass in the pinUvAuthProtocol parameter in various commands, to select it.

Note: This PIN protocol was essentially defined in CTAP2.0, the difference between the original definition and this updated definition is that originally the pinToken (herein termed a pinUvAuthToken) length was unlimited. The definition given here states specific lengths for pinUvAuthTokens in both this PIN/UV Auth Protocol 1, and in PIN/UV Auth Protocol 2.

This PIN/UV auth protocol maintains the following state:

• Key agreement key: a P-256 private key, x, and the associated public point xB, which is the result of a scalar-multiplication of the P-256 base point, B, by the private key.

• pinUvAuthToken, a random, opaque byte string that MUST be either 16 or 32 bytes long. This is generated afresh at power-on and reset when specified below.

This PIN/UV auth protocol defines the following internal functions:

ecdh(peerCoseKey) → sharedSecret | error

1. Parse peerCoseKey as specified for getPublicKey, below, and produce a P-256 point, Y. If unsuccessful, or if the resulting point is not on the curve, return error.

2. Calculate xY, the shared point. (I.e. the scalar-multiplication of the peer’s point, Y, with the local private key agreement key.)

3. Let Z be the 32-byte, big-endian encoding of the x-coordinate of the shared point.

4. Return kdf(Z).

kdf(Z) → sharedSecret

Return SHA-256(Z)

(See [RFC6090] Section 4.1 and appendix (C.2) of [SP800-56A] for more ECDH key agreement protocol details and key representation.)

The operations of PIN/UV auth protocol 1 are defined as follows:

initialize()

Calls regenerate followed by resetPinUvAuthToken.

regenerate()

Generate a fresh, random P-256 private key, x, and compute the associated public point.

resetPinUvAuthToken()

1. Generate a fresh, random, pinUvAuthToken of either 16 or 32 bytes in length.

2. Associate pinUvAuthToken state variables with the new pinUvAuthToken, initialized per § 6.5.2.1 pinUvAuthToken State.

getPublicKey()

Return a COSE_Key with the following header parameters:

• 1 (kty) = 2 (EC2)

• 3 (alg) = -25 (although this is not the algorithm actually used)

• -1 (crv) = 1 (P-256)

• -2 (x) = 32-byte, big-endian encoding of the x-coordinate of xB (the key agreement key's public point)

• -3 (y) = 32-byte, big-endian encoding of the y-coordinate of xB

encapsulate(peerCoseKey) → (coseKey, sharedSecret) | error

1. Let sharedSecret be the result of calling ecdh(peerCoseKey). Return any resulting error.

2. Return (getPublicKey(), sharedSecret)

decapsulate(peerCoseKey) → sharedSecret | error

Return ecdh(peerCoseKey)

encrypt(key, demPlaintext) → ciphertext

Return the AES-256-CBC encryption of demPlaintext using an all-zero IV. (No padding is performed as the size of demPlaintext is required to be a multiple of the AES block length.)

decrypt(key, demCiphertext) → plaintext | error

If the size of demCiphertext is not a multiple of the AES block length, return error. Otherwise return the AES-256-CBC decryption of demCiphertext using an all-zero IV.

authenticate(key, message) → signature

Return the first 16 bytes of the result of computing HMAC-SHA-256 with the given key and message.

verify(key, message, signature) → success | error

1. If the key parameter value is the current pinUvAuthToken and it is not in use, then return error.

2. Compute HMAC-SHA-256 with the given key and message. Return success if signature is 16 bytes and is equal to the first 16 bytes of the result, otherwise return error.

6.5.7. PIN/UV Auth Protocol Two

This section provides a PIN/UV auth protocol that is intended to aid FIPS [CMVP] certification of authenticators. It is given the numeric identifier 2, and that is the value to pass in the pinUvAuthProtocol parameter in various commands, to select it.

Note: support for this is mandatory in some cases. See § 9 Mandatory features.

The length of the pinUvAuthToken for PIN/UV auth protocol two MUST be 32 bytes. Otherwise, it inherits all the behavior of PIN protocol one and overrides only these functions:

kdf(Z) → sharedSecret

Return
HKDF-SHA-256(salt = 32 zero bytes, IKM = Z, L = 32, info = "CTAP2 HMAC key") ||
HKDF-SHA-256(salt = 32 zero bytes, IKM = Z, L = 32, info = "CTAP2 AES key")
(see [RFC5869] for the definition of HKDF).

Note: This is two separate invocations of HKDF whose results are concatenated together. It can NOT be equivalently performed using a single invocation with L=64.

resetPinUvAuthToken()

1. Generate a fresh, random, 32-byte, pinUvAuthToken.

2. Associate pinUvAuthToken state variables with the new pinUvAuthToken, initialized per § 6.5.2.1 pinUvAuthToken State.

encrypt(key, demPlaintext) → ciphertext

1. Discard the first 32 bytes of key. (This selects the AES-key portion of the shared secret.)

2. Let iv be a 16-byte, random bytestring.

3. Let ct be the AES-256-CBC encryption of demPlaintext using key and iv. (No padding is performed as the size of demPlaintext is required to be a multiple of the AES block length.)

4. Return iv || ct.

decrypt(key, demCiphertext) → plaintext | error

1. Discard the first 32 bytes of key. (This selects the AES-key portion of the shared secret.)

2. If demPlaintext is less than 16 bytes in length, return an error

3. Split demPlaintext after the 16^th byte to produce two subspans, iv and ct.

4. Return the AES-256-CBC decryption of ct using key and iv.

authenticate(key, message) → signature

1. If key is longer than 32 bytes, discard the excess. (This selects the HMAC-key portion of the shared secret. When key is the pinUvAuthToken, it is exactly 32 bytes long and thus this step has no effect.)

2. Return the result of computing HMAC-SHA-256 on key and message.

verify(key, message, signature) → success | error

1. If the key parameter value is the current pinUvAuthToken and it is not in use, then return error.

2. If key is longer than 32 bytes, discard the excess. (This selects the HMAC-key portion of the shared secret. When key is the pinUvAuthToken, it is exactly 32 bytes long and thus this step has no effect.)

3. Compute HMAC-SHA-256 with the given key and message. Return success if the signature is equal to the result, otherwise return an error.

6.5.8. PRF values used

Throughout this protocol, the pseudo-random function defined by HMAC-SHA-256 and the pinUvAuthToken is evaluated for various values in order to authenticate requests from the platform. It is important that these values uniquely identify the salient parameters of the requests that they authenticate otherwise a PRF output from one context could be observed by an attacker and replayed in a different context.

(It is a known weakness that, within the scope of a single pinUvAuthToken value, requests may be reordered or replayed by an attacker.)

For clarity, all the patterns of values used by this protocol are enumerated in the following table:

In order to avoid collisions with values already used the following pattern will be used for future commands: 32 0xff bytes, followed by the command code as a single byte, followed by an unambiguous substructure defined by each command.

The leading 0xff bytes in the pattern separate the value from any possible value used in an authenticatorMakeCredential or authenticatorGetAssertion command. As motivation, consider the authenticatorBioEnrollment command which does not use this pattern. The argument to authenticatorGetAssertion is a clientDataHash which, in a WebAuthn context, is the hash of a potentially predictable JSON string containing an attacker-controlled nonce. Offline, an attacker can iterate over many nonces until they find one which will produce a clientDataHash that starts with 0101a1, is followed by a CBOR string or integer not equal to three, and then by a CBOR value that exactly fills the remaining space. This requires around 2³² offline hash evaluations but, if the attacker can observe the PRF output sent by the platform for an authenticatorGetAssertion command using that nonce, then they can replay it to start a fingerprint enrollment as the PRF argument also matches the pattern for enrolling a fingerprint. (Although note that more work is required to complete the enrollment as that requires further commands to be authenticated.)

6.6. authenticatorReset (0x07)

Resetting an authenticator is a potentially destructive operation. Authenticators MAY thus choose, for each transport they support, whether this command will be supported when received on that transport. For example, an authenticator may choose not to support this command over NFC, fearing that coincidentally nearby readers may send malicious reset commands.

However this command MUST be supported on at least one transport. If the USB HID transport is supported then this command MUST be supported on that transport.

This method is used by the client to reset an authenticator back to a factory default state. Specifically this action at least:

• Invalidates all generated credentials, including those created over CTAP1/U2F.

• Erases all discoverable credentials.

• Resets the serialized large-blob array storage, if any, to the initial serialized large-blob array value.

• Disables those features that are denoted as being subject to disablement by authenticatorReset:

  • Enterprise attestation

• Resets those features that are denoted as being subject to reset by authenticatorReset:

  • Always Require User Verification

  • Set Minimum PIN Length

Additionally:

• In order to prevent an accidental triggering of this mechanism, evidence of user interaction is required.

• In case of authenticators with no display, request MUST have come to the authenticator within 10 seconds of powering up of the authenticator.

If all conditions are met, authenticator returns CTAP2_OK. If this command is disabled for the transport used, the authenticator returns CTAP2_ERR_OPERATION_DENIED. If user presence is explicitly denied, the authenticator returns CTAP2_ERR_OPERATION_DENIED. If a user action timeout occurs, the authenticator returns CTAP2_ERR_USER_ACTION_TIMEOUT. If the request comes after 10 seconds of powering up, the authenticator returns CTAP2_ERR_NOT_ALLOWED.

6.7. authenticatorBioEnrollment (0x09)

This command is used by the platform to provision/enumerate/delete bio enrollments in the authenticator.

It takes the following input parameters:

The type of modalities supported are as under:

The list of sub commands for fingerprint(0x01) modality is:

subCommandParams Fields:

On success, authenticator returns the following structure in its response:

TemplateInfo definition:

lastEnrollSampleStatus types:

Note: In order to support the authenticator performing authenticatorMakeCredential or authenticatorGetAssertion immediately after bio enrollment, authenticators SHOULD NOT expire the pinUvAuthToken at the completion of bio enrollment.

6.7.1. Feature detection

The bioEnroll option ID in the authenticatorGetInfo response defines feature support detection for this feature.

6.7.2. Get bio modality

Following operations are performed to get bio modality supported by the authenticator:

• Platform sends authenticatorBioEnrollment command with following parameters:

  • getModality (0x06): true.

• Authenticator returns authenticatorBioEnrollment response with following parameters:

  • modality (0x01): It represents the type of modality authenticator supports. For fingerprint, its value is 1.

6.7.3. Get fingerprint sensor info

Following operations are performed to get fingerprint sensor information:

• Platform sends authenticatorBioEnrollment command with following parameters:

  • modality (0x01): fingerprint (0x01).

  • subCommand (0x02): getFingerprintSensorInfo (0x07)

• Authenticator returns authenticatorBioEnrollment response with following parameters:

  • fingerprintKind (0x02):

    • For touch type fingerprints, its value is 1.

    • For swipe type fingerprints, its value is 2.

  • maxCaptureSamplesRequiredForEnroll (0x03): Indicates the maximum good samples required for enrollment.

  • maxTemplateFriendlyName (0x08): Indicates the maximum number of bytes the authenticator will accept as a templateFriendlyName.

6.7.4. Enrolling fingerprint

Following operations are performed to enroll a fingerprint:

• Platform gets pinUvAuthToken from the authenticator with the be permission.

• Platform sends authenticatorBioEnrollment command with following parameters to begin the enrollment:

  • modality (0x01): fingerprint (0x01).

  • subCommand (0x02): enrollBegin (0x01).

  • subCommandParams (0x03): Map containing following parameters

    • timeoutMilliseconds (0x03) (optional): timeout in milliseconds

  • pinUvAuthProtocol (0x04): as selected when getting the shared secret.

  • pinUvAuthParam (0x05): authenticate(pinUvAuthToken, fingerprint (0x01) || enrollBegin (0x01) || subCommandParams).

• Authenticator on receiving such request performs following procedures.

  • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

  • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • Authenticator calls verify(pinUvAuthToken, fingerprint (0x01) || enrollBegin (0x01) || subCommandParams, pinUvAuthParam)

    • If the verification fails, return CTAP2_ERR_PIN_AUTH_INVALID.

  • Authenticator verifies that the token has be permission, if not, it returns CTAP2_ERR_PIN_AUTH_INVALID.

  • If there is no space available, authenticator returns CTAP2_ERR_FP_DATABASE_FULL.

  • Authenticator cancels any unfinished ongoing enrollment.

  • Authenticator generates templateId for new enrollment.

  • Authenticator sends the command to the sensor to capture the sample.

  • Authenticator returns authenticatorBioEnrollment response with following parameters:

    • templateId (0x04): template identifier of the new template being enrolled.

    • lastEnrollSampleStatus (0x05) : Status of enrollment of last sample.

    • remainingSamples (0x06) : Number of sample remaining to complete the enrollment.

• Platform sends authenticatorBioEnrollment command with following parameters to continue enrollment in a loop till remainingSamples is zero or authenticator errors out with unrecoverable error or platform wants to cancel current enrollment:

  • Platform sends authenticatorBioEnrollment command with following parameters

    • modality (0x01): fingerprint (0x01).

    • subCommand (0x02): enrollCaptureNextSample (0x02).

    • subCommandParams (0x03): Map containing following parameters

      • templateId (0x01) : template identifier platform received from enrollBegin subCommand.

      • timeoutMilliseconds (0x03) (optional): timeout in milliseconds

    • pinUvAuthProtocol (0x04): as selected when getting the shared secret.

    • pinUvAuthParam (0x05): authenticate(pinUvAuthToken, fingerprint (0x01) || enrollCaptureNextSample (0x02) || subCommandParams).

  • Authenticator on receiving such request performs following procedures.

    • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

    • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

    • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

    • Authenticator calls verify(pinUvAuthToken, fingerprint (0x01) || enrollCaptureNextSample (0x02) || subCommandParams, pinUvAuthParam)

      • If the verification fails, return CTAP2_ERR_PIN_AUTH_INVALID.

    • Authenticator verifies that the pinUvAuthToken has be permission, if not, it returns CTAP2_ERR_PIN_AUTH_INVALID.

    • If there is no space available, authenticator returns CTAP2_ERR_FP_DATABASE_FULL.

    • If fingerprint is already present on the sensor, authenticator waits for user to lift finger from the sensor.

    • Authenticator sends the command to the sensor to capture the sample.

    • Authenticator returns authenticatorBioEnrollment response with following parameters:

      • lastEnrollSampleStatus (0x05) : Status of enrollment of last sample.

      • remainingSamples (0x06) : Number of sample remaining to complete the enrollment.

6.7.5. Cancel current enrollment

Following operations are performed to cancel current enrollment:

• Platform sends authenticatorBioEnrollment command with following parameters:

  • modality (0x01): fingerprint (0x01).

  • subCommand (0x02): cancelCurrentEnrollment (0x03).

• Authenticator on receiving such command, cancels current ongoing enrollment, if any, and returns CTAP2_OK.

6.7.6. Enumerate enrollments

Following operations are performed to enumerate enrollments:

• Platform gets pinUvAuthToken from the authenticator with the be permission.

• Platform sends authenticatorBioEnrollment command with following parameters:

  • modality (0x01): fingerprint (0x01).

  • subCommand (0x02): enumerateEnrollments (0x04).

  • pinUvAuthProtocol (0x04): as selected when getting the shared secret.

  • pinUvAuthParam (0x05): authenticate(pinUvAuthToken, fingerprint (0x01) || enumerateEnrollments (0x04)).

• Authenticator on receiving such request performs following procedures.

  • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

  • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • Authenticator calls verify(pinUvAuthToken, fingerprint (0x01) || enumerateEnrollments (0x04), pinUvAuthParam)

    • If the verification fails, return CTAP2_ERR_PIN_AUTH_INVALID.

  • Authenticator verifies that the token has be permission, if not, it returns CTAP2_ERR_PIN_AUTH_INVALID.

  • If there are no enrollments existing on authenticator, it returns CTAP2_ERR_INVALID_OPTION.

  • Authenticator returns authenticatorBioEnrollment response following parameters:

    • templateInfos (0x07) : Array of templateInfo’s for all the enrollments available on the authenticator.

6.7.7. Rename/Set FriendlyName

Following operations are performed to rename a fingerprint:

• Platform gets pinUvAuthToken from the authenticator with the be permission.

• Platform sends authenticatorBioEnrollment command with following parameters:

  • modality (0x01): fingerprint (0x01).

  • subCommand (0x02): setFriendlyName (0x05).

  • subCommandParams (0x03): Map containing following parameters

    • templateId (0x01) : template identifier.

    • templateFriendlyName (0x02): Friendly name of the template. (The maximum size SHOULD be the lessor of 64 bytes or the value of maxTemplateFriendlyName)

  • pinUvAuthProtocol (0x04): as selected when getting the shared secret.

  • pinUvAuthParam (0x05): authenticate(pinUvAuthToken, fingerprint (0x01) || setFriendlyName (0x05) || subCommandParams).

• Authenticator on receiving such request performs following procedures.

  • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

  • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • If templateFriendlyName is longer than specified by maxTemplateFriendlyName, return an error e.g., CTAP1_ERR_INVALID_LENGTH.

  • Authenticator calls verify(pinUvAuthToken, fingerprint (0x01) || setFriendlyName (0x05) || subCommandParams, pinUvAuthParam)

    • If the verification fails, return CTAP2_ERR_PIN_AUTH_INVALID.

  • Authenticator verifies that the token has be permission, if not, it returns CTAP2_ERR_PIN_AUTH_INVALID.

  • If there are no enrollments existing on authenticator for the passed templateId, it returns CTAP2_ERR_INVALID_OPTION.

  • If there is an existing enrollment with that identifier, rename its friendly name and return CTAP2_OK.

6.7.8. Remove enrollment

Following operations are performed to remove a fingerprint:

• Platform gets pinUvAuthToken from the authenticator with the be permission.

• Platform sends authenticatorBioEnrollment command with following parameters:

  • modality (0x01): fingerprint (0x01).

  • subCommand (0x02): removeEnrollment (0x06).

  • subCommandParams (0x03): Map containing following parameters

    • templateId (0x01) : template identifier.

  • pinUvAuthProtocol (0x04): as selected when getting the shared secret.

  • pinUvAuthParam (0x05): authenticate(pinUvAuthToken, fingerprint (0x01) || removeEnrollment (0x06) || subCommandParams).

• Authenticator on receiving such request performs following procedures.

  • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

  • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • Authenticator calls verify(pinUvAuthToken, fingerprint (0x01) || removeEnrollment (0x06) || subCommandParams, pinUvAuthParam)

    • If the verification fails, return CTAP2_ERR_PIN_AUTH_INVALID.

  • Authenticator verifies that the token has be permission, if not, it returns CTAP2_ERR_PIN_AUTH_INVALID.

  • If there are no enrollments existing on authenticator for passed templateId, it returns CTAP2_ERR_INVALID_OPTION.

  • If there is an exiting enrollment with passed in templateInfo, delete that enrollment and return CTAP2_OK.

6.8. authenticatorCredentialManagement (0x0A)

This command is used by the platform to manage discoverable credentials on the authenticator.

Note: support for this command is mandatory in some cases. See § 9 Mandatory features.

It takes the following input parameters:

The list of sub commands for credential management is:

subCommandParams Fields:

On success, authenticator returns the following structure in its response:

6.8.1. Feature detection

The credMgmt option ID in the authenticatorGetInfo response defines feature support detection for this feature.

6.8.2. Getting Credentials Metadata

Following operations are performed to get credentials metadata information :

• Platform gets pinUvAuthToken from the authenticator with the cm permission, and MUST NOT include a permissions RP ID parameter.

• Platform sends authenticatorCredentialManagement command with following parameters:

  • subCommand (0x01): getCredsMetadata (0x01).

  • pinUvAuthProtocol (0x03): as selected when getting the shared secret.

  • pinUvAuthParam (0x04): authenticate(pinUvAuthToken, getCredsMetadata (0x01)).

• Authenticator on receiving such request performs following procedures.

  • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

  • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • Authenticator calls verify(pinUvAuthToken, getCredsMetadata (0x01), pinUvAuthParam)

  • If pinUvAuthParam verification fails, authenticator returns CTAP2_ERR_PIN_AUTH_INVALID error.

  • The authenticator verifies that the pinUvAuthToken has the cm permission and no associated permissions RP ID. If not, return CTAP2_ERR_PIN_AUTH_INVALID.

  • Authenticator returns authenticatorCredentialManagement response with following parameters:

    • existingResidentCredentialsCount (0x01) : total number of discoverable credentials existing on the authenticator.

    • maxPossibleRemainingResidentCredentialsCount (0x02) : maximum number of possible remaining discoverable credentials that can be created on the authenticator. Note that this number is an estimate as actual space consumed to create a credential depends on various conditions such as which algorithm is picked, user entity information etc.

6.8.3. Enumerating RPs

Following operations are performed to enumerate RPs present on the authenticator:

• Platform gets pinUvAuthToken from the authenticator with the cm permission, and MUST NOT include a permissions RP ID parameter.

• Platform sends authenticatorCredentialManagement command with following parameters:

  • subCommand (0x01): enumerateRPsBegin (0x02).

  • pinUvAuthProtocol (0x03): as selected when getting the shared secret.

  • pinUvAuthParam (0x04): authenticate(pinUvAuthToken, enumerateRPsBegin (0x02)).

• Authenticator on receiving such request performs following procedures.

  • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

  • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • Authenticator calls verify(pinUvAuthToken, enumerateRPsBegin (0x02), pinUvAuthParam).

  • If pinUvAuthParam verification fails, authenticator returns CTAP2_ERR_PIN_AUTH_INVALID error.

  • The authenticator verifies that the pinUvAuthToken has the cm permission and no associated permissions RP ID. If not, return CTAP2_ERR_PIN_AUTH_INVALID.

  • If no discoverable credentials exist on this authenticator, return CTAP2_ERR_NO_CREDENTIALS.

  • Authenticator returns an authenticatorCredentialManagement response with following parameters:

    • rp (0x03): PublicKeyCredentialRpEntity, where the id field SHOULD be included and other fields MAY be included. (See § 6.8.7 Truncation of relying party identifiers about possible truncation of the id field and [WebAuthn] about other fields.)

    • rpIDHash (0x04) : RP ID SHA-256 hash.

    • totalRPs (0x05) : Total number of RPs present on the authenticator.

• Platform on receiving more than 1 totalRPs, performs following procedure for (totalRPs - 1 ) number of times:

  • Platform sends authenticatorCredentialManagement command with following parameters:

    • subCommand (0x01): enumerateRPsGetNextRP (0x03).

  Note: this is a stateful command and the specified implementation accommodations apply to it.

  • Authenticator on receiving such enumerateCredentialsGetNext subCommand returns authenticatorCredentialManagement response with following parameters:

    • rp (0x03): PublicKeyCredentialRpEntity

    • rpIDHash (0x04) : RP ID SHA-256 hash.

6.8.4. Enumerating Credentials for an RP

Following operations are performed to enumerate credentials for an RP:

• Platform gets pinUvAuthToken from the authenticator with the cm permission.

• Platform sends authenticatorCredentialManagement command with following parameters:

  • subCommand (0x01): enumerateCredentialsBegin (0x04).

  • subCommandParams (0x02): Map containing following parameters

    • rpIDHash (0x01): RP ID SHA-256 hash.

  • pinUvAuthProtocol (0x03): as selected when getting the shared secret.

  • pinUvAuthParam (0x04): authenticate(pinUvAuthToken, enumerateCredentialsBegin (0x04) || subCommandParams).

• Authenticator on receiving such request performs following procedures.

  • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

  • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • Authenticator calls verify(pinUvAuthToken, enumerateCredentialsBegin (0x04) || subCommandParams, pinUvAuthParam)

  • If pinUvAuthParam verification fails, authenticator returns CTAP2_ERR_PIN_AUTH_INVALID error.

  • The authenticator verifies that the pinUvAuthToken has the cm permission and that the pinUvAuthToken does not have an permissions RP ID associated or that the pinUvAuthToken permissions RP ID matches the RP ID of this request. If not, return CTAP2_ERR_PIN_AUTH_INVALID.

  • If no discoverable credentials for this RP ID hash exist on this authenticator, return CTAP2_ERR_NO_CREDENTIALS.

  • Authenticator returns authenticatorCredentialManagement response with following parameters:

    • user (0x06): PublicKeyCredentialUserEntity

    • credentialID (0x07): PublicKeyCredentialDescriptor

    • publicKey (0x08): public key of the credential in COSE_Key format

    • totalCredentials (0x09): total number of credentials for this RP

    • credProtect (0x0A): credential protection policy

    • largeBlobKey (0x0B): the contents, if any, of the stored largeBlobKey.

• Platform on receiving more than 1 totalCredentials, performs following procedure for (totalCredentials - 1 ) number of times:

  • Platform sends authenticatorCredentialManagement command with following parameters:

    • subCommand (0x01): enumerateCredentialsGetNextCredential (0x05).

  Note: this is a stateful command and the specified implementation accommodations apply to it.

  • Authenticator on receiving such enumerateCredentialsGetNext subCommand returns with following parameters:

    • user (0x06): PublicKeyCredentialUserEntity

    • credentialID (0x07): PublicKeyCredentialDescriptor

    • publicKey (0x08): public key of the credential in COSE_Key format

    • credProtect (0x0A): credential protection policy

    • largeBlobKey (0x0B): the contents, if any, of the stored largeBlobKey.

Note: when enumerating credentials, platforms SHOULD take the opportunity to perform large-blob garbage collection, if applicable.

6.8.5. DeleteCredential

Following operations are performed to delete a credential:

• Platform gets pinUvAuthToken from the authenticator with the cm permission.

• Platform sends authenticatorCredentialManagement command with following parameters:

  • subCommand (0x01): deleteCredential (0x06).

  • subCommandParams (0x02): Map containing following parameters

    • credentialId (0x02): PublicKeyCredentialDescriptor of the credential to be deleted.

  • pinUvAuthProtocol (0x03): as selected when getting the shared secret.

  • pinUvAuthParam (0x04): authenticate(pinUvAuthToken, deleteCredential (0x06) || subCommandParams).

• Authenticator on receiving such request performs following procedures.

  • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

  • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • Authenticator calls verify(pinUvAuthToken, deleteCredential (0x06) || subCommandParams, pinUvAuthParam)

  • If pinUvAuthParam verification fails, authenticator returns CTAP2_ERR_PIN_AUTH_INVALID error.

  • The authenticator verifies that the pinUvAuthToken has the cm permission and that the pinUvAuthToken does not have a permissions RP ID associated or that the pinUvAuthToken permissions RP ID matches the RP ID of the credential. If not, return CTAP2_ERR_PIN_AUTH_INVALID.

  • If there are not credential existing matching credentialDescriptor, return CTAP2_ERR_NO_CREDENTIALS.

  • Delete the credential and return CTAP2_OK.

Note: when deleting a credential, platforms SHOULD also delete any associated large blobs.

6.8.6. Updating user information

Following operations are performed to update user information associated to a credential:

• Platform gets pinUvAuthToken from the authenticator with the cm permission.

• Platform sends authenticatorCredentialManagement command with following parameters:

  • subCommand (0x01): updateUserInformation (0x07).

  • subCommandParams (0x02): Map containing the parameters that need to be updated.

    • credentialId (0x02): PublicKeyCredentialDescriptor of the credential to be updated.

    • user (0x03): a PublicKeyCredentialUserEntity with the updated information.

  • pinUvAuthProtocol (0x03): as selected when getting the shared secret.

  • pinUvAuthParam (0x04): authenticate(pinUvAuthToken, updateUserInformation (0x07) || subCommandParams).

• Authenticator on receiving such request performs following procedures.

  • If pinUvAuthParam is missing from the input map, end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

  • If the authenticator does not receive mandatory parameters for this subcommand, end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

  • If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

  • Authenticator calls verify(pinUvAuthToken, updateUserInformation (0x07) || subCommandParams, pinUvAuthParam)

  • If pinUvAuthParam verification fails, authenticator returns CTAP2_ERR_PIN_AUTH_INVALID error.

  • The authenticator verifies that the pinUvAuthToken has the cm permission and that the pinUvAuthToken does not have a permissions RP ID associated or that the pinUvAuthToken permissions RP ID matches the RP ID of the credential. If not, return CTAP2_ERR_PIN_AUTH_INVALID.

  • The authenticator searches for an existing credential matching credentialId.

  • If no matching credential is found, return CTAP2_ERR_NO_CREDENTIALS.

  • If the authenticator does not have enough internal storage to update the matching credential, return CTAP2_ERR_KEY_STORE_FULL.

  • If the supplied user parameter’s id field is not the same as the matching credential’s id field then return CTAP1_ERR_INVALID_PARAMETER.

  • Replace the matching credential’s PublicKeyCredentialUserEntity's name, displayName with the passed-in user details. If a field is not present in the passed user details, or it is present and empty, remove it from the matching credential’s PublicKeyCredentialUserEntity.

  • Return CTAP2_OK.

6.8.7. Truncation of relying party identifiers

An authenticator MAY store relying party identifiers in order to implement authenticatorCredentialManagement. As there is no bound on their length, authenticators MAY truncate them using a procedure that produces the same results as the code included below. If authenticators store relying party identifiers at all, they MUST store at least 32 bytes. Truncation of relying party identifiers only applies to returning a PublicKeyCredentialRpEntity structure in the context of this command. I.e. authenticators MUST NOT use truncated relying party identifiers for comparisons at any time, including in the context of this command.

#define MAX_STORED_RPID_LENGTH 32  /* MUST be >= 32 */

void maybe_truncate_rpid(uint8_t stored_rpid[MAX_STORED_RPID_LENGTH],
                         size_t *stored_len, const uint8_t *rpid,
                         size_t rpid_len) {
  if (rpid_len <= MAX_STORED_RPID_LENGTH) {
    memcpy(stored_rpid, rpid, rpid_len);
    *stored_len = rpid_len;
    return;
  }

  size_t used = 0;
  const uint8_t *colon_position = memchr(rpid, ':', rpid_len);
  if (colon_position != NULL) {
    const size_t protocol_len = colon_position - rpid + 1;
    const size_t to_copy = protocol_len <= MAX_STORED_RPID_LENGTH
                               ? protocol_len
                               : MAX_STORED_RPID_LENGTH;
    memcpy(stored_rpid, rpid, to_copy);
    used += to_copy;
  }

  if (MAX_STORED_RPID_LENGTH - used < 3) {
    *stored_len = used;
    return;
  }

  // U+2026, horizontal ellipsis.
  stored_rpid[used++] = 0xe2;
  stored_rpid[used++] = 0x80;
  stored_rpid[used++] = 0xa6;

  const size_t to_copy = MAX_STORED_RPID_LENGTH - used;
  memcpy(&stored_rpid[used], rpid + rpid_len - to_copy, to_copy);
  assert(used + to_copy == MAX_STORED_RPID_LENGTH);
  *stored_len = MAX_STORED_RPID_LENGTH;
}

For illutrative purposes, here are some examples of the truncation in effect:

6.9. authenticatorSelection (0x0B)

This command allows the platform to let a user select a certain authenticator by asking for user presence.

The command has no input parameters.

When the authenticatorSelection command is received, the authenticator will ask for user presence:

• If User Presence is received, the authenticator will return CTAP2_OK.

• If User Presence is explicitly denied by the user, the authenticator will return CTAP2_ERR_OPERATION_DENIED. The platform SHOULD NOT repeat the command for this authenticator.

• If a user action timeout occurs, the authenticator will return CTAP2_ERR_USER_ACTION_TIMEOUT. The platform MAY repeat the command for this authenticator.

If an authenticator is selected, the platform SHOULD send a cancel to all other authenticators.

6.10. authenticatorLargeBlobs (0x0C)

The credBlob extension allows for a small amount of additional, secret information to be stored with a credential. In contrast, this command allows a platform to store a larger amount of information associated with a credential, protected by a key that is then stored and accessed using the largeBlobKey extension. The opaque large-blob data that is stored for a credential is a byte string with RP-specific structure. This is only applicable to discoverable credentials so that garbage collection is possible.

This command allows at least 1024 bytes of large blob data to be stored on CTAP2 authenticators. For the purposes of this command, this data is serialized as a CBOR-encoded array (called the large-blob array) of large-blob maps, concatenated with 16 following bytes. Those final 16 bytes are the truncated SHA-256 hash of the preceding bytes. This concatenation is referred to as the serialized large-blob array.

The initial serialized large-blob array is the value of the serialized large-blob array on a fresh authenticator, as well as immediately after a reset. It is the byte string h'8076be8b528d0075f7aae98d6fa57a6d3c', which is an empty CBOR array (80) followed by LEFT(SHA-256(h'80'), 16).

Note: the minimum length of a serialized large-blob array is 17 bytes. Omitting 16 bytes for the trailing SHA-256 hash, this leaves just one byte. This is the size of an empty CBOR array.

6.10.1. Feature detection

The largeBlobs option ID in the authenticatorGetInfo response defines feature support detection for this feature.

6.10.2. Reading and writing serialised data

The command takes the following input parameters:

A per-authenticator constant, maxFragmentLength, is here defined as the value of maxMsgSize (from the authenticatorGetInfo response) minus 64. The value 64 is a comfortable over-estimate of the encoding overhead of the messages defined in this section such that a byte string of length maxFragmentLength can be transferred without exceeding the maximum message size of the authenticator. If no maxMsgSize is given in the authenticatorGetInfo response) then it defaults to 1024, leaving maxFragmentLength to default to 960.

In addition to persistently storing the serialized large-blob array, authenticators implementing this command are required to maintain two unsigned integers in volatile memory named expectedNextOffset and expectedLength, both initially zero. This makes this command a stateful command and the specified implementation accommodations apply to it.

An authenticator performs the following actions upon receipt of this command:

1. If offset is not present in the input map, return CTAP1_ERR_INVALID_PARAMETER.

2. If neither get nor set are present in the input map, return CTAP1_ERR_INVALID_PARAMETER.

3. If both get and set are present in the input map, return CTAP1_ERR_INVALID_PARAMETER.

4. If get is present in the input map:

   1. If length is present, return CTAP1_ERR_INVALID_PARAMETER.

   2. If either of pinUvAuthParam or pinUvAuthProtocol are present, return CTAP1_ERR_INVALID_PARAMETER.

   3. If the value of get is greater than maxFragmentLength, return CTAP1_ERR_INVALID_LENGTH.

   4. If the value of offset is greater than the length of the stored serialized large-blob array, return CTAP1_ERR_INVALID_PARAMETER.

   5. Return a CBOR map, as defined below, where the value of config is a substring of the stored serialized large-blob array. The substring SHOULD start at the offset given in offset and contain the number of bytes specified as get's value. If too few bytes exist at that offset, return the maximum number available. Note that if offset is equal to the length of the serialized large-blob array then this will result in a zero-length substring.

5. Else (implying that set is present in the input map):

   1. If the length of the value of set is greater than maxFragmentLength, return CTAP1_ERR_INVALID_LENGTH. (The “value of set” means the contents of the byte string corresponding to the key set (0x02), not including the outer CBOR tag with major type two.)

   2. If the value of offset is zero:

      1. If length is not present, return CTAP1_ERR_INVALID_PARAMETER.

      2. If the value of length is greater than 1024 bytes and exceeds the capacity of the device, return CTAP2_ERR_LARGE_BLOB_STORAGE_FULL. (Authenticators MUST be capable of storing at least 1024 bytes.)

      3. If the value of length is less than 17, return CTAP1_ERR_INVALID_PARAMETER. (See note above about minimum lengths.)

      4. Set expectedLength to the value of length.

      5. Set expectedNextOffset to zero.

   3. Else (i.e. the value of offset is not zero):

      1. If length is present, return CTAP1_ERR_INVALID_PARAMETER.

   4. If the value of offset is not equal to expectedNextOffset, return CTAP1_ERR_INVALID_SEQ.

   5. If the authenticator is protected by some form of user verification or the alwaysUv option ID is present and true:

      1. If pinUvAuthParam is absent from the input map, then end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

      2. If pinUvAuthProtocol is absent from the input map, then end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

      3. If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

      4. The authenticator calls verify(pinUvAuthToken, 32×0xff || h’0c00' || uint32LittleEndian(offset) || SHA-256(contents of set byte string, i.e. not including an outer CBOR tag with major type two), pinUvAuthParam).

         1. If the verification fails, return CTAP2_ERR_PIN_AUTH_INVALID.

      5. Check if the pinUvAuthToken has the lbw permission, if not, return CTAP2_ERR_PIN_AUTH_INVALID.

   6. If the sum of offset and the length of the value of set is greater than the value of expectedLength, return CTAP1_ERR_INVALID_PARAMETER.

   7. If the value of offset is zero, prepare a buffer to receive a new serialized large-blob array.

   8. Append the value of set to the buffer containing the pending serialized large-blob array.

   9. Update expectedNextOffset to be the new length of the pending serialized large-blob array.

   10. If the length of the pending serialized large-blob array is equal to expectedLength:

       1. Verify that the final 16 bytes in the buffer are the truncated SHA-256 hash of the preceding bytes. If the hash does not match, return CTAP2_ERR_INTEGRITY_FAILURE.

       2. Commit the contents of the buffer as the new serialized large-blob array for this authenticator.

       3. Return CTAP2_OK and an empty response.

   11. Else:

       1. More data is needed to complete the pending serialized large-blob array.

       2. Return CTAP2_OK and an empty response. Await further writes.

Note: user verification is only checked above if user verification is configured on a device or the authenticator always requires some form of user verification feature is enabled. This implies that a serialized large-blob array can be written without user verification if user verification is not configured.

Note: To read (i.e., "get") per-credential large-blob data given a credential ID, the platform must first use an authenticatorGetAssertion operation to obtain the associated largeBlobKey in order to be able to decrypt the large-blob data (if any). Thus the confidentiality of any large-blob data associated with the credential is dependent upon the credential’s protection policy. This means that even though a platform may obtain the large-blob array at will, it will be unable to obtain large-blob plaintexts if it cannot successfully perform authenticatorGetAssertion operations using the associated credential(s), e.g., without obtaining user verification. Also, the "trial decryption" approach employed for obtaining plaintext means that large-blobs do not disclose a priori the existence of credentials having a credProtect level 3 userVerificationRequired policy.

The response to a get request, referenced above, takes the following form:

In order to read a serialized large-blob array, a platform is expected to first issue a request where offset is zero and get equals the value of maxFragmentLength, which is maxMsgSize − 64 bytes, as defined above. If the length of the response is equal to the value of get then more data may be available and the platform SHOULD repeatedly issue requests, each time updating offset to equal the amount of data received so far. It stops once a short (or empty) fragment is returned. Once complete, the platform MUST confirm that the embedded SHA-256 hash is correct, based on the definition above. If not, the configuration is corrupt and the platform MUST discard it and act as if the initial serialized large-blob array was received.

In order to write a serialized large-blob array, a platform is expected to first issue a request where offset is zero, length is the full length of the data to be written, and set contains a prefix of the data to be written, truncated at maxFragmentLength bytes, if length is greater than maxFragmentLength. If truncation is needed then one or more further requests are needed to complete the transfer, with offset updated each time to contain the amount of data written so far and set containing consecutive substrings of the data. The authenticator will implicitly know when the transfer is complete because of the length given in the first request.

The algorithm to be performed by the authenticator given above assumes that the authenticator double-buffers the serialized large-blob array. (I.e. it writes proposed updates into a separate buffer and only overwrites the effective config once validation has completed.) A compliant authenticator MAY be implemented using only a single buffer as follows: when appending to the buffer, use expectedLength to buffer the final 16 bytes of the serialized large-blob array in volatile storage. Once the transfer is complete, perform validation and only write the final 16 bytes to persistent storage if successful. This prevents the SHA-256 checksum of an invalid serialized large-blob array from being persisted.

Note: even with double-buffering, the copy from the temporary buffer might be interrupted, resulting in a “torn write”. This will be detected by the platform when reading because the checksum won’t match, but results in an unusable config. Thus double-buffering minimises the chance of corruption, but does not always eliminate it.

Despite best efforts, torn writes, platform errors, and storage corruption may result in a situation where an authenticator finds itself having stored an invalid serialized large-blob array. (I.e. the SHA-256 hash does not match.) In this case, the authenticator MAY reset the stored value with the initial serialized large-blob array.

An authenticator MUST NOT act on the contents of the serialized large-blob array except for checking the trailing hash: it is purely for platforms to adjust their behavior in response to.

Authenticators MUST set the serialized large-blob array to the initial serialized large-blob array byte string when reset.

Platforms MUST ensure that the large-blob array (i.e. without the trailing 16 bytes) is a CBOR array where all entries conform to the large-blob map structure defined below. The maps and array MUST be encoded using the canonical rules. Platforms MUST NOT attempt to write a serialized large-blob array that exceeds the maxSerializedLargeBlobArray reported by the authenticator in the authenticatorGetInfo response. Platforms SHOULD take care to preserve existing entries in a large-blob array where space permits. For example, platforms should read, and then insert values into, an existing large-blob array as opposed to blindly writing a fresh array.

6.10.3. Large, per-credential blobs

The elements of the large-blob array MUST conform to the following large-blob map structure. Conformance, in this context, means that a map MUST include all required elements, MAY include optional elements, and MAY include unknown elements. The values of all documented elements present MUST match the specified type and MUST comply with any additional restrictions documented for them.

The ciphertext member contains the output of encrypting the opaque large-blob data with the AEAD_AES_256_GCM algorithm from [RFC5116]. The inputs to the AEAD are:

• Nonce: the 12-byte value from nonce.

• Plaintext: the compressed opaque large-blob data.

• Associated data: The value 0x626c6f62 ("blob") || uint64LittleEndian(origSize).

• Key: the 32-byte value stored using the largeBlobKey extension.

6.10.4. Reading per-credential large-blob data

The platform SHOULD perform the following steps in order to read the opaque large-blob data for a given credential. The platform must know the credential ID of the intended credential a priori, which it might have been given, or might have learnt from performing an authenticatorGetAssertion operation without an allowList parameter.

1. If the authenticator does not support the largeBlobKey extension, as defined in that section, return an error.

2. Perform an authenticatorGetAssertion operation with "largeBlobKey": true in the extensions map in order to fetch the largeBlobKey for the credential. (This step may be skipped if the pertinent output is already known.)

3. If largeBlobKey is not included in the authenticatorGetAssertion response structure (i.e., not in the extensions field of the authenticator data) then return that no large blob exists.

4. Let key be the value of largeBlobKey in the assertion result. If it is not 32 bytes long, return an error.

5. Fetch the large-blob array. If this fails, return an error.

6. For each element in that array:

   1. If the element is not a map conforming to the large-blob map structure defined above, skip this array element.

   2. Perform an AEAD_AES_256_GCM authenticated decryption of ciphertext using key, nonce, and the associated data specified above. If the decryption fails, skip this array element.

   3. Decompress the resulting plaintext with DEFLATE [RFC1951]. If decompression fails, return an error.

   4. If the length of the decompression result is not equal to origSize, return an error.

   5. Return the decompression result as the opaque large-blob data for the credential.

7. Return that no large blob exists.

Note: DEFLATE has a maximum compression ratio of over 1000:1, thus the result of decompressing a small amount of data can be extremely large which might cause excessive memory use. Platforms SHOULD limit the maximum permitted value of origSize and that maximum SHOULD be at least 1MiB.

6.10.5. Writing per-credential large-blob data for a new credential

The platform SHOULD perform the following steps in order to write the opaque large-blob data for a new credential.

1. If the authenticator does not support the largeBlobKey extension, as defined in that section, return an error.

2. If the authenticatorMakeCredential operation for the new credential does not map rk to true in the options map, return an error. (Large blobs are only applicable for discoverable credentials.)

3. Perform the authenticatorMakeCredential operation for the new credential. In the extensions input additionally map largeBlobKey to true.

4. Let key be the largeBlobKey returned in the authenticatorMakeCredential response structure.

5. Let origData equal the opaque large-blob data.

6. Let origSize be the length, in bytes, of origData.

7. Let plaintext equal origData after compression with DEFLATE [RFC1951].

8. Let nonce be a fresh, random, 12-byte value.

9. Let ciphertext be the AEAD_AES_256_GCM authenticated encryption of plaintext using key, nonce, and the associated data as specified above.

10. Fetch the large-blob array. If this fails, return an error.

11. Append an element to the array, following the structure above, containing nonce, origSize, and ciphertext.

12. Perform the actions for writing the new large-blob array.

6.10.6. Updating per-credential large-blob data

Unlike the underlying largeBlobKey data, the opaque large-blob data for a credential may be updated or deleted. Given a credential, the platform SHOULD perform the following steps in order to update or delete it:

1. If the authenticator does not support the largeBlobKey extension, as defined in that section, return an error.

2. Perform an authenticatorGetAssertion operation with "largeBlobKey": true in the extensions map in order to fetch the largeBlobKey for the credential. (This step may be skipped if the pertinent output is already known.)

3. If largeBlobKey is not included in the authenticatorGetAssertion response structure (i.e., not in the extensions field of the authenticator data) then return that no large blob exists.

4. Let key be the value of largeBlobKey in the authenticatorGetAssertion response structure. If it is not 32 bytes long, return an error.

5. Fetch the large-blob array. If this fails, return an error.

6. For each element in that array:

   1. If the element is not a map conforming to the large-blob map structure defined above, skip this array element.

   2. Perform an AEAD_AES_256_GCM authenticated decryption of ciphertext using key, nonce, and the associated data specified above. If the decryption fails, skip this array element.

   3. If the platform wishes to delete the opaque large-blob data:

      1. Erase the current array element.

   4. Else (i.e. the platform wishes to update the opaque large-blob data):

      1. Let origData equal the new opaque large-blob data.

      2. Let origSize be the length, in bytes, of origData.

      3. Let plaintext equal origData after compression with DEFLATE [RFC1951].

      4. Let nonce be a fresh, random, 12-byte value.

      5. Let ciphertext be the AEAD_AES_256_GCM authenticated encryption of plaintext using key, nonce, and the associated data as specified above.

      6. Replace the current array element with a map, following the structure above, containing nonce, origSize, and ciphertext.

   5. Perform the actions for writing the new large-blob array.

   6. Return success.

7. Return an error.

6.10.7. Garbage collection of large-blob data

Large blobs may remain even when the linked credential has been erased. This can occur when a platform that doesn’t support large blobs deletes a credential, or when a credential is implicitly deleted because a new credential with the same user ID and RP ID is created. Thus platform MAY perform a garbage collection at will and SHOULD perform a garbage collection when a large-blob cannot be stored because of lack of space, or when using credential management to enumerate credentials for other reasons.

Performing a garbage collection involves the following steps:

1. If credMgmt is not present in the options field of the authenticatorGetInfo response, garbage collection is not possible.

2. Use the authenticatorCredentialManagement command to enumerate all RPs with discoverable credentials, and then to enumerate all credentials for each of them.

3. Collect the set of largeBlobKey values returned, ignoring any that are not 32 bytes long.

4. Fetch the large-blob array. If this fails, return an error.

5. For each element in that array:

   1. If the element is not a map conforming to the large-blob map structure defined above, skip this array element. (The large-blob map is permitted to include extra elements.)

   2. Perform an AEAD_AES_256_GCM authenticated decryption of ciphertext using nonce, the associated data specified above, and each of the largeBlobKey values in turn as the key. If the decryption fails in every case, erase this array element.

6. If any array elements were erased then perform the actions for writing the updated large-blob array.

6.11. authenticatorConfig (0x0D)

Note: Platforms MUST NOT invoke this command unless the authnrCfg option ID is present and true in the response to an authenticatorGetInfo command.

This command is used to configure various authenticator features through the use of its subcommands.

It takes the following input map containing its input parameters:

The currently defined authenticatorConfig subcommands are:

This authenticatorConfig command allows the platform to invoke various simple configuration operations on an authenticator. Parameters may be passed into subcommands, and only status codes are returned (i.e. no response map is defined). Typically, the platform may subsequently request and examine an authenticatorGetInfo response, per directions given for each subcommand, in order to ascertain results of having invoked the subcommand.

Authenticators MAY implement none, some, or all currently defined authenticatorConfig subcommands.

Note: The vendorPrototype subCommand is reserved for vendor-specific authenticator configuration and experimentation. Platforms are not expected to generally utilize this subCommand.

To invoke authenticatorConfig the platform performs the following actions:

1. The platform sends the authenticatorConfig command with the following parameters:

   1. subCommand (0x01): The subcommand selected by the platform from the currently defined authenticatorConfig subcommands.

   2. subCommandParams (0x02): Map containing subcommand parameters, if the selected subcommand takes parameters.

   3. pinUvAuthProtocol (0x03): as selected when obtaining the shared secret.

   4. pinUvAuthParam (0x04): the result of calling authenticate(pinUvAuthToken, 32×0xff || 0x0d || uint8(subCommand) || subCommandParams).

The authenticator performs the following actions upon receipt of this command:

1. If subCommand is not present in the input map, return CTAP2_ERR_MISSING_PARAMETER.

2. If the authenticator does not support the subcommand being invoked, per subCommand's value, return CTAP1_ERR_INVALID_PARAMETER.

3. If the following statements are all true:

   1. subCommand value is toggleAlwaysUv (0x02).

   2. The authenticator is not protected by some form of user verification.

   3. The alwaysUv option ID is present and true.

   then go to Step 5.

   Note: This allows for initial configuration of authenticators that have the Always UV feature enabled by default.

4. If the authenticator is protected by some form of user verification or the alwaysUv option ID is present and true:

   1. If pinUvAuthParam is absent from the input map, then end the operation by returning CTAP2_ERR_PUAT_REQUIRED.

   2. If pinUvAuthProtocol is absent from the input map, then end the operation by returning CTAP2_ERR_MISSING_PARAMETER.

   3. If pinUvAuthProtocol is not supported, return CTAP1_ERR_INVALID_PARAMETER.

   4. Call verify(pinUvAuthToken, 32×0xff || 0x0d || uint8(subCommand) || subCommandParams, pinUvAuthParam).

      1. If the verification fails, return CTAP2_ERR_PIN_AUTH_INVALID.

   5. Check whether the pinUvAuthToken has the acfg permission. If not, return CTAP2_ERR_PIN_AUTH_INVALID.

5. Invoke subCommand (see below subsections for each defined subcommand), passing it the subCommandParams map.

6. Return the resulting status code as produced by subCommand, as defined in each subcommand subsection below.

Note: User verification is only checked above if user verification is configured on a device. This implies that authenticatorConfig can be invoked without user verification if user verification is not configured, and the Always UV feature is disabled. This allows organisations to configure authenticators suitably for their environment before distributing them to users. See also authenticatorLargeBlobs.

6.11.1. Enable Enterprise Attestation

This enableEnterpriseAttestation subcommand is only implemented if the enterprise attestation feature is supported. This subcommand does not take any parameters: subCommandParams is ignored.

This subcommand performs the following steps:

1. If the enterprise attestation feature is disabled, then re-enable the enterprise attestation feature and return CTAP2_OK.

   Note: Upon re-enabling the enterprise attestation feature, the authenticator will return an ep option id with the value of true in the authenticatorGetInfo command response upon receipt of subsequent authenticatorGetInfo commands.

2. Else (implying the enterprise attestation feature is enabled) take no action and return CTAP2_OK.

6.11.2. Toggle Always Require User Verification

This toggleAlwaysUv subcommand is only implemented if the Always Require User Verification feature is supported. This subcommand does not take any parameters: subCommandParams is ignored.

This subcommand performs the following steps:

1. If the alwaysUv feature is disabled:

   1. If the makeCredUvNotRqd option ID is present and true, then disable the makeCredUvNotRqd feature and set the makeCredUvNotRqd option ID to false or absent.

   2. Enable the alwaysUv feature and return CTAP2_OK.

   Note: Upon enabling the Always Require User Verification feature, the authenticator will return an alwaysUv option ID with the value of true in the authenticatorGetInfo command response upon receipt of subsequent authenticatorGetInfo commands.

2. Else (implying the alwaysUv feature is enabled)

   1. If disabling the feature is supported:

      1. Set the makeCredUvNotRqd option ID to its default.

      2. Disable the alwaysUv feature and return CTAP2_OK.

   2. Else return CTAP2_ERR_OPERATION_DENIED.

   Note: Authenticators SHOULD support users disabling the Always Require User Verification feature unless required not to by specific external certifications such as [CMVP].

6.11.3. Vendor Prototype Command

This subCommand allows vendors to test authenticator configuration features.

This vendorPrototype subcommand is only implemented if the vendorPrototypeConfigCommands member in the authenticatorGetInfo response is present.

Vendors SHOULD place implemented vendorCommandId values in the vendorPrototypeConfigCommands array.

subCommandParams Fields:

This subCommand MUST include a subCommandParams map that MUST contain vendorCommandId as a member. The vendor randomly selects a 64-bit Unsigned Integer value to use for the value of vendorCommandId, e.g., by using a cryptographic random number generator. An example of such a vendorCommandId value is (in hex): 0x4e5a15aa89d2b8b6. This approach avoids collisions amongst different vendors' vendorCommandIds. Thus there is no need for a registry of vendorCommandId values. One way to easily generate such values is by using the commonly available openssl tool.

This subCommand performs the following steps:

1. If the vendorCommandId value is unknown:

   1. return CTAP2_ERR_INVALID_SUBCOMMAND

2. Else: (implying the vendorCommandId value is known)

   1. Extract any additional members form the subCommandParams map.

   2. Perform Vendor Command specific processing and return any status code it generates. Success MUST be indicated by returning CTAP2_OK.

   Note: Vendors MUST NOT count on obscurity of the vendorCommandId value as any sort of security.

6.11.4. Setting a minimum PIN Length

This setMinPINLength subcommand is only implemented if the setMinPINLength option ID is present.

This command sets the minimum PIN length in Unicode code points to be enforced by the authenticator while changing/setting up a ClientPIN.

Note: This is not applicable for any other type of PIN functionality the authenticator may have.

subCommandParams members defined for this subcommand:

1. Platform sends the following subCommandParams (0x03) map containing following parameters:

   1. newMinPINLength (0x01) (Optional): Minimum PIN length in code points

   2. minPinLengthRPIDs (0x02) (Optional): List of RP IDs allowed to get the current newMinPINLength via minPinLength extension.

   3. forceChangePin (0x03) (Optional): If true a PIN change is required after this command.

2. Authenticator performs following operations upon receiving the request:

   1. If newMinPINLength is absent, then let newMinPINLength be present with the value of current minimum PIN length.

   2. If minPinLengthRPIDs is present and the authenticator does not support the minPinLength extension, return CTAP1_ERR_INVALID_PARAMETER.

   3. If newMinPINLength is less than the current minimum PIN length, return CTAP2_ERR_PIN_POLICY_VIOLATION.

      Note: Minimum PIN lengths may only be increased; they cannot be made shorter.

      NOTE: The authenticator must be reset to return the current minimum PIN length to the pre-configured minimum PIN length.

   4. If the value of forceChangePin is true, then:

      1. If the value of clientPIN is false, then return CTAP2_ERR_PIN_NOT_SET.

      2. Let the value of the forcePINChange authenticatorGetInfo response member be true.

         Note: This will force the user to change their PIN upon the next use of the authenticator, if a PIN is set.

   5. If the value of PINCodePointLength is less than newMinPINLength and the value of clientPIN is true then let the value of the forcePINChange member of the authenticatorGetInfo response be true.

   6. Authenticator stores newMinPINLength as minPINLength.

   7. If minPinLengthRPIDs is present and contains at least one string, then:

      1. If the authenticator does not have a pre-configured list of RP IDs authorized to receive the current minimum PIN length value, the authenticator stores the minPinLengthRPIDs parameter’s list as the entire list of RP IDs authorized to receive the current minimum PIN length value.

      2. Otherwise, if the authenticator has a pre-configured list of RP IDs authorized to receive the current minimum PIN length value, it adds the minPinLengthRPIDs parameter’s list to the immutable pre-configured list. Any previously added RP IDs are overwritten.

         Note: How the authenticator "adds" the minPinLengthRPIDs parameter’s list to the pre-configured list is an implementation detail.

      3. If the authenticator cannot store or add the minPinLengthRPIDs, it returns CTAP2_ERR_KEY_STORE_FULL.

   8. Authenticator returns CTAP2_OK.

6.12. Prototype authenticatorBioEnrollment (0x40) (For backwards compatibility with "FIDO_2_1_PRE")

This superseded command is OPTIONAL and ONLY provided for backwards compatibility with platforms that implemented "FIDO_2_1_PRE" functionality, and have not been updated to "FIDO_2_1". CTAP2.1 platforms MUST NOT use this command if bioEnroll option ID is present in the authenticatorGetInfo response.

If a CTAP2.1 authenticator implements this prototype (0x40) command:

1. The authenticator MUST also implement the authenticatorBioEnrollment (0x09) commands.

2. The authenticator MUST provide the bioEnroll option ID in the authenticatorGetInfo response for feature detection of the CTAP2.1 feature.

3. The authenticator MUST utilize the appropriate PIN protocol’s verify() function to validate the pinUvAuthParam (referred to as pinAuth in the Bio Enrollment Prototype specification), and MUST return CTAP2_ERR_PIN_AUTH_INVALID if verify() returns error.

The feature detection logic for the Bio Enrollment Prototype vendor specific feature is:

1. "FIDO_2_1_PRE" is present in the authenticatorGetInfo response versions member.

2. The userVerificationMgmtPreview option ID in the authenticatorGetInfo response is present and true.

This preview command does not require permissions, thus it is compatible with a pinUvAuthToken generated by the getPinToken command. CTAP 2.1 platforms MUST use the newer authenticatorBioEnrollment (0x09) command if the authenticator supports it.

6.13. Prototype authenticatorCredentialManagement (0x41) (For backwards compatibility with "FIDO_2_1_PRE" )

This superseded command is OPTIONAL and ONLY provided for backwards compatibility with platforms that implemented "FIDO_2_1_PRE" functionality, and have not been updated to "FIDO_2_1". CTAP2.1 platforms MUST NOT use this command if credMgmt option ID is present in the authenticatorGetInfo response.

If a CTAP2.1 authenticator implements this prototype (0x41) command:

1. The authenticator MUST also implement the authenticatorCredentialManagement (0x0A) commands.

2. The authenticator MUST provide the credMgmt option ID in the authenticatorGetInfo response for feature detection of the CTAP2.1 feature.

3. The authenticator MUST utilize the appropriate PIN protocol’s verify() function to validate the pinUvAuthParam (referred to as pinAuth in the Credential Management Prototype specification), and MUST return CTAP2_ERR_PIN_AUTH_INVALID if verify() returns error.

The feature detection logic for the Credential Management Prototype vendor specific feature is:

1. "FIDO_2_1_PRE" is present in the authenticatorGetInfo response versions member.

2. The credentialMgmtPreview option ID in the authenticatorGetInfo response is present and true.

This preview command does not require permissions, thus it is compatible with a pinUvAuthToken generated by the getPinToken command. CTAP 2.1 platforms MUST use the newer authenticatorCredentialManagement (0x0A) command if the authenticator supports it.

7. Feature-Specific Descriptions and Actions

This section provides detailed descriptions of specific features along with normative feature-specific platform (and possibly authenticator) actions whose specification is not appropriate to include in other parts of this specification.

7.1. Enterprise Attestation

An enterprise is some form of organization, often a business entity. An enterprise context is in effect when a device, e.g., a computer, an authenticator, etc., is controlled by an enterprise.

An enterprise attestation is an attestation that may include uniquely identifying information. This is intended for controlled deployments within an enterprise where the organization wishes to tie registrations to specific authenticators.

The expectation is that enterprises will work directly with their authenticator vendor(s) in order to source their enterprise attestation capable authenticators.

An enterprise attestation capable authenticator MAY be configured to support either or both:

• Vendor-facilitated enterprise attestation:

  In this case, an enterprise attestation capable authenticator, on which enterprise attestation is enabled, upon receiving the enterpriseAttestation parameter with a value of 1 (or 2, see Note below) on a authenticatorMakeCredential command, will provide enterprise attestation to a non-updateable pre-configured RP ID list, as identified by the enterprise and provided to the authenticator vendor, which is "burned into" the authenticator by the vendor.

  If enterprise attestation is requested for any RP ID other than the pre-configured RP ID(s), the attestation returned along with the new credential is a regular privacy-preserving attestation, i.e., NOT an enterprise attestation.

• Platform-managed enterprise attestation:

  In this case, an enterprise attestation capable authenticator on which enterprise attestation is enabled, upon receiving the enterpriseAttestation parameter with a value of 2 on a authenticatorMakeCredential command, will return an enterprise attestation. The platform is enterprise-managed and has already performed the necessary vetting of the RP ID.

  Note: Authenticators wishing to support only vendor-facilitated enterprise attestation MAY treat enterpriseAttestation = 2 the same as enterpriseAttestation = 1.

7.1.1. Feature detection

The ep option ID in the authenticatorGetInfo response defines feature support detection for this feature.

7.1.2. Platform Actions

A platform wishing to obtain an enterprise attestation, e.g., when running in an enterprise context, SHOULD invoke the authenticatorMakeCredential operation in the following manner:

1. Invoke the authenticatorGetInfo command and examine the returned response structure for the ep Option ID. If ep is not present or present and set to false, the platform SHOULD either terminate these steps or invoke the authenticatorMakeCredential command without the enterpriseAttestation parameter, and skip the following steps.

2. Invoke the authenticatorMakeCredential command and pass the enterpriseAttestation parameter with a value of either 1 or 2.

3. If the platform is operating in a non-enterprise context, it SHOULD display an explicit warning to the user, including the RP ID, notifying the user that they are being uniquely identified to this Relying Party.

7.1.3. Authenticator Actions

If an enterprise attestation capable authenticator receives an authenticatorReset command, it MUST disable the enterprise attestation feature. The enterprise attestation feature may be re-enabled by invoking the authenticatorConfig command’s enable-enterprise-attestation subcommand.

7.2. Always Require User Verification

This feature allows a user to protect the credentials on their authenticator with some form of user verification independent of the Relying Party requesting some form of user verification in its higher-level API request, e.g., via [WebAuthn]. Platform authenticators and other authenticators with the alwaysUv feature enabled will always perform user verification and set the "uv" bit to true in the response, e.g., even if the Relying Party sets user verification to Discouraged in a [WebAuthn] request. Some external certification programs such as [CMVP] for [FIPS140-3] prohibit the authenticator performing signing operations without authentication. This feature allows authenticators to conform to such non FIDO certification requirements.

Note: Platform authenticators typically provide users and platforms this sort of behaviour via private API.

7.2.1. Feature detection

The alwaysUv option ID in the authenticatorGetInfo response defines feature support detection for this feature.

7.2.2. Platform Actions

1. If the feature is supported and enabled: (alwaysUv is present and true)

   1. The platform SHOULD treat all Relying Party requests (e.g., those being made by a Relying Party via [WebAuthn] or a platform API) as requiring user verification.

   2. If the authenticator is not protected by some form of user verification, the platforms SHOULD help users enroll a clientPin and or a built-in user verification method, if either or both are supported.

2. Platforms may enable or disable this feature by invoking the authenticatorConfig command’s toggleAlwaysUv subcommand.

7.2.3. Authenticator Actions

1. If the feature is supported and enabled: (alwaysUv is present and true)

   1. The authenticator MUST require some form of user verification for the authenticatorMakeCredential and authenticatorGetAssertion commands.

   2. Authenticators supporting CTAP1/U2F MUST protect the credentials with built-in user verification methods, or disable CTAP1/U2F when the alwaysUv option ID is present and true.

   3. If the "uv" bit set in the response is false some authenticators conforming to [FIPS140-3] or other security requirements may return an syntactically-correct but invalid signature (i.e., one that no credential public key minted by this authenticator, now or ever, will match) rather than a signature from the private key from the selected credential. An example for a ECDSA signature is to return a fixed value of (1, 1). Thus the returned signature will not be verifiable, which is up to the Relying Party to handle. This approach avoids returning an error to the platform because doing that would interfere with some platforms' approach of "pre-flighting" the allowList or excludeList.

2. If the feature is supported and disabled: (alwaysUv is present and false)

   1. The authenticator does not always require user verification for its operations. It is dependent on the parameters passed to individual operations as specified herein.

3. After an authenticator reset:

   1. Set the makeCredUvNotRqd option ID to its default pre-configured state.

   2. Set the alwaysUv option ID to its default pre-configured state (may be either true or false).

7.2.4. Disabling CTAP1/U2F

Authenticators MUST disable CTAP1/U2F when the alwaysUv option ID is present and true in the authenticatorGetInfo response, unless the CTAP1/U2F authenticator is protected by a built-in user verification method. When CTAP1/U2F is disabled:

1. The authenticator MUST NOT return "U2F_V2" in the versions array.

2. The U2F_REGISTER and U2F_AUTHENTICATE commands MUST immediately fail and return SW_COMMAND_NOT_ALLOWED.

7.3. Authenticator Certifications

The certifications member provides a hint to the platform with additional information about certifications that the authenticator has received. Certification programs may revoke certification of specific devices at any time. Relying partys are responsible for validating attestations and AAGUID via appropriate methods. Platforms may alter their behaviour based on these hints such as selecting a PIN protocol or credProtect level.

7.3.1. Authenticator Actions

An authenticator’s supported certifications MAY be returned in the certifications member of an authenticatorGetInfo response.

All certifications are in the form key-value pairs with string IDs and integer values. The following table lists all defined certification types as of CTAP version "FIDO_2_1":

7.4. Set Minimum PIN Length

This feature allows a Relying Party (e.g., an enterprise) to enforce a minimum pin length policy for authenticators registering credentials by examining the return value of the Minimum PIN Length Extension (minPinLength). The authenticatorConfig command’s setMinPINLength subCommand allows the platform to set the minimum pin length policy for authenticator, force a change of PIN before allowing User Verification, and setting the list of minPinLengthRPIDs that allow the specified RP ID to receive the extension response.

If this feature is supported, the authenticator MUST implement:

1. The ClientPIN feature.

2. The setMinPINLength subCommand of the authenticatorConfig command.

3. The Minimum PIN Length Extension (minPinLength).

7.4.1. Feature detection

The setMinPinLength option ID in the authenticatorGetInfo response defines feature support detection for this feature.

7.4.2. Platform Actions

Note: Because ClientPIN must be implemented for this set minimum PIN length feature to be implemented, basic minimum PIN length enforcement already occurs. This feature is only about providing for the minimum PIN length to be altered from its pre-configured value.

1. If the forcePINChange member of the authenticatorGetInfo response is present and true:

   1. The platform should guide the user to change the PIN before invoking the getPinToken or getPinUvAuthTokenUsingPinWithPermissions subcommands.

2. Platforms may perform the following actions by invoking the authenticatorConfig command’s setMinPINLength subcommand:

   1. Increase the minimum pin length for clientPin.

   2. Set the minPinLengthRPIDs parameter’s list to allow Relying Parties receiving the minPinLength extension.

   3. Set the authenticator to require a PIN change before allowing clientPin based authentication.

7.4.3. Authenticator Actions

1. If this feature is enabled the extension identifier minpinlength in the extensions member of the authenticatorGetInfo response MUST be present.

2. After an authenticator reset:

   1. Set the minPINLength member of the authenticatorGetInfo response to its default pre-configured minimum PIN length.

   2. Set the minPinLengthRPIDs parameter’s list to the immutable pre-configured list, if any. Any previously added RP IDs are removed.

   3. Set the forcePINChange member of the authenticatorGetInfo response to false.

8. Message Encoding

Many transports (e.g., Bluetooth Smart) are bandwidth-constrained, and serialization formats such as JSON are too heavy-weight for such environments. For this reason, all encoding is done using the concise binary encoding CBOR [RFC8949].

To reduce the complexity of the messages and the resources required to parse and validate them, all messages MUST use the CTAP2 canonical CBOR encoding form as specified below, which differs from the canonicalization suggested in Section 3.9 of [RFC8949]. All encoders MUST serialize CBOR in the CTAP2 canonical CBOR encoding form without duplicate map keys. All decoders SHOULD reject CBOR that is not validly encoded in the CTAP2 canonical CBOR encoding form and SHOULD reject messages with duplicate map keys.

The CTAP2 canonical CBOR encoding form uses the following rules:

• Integers MUST be encoded as small as possible.

  • 0 to 23 and -1 to -24 MUST be expressed in the same byte as the major type;

  • 24 to 255 and -25 to -256 MUST be expressed only with an additional uint8_t;

  • 256 to 65535 and -257 to -65536 MUST be expressed only with an additional uint16_t;

  • 65536 to 4294967295 and -65537 to -4294967296 MUST be expressed only with an additional uint32_t.

• The representations of any floating-point values are not changed.

  Note: The size of a floating point value—16-, 32-, or 64-bits—is considered part of the value for the purpose of CTAP2. E.g., a 16-bit value of 1.5, say, has different semantic meaning than a 32-bit value of 1.5, and both can be canonical for their own meanings.

• The expression of lengths in major types 2 through 5 MUST be as short as possible. The rules for these lengths follow the above rule for integers.

• Indefinite-length items MUST be made into definite-length items.

• The keys in every map MUST be sorted lowest value to highest. The sorting rules are:

  • If the major types are different, the one with the lower value in numerical order sorts earlier.

  • If two keys have different lengths, the shorter one sorts earlier;

  • If two keys have the same length, the one with the lower value in (byte-wise) lexical order sorts earlier.

  Note: These rules are equivalent to a lexicographical comparison of the canonical encoding of keys for major types 0-3 and 7 (integers, strings, and simple values). They differ for major types 4-6 (arrays, maps, and tags), which CTAP2 does not use as keys in maps. These rules should be revisited if CTAP2 does start using the complex major types as keys.

• Tags as defined in Section 2.4 in [RFC8949] MUST NOT be present.

Because some authenticators are memory constrained, the depth of nested CBOR structures used by all message encodings is limited to at most four (4) levels of any combination of CBOR maps and/or CBOR arrays. Authenticators MUST support at least 4 levels of CBOR nesting. Clients, platforms, and servers MUST NOT use more than 4 levels of CBOR nesting.

Likewise, because some authenticators are memory constrained, the maximum message size supported by an authenticator MAY be limited. By default, authenticators MUST support messages of at least 1024 bytes. Authenticators MAY declare a different maximum message size supported using the maxMsgSize authenticatorGetInfo result parameter. Clients, platforms, and servers MUST NOT send messages larger than 1024 bytes unless the authenticator’s maxMsgSize indicates support for the larger message size. Authenticators MAY return the CTAP2_ERR_REQUEST_TOO_LARGE error if size or memory constraints are exceeded.

If map keys are present that an implementation does not understand, they MUST be ignored. Note that this enables additional fields to be used as new features are added without breaking existing implementations.

Messages from the host to authenticator are called "commands" and messages from authenticator to host are called "responses". All values are big endian encoded.

Authenticators SHOULD return the CTAP2_ERR_INVALID_CBOR error if received CBOR does not conform to the requirements above.

Several commands reference externally-defined structures such as PublicKeyCredentialRpEntity which, for the purposes of this protocol, are encoded as CBOR. The rules and behaviours for processing such CBOR are defined above, but such structures can also be invalid because of missing required fields, or because values have an incorrect type. If structures in messages from the host are missing required members, or the values of those members have the wrong type, then the authenticator SHOULD return CTAP2_ERR_CBOR_UNEXPECTED_TYPE.

8.1. Command Codes

The assigned values for vendor specific commands and their descriptions are:

If an authenticator receives a command code it does not implement, it MUST return CTAP1_ERR_INVALID_COMMAND. If the authenticator implements a command code having subcommands, but does not implement an invoked subcommand, it MUST return CTAP2_ERR_INVALID_SUBCOMMAND.

Note: Some authenticators implementing earlier versions of this specification may not behave as specified by the prior paragraph, because this behavior was only implied at that time.

Command codes in the range between authenticatorVendorFirst and authenticatorVendorLast may be used for vendor-specific implementations. For example, the vendor may choose to put in some testing commands. Note that the FIDO client will never generate these commands. All other command codes are reserved for future use and may not be used.

Command parameters are encoded using a CBOR map (CBOR major type 5). The CBOR map MUST be encoded using the definite length variant.

Some commands have optional parameters. Therefore, the length of the parameter map for these commands may vary. For example, authenticatorMakeCredential may have 4, 5, 6, or 7 parameters, while authenticatorGetAssertion may have 2, 3, 4, or 5 parameters.

All command parameters are CBOR encoded following the JSON to CBOR conversion procedures as per the CBOR specification [RFC8949]. Specifically, parameters that are represented as DOM objects in the Authenticator API layers (formally defined in the Web API [WebAuthn]) are converted first to JSON and subsequently to CBOR.

8.2. Status codes

The error response values range from 0x01 - 0xff. This range is split based on error type.

Error response values in the range between CTAP2_OK and CTAP2_ERR_SPEC_LAST are reserved for spec purposes.

Error response values in the range between CTAP2_ERR_VENDOR_FIRST and CTAP2_ERR_VENDOR_LAST may be used for vendor-specific implementations. All other response values are reserved for future use and may not be used. These vendor specific error codes are not interoperable and the platform SHOULD treat these errors as any other unknown error codes.

Error response values in the range between CTAP2_ERR_EXTENSION_FIRST and CTAP2_ERR_EXTENSION_LAST may be used for extension-specific implementations. These errors need to be interoperable for vendors who decide to implement such optional extension.