U2F Authentication for Node.js
Switch branches/tags
Nothing to show
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
test Initial commit. Version 0.1 Nov 4, 2014
.gitignore Initial commit. Version 0.1 Nov 4, 2014
README.md Small error in the Readme May 26, 2018
index.js Don't error out on errorCode = "0" (#9) Oct 11, 2017
package.json add test script to package.json Apr 7, 2018

README.md

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:
const u2f = require('u2f');

// The app ID is a string used to uniquely identify your U2F app, for both registration requests and
// authentication requests. It is usually the fully qualified URL of your website. The website MUST
// be HTTPS, otherwise the registration will fail client-side.
const APP_ID = ...

function registrationChallengeHandler(req, res) {
  // 1. Check that the user is logged in.

  // 2. Generate a registration request and save it in the session.
  const registrationRequest = u2f.request(APP_ID);
  req.session.registrationRequest = registrationRequest;

  // 3. Send the registration request to the client, who will use the Javascript U2F API to sign
  // the registration request, and send it back to the server for verification. The registration
  // request is a JSON object containing properties used by the client to sign the request.
  return res.send(registrationRequest);
}

function registrationVerificationHandler(req, res) {
  // 4. Verify the registration response from the client against the registration request saved
  // in the server-side session.
  const result = u2f.checkRegistration(req.session.registrationRequest, req.body.registrationResponse);

  if (result.successful) {
    // Success!
    // Save result.publicKey and result.keyHandle to the server-side datastore, associated with
    // this user.
    return res.sendStatus(200);
  }

  // result.errorMessage is defined with an English-language description of the error.
  return res.send({result});
}
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:
const u2f = require('u2f');

function authenticationChallengeHandler(req, res) {
  // 1. Check that the user is logged in using password authentication.

  // 2. Fetch the user's key handle from the server-side datastore. This field should have been
  // saved after the registration procedure.
  const keyHandle = ...

  // 3. Generate an authentication request and save it in the session. Use the same app ID that
  // was used in registration!
  const authRequest = u2f.request(APP_ID, keyHandle);
  req.session.authRequest = authRequest;

  // 4. Send the authentication request to the client, who will use the Javascript U2F API to sign
  // the authentication request, and send it back to the server for verification.
  return res.send(authRequest);
}

function authenticationVerificationHandler(req, res) {
  // 5. Fetch the user's public key from the server-side datastore. This field should have been
  // saved after the registration procedure.
  const publicKey = ...

  // 6. Verify the authentication response from the client against the authentication request saved
  // in the server-side session.
  const result = u2f.checkSignature(req.session.authRequest, req.body.authResponse, publicKey);

  if (result.successful) {
    // Success!
    // User is authenticated.
    return res.sendStatus(200);
  }

  // result.errorMessage is defined with an English-language description of the error.
  return res.send({result});
}
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