U2FVAL REST API

U2FVAL REST API (V1)

Note	There is a newer version of this API available here.

U2FVAL exposes its functionality over a REST API, which is made accessible to authenticated clients. Clients are responsible for supplying a unique-per-user persistent identifier for each user in its system in the form of a string no more than 32 characters long. Usernames should only be used if they are immutable. This user identification string is denoted userId in the API below.

JavaScript object type definitions

The following JavaScript objects are used when interacting with the REST API. In addition to these, the RegisterRequest, RegisterResponse, AuthenticationRequest, and AuthenticationResponse types from the U2F_V2 specification are used.

Error

Whenever an API call results in an error, an Error object is returned. The errorCode determines the type of error, and the errorMessage gives a textual description of the error. If applicable to the specific error, additional data will be available in the errorData field. The HTTP status code for an error is always a 4XX status code, such as 400 (Bad Request) or 404 (Not Found).

dictionary Error {
  int errorCode;
  DOMString errorMessage;
  optional any errorData;
}

Error codes

Name	Code	Description
BadInput	10	The arguments passed to the function are invalid.
NoEligibleDevices	11	The user has no eligible devices capable of performing the requested action. A DeviceDescriptor[] containing the users devices will be passed along with this error, as it is often desirable to handle a user with no registered devices differently from a user with devices that have been marked compromised and therefore been disabled.
DeviceCompromised	12	The requested action caused the server to determine that one of the users devices may be compromised, and has been disabled. The DeviceDescriptor in question is returned with the error.

Device Descriptor

The DeviceDescriptor describes a registered U2F device. Each Device has a unique handle used to identify the device, as well as fields showing when the device was registered (created) and last successfully used (lastUsed). When available, metadata about the device will be present in the metadata field, containing vendor and device information. This field will be omitted if no such metadata exists. A dictionary of key-value properties is available, which can be used by the client to store arbitrary data. A boolean shows if the device has been marked as compromised. A compromised device cannot be used for authentication. The system will mark a device as compromised if it detects something which may indicate this, and a compromised device should be replaced. Lastly, there may be an integer indicating the available transports a device has. As this is an optional field, and the data is provided by the device itself, this should not be fully trustedi, but rather treated as a hint about what is available. While it is unlikely that a device specifies support for a transport which it does not actually support, it may happen. More likely is that a device supports additional transports which are not listed in this field. For a description on how to interpret the value of this field, see the transport bit definitions here.

dictionary DeviceDescriptor {
  DOMString handle;
  DOMString created;
  DOMString lastUsed;
  DeviceMetadata metadata;
  dictionary properties;
  boolean compromised;
  optional int transports;
};

DeviceMetadata

The metadata provided in the DeviceDescriptor contains metadata about the device vendor as well as the device itself. The two contained fields (VendorInfo and DeviceInfo) are described here. If no metadata exists for either (or both) of these fields the fields will be omitted.

dictionary DeviceMetadata {
  optional VendorInfo vendor;
  optional DeviceInfo device;
};

RegisterRequestData

The RegisterRequestData contains the parameters needed to invoke the register function of a FIDO client, as well as an array of DeviceDescriptors to provide more information about the devices that are already registered. Each descriptor in the authenticateDescriptors array matches the request in authenticateRequests with the same index.

dictionary RegisterRequestData {
  AuthenticateRequest[] authenticateRequests;
  DeviceDescriptor[] authenticateDescriptors;
  RegisterRequest[] registerRequests;
};

Members

authenticateRequests of type array of AuthenticateRequest	A list of AuthenticateRequest dictionaries, one for each U2F device already registered by the user.
registerRequests of type array of RegisterRequest	A list of RegisterRequest dictionaries, one for each protocol version that the server is willing to support.

RegisterResponseData

The RegisterResponseData contains the RegisterResponse returned by a successful call to the register function of a FIDO client, as well as any properties to set, and names of properties to return, if the registration succeeds.

dictionary RegisterResponseData {
  RegisterResponse registerResponse;
  Dictionary properties;
};

Members

registerResponse of type RegisterResponse	The RegisterResponse to return to the server for validation.
properties of type Dictionary	A Dictionary of properties to set for the Device created upon successful validation of the RegisterResponse.

AuthenticationRequestData

The AuthenticationRequestData contains the parameters needed to invoke the authenticate function of a FIDO client, as well as an array of DeviceDescriptors to provide more information about the devices that are eligible for authentication. Each descriptor in the authenticateDescriptors array matches the request in authenticateRequests with the same index.

dictionary AuthenticateRequestData {
  AuthenticateRequest[] authenticateRequests;
  DeviceDescriptor[] authenticateDescriptors;
}

Members

authenticateRequests of type array of AuthenticateRequest

A list of AuthenticateRequest dictionaries, one for each previously registered U2F device for the user.

AuthenticationResponseData

The AuthenticationResponseData contains the AuthenticateResponse returned by a successful call to the authenticate function of a FIDO client, as well as any properties to set, and names of properties to return, if the authentication succeeds.

dictionary AuthenticateResponseData {
  AuthenticateResponse authenticateResponse;
  Dictionary properties;
};

Members

authenticateResponse of type AuthenticateResponse	The AuthenticateResponse to return to the server for validation.
properties of type Dictionary	A Dictionary of properties to set for the Device for which authentication is performed, if authentication succeeds.

HTTP resources

/:userId

Example

https://example.com/johndoe

HTTP GET

Returns a list of device handles, with their properties.

Server response

DeviceDescriptor[]

HTTP DELETE

Deletes all data associated with the user.

/:userId/register

Example

https://example.com/johndoe/register

HTTP GET

Initializes registration for the given user (all registered devices).

Server response

RegisterRequestData

HTTP POST

Completes the registration, storing a new device associated with the user.

Client request body

RegisterResponseData

Server response

DeviceDescriptor

/:userId/authenticate

Example

https://example.com/johndoe/authenticate

HTTP GET

Initializes authentication for the given user (all registered devices).

Server response

AuthenticateRequestData

HTTP POST

Completes the authentication, updating and returning properties for the device which signed the challenge.

Client request

AuthenticateResponseData

Server response

DeviceDescriptor

/:uid/:handle

Example

https://example.com/johndoe/0f0f0f0f0f…0f

HTTP GET

Returns properties for the device.

Server Response

DeviceDescriptor

HTTP POST

Sets properties for the device, then returns the devices (updated) properties.

Client Request

Dictionary

Server Response

DeviceDescriptor

HTTP DELETE

Removes the device registration.

Server Response

HTTP 204 No Content