Notation

Type names, attribute names and element names are written as code.

String literals are enclosed in “”, e.g. “UAF-TLV”.

In formulas we use “|” to denote byte wise concatenation operations.

DOM APIs are described using the ECMAScript [[!ECMA-262]] bindings for WebIDL [[!WebIDL]].

U2F specific terminology used in this document is defined in [[!FIDOGlossary]].

Symbolic constants such as U2F_REGISTER which are referred to when defining messages in this documents have their values defined in (See [[!U2FHeader]] in bibliography].

Key Words

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

Introduction

Note: Reading the 'FIDO U2F Overview' (see [[U2FOverview]] in bibliography) is recommended as a background for this document.

U2F Tokens provide cryptographic assertions that can be verified by relying parties. Typically, the relying party is a web server, and the cryptographic assertions are used as second-factors (in addition to passwords) during user authentication.

U2F Tokens are typically small special-purpose devices that aren't directly connected to the Internet (and hence, able to talk directly to the relying party). Therefore, they rely on a FIDO Client to relay messages between the token and the relying party. Typically, the FIDO Client is a web browser.

The U2F protocol supports two operations, registration and authentication. The registration operation introduces the relying party to a freshly-minted keypair that is under control of the U2F token. The authentication operation proves possession of a previously-registered keypair to the relying party. Both the registration and authentication operation consist of three phases:

  1. Setup: In this phase, the FIDO Client contacts the relying party and obtains a challenge. Using the challenge (and possibly other data obtained from the relying party and/or prepared by the FIDO Client itself), the FIDO Client prepares a request message for the U2F Token.

  2. Processing: In this phase, the FIDO Client sends the request message to the token, and the token performs some cryptographic operations on the message, creating a response message. This response message is sent to the FIDO Client.

  3. Verification: In this phase, the FIDO Client transmits the token's response message, along with other data necessary for the relying party to verify the token response, to the relying party. The relying party then processes the token response and verifies its correctness. A correct registration response will cause the relying party to register a new public key for a user, while a correct authentication response will cause the relying party to accept that the client is in possession of the corresponding private key.

Three phases of Registration and Authentication

Above is a picture illustrating the three phases.

At the heart of the U2F protocol are the request messages sent to the U2F token, and the response messages received from the U2F token.1

Note that the request message is usually obtained by the FIDO client from the relying party during the setup phase, and therefore reaches the FIDO client as part of an HTTP response. Similarly, the response message that is processed by the relying party during the verification phase is sent by the FIDO Client to the relying party in an HTTP request. Beware the possibility of confusion when talking about requests and responses!

Request messages are created by the relying party and consumed by the U2F token. Response messages are created by the U2F token and consumed by the relying party.

As the messages flow from relying party (through the FIDO Client) to the U2F token and back, they undergo various transformations and encodings. Some of these transformations and encodings are up to the individual implementations and are not standardized as part of FIDO U2F. For example, FIDO U2F does not prescribe how request and response messages are encoded between the FIDO Client and the relying party.

However, to ensure that U2F tokens from different vendors can work across U2F-compliant web sites certain encodings are standardized:

  1. FIDO U2F standardizes a Javascript API that prescribes how a web application can pass request messages into the FIDO Client (in the case where the web browser is the FIDO Client), and what the encoding of the response messages is.

  2. FIDO U2F standardizes how request and response messages are to be encoded when sent over from the client over the USB transport to U2F tokens. In addition to specifying the encoding, the transport level specification also specifies the format for control messages to the tokens and the format for the error responses from the tokens. We anticipate that FIDO U2F will standardize how request and response messages are encoded over other non-USB transports such as NFC or Bluetooth.

In this document we describe the "raw", or canonical, format of the messages, i.e., without regard to the various encodings that are prescribed in U2F standards or that implementors might choose when sending messages around. The raw format of the messages is important to know for two reasons:

  1. The encoding of messages and parameters described elsewhere may refer to the raw messages described in this document. For example, a Javascript API might refer to a parameter of a function as the Base64-encoding of a raw registration response message. It is this document that describes what the raw registration response message looks like.

  2. Cryptographic signatures are calculated over raw data. For example, the standard might prescribe that a certain cryptographic signature is taken over bytes 5 through 60 of a certain raw message. The implementor therefore has to know how what the raw message looks like.

U2F message framing

The U2F protocol is based on a request-response mechanism, where a requester sends a request message to a U2F device, which always results in a response message being sent back from the U2F device to the requester.

The request message has to be "framed" to send to the lower layer. Taking the signature request as an example, the "framing" is a way for the FIDO client to tell the lower transport layer that it is sending a signature request and then send the raw message contents. The framing also specifies how the transport will carry back the response raw message and any meta-information such as an error code if the command failed.

In this current version of U2F, the framing is defined based on the ISO7816-4:2005 extended APDU format. This is very appropriate for the USB transport since devices are typically built around secure elements which understand this format already. This same argument may apply for futures such as Bluetooth based devices. For other futures based on other transports, such as a built-in u2f token on a mobile device TEE, this framing may not be appropriate and a different framing may need to be defined.

Request Message Framing

The raw request message is framed as a command APDU:

CLA INS P1 P2 LC1 LC2 LC3 <request-data>

Where:

  • CLA: Reserved to be used by the underlying transport protocol (if applicable). The host application shall set this byte to zero.

  • INS: U2F command code, defined in the following sections.

  • P1,P2: Parameter 1 and 2, defined by each command.

  • LC1-LC3: Length of the request data, big-endian coded, i.e. LC1 being MSB and LC3 LSB

  • Response Message Framing

    The raw response data is framed as a response APDU:

    <response-data> SW1 SW2

    Where:

  • SW1,SW2: Status word bytes 1 and 2, forming a 16-bit status word, defined below. SW1 is MSB and SW2 LSB.

  • Status Codes

    The following ISO7816-4 defined status words have a special meaning in U2F:

  • SW_NO_ERROR: The command completed successfully without error.

  • SW_CONDITIONS_NOT_SATISFIED: The request was rejected due to test-of-user-presence being required.

  • SW_WRONG_DATA: The request was rejected due to an invalid key handle.

  • Each implementation may define any other vendor-specific status codes, providing additional information about an error condition. Only the error codes listed above will be handled by U2F FIDO Client, where others will be seen as general errors and logging of these is optional.

    Registration Messages

    Registration Request Message - U2F_REGISTER

    Registration Request Message

    This message is used to initiate a U2F token registration. The FIDO Client first contacts the relying party to obtain a challenge, and then constructs the registration request message. The registration request message has two parts:

    Registration Response Message: Error: Test-of-User-Presence Required

    This is an error message that is output by the U2F token if no test-of-user-presence could be obtained by the U2F token. The error message details are specified in the framing for the underlying transport (see Section "U2F Message Framing" above).

    Registration Response Message: Success

    Registration Response Message

    This message is output by the U2F token once it created a new keypair in response to the registration request message. Note that U2F tokens SHOULD verify user presence before returning a registration response success message (otherwise they SHOULD return a test-of-user-presence-required message - see above). Its raw representation is the concatenation of the following:

    The signature is to be verified by the relying party using the public key certified in the attestation certificate. The relying party should also verify that the attestation certificate was issued by a trusted certification authority. The exact process of setting up trusted certification authorities is to be defined by the FIDO Alliance and is outside the scope of this document.

    Once the relying party verifies the signature, it should store the public key and key handle so that they can be used in future authentication operations.

    Authentication Messages

    Authentication Request Message - U2F_AUTHENTICATE

    Authentication Request Message

    This message is used to initiate a U2F token authentication. The FIDO Client first contacts the relying party to obtain a challenge, and then constructs the authentication request message. The authentication request message has five parts:

    Authentication Response Message: Error: Test-of-User-Presence Required

    This is an error message that is output by the U2F token if no test-of-user-presence could be obtained by the U2F token. The error message details are specified in the framing for the underlying transport (see Section "U2F Message Framing" above).

    Authentication Response Message: Error: Bad Key Handle

    This is an error message that is output by the U2F token if the provided key handle was not originally created by this token, or if the provided key handle was created by this token, but for a different application parameter. The error message details are specified in the framing for the underlying transport (see Section "U2F Message Framing" above).

    Authentication Response Message: Success

    Authentication Response Message: Success

    This message is output by the U2F token after processing/signing the authentication request message described above. Its raw representation is the concatenation of the following:

    Other Messages

    GetVersion Request and Response - U2F_VERSION

    The FIDO Client can query the U2F token about the U2F protocol version that it implements. The protocol version described in this document is U2F_V2.

    The response message's raw representation is the ASCII representation of the string 'U2F_V2' (without quotes).

    Extensions and vendor-specific messages

    Command codes in the range between U2F_VENDOR_FIRST and U2F_VENDOR_LAST 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 RFU and may not be used.

    Client Data

    TermDefinition

    websafe-base64 encoding

    This is the "Base 64 Encoding with URL and Filename Safe Alphabet" from Section 5 in [[!RFC 4648]] without padding.

    stringified javascript object

    This is the JSON object (i.e., a string starting with "{" and ending with "}") whose keys are the property names of the javascript object, and whose values are the corresponding property values. Only "data objects" can be stringified, i.e., only objects whose property names and values are supported in JSON.

    The registration and authentication request messages contain a challenge parameter, which is defined as the SHA-256 hash of a (UTF8 representation of a) stringified JSON data structure that the FIDO client has to prepare. The FIDO Client MUST send the Client Data (rather than its hash - the challenge parameter) to the relying party during the verification phase, where the relying party can re-generate the challenge parameter (by hashing the client data), which is necessary in order to verify the signature both on the registration response message and authentication response message.

    In the case where the FIDO Client is a web browser, the client data is defined as follows (in WebIDL):

    DOMString typ
    the constant 'navigator.id.getAssertion' for authentication, and 'navigator.id.finishEnrollment' for registration
    DOMString challenge
    the websafe-base64-encoded challenge provided by the relying party
    DOMString origin
    the facet id of the caller, i.e., the web origin of the relying party.
    (Note: this might be more accurately called 'facet_id', but for compatibility with existing implementations within Chrome we keep the legacy name.)
    (DOMString or JwkKey) cid_pubkey
    The Channel ID public key used by this browser to communicate with the above origin. This parameter is optional, and missing if the browser doesn't support Channel ID. It is present and set to the constant 'unused' if the browser supports Channel ID, but is not using Channel ID to talk to the above origin (presumably because the origin server didn't signal support for the Channel ID TLS extension).

    Otherwise (i.e., both browser and origin server at the above origin support Channel ID), it is present and of type JwkKey.

    The JwkKey is a dictionary representing the public key used by a browser for the Channel ID TLS extension. The current version of the Channel ID draft prescribes the algorithm ([[!ECDSA-ANSI]] in bibliography) and curve used, so the dictionary will have the following parameters

    DOMString kty
    signature algorithm used for Channel ID, i.e., the constant 'EC'
    DOMString crv
    Elliptic curve on which this public key is defined, i.e., the constant 'P-256'
    DOMString x
    websafe-base64-encoding of the x coordinate of the public key (big-endian, 32-byte value)
    DOMString y
    websafe-base64-encoding of the y coordinate of the public key (big-endian, 32-byte value)

    Examples

    Registration Example

    Assume we have a U2F token with the following private attestation key:

    f3fccc0d00d8031954f90864d43c247f4bf5f0665c6b50cc17749a27d1cf7664

    the corresponding public key:

    048d617e65c9508e64bcc5673ac82a6799da3c1446682c258c463fffdf58dfd2fa3e6c378b53d795c4a4dffb4199edd7862f23abaf0203b4b8911ba0569994e101

    and the following attestation cert:

    [
    [
    Version: V3
    Subject: CN=PilotGnubby-0.4.1-47901280001155957352 Signature Algorithm: SHA256withECDSA, OID = 1.2.840.10045.4.3.2

    Key: EC Public Key
    X:
    8d617e65c9508e64bcc5673ac82a6799da3c1446682c258c463fffdf58dfd2fa Y:
    3e6c378b53d795c4a4dffb4199edd7862f23abaf0203b4b8911ba0569994e101

    Validity: [From: Tue Aug 14 11:29:32 PDT 2012, To: Wed Aug 14 11:29:32 PDT 2013]

    Issuer: CN=Gnubby Pilot
    SerialNumber: [ 47901280 00115595 7352] ]

    Algorithm: [SHA256withECDSA]
    Signature:
    0000: 30 44 02 20 60 CD B6 06 1E 9C 22 26 2D 1A AC 1D 0D. `....."&-...
    0010: 96 D8 C7 08 29 B2 36 65 31 DD A2 68 83 2C B8 36 ....).6e1..h.,.6
    0020: BC D3 0D FA 02 20 63 1B 14 59 F0 9E 63 30 05 57 ..... c..Y..c0.W
    0030: 22 C8 D8 9B 7F 48 88 3B 90 89 B8 8D 60 D1 D9 79 "....H.;....`..y
    0040: 59 02 B3 04 10 DF Y.....
    ]

    The attestation cert in hex form:

    3082013c3081e4a003020102020a47901280001155957352300a06082a8648ce3d0403023017311530130603550403130c476e756262792050696c6f74301e170d3132303831343138323933325a170d3133303831343138323933325a3031312f302d0603550403132650696c6f74476e756262792d302e342e312d34373930313238303030313135353935373335323059301306072a8648ce3d020106082a8648ce3d030107034200048d617e65c9508e64bcc5673ac82a6799da3c1446682c258c463fffdf58dfd2fa3e6c378b53d795c4a4dffb4199edd7862f23abaf0203b4b8911ba0569994e101300a06082a8648ce3d0403020347003044022060cdb6061e9c22262d1aac1d96d8c70829b2366531dda268832cb836bcd30dfa0220631b1459f09e6330055722c8d89b7f48883b9089b88d60d1d9795902b30410df

    Now let's assume that we use the following client data

    {"typ":"navigator.id.finishEnrollment","challenge":"vqrS6WXDe1JUs5_c3i4-LkKIHRr-3XVb3azuA5TifHo","cid_pubkey":{"kty":"EC","crv":"P-256","x":"HzQwlfXX7Q4S5MtCCnZUNBw3RMzPO9tOyWjBqRl4tJ8","y":"XVguGFLIZx1fXg3wNqfdbn75hi4-_7-BxhMljw42Ht4"},"origin":"http://example.com"}

    with hash:

    4142d21c00d94ffb9d504ada8f99b721f4b191ae4e37ca0140f696b6983cfacb

    and application id:

    http://example.com

    with hash:

    f0e6a6a97042a4f1f1c87f5f7d44315b2d852c2df5c7991cc66241bf7072d1c4

    to construct a registration request message.

    Let's say the U2F token generates the following key pair:

    Private key:

    9a9684b127c5e3a706d618c86401c7cf6fd827fd0bc18d24b0eb842e36d16df1

    Public key:

    04b174bc49c7ca254b70d2e5c207cee9cf174820ebd77ea3c65508c26da51b657c1cc6b952f8621697936482da0a6d3d3826a59095daf6cd7c03e2e60385d2f6d9

    Associated key handle:

    2a552dfdb7477ed65fd84133f86196010b2215b57da75d315b7b9e8fe2e3925a6019551bab61d16591659cbaf00b4950f7abfe6660e2e006f76868b772d70c25

    The signature base string for the registration response message is therefore:

    00f0e6a6a97042a4f1f1c87f5f7d44315b2d852c2df5c7991cc66241bf7072d1c44142d21c00d94ffb9d504ada8f99b721f4b191ae4e37ca0140f696b6983cfacb2a552dfdb7477ed65fd84133f86196010b2215b57da75d315b7b9e8fe2e3925a6019551bab61d16591659cbaf00b4950f7abfe6660e2e006f76868b772d70c2504b174bc49c7ca254b70d2e5c207cee9cf174820ebd77ea3c65508c26da51b657c1cc6b952f8621697936482da0a6d3d3826a59095daf6cd7c03e2e60385d2f6d9

    A possible signature over the base string with the above private attestation key is:

    304502201471899bcc3987e62e8202c9b39c33c19033f7340352dba80fcab017db9230e402210082677d673d891933ade6f617e5dbde2e247e70423fd5ad7804a6d3d3961ef871

    Which means the whole registration response message is:

    0504b174bc49c7ca254b70d2e5c207cee9cf174820ebd77ea3c65508c26da51b657c1cc6b952f8621697936482da0a6d3d3826a59095daf6cd7c03e2e60385d2f6d9402a552dfdb7477ed65fd84133f86196010b2215b57da75d315b7b9e8fe2e3925a6019551bab61d16591659cbaf00b4950f7abfe6660e2e006f76868b772d70c253082013c3081e4a003020102020a47901280001155957352300a06082a8648ce3d0403023017311530130603550403130c476e756262792050696c6f74301e170d3132303831343138323933325a170d3133303831343138323933325a3031312f302d0603550403132650696c6f74476e756262792d302e342e312d34373930313238303030313135353935373335323059301306072a8648ce3d020106082a8648ce3d030107034200048d617e65c9508e64bcc5673ac82a6799da3c1446682c258c463fffdf58dfd2fa3e6c378b53d795c4a4dffb4199edd7862f23abaf0203b4b8911ba0569994e101300a06082a8648ce3d0403020347003044022060cdb6061e9c22262d1aac1d96d8c70829b2366531dda268832cb836bcd30dfa0220631b1459f09e6330055722c8d89b7f48883b9089b88d60d1d9795902b30410df304502201471899bcc3987e62e8202c9b39c33c19033f7340352dba80fcab017db9230e402210082677d673d891933ade6f617e5dbde2e247e70423fd5ad7804a6d3d3961ef871

    from which (together with challenge and application parameters) the signature base string and signature can be extracted, and verified with the public key from the attestation cert.

    Authentication Example

    Let's assume we have a U2F device with private key:

    ffa1e110dde5a2f8d93c4df71e2d4337b7bf5ddb60c75dc2b6b81433b54dd3c0

    and corresponding public key:

    04d368f1b665bade3c33a20f1e429c7750d5033660c019119d29aa4ba7abc04aa7c80a46bbe11ca8cb5674d74f31f8a903f6bad105fb6ab74aefef4db8b0025e1d

    Example application id:

    https://gstatic.com/securitykey/a/example.com

    Example client data:

    {"typ":"navigator.id.getAssertion","challenge":"opsXqUifDriAAmWclinfbS0e-USY0CgyJHe_Otd7z8o","cid_pubkey":{"kty":"EC","crv":"P-256","x":"HzQwlfXX7Q4S5MtCCnZUNBw3RMzPO9tOyWjBqRl4tJ8","y":"XVguGFLIZx1fXg3wNqfdbn75hi4-_7-BxhMljw42Ht4"},"origin":"http://example.com"}

    Hash of the above client data (challenge parameter):

    ccd6ee2e47baef244d49a222db496bad0ef5b6f93aa7cc4d30c4821b3b9dbc57

    Hash of the above application id (application parameter):

    4b0be934baebb5d12d26011b69227fa5e86df94e7d94aa2949a89f2d493992ca

    Assuming counter = 1 and user_presence = 1, signature base string is:

    4b0be934baebb5d12d26011b69227fa5e86df94e7d94aa2949a89f2d493992ca0100000001ccd6ee2e47baef244d49a222db496bad0ef5b6f93aa7cc4d30c4821b3b9dbc57

    A possible signature with above private key is:

    304402204b5f0cd17534cedd8c34ee09570ef542a353df4436030ce43d406de870b847780220267bb998fac9b7266eb60e7cb0b5eabdfd5ba9614f53c7b22272ec10047a923f

    Authentication Response Message:

    0100000001304402204b5f0cd17534cedd8c34ee09570ef542a353df4436030ce43d406de870b847780220267bb998fac9b7266eb60e7cb0b5eabdfd5ba9614f53c7b22272ec10047a923f

    The above signature and signature base string can be reconstructed from the authentication response message and the challenge and application parameters, and can be verified with the above public key.