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

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.

dictionary 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>