u2f

U2F authentication library

This is a simple library to register and check signatures provided by U2F clients/devices. It's intended to be used in Relying Parties - websites that want to add U2F 2-factor authentication for their users.

To use U2F, it is recommended to familiarize yourself with FIDO Alliance Specifications, although basic usage is shown below.

U2F Overview/properties

• U2F provides hardware-based 2-nd factor authentication system. Public/private key infrastructure is used to ensure good security.
• Provides proof of posession of hardware key, plus user presence flag.
• Public/private key pairs are specific to website origin and 'application id'. Keys are useless if used from other origins.
• Needs to be stored on server for each user: Key handle and public key (both strings).
• Cannot be used as main authentication system because server needs to provide unique key handle to the user to get the signature.

Basic usage

User Registration Flow

Server endpoints:

…

Client logic:

Note that the window.u2f object is defined in the official Javascript U2F API, for which a polyfill is available as an npm module.

const registrationRequest = ...  // Retrieve this from hitting the registration challenge endpoint

window.u2f.register(registrationRequest.appId, [registrationRequest], [], (registrationResponse) => {
  // Send this registration response to the registration verification server endpoint
});

User Authentication Flow

Server endpoints:

…

Client logic:

const authRequest = ...;  // Retrieve this from hitting the authentication challenge endpoint

window.u2f.sign(authRequest.appId, authRequest.challenge, [authRequest], (authResponse) => {
  // Send this authentication response to the authentication verification server endpoint
});

Useful links

http://demo.yubico.com/u2f
https://github.com/Yubico/python-u2flib-server

TODO

• Provide instructions for client-side. How to get the 'u2f' namespace, what browsers are supported.
• Change API to enable multiple keyhandle/publickey pairs for a single user.
• Unpack registration certificate and check its own signature and time constraints.

License

MIT