yubikey

README

yubikey

[] (https://travis-ci.org/conformal/yubikey)

Package yubikey implements the Yubico YubiKey API.

Example

The package needs to know the secret key of the YubiKey token; this may be stored as a string. For example, the secret key could be loaded from a file with:

import (
	"bytes"
	"encoding/hex"
	"github.com/conformal/yubikey"
	"io/ioutil"
)

func LoadSecretKey(filename string) (*Key, error) {
	in, err := ioutil.ReadFile(filename)
	if err != nil {
		return nil, err
	}

	in, err = bytes.TrimSpace(in)
	if err != nil {
		return nil, err
	}

	keyBytes := make([]byte, len(in) / 2)
	err = hex.Decode(keyBytes, in)
	if err != nil {
		return nil, err
	}

	priv := yubikey.NewKey(keyBytes)
	return priv, nil
}

Then, you can pass the OTP string directly from the YubiKey to ParseOTPString:

	func GetToken(otpString string, priv *Key) (*Token, error) {
		pub, otp, err := yubikey.ParseOTPString(otpString)
		if err != nil {
			return nil, err
		}

	        keyBytes, err := hex.DecodeString(secretKey)
		if err != nil {
			return nil, err
		}
		t, err := otp.Parse(priv)
		return t, nil
	}

It is important to keep track of the YubiKey's counter as well; this is a 16-bit unsigned integer. The counter value in the token should be checked against the last known counter value of the YubiKey to prevent replay attacks.

License

Package yubikey is licensed under the liberal ISC License.

Documentation

Overview

Package yubikey implements the Yubico YubiKey OTP API, using 6-byte public identities and 16-byte secret keys.

Given a YubiKey private key and the generated OTP, this package provides for validation of OTP tokens.

A key is set up by passing the bytes into the NewKey function; YubiKey secret keys are 32-bytes and hex-encoded. For example, the YubiKey personalisation tool will provide a key like "99cbcef30228f2539aa20358c46c0ad2".

A typical OTP token looks something like "ccccccbtirngifjtulftrrijbkuuhtcgvhfdehighcdh"; in this case, "ccccccbtirng" is the 12-byte modhex-encoded public identity, while the rest of the string contains the actual token. The token can be parsed with the NewOTP or ParseOTPString functions, which converts a string containing the token to a valid OTP structure. This OTP can be validated and turned into a token using the Parse method. The NewOTP requires a string containing only the 32-byte token, while ParseOTPString will take the string directly from the YubiKey and returns a UID and OTP.

See examples/login/login.go for an example login authentication flow.

Remember to keep track of the counter returned from the tokens; this should be checked to prevent replay attacks.

Index

• Constants
• Variables
• func Crc16BufOkP(buf []byte) bool
• func ModHexDecode(src []byte) []byte
• func ModHexEncode(src []byte) []byte
• func ModHexP(src []byte) bool
• func ParseOTPString(str string) (PubID, OTP, error)
• type Key
  • func NewKey(buf []byte) Key
• type OTP
  • func NewOTP(buf string) OTP
  • func (o OTP) Bytes() []byte
  • func (o OTP) Parse(key Key) (*Token, error)
• type PubID
  • func NewPubID(str string) (PubID, error)
• type Token
  • func NewToken(uid Uid, ctr, tstpl uint16, tstph, use uint8, rnd uint16) *Token
  • func NewTokenFromBytes(buf []byte) (*Token, error)
  • func (t *Token) Bytes() []byte
  • func (t *Token) Capslock() bool
  • func (t *Token) Counter() uint16
  • func (t *Token) Crc16() uint16
  • func (t *Token) CrcOkP() bool
  • func (t *Token) Generate(key Key) *OTP
• type Uid
  • func NewUid(buf []byte) Uid

Constants

const (
	BlockSize    = 16
	KeySize      = 16
	OTPSize      = 32 // BlockSize * 2
	UidSize      = 6
	MaxPubIdSize = 32 // BlockSize * 2
	CrcOkResidue = 0xf0b8
)

const (
	ModHexMap = "cbdefghijklnrtuv"
)

Variables

var (
	ErrCrcFailure       = errors.New("yubikey: CRC failure")
	ErrInvalidOTPString = errors.New("yubikey: invalid OTP string")
	ErrInvalidPubIdLen  = errors.New("yubikey: invalid public id length")
)

Functions

func Crc16BufOkP

func Crc16BufOkP(buf []byte) bool

func ModHexDecode

func ModHexDecode(src []byte) []byte

func ModHexEncode

func ModHexEncode(src []byte) []byte

func ModHexP

func ModHexP(src []byte) bool

func ParseOTPString

func ParseOTPString(str string) (PubID, OTP, error)

ParseOTPString returns an OTP and public id from an OTP string.

Types

type Key

type Key [KeySize]byte

Key represents the symmetric 128-bit AES Key

func NewKey

func NewKey(buf []byte) Key

NewKey the specified string to a Key structure.

type OTP

type OTP [OTPSize]byte

OTP represents the One Time Password

func NewOTP

func NewOTP(buf string) OTP

NewOTP converts a string into an OTP structure.

func (OTP) Bytes

func (o OTP) Bytes() []byte

Bytes returns the byte stream associated with the OTP.

func (OTP) Parse

func (o OTP) Parse(key Key) (*Token, error)

Parse decodes and decrypts the OTP with the specified Key returning a Token.

type PubID

type PubID []byte

Pub represents the Public id.

func NewPubID

func NewPubID(str string) (PubID, error)

type Token

type Token struct {
	Uid   Uid
	Ctr   uint16
	Tstpl uint16
	Tstph uint8
	Use   uint8
	Rnd   uint16
	Crc   uint16
}

Token represents the YubiKey token structure.

func NewToken

func NewToken(uid Uid, ctr, tstpl uint16, tstph, use uint8, rnd uint16) *Token

NewToken is a helper function to create a new Token. The CRC is calculated for the caller.

func NewTokenFromBytes

func NewTokenFromBytes(buf []byte) (*Token, error)

NewTokenFromBytes converts a byte stream into a Token. An error will be returned on a CRC failure.

func (*Token) Bytes

func (t *Token) Bytes() []byte

Bytes returns the byte stream associated with the Token.

func (*Token) Capslock

func (t *Token) Capslock() bool

Capslock returns true if the token was generated by the users pressing the capslock key

func (*Token) Counter

func (t *Token) Counter() uint16

func (*Token) Crc16

func (t *Token) Crc16() uint16

Crc16 returns the CRC associated with the Token.

func (*Token) CrcOkP

func (t *Token) CrcOkP() bool

func (*Token) Generate

func (t *Token) Generate(key Key) *OTP

Generate encrypts a Token with the specified Key and returns a OTP.

type Uid

type Uid [UidSize]byte

Uid represents the Private (secret) id.

func NewUid

func NewUid(buf []byte) Uid

NewUid returns a UID structure.