ykoath

README

ykoath

This library implements the instructions, as defined in the YKOATH protocol specification, to interact with the YubiKey in Go.

!!! ATTENTION !!!

This library is not yet stable and will undergo breaking changes.

Implementation status

The following instructions are implemented:

Instruction	Implementation status
PUT	N
DELETE	N
SET CODE	N
RESET	N
LIST	Y
CALCULATE	Y
VALIDATE	Y
CALCULATE ALL	Y
SEND REMAINING	Y

Tutorial

Documentation

Index

• Constants
• Variables
• type CalculateAllData
• type Card
• type Clock
• type ListData
• type Rand
• type YKO
  • func New(c Card) *YKO
  • func (y *YKO) AuthRequired() bool
  • func (y *YKO) Calculate(name string) (string, error)
  • func (y *YKO) CalculateAll() ([]CalculateAllData, error)
  • func (y *YKO) List() ([]ListData, error)
  • func (y *YKO) Select() error
  • func (y *YKO) Validate(password []byte) error

Constants

const (
	PUT            yubiKeyInstruction = 0x01
	DELETE         yubiKeyInstruction = 0x02
	SET_CODE       yubiKeyInstruction = 0x03
	RESET          yubiKeyInstruction = 0x04
	LIST           yubiKeyInstruction = 0xa1
	CALCULATE      yubiKeyInstruction = 0xa2
	VALIDATE       yubiKeyInstruction = 0xa3
	CALCULATE_ALL  yubiKeyInstruction = 0xa4
	SELECT         yubiKeyInstruction = 0xa4 // Synthetic, does not realy exists
	SEND_REMAINING yubiKeyInstruction = 0xa5
)

const (
	HMAC_SHA1   yubiKeyAlgo = 0x01
	HMAC_SHA256 yubiKeyAlgo = 0x02
	HMAC_SHA512 yubiKeyAlgo = 0x03
)

const (
	HOTP yubiKeyType = 0x10
	TOTP yubiKeyType = 0x20
)

const (
	ONLY_INCREASING yubiKeyProperty = 0x01
	REQUIRE_TOUCH   yubiKeyProperty = 0x02
)

const (
	RES_SUCCESS                 yubiKeyResponse = 0x9000
	RES_NO_SPACE                yubiKeyResponse = 0x6a84
	RES_AUTH_REQUIRED           yubiKeyResponse = 0x6982
	RES_WRONG_SYNTAX            yubiKeyResponse = 0x6a80
	RES_NO_SUCH_OBJECT          yubiKeyResponse = 0x6984
	RES_RESPONSE_DOES_NOT_MATCH yubiKeyResponse = 0x6984
	RES_MORE_DATA_AVAILABLE     yubiKeyResponse = 0x61
	RES_GENERIC_ERROR           yubiKeyResponse = 0x6581
	RES_AUTH_NOT_ENABLED        yubiKeyResponse = 0x6984
)

const (
	VERSION   yubiKeyTag = 0x79
	NAME      yubiKeyTag = 0x71
	NAME_LIST yubiKeyTag = 0x72
	CHALLENGE yubiKeyTag = 0x74
	ALGORITHM yubiKeyTag = 0x7b
	KEY       yubiKeyTag = 0x73
	PROPERTY  yubiKeyTag = 0x78
	IMF       yubiKeyTag = 0x7a
	RESPONSE  yubiKeyTag = 0x75
)

Variables

var (
	ErrNoSpace              ykoError = ykoError{/* contains filtered or unexported fields */}
	ErrAuthRequired         ykoError = ykoError{/* contains filtered or unexported fields */}
	ErrWrongSyntax          ykoError = ykoError{/* contains filtered or unexported fields */}
	ErrNoSuchObject         ykoError = ykoError{/* contains filtered or unexported fields */}
	ErrResponseDoesNotMatch ykoError = ykoError{/* contains filtered or unexported fields */}
	ErrGenericError         ykoError = ykoError{/* contains filtered or unexported fields */}
	ErrAuthNotEnabled       ykoError = ykoError{/* contains filtered or unexported fields */}

	ErrChallengeValidation ykoError = ykoError{/* contains filtered or unexported fields */}
	ErrUnexpectedTag       ykoError = ykoError{/* contains filtered or unexported fields */}
	ErrSomethingEles       ykoError = ykoError{/* contains filtered or unexported fields */}
)

All errors the library might expose to the outside

Types

type CalculateAllData

type CalculateAllData struct {
	Name  string
	Type  yubiKeyType
	Touch bool
	Code  string
}

type Card

type Card interface {
	Transmit(command []byte) ([]byte, error)
}

Its called Card because the YubiKey acts as smart card. The Transmit() function needs to be supported in order to interact with the YubiKey.

type Clock

type Clock interface {
	Now() time.Time
}

type ListData

type ListData struct {
	Name string
	Algo yubiKeyAlgo
	Type yubiKeyType
}

type Rand

type Rand interface {
	Read(b []byte) (n int, err error)
}

type YKO

type YKO struct {
	// contains filtered or unexported fields
}

Main structure to use most of the methods of this library.

func New

func New(c Card) *YKO

Starting point to use this library on a YubiKey. There is no initial check if the interaction with the YubiKey works, that's why no error is returned at this stage.

func (*YKO) AuthRequired

func (y *YKO) AuthRequired() bool

Can be called after the SELECT instruction was executed, to identify if authentication is needed for further instructions. The error handling is not as straight forward, because based on the instruction, one response can mean different things. Because of that, the error code is returned to the caller and based on the instruction the final error message is created.

func (*YKO) Calculate

func (y *YKO) Calculate(name string) (string, error)

func (*YKO) CalculateAll

func (y *YKO) CalculateAll() ([]CalculateAllData, error)

func (*YKO) List

func (y *YKO) List() ([]ListData, error)

func (*YKO) Select

func (y *YKO) Select() error

func (*YKO) Validate

func (y *YKO) Validate(password []byte) error