1.1 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].

3.1 Low-level MessagePort API

RP web pages communicate with the FIDO client over an instance of the HTML5 MessagePort interface. Client implementations may choose how this instance is made available to web pages.

Messages sent to the FIDO client SHOULD be Request dictionaries:

dictionary Request {
    DOMString          type;
    SignRequest[]      signRequests;
    RegisterRequest[]? registerRequests;
    int?               timeoutSeconds;
    optional int?      requestId;
};

SignRequest and RegisterRequest are defined below. If timeoutSeconds is omitted, timeout behavior is unspecified. If requestId is present, the FIDO client MUST include its value the corresponding Response dictionary under the same key.

Responses from the FIDO client to the RP webpage SHOULD be Response dictionaries:

dictionary Response {
    DOMString                                   type;
    (Error or RegisterResponse or SignResponse) responseData;
    int?                                        requestId;
};

Errors are indicated by an Error dictionary sent as the response data. An error dictionary can be identified by checking for its non-zero integer errorCode key. RegisterResponse and SignResponse do not define this key. An error object may optionally contain a string errorMessage with further description of the error.

dictionary Error {
    ErrorCode  errorCode;
    DOMString? errorMessage;
};

3.2 High-level Javascript API

A FIDO client MAY provide a JavaScript convenience API that abstracts the lower-level MessagePort API. Implementations may choose how to make such an API available to RP web pages. If such an API is provided, it SHOULD provide a namespace object u2f of the following interface.

interface u2f {
    void register (RegisterRequest[] registerRequests, SignRequest[] signRequests, function(RegisterResponse or Error) callback, optional int? opt_timeoutSeconds);
    void sign (SignRequest[] signRequests, function(SignResponse or Error) callback, optional int? opt_timeoutSeconds);
};

The JavaScript API MUST invoke the provided callbacks with either response objects, or an error object. An error can be detected by testing for a non-zero errorCode key.

u2f.sign(reqs, function(response) {
                if (response.errorCode) {
                  // response is an Error
                  ...
                } else {
                  // response is a SignResponse
                  ...
                }
              });

4.1 Registration

To register a U2F token for a user account at the RP, the RP MUST:

• decide which U2F protocol version(s) of device it wants to register,
• pick an appropriate application id for the registration request,
• generate a random challenge, and
• store all private information associated with the registration (expiration times, user ids, etc.)

For each version it is willing to register, it then prepares a RegisterRequest dictionary as follows:

dictionary RegisterRequest {
    DOMString version;
    DOMString challenge;
    DOMString appId;
};

The RP delivers a registration request to the FIDO client either via the low-level MessagePort API, or by invoking the high-level JavaScript API.

// Low-level API
var port = <obtain U2F MessagePort in a browser specific manner>;
port.addEventListener(‘message’, responseHandler);
port.postMessage({
 ‘type’: ‘u2f_register_request’,
 ‘registerRequests’: [<RegisterRequest instance>, ...],
 ‘signRequests’: [<SignRequest for known token 1>, ...],
 ‘timeoutSeconds’: 30,
 ‘requestId’: <unique integer>  // optional
});

// High-level API
u2f.register([<RegisterRequest instance>, ...], 
             [<SignRequest for known token 1>, ...],
             registerResponseHandler);

The FIDO client SHOULD treat the order of RegisterRequest dictionaries in the first parameter as a prioritized list. That is, if multiple tokens are present that support more than one version provided by the RP, the version that appears first should be selected. Note that this means multiple RegisterRequests with the same version are redundant, since the first one will always be selected.

Note also that the responseHandler in the low-level API receives a Response object, while the registerResponseHandler in the high-level API receives the Error or RegisterResponse objects directly.

The FIDO client will create the raw registration and sign request messages from this data (see [U2FRawMsgs] in bibliography), and attempt to perform a registration operation with a U2F token. The sign request messages will have the (internal) checkOnly boolean of the control state set to true, and are used to identity such U2F tokens that are already registered with the relying party. The registration request message is then used to register a U2F token that is not already registered (if such a token is present).

Note that as part of creating the registration request message, the FIDO client will create a Client Data object (see [U2FRawMsgs]). This Client Data object will be returned to the caller as part of the registration response (see below).

If the registration is successful, the FIDO client returns (via the message port, or the JS API callback) a RegisterResponse dictionary as follows.

dictionary RegisterResponse {
    DOMString registrationData;
    DOMString clientData;
};

4.2 Generating signed identity assertions

To obtain an identity assertion from a locally-attached U2F token, the RP must

• prepare a SignRequest object for each U2F token that the user has currently registered with the RP.

dictionary SignRequest {
    DOMString version;
    DOMString challenge;
    DOMString keyHandle;
    DOMString appId;
};

In response to a sign request, the FIDO client should perform the following steps:

• Verify the application identity of the caller.
• Using the provided challenge, create a client data object.
• Using the client data, the application id, and the key handle, create a raw authentication request message (see [U2FRawMsgs] in bibliography) and send it to the U2F token.

Eventually the FIDO client must respond (via the MessageChannel or the provided callback). In the case of an error, an Error dictionary is returned. In case of success, a SignResponse is returned.

dictionary SignResponse {
    DOMString keyHandle;
    DOMString signatureData;
    DOMString clientData;
};

If there are multiple U2F tokens that responded to the authentication request, the FIDO client will pick one of the responses and pass it to the caller.

4.3 Error codes

When an Error object is returned, its errorCode field is set to a non-negative integer indicating the general error that occurred, from the following enumeration.

interface ErrorCode {
    const int OK = 0;
    const int OTHER_ERROR = 1;
    const int BAD_REQUEST = 2;
    const int CONFIGURATION_UNSUPPORTED = 3;
    const int DEVICE_INELIGIBLE = 4;
    const int TIMEOUT = 5;
};