ykoath

README

go-ykoath

The package ykoath implements the YubiKey YKOATH protocol over USB with the following exceptions:

• No support for HOTP (only TOTP)
• No support for SET CODE and subsequently no support for VALIDATE and SELECT challenges - no authentication schema except requiring touch is supported
• No support for RESET (removing all state from device)

Usage

oath, err := ykoath.New()
if err != nil {
    log.Fatal(err)
}

defer oath.Close()

if _, err = oath.Select(); err != nil {
    log.Fatalf("Failed to select app: %v", err)
}

names, err := oath.List()
if err != nil {
    log.Fatal("Failed to list slots: %v", err)
}

for _, name := range names {
    calc, err := oath.Calculate(name.Name, func(name string) error {
        log.Printf("*** Please touch your YubiKey to unlock slot: %q ***", name)
        return nil
    })
    if err != nil {
        log.Fatal("Failed to calculate code for slot %q: %v", name.Name, err)
    }

    log.Printf("Got one-time-password %s for slot %q", calc, name)
}

if err := oath.Put("test", ykoath.HmacSha1, ykoath.Totp, 6, []byte("open sesame"), true); err != nil {
    log.Fatal(err)
}

if err := oath.Put("test2", ykoath.HmacSha1, ykoath.Totp, 6, []byte("open sesame"), true); err != nil {
    log.Fatal(err)
}

Authors

go-ykoath has been forked from yawn/ykoath at commit 201009e

• Joern Barthel (@yawn)
• Steffen Vogel (@stv0g)

License

go-ykoath is licensed under the Apache 2.0 license.

Documentation

Overview

Example

oath, err := New()
if err != nil {
	log.Print(err)
	return
}

defer oath.Close()

// Fix the clock
oath.Clock = func() time.Time {
	return time.Unix(59, 0)
}

// Enable OATH for this session
if _, err = oath.Select(); err != nil {
	log.Printf("Failed to select app: %v", err)
	return
}

// Add the testvector
if err = oath.Put("testvector", HmacSha1, Totp, 8, []byte("12345678901234567890"), false); err != nil {
	log.Printf("Failed to put: %v", err)
	return
}

names, err := oath.List()
if err != nil {
	log.Printf("Failed to list: %v", err)
	return
}

for _, name := range names {
	fmt.Printf("Name: %s\n", name)
}

otp, _ := oath.Calculate("testvector", nil)
fmt.Printf("OTP: %s\n", otp)

Output:

Name: testvector (HMAC-SHA1 TOTP)
OTP: 94287082

Index

• type Algorithm
  • func (a Algorithm) String() string
• type Name
  • func (n *Name) String() string
• type OATH
  • func New() (*OATH, error)
  • func (o *OATH) Calculate(name string, touchRequiredCallback func(string) error) (string, error)
  • func (o *OATH) Close() error
  • func (o *OATH) Delete(name string) error
  • func (o *OATH) List() ([]*Name, error)
  • func (o *OATH) Put(name string, a Algorithm, t Type, digits uint8, key []byte, touch bool) error
  • func (o *OATH) Select() (*Select, error)
• type Select
• type Type
  • func (t Type) String() string

Examples

• Package

Types

type Algorithm

type Algorithm byte

Algorithm denotes the HMAc algorithm used for deriving the one-time passwords

const (
	// HmacSha1 describes a HMAC with SHA-1
	HmacSha1 Algorithm = 0x01

	// HmacSha256 describes a HMAC with SHA-2 (256-bit)
	HmacSha256 Algorithm = 0x02

	// HmacSha512 describes a HMAC with SHA-2 (512-bit)
	HmacSha512 Algorithm = 0x03
)

func (Algorithm) String

func (a Algorithm) String() string

String returns a string representation of the algorithm

type Name

type Name struct {
	Algorithm Algorithm
	Type      Type
	Name      string
}

Name encapsulates the result of the "LIST" instruction

func (*Name) String

func (n *Name) String() string

String returns a string representation of the algorithm

type OATH

type OATH struct {
	Clock func() time.Time
	// contains filtered or unexported fields
}

OATH implements most parts of the TOTP portion of the YKOATH specification https://developers.yubico.com/OATH/YKOATH_Protocol.html

func New

func New() (*OATH, error)

New initializes a new OATH session

func (*OATH) Calculate

func (o *OATH) Calculate(name string, touchRequiredCallback func(string) error) (string, error)

Calculate is a high-level function that first identifies all TOTP credentials that are configured and returns the matching one (if no touch is required) or fires the callback and then fetches the name again while blocking during the device awaiting touch

func (*OATH) Close

func (o *OATH) Close() error

Close terminates an OATH session

func (*OATH) Delete

func (o *OATH) Delete(name string) error

Delete sends a "DELETE" instruction, removing one named OATH credential

func (*OATH) List

func (o *OATH) List() ([]*Name, error)

List sends a "LIST" instruction, return a list of OATH credentials

func (*OATH) Put

func (o *OATH) Put(name string, a Algorithm, t Type, digits uint8, key []byte, touch bool) error

Put sends a "PUT" instruction, storing a new / overwriting an existing OATH credentials with an algorithm and type, 6 or 8 digits one-time password, shared secrets and touch-required bit

func (*OATH) Select

func (o *OATH) Select() (*Select, error)

Select sends a "SELECT" instruction, initializing the device for an OATH session

type Select

type Select struct {
	Algorithm []byte
	Challenge []byte
	Name      []byte
	Version   []byte
}

Select encapsulates the results of the "SELECT" instruction

type Type

type Type byte

Type denotes the kind of derivation used for the one-time password

const (

	// Hotp describes HMAC based one-time passwords (https://tools.ietf.org/html/rfc4226)
	Hotp Type = 0x10

	// Totp describes time-based one-time passwords (https://tools.ietf.org/html/rfc6238)
	Totp Type = 0x20
)

func (Type) String

func (t Type) String() string

String returns a string representation of the type