digital-identity-labs / yubikey_otp

Unofficial Elixir client for the classic Yubikey OTP protocol

YubikeyOTP

YubikeyOTP is an Elixir client for authenticating Yubikey one-time-passwords. It can verify OTPs using Yubico's public API or by using your own or third-party OTP validation services.

In addition to acting as a client, YubikeyOTP's OTP parsing feature can be used to build your own validation service.

This early release has not been used in production yet and doesn't have enough tests - please try it and get in touch if something doesn't behave as expected.

Installation

The package can be installed by adding yubikey_otp to your list of dependencies in mix.exs:

def deps do
  [
    {:yubikey_otp, "~> 0.2.4"}
  ]
end

Purpose

A Yubikey is a tiny USB device that connects to your computer as if it was USB keyboard. Pressing the button on a Yubikey causes it to type a new unique password that can be checked against a remote server once. Yubikeys can be used for authentication with both command-line and web applications, but are most commonly used alongside traditional passwords to provide Two Factor Authentication on web sites - the key is "something you have".

Most Yubikeys since 2008 can generate OTPs, but modern Yubikeys also support the U2F and WebAuthn standards: these standard are more secure and immune to phishing, and should be prefered for new services. The older OTP format is more widely deployed and still actively used. This library only supports the older OTP format.

YubikeyOTP takes the OTP code generated by the Yubikey, sends it to a Yubkey Validation Service to be verified, and parses the API result. It follows Yubico's recommendation to send queries to five different API endpoints simultaneously.

    my_id = Application.get_env(:my_app, :yubikey_client_id)

    {:ok, service} = YubikeyOTP.service(api_id: my_id)

    YubikeyOTP.verify("ccccccclzlojikekndkhfibggvkgujttihkcuvkjfrvj", service)
    # => {:ok, :ok}

    YubikeyOTP.verify("ccccccclzlojikekndkhfibggvkgujttihkcuvkjfrvj", service)
    # => {:error, :replayed_otp}

Requirements

• You'll need a Yubikey! They can be bought from Yubico or other online stores such as Amazon. The cheaper "Security Key" range does not generate OTPs, only WebAuthn, and won't work with this code.

• You need to sign up for an API key (using your Yubikey)

API Documentation

Full API documentation can be found at https://hexdocs.pm/yubikey_otp.

Contributing

You can request new features by creating an issue, or submit a pull request with your contribution.

Contributors

• Thom Dixon
• Andrew Allen

Copyright and License

Copyright (c) 2022 Digital Identity Ltd, UK

YubikeyOTP is MIT licensed.

References

• Wikipedia - Yubikey
• Yubico - Using A Client Library
• Yubico - Getting Started Writing Clients
• Yubico - Validation Protocol V2
• Yubico - Yubicloud Connector Libraries
• Yubico - Self Hosted OTP Validation

Disclaimer

YubikeyOTP is not endorsed by Yubico.

yubikey_otp's Issues

Parsing and verifying OTPs locally, using key from Yubikey Manager

I can't get the full parsing and verification of OTPs to work with a Yubikey I've configured using Yubikey Manager on a Mac.

Yubikey Manager generates values like this:

Using a 32 character key with YubikeyOTP produces an error for bad key size

YubikeyOTP.OTP.parse!("ccccccegjdngvritidjdcbggrkgchgigghrtkbnvnfkg", key: "8eb45d90988808c85147451ee4b28adc", skip_checksum: true)
** (YubikeyOTP.OTP.ParseError) Erlang error: {:badarg, {'api_ng.c', 95}, 'Bad key size'}
    (crypto 4.6.4) :crypto.ng_crypto_one_time_nif(:aes_128_ecb, "8eb45d90988808c85147451ee4b28adc", "", <<252, 125, 114, 130, 1, 85, 201, 80, 101, 117, 86, 205, 145, 191, 180, 149>>, false)
    (yubikey_otp 0.2.0) lib/yubikey_otp/otp.ex:196: YubikeyOTP.OTP.do_parse!/2

The example/test still works fine, but is using a 16 character key

YubikeyOTP.OTP.parse!("ccccccclulvjhnblleegivrcjlvvtvujejbclrdjdgvk", key: "1111111111111111")
%YubikeyOTP.OTP{
  checksum: ",3",
  encrypted_otp: "hnblleegivrcjlvvtvujejbclrdjdgvk",
  prefix: "cccccc",
  private_id: "111111",
  public_id: "ccccccclulvj",
  random: <<64, 22>>,
  serial: 715512,
  session_counter: 0,
  timestamp: 8002816,
  use_counter: 0
}

I'm confused - is this an issue with the encoding/base of the keyfile?