u2fhost

u2f-host-ruby

Ruby bindings for libu2f-host library. The u2fhost gem exposes two API's

• register Register using a U2F device
• sign Sign using a U2F device This is similar to the API exposed by u2f-api.js javascript library.

Dependencies

Before installing this gem please install libu2f-host for you platform.

macos

$ brew install libu2f-host

If Homebrew throws any error stating unable to link some library, it may be necessary to explictly call

$ brew link <libray name>

Sometimes it may be necessary to change the ownership of /usr/local/{lib,share,bin} for the above commands to work.

sudo chown -R `whoami`:admin /usr/local/bin
$ sudo chown -R `whoami`:admin /usr/local/lib
$ sudo chown -R `whoami`:admin /usr/local/share

debian/ubuntu

$ apt-get update
$ apt-get install libu2f-host-dev

windows/other OS

Build from source following instructions in libu2f-host repository.

Installation

Add this line to your application's Gemfile:

gem 'u2fhost'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install u2fhost

Usage

Require the gem in your code

require 'u2fhost'

Register

challenge = "..." ## challenge from server
origin = "..." ## U2F origin URL
response = U2fhost::register(challenge, origin)

## send response to server to complete registration

Sign

challenge = "..." ## challenge from server
origin = "..." ## U2F origin URL
response = U2fhost::sign(challenge, origin)

## send response to server to verify signature

The API's throw U2fhost::ERROR exception in case of any errors.

Development

• Ensure bundler gem is installed. If not, install using

  $ gem install bundler
  

• Clone the repository

• Install dependent gems

  $ cd u2f-host-ruby
  $ make bundle
  

• Create a new branch

  git checkout -b <GIT_USER_NAME>/<BRANCH_NAME>
  

• Bump the version

  make bump-pre
  

• Ensure code is formatted using rufo. The build process will fail if the code is not formatted.

  make format
  

NOTE: Do not fork the repository

Testing

As this gem interacts with a hardware device, any changes has to be tested manually. The project is setup to build and install the gem on the local machine.

• build the gem

  $ make build
  

This will create the u2fhost-VERSION.gem file in pkg directory

• install gem

  $ make install
  

This will install the gem on the local machine

• run the test executable

  $ bin/test
  

Another way to test after installing the gem is to launch irb

$ irb
irb(main):001:0> require 'u2fhost' 
=> true
irb(main):002:0>

Release

u2fhost pre-release and release versions are automatically published to RubyGems by the build process. Each commit to master branch publishes a pre-release version of the gem.

Publishing Pre-Release version

• Open a pull request to merge the feature branch into master
• After review and approval merge feature branch into master
• The build process publishes a pre-release version if gem version matches one of the following patterns:
  • MAJOR.MINOR.PATCH-alpha
  • MAJOR.MINOR.PATCH-beta
  • MAJOR.MINOR.PATCH-rc

Publishing a Release version

• Update u2fhost version to MAJOR.MINOR.PATCH in lib/u2fhost/version.rb and commit the change to master
• Create and push a tag with the same name as the version
• The build process publishes a release version of the gem

License

Copyright 2020 Xaptum, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License from the LICENSE.txt file or at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.