7.2.1 Extending request parameters

An extension defines two request arguments. The client argument is passed from the RP to the client in the getAssertion or makeCredential call, while the authenticator argument is passed from the client to the authenticator during the processing of these calls, either natively or through the external authenticator protocol [FIDOEAP].

Extension definitions MUST specify the valid values for their client argument. Clients are free to ignore extensions with an invalid client argument. Specifying an authenticator argument is optional, since some extensions may only affect client processing.

An RP simultaneously requests the use of an extension and sets its client argument by including an entry in the extensions dictionary parameter to the getAssertion or makeCredential call. The entry key MUST be the extension identifier, and the value MUST be the client argument.

var assertionPromise = credentials.getAssertion(..., /* extensions */ {
  "com.example.fido.foobar": 42
});

Extensions that affect the behavior of the client platform can define their argument to be any set of values that can be encoded in JSON. Such an extension will in general (but not always) specify additional values to the clientData structure (see below). It may also specify an authenticator argument that platforms implementing the extension are expected to send to the authenticator. The authenticator argument should be a byte string.

For extensions that specify additional authenticator processing only, it is desirable that the platform need not know the extension. To support this, platforms SHOULD pass the client argument of unknown extension as the authenticator argument unchanged, under the same extension identifier. The authenticator argument should be the CBOR encoding of the client argument, as specified in Section 4.2 of [RFC7049]. Clients SHOULD silently drop unknown extensions whose client argument cannot be encoded as a CBOR structure.

7.2.2 Extending client processing

Extensions may define additional processing requirements on the client platform during the creation of credentials or the generation of an assertion. In order for the RP to verify the processing took place, or if the processing has a result value that the RP needs to be aware of, the extension should specify a client data value to be included in the clientData structure.

The value may be any value that can be encoded as a JSON value. If any extension processed by a client defines such a value, the client SHOULD include a dictionary in clientData with the key extensions. For each such extension, the client SHOULD add an entry to this dictionary with the extension identifier as the key, and the extension's client data value.

7.2.3 Extending authenticator processing with signature extensions

Signature extensions that define additional authenticator processing should similarly define an authenticator data value. The value may be any data that can be encoded as a CBOR value. An authenticator that processes a signature extension that defines such a value must include it in the authenticatorData.

As specified in 4. Authenticator data, the authenticator data value of each processed extension is included in the extended data part of the authenticatorData. This part is a CBOR map, with extension identifiers as keys, and the authenticator data value of each extension as the value.

7.2.4 Example extension

This section is non-normative.

To illustrate the requirements above, consider a hypothetical extension Geo. This extension, if supported, lets both clients and authenticators embed their geolocation in signatures.

The extension identifier is chosen as com.example.fido.geo. The client argument is the constant value true, since the extension does not require the RP to pass any particular information to the client, other than that it requests the use of the extension. The RP sets this value in its request for an assertion:

  var assertionPromise =
      credentials.getAssertion("SGFuIFNvbG8gc2hvdCBmaXJzdC4",
          {}, /* Empty filter */
          { 'com.example.fido.geo': true });
  

The extension defines the additional client data to be the client's location, if known, as a GeoJSON [GeoJSON] point. The client constructs the following client data:

  {
     ...,
     'extensions': {
         'com.example.fido.geo': {
             'type': 'Point',
             'coordinates': [65.059962, -13.993041]
         }
     }
  }
  

The extension also requires the client to set the authenticator parameter to the fixed value 1.

Finally, the extension requires the authenticator to specify its geolocation in the authenticator data, if known. The extension e.g. specifies that the location shall be encoded as a two-element array of floating point numbers, encoded with CBOR. An authenticator does this by including it in the authenticatorData. As an example, authenticator data may be as follows (notation taken from [RFC7049]):

  81 (hex)                      -- Flags, ED and TUP both set.
  20 05 58 1F                   -- Signature counter
  A1                            -- CBOR map of one element
    68                          -- Key 1: CBOR text string of 8 bytes
      66 69 64 6F 2E 67 65 6F   -- "fido.geo" UTF-8 string
    82                          -- Value 1: CBOR array of two elements
      FA 42 82 1E B3            -- Element 1: Latitude as CBOR encoded float
      FA C1 5F E3 7F            -- Element 2: Longitude as CBOR encoded float
  

7.3.1 Transaction authorization

This signature extension allows for a simple form of transaction authorization. A relying party can specify a prompt string, intended for display on a trusted device on the authenticator.

Extension identifier

fido.txauth.simple

Client argument

A single UTF-8 encoded string prompt

Client processing

None, except default forwarding of client argument to authenticator argument.

Authenticator argument

The client argument encoded as a CBOR text string (major type 3).

Authenticator processing

The authenticator MUST display the prompt to the user before performing the user verification / test of user presence. The authenticator may insert line breaks if needed.

Authenticator data

A single UTF-8 string, representing the prompt as displayed (including any eventual line breaks).

Extension identifier

fido.txauth.generic

Client argument

A CBOR map with one pair of data items (CBOR tagged as 0xa1). The pair of data items consists of

1. one UTF-8 encoded string contentType, containing the MIME-Type of the content, e.g. "image/png"
2. and the content itself, encoded as CBOR byte array.

Client processing

None, except default forwarding of client argument to authenticator argument.

Authenticator argument

The client argument encoded as a CBOR map.

Authenticator processing

The authenticator MUST display the content to the user before performing the user verification / test of user presence. The authenticator may add other information below the content. No changes are allowed to the content itself, i.e. inside content boundary box.

Authenticator data

The hash value of the content which was displayed. The authenticator MUST use the same hash algorithm as it uses for the signature itself.

7.3.2 Authenticator Selection Extension

This registration extension allows a Relying Party to guide the selection of the authenticator that will be leveraged when creating the credential. It is intended primarily for Relying Parties that wish to tightly control the experience around credential creation.

Extension identifier

fido.authn-sel (only used during makeCredential)

Client argument

A sequence of AAGUIDs:

typedef sequence < AAGUID > AuthenticatorSelectionList;
      

Each AAGUID corresponds to an authenticator attestation that is acceptable to the RP for this credential creation. The list is ordered by decreasing preference.
An AAGUID is defined as a DOMString, and is the globally unique identifier of the authenticator attestation being sought.

typedef DOMString AAGUID;
      

Client processing

If the client supports the Authenticator Selection Extension, it MUST use the first available authenticator whose AAGUID is present in the AuthenticatorSelectionList. If none of the available authenticators match a provided AAGUID, the client MUST select an authenticator from among the available authenticators to generate the credential.

Authenticator argument

There is no authenticator argument.

Authenticator processing

None.