U2FVAL REST API V2

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.

Notable changes from V1

  • The return types for register and sign operations have changed to be in line with the FIDO U2F JavaScript API v1.1.

  • The /:userId/authenticate endpoint has been renamed to /:userId/sign to better map to the FIDO JavaScript API.

  • Properties can be given during creation of register/sign challenges, to be set on successful device creation/authentication.

  • More control is available in the creation of register/sign requests.

JavaScript object type definitions

The following JavaScript objects are used when interacting with the REST API. In addition to these, the types from the FIDO U2F JavaScript API v1.1 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 conpromised 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.

Properties

The Properties dictionary is simply a regular JSON object with values being either strings or null. When sending Properties, a null value denotes unsetting the property, ie. deleting it. When getting Properties all values will be strings. Keys have a 40 character limit.

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 array 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 trusted 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 section 4 of the FIDO U2F JavaScript API v1.1 available here.

dictionary DeviceDescriptor {
  DOMString handle;
  DOMString created;
  DOMString lastUsed;
  DeviceMetadata metadata;
  Properties properties;
  boolean compromised;
  optional DOMString[] transports;
};
Members
handle

A U2FVAL specific identifier for the credential.

created

The time and date of registration of the credential.

lastUsed

The time and date of the last successful use of the credential.

metadata

Metadata for the device.

properties

Client-settable key-value pairs.

compromised

Flag indicating if the credential is considered to be compromised or not.

transports

An optional list of transports supported by the credential.

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 descriptors array matches the RegisteredKey in registeredKeys with the same index.

dictionary RegisterRequestData {
  DOMString appId;
  RegisterRequest[] registerRequests;
  RegisteredKey[] registeredKeys;
  DeviceDescriptor[] descriptors;
};
Members
appId

The AppID for the request.

registeredKeys

A list of RegisteredKey dictionaries, one for each U2F device already registered by the user.

registerRequests

A list of RegisterRequest dictionaries, one for each protocol version that the server is willing to support.

descriptors

A list of DeviceDescriptors matching the registeredKeys list, with device information.

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;
  Properties properties;
};
Members
registerResponse

The RegisterResponse to return to the server for validation.

properties

A Dictionary of properties to set for the Device created upon successful validation of the RegisterResponse.

SignRequestData

The SignRequestData contains the parameters needed to invoke the sign 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 descriptors array matches the RegisteredKey in registeredKeys with the same index.

dictionaty SignRequestData {
  DOMString appId;
  DOMString challenge;
  RegisteredKey[] registeredKeys;
  DeviceDescriptor[] descriptors;
}
Members
appId

The AppID for the request.

challenge

The challenge for the request.

registeredKeys

A list of RegisteredKey dictionaries, one for each U2F device available for authentication.

descriptors

A list of DeviceDescriptors matching the registeredKeys list, with device information.

SignResponseData

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

dictionary SignResponseData {
  SignResponse signResponse;
  Properties properties;
};
Members
signResponse

The SignResponse to return to the server for validation.

properties

A Dictionary of properties to set for the Device for which authentication is performed, if authentication succeeds.

HTTP resources

Endpoint: /: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.

Endpoint: /:userId/register

Example

https://example.com/johndoe/register

HTTP GET

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

Query parameters
challenge

An optional challenge as websafe base64 string.

properties

Optional key-value Properties to set upon successful completion of device registration as a urlencoded JSON object.

Server response

RegisterRequestData

HTTP POST

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

Client request body

RegisterResponseData

Server response

DeviceDescriptor

Endpoint: /:userId/sign

Example

_https://example.com/johndoe/sign

Note
This has been renamed from /:userId/authenticate.

HTTP GET

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

Query parameters
challenge

An optional challenge as websafe base64 string.

properties

Optional key-value Properties to set upon successful completion of device registration as a urlencoded JSON object.

handle

Optional device handle to specify which of the users devices to generate the sign challenge for. Can be provided multiple times. If omitted, all eligible devices are used.

Server response

SignRequestData

HTTP POST

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

Client request

SignResponseData

Server response

DeviceDescriptor

Endpoint: /: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

Endpoint: /:uid/:handle/certificate

Example

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

HTTP GET

Returns the attestation certificate for the device.

Server Response

<PEM encoded X509 certificate>