yub

YUB

Introduction

What is Yub? It's a simple Yubico Yubikey API client that

• authenticates a Yubkiey's OTP (one time password) using the Yubico API
• signs the outgoing data
• checks the incoming data's signature
• extracts the Yubkey's unique identifier if the OTP is valid

Installation

Yub is published as an NPM module for your convenience:

  npm install yub
``

You'll also need a Yubico API Key from here: https://upgrade.yubico.com/getapikey/. This gives you the
client_id and secret_key that must be passed to "yub.init()", see below.

## Example code

var yub = require('yub');

// initialise the yub library yub.init("", "");

// attempt to verify the key yub.verify("", function(err,data) { console.log(err, data) });

## What's in the 'data' returned by yub.verify?

A typical 'data' return from yub.verify looks like this:

{ t: '2013-08-31T07: 13: 27Z0111', otp: 'cccaccbtbvkwjjirhcctvdgbahdbijduldcjdurgjgfi', nonce: '50fb8a88a327b4af16e6e7bd9ec4e4e6c692f2e5', sl: '25', status: 'OK', signatureVerified: true, nonceVerified: true, identity: 'cccaccbtbvkw' }

* t - the timestamp of the interaction
* otp - the supplied one-time-password
* nonce - a unique piece of information provided by the client to the server
* sl - the percentage of servers responding. This library only picks one (of the 5) Yubico server to authenticate with, so this value should be 20 (percent)
* status - whether the supplied one-time-password was valid or not. Common return values 
** 'OK' - everything's fine
** 'BAD_OTP' - invalid password supplied
** 'REPLAYED_OTP' - the password has been used before
** further return values documented here https://code.google.com/p/yubikey-val-server-php/wiki/ValidationProtocolV20
* signatureVerified - whether the reply from the Yubico server was correctly signed
* nonceVerified - whether the reply 'nonce' was the same as the outgoing 'nonce'
* identity - the unique identifier of the Yubikey that generated the password. If you want to write software the detects the presence of a specific Yubikey (not just any Yubikey), then data.identity is your friend.

## Further examples

In the 'example' directory is an example command-line utility (test.js) which exits with a different return code, depending
on whether the supplied OTP was valid or not. This could easily be plumbed into a command-line script to only allow execution
to proceed with a valid OTP.

It takes the OTP as a command-line parameter i.e. type "node test.js ", insert your Yubikey and press the gold button:

node test.js cccaccbtbvkwjjirhcctvdgbahdbijduldcjdurgjgfi { t: '2013-08-31T07: 13: 27Z0111', otp: 'cccaccbtbvkwjjirhcctvdgbahdbijduldcjdurgjgfi', nonce: '50fb8a88a327b4af16e6e7bd9ec4e4e6c692f2e5', sl: '25', status: 'OK', signatureVerified: true, nonceVerified: true, identity: 'cccaccbtbvkw'}

## References

* https://code.google.com/p/yubikey-val-server-php/wiki/GettingStartedWritingClients
* https://code.google.com/p/yubikey-val-server-php/wiki/ValidationProtocolV20

## Disclaimer

This software is open-source and is a personal project, not officially endorsed by Yubico in any way.