Ruby U2F

Provides functionality for working with the server side aspects of the U2F protocol as defined in the FIDO specifications. To read more about U2F and how to use a U2F library, visit developers.yubico.com/U2F.

What is U2F?

U2F is an open 2-factor authentication standard that enables keychain devices, mobile phones and other devices to securely access any number of web-based services — instantly and with no drivers or client software needed. The U2F specifications were initially developed by Google, with contribution from Yubico and NXP, and are today hosted by the FIDO Alliance.

Working example application

Check out the example directory for a fully working Padrino server demonstrating U2F.

There is another demo application available using the Cuba framework: cuba-u2f-demo and a blog post explaining the protocol and the implementation.

You'll need Google Chrome 41 or later to use U2F.

Installation

Add the u2f gem to your Gemfile

gem 'u2f'

Usage

The U2F library has two major tasks:

• Register new devices.
• Authenticate previously registered devices.

Each task starts by generating a challenge on the server, which is rendered to a web view, read by the browser APIs and transmitted to the plugged in U2F devices for verification. The U2F device responds and triggers a callback in the browser, and a form is posted back to your server where you verify the challenge and store the U2F device information to your database.

Note that ordinarily, each user will have one or more U2F registrations (as it's a common usage pattern for users to have more than one U2F device -- for example one for regular use, and a second stored safely as a backup). While it's omitted from examples here for brevity, a new registration should typically be associated with the particular user registering. Likewise, when authenticating, queries over "all registrations" should actually be scoped to registrations associated with the particular user being authenticated.

You'll need an instance of U2F::U2F, which is conveniently placed in an instance method on the controller. The initializer takes an App ID as argument.

def u2f
  @u2f ||= U2F::U2F.new(request.base_url)
end

Important: A U2F client (e.g. Chrome) will compare the App ID with the current URI, so make sure it's the right format including schema and port, e.g. https://demo.example.com:3000. Check out the App ID specification for more details.

Registration

Generate the requests which will be sent to the U2F device.

# registrations_controller.rb
def new
  # Generate one for each version of U2F, currently only `U2F_V2`
  @registration_requests = u2f.registration_requests

  # Store challenges. We need them for the verification step
  session[:challenges] = @registration_requests.map(&:challenge)

  # Fetch existing Registrations from your db and generate SignRequests
  key_handles = Registration.map(&:key_handle)
  @sign_requests = u2f.authentication_requests(key_handles)

  @app_id = u2f.app_id

  render 'registrations/new'
end

Render a form that will be automatically posted when the U2F device reponds.

<!-- registrations/new.html -->
<form action="/registrations" method="post">
  <input type="hidden" name="response">
</form>

// render requests from server into Javascript format
var appId = <%= @app_id.to_json.html_safe %>
var registerRequests = <%= @registration_requests.to_json.html_safe %>;
var signRequests = <%= @sign_requests.as_json.to_json.html_safe %>;

u2f.register(appId, registerRequests, signRequests, function(registerResponse) {
  var form, reg;

  if (registerResponse.errorCode) {
    return alert("Registration error: " + registerResponse.errorCode);
  }

  form = document.forms[0];
  response = document.querySelector('[name=response]');

  response.value = JSON.stringify(registerResponse);

  form.submit();
});

Catch the response on your server, verify it, and store a reference to it in your database.

# registrations_controller.rb
def create
  response = U2F::RegisterResponse.load_from_json(params[:response])

  reg = begin
    u2f.register!(session[:challenges], response)
  rescue U2F::Error => e
    return "Unable to register: <%= e.class.name %>"
  ensure
    session.delete(:challenges)
  end

  # save a reference to your database
  Registration.create!(certificate: reg.certificate,
                       key_handle:  reg.key_handle,
                       public_key:  reg.public_key,
                       counter:     reg.counter)

  'Registered!'
end

Authentication

Generate the requests which will be sent to the U2F device.

# authentications_controller.rb
def new
  # Fetch existing Registrations from your db
  key_handles = Registration.map(&:key_handle)
  return 'Need to register first' if key_handles.empty?

  # Generate SignRequests
  @app_id = u2f.app_id
  @sign_requests = u2f.authentication_requests(key_handles)
  @challenge = u2f.challenge

  # Store challenge. We need it for the verification step
  session[:challenge] = @challenge

  render 'authentications/new'
end

Render a form that will be automatically posted when the U2F device reponds.

<!-- registrations/new.html -->
<form action="/authentications" method="post">
  <input type="hidden" name="response">
</form>

// render requests from server into Javascript format
var signRequests = <%= @sign_requests.to_json.html_safe %>;
var challenge = <%= @challenge.to_json.html_safe %>;
var appId = <%= @app_id.to_json.html_safe %>;

u2f.sign(appId, challenge, signRequests, function(signResponse) {
  var form, reg;

  if (signResponse.errorCode) {
    return alert("Authentication error: " + signResponse.errorCode);
  }

  form = document.forms[0];
  response = document.querySelector('[name=response]');

  response.value = JSON.stringify(signResponse);

  form.submit();
});

Catch the response on your server, verify it, and bump the counter in your database reference.

# authentications_controller.rb
def create
  response = U2F::SignResponse.load_from_json(params[:response])

  registration = Registration.first(key_handle: response.key_handle)
  return 'Need to register first' unless registration

  begin
    u2f.authenticate!(session[:challenge], response,
                      Base64.decode64(registration.public_key),
                      registration.counter)
  rescue U2F::Error => e
    return "Unable to authenticate: <%= e.class.name %>"
  ensure
    session.delete(:challenge)
  end

  registration.update(counter: response.counter)

  'Authenticated!'
end

License

MIT License. Copyright (c) 2015 by Johan Brissmyr and Sebastian Wallin