yubikey

README

YubiKey

A Golang library that provides PIV smart card interface for YubiKey security keys.

Usage

See yubikey_test.go, slot_test.go.

Test

# Run tests
make test

# Continuous testing
make test-ui

Contributing

See CONTRIBUTING.md

License

Licensed under The MIT License (MIT)
For the full copyright and license information, please view the LICENSE.txt file.

Documentation

Overview

Package yubikey provides PIV smart card interface for YubiKey security keys.

Index

• Variables
• func CardSlots(serials, slots, pins []string) (map[string]map[string]*Slot, error)
• type Algorithm
  • func (alg Algorithm) String() string
• type Card
  • func Cards() ([]*Card, error)
  • func (card *Card) Name() string
  • func (card *Card) Serial() string
  • func (card *Card) SetManKey(manKey []byte)
  • func (card *Card) SetPIN(pin string)
  • func (card *Card) SetPUK(puk string)
  • func (card *Card) SlotKeys() []string
  • func (card *Card) Slots() ([]*Slot, error)
  • func (card *Card) SlotsByKey(slotKeys []string) ([]*Slot, error)
  • func (card *Card) Unblock(puk, newPIN string) error
  • func (card *Card) VerifyPIN(pin string) error
  • func (card *Card) Version() string
• type GenerateKeyOpts
• type PINPolicy
  • func (pinPolicy PINPolicy) String() string
• type Slot
  • func CardSlot(serial, slot, pin string) (*Slot, error)
  • func (slot *Slot) GenerateKey(opts GenerateKeyOpts) error
  • func (slot *Slot) HasKey() bool
  • func (slot *Slot) IsGenerated() bool
  • func (slot *Slot) IsImported() bool
  • func (slot *Slot) Key() string
  • func (slot *Slot) PINPolicy() PINPolicy
  • func (slot *Slot) PublicKey() []byte
  • func (slot *Slot) PublicKeyAlgorithm() Algorithm
  • func (slot *Slot) SharedKey(peerPublicKey []byte) ([]byte, error)
  • func (slot *Slot) TouchPolicy() TouchPolicy
• type TouchPolicy
  • func (touchPolicy TouchPolicy) String() string

Variables

var (
	// ErrInvalidPIN represents an invalid PIN error.
	ErrInvalidPIN = errors.New("invalid PIN")
	// ErrMissingPIN represents a missing PIN error.
	ErrMissingPIN = errors.New("missing PIN")
	// ErrAuthError represents an authentication error.
	ErrAuthError = errors.New("authentication error")
	// ErrAuthBlocked represents an authentication block error.
	ErrAuthBlocked = errors.New("authentication method blocked")
)

var (

	// DefaultPIN holds the default card PIN.
	DefaultPIN = piv.DefaultPIN
	// DefaultPUK holds the default card PUK.
	DefaultPUK = piv.DefaultPUK
	// DefaultManagementKey holds the default card management key.
	DefaultManagementKey = piv.DefaultManagementKey

	// ErrOutstandingConnections returns an outstanding connections error.
	ErrOutstandingConnections = errors.New("outstanding connections")
)

Functions

func CardSlots

func CardSlots(serials, slots, pins []string) (map[string]map[string]*Slot, error)

CardSlots returns the card slots by the given card serials, slots and pins. It doesn't return error if the given serial or slot not found.

Types

type Algorithm

type Algorithm int

Algorithm represents an algorithm.

const (
	// AlgorithmUnknown represents the unknown algorithm.
	AlgorithmUnknown Algorithm = 0
	// AlgorithmEC256 represents the EC256 algorithm.
	AlgorithmEC256 Algorithm = 1
	// AlgorithmEC384 represents the EC384 algorithm.
	AlgorithmEC384 Algorithm = 2
	// AlgorithmEd25519 represents the Ed25519 algorithm.
	AlgorithmEd25519 Algorithm = 3
	// AlgorithmRSA1024 represents the RSA1024 algorithm.
	AlgorithmRSA1024 Algorithm = 4
	// AlgorithmRSA2048 represents the RSA2048 algorithm.
	AlgorithmRSA2048 Algorithm = 5
)

func (Algorithm) String

func (alg Algorithm) String() string

String returns the algorithm name.

type Card

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

Card represents a YubiKey smart card. For more information see https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html

func Cards

func Cards() ([]*Card, error)

Cards returns the connected YubiKey smart cards.

func (*Card) Name

func (card *Card) Name() string

Name returns the card name.

func (*Card) Serial

func (card *Card) Serial() string

Serial returns the card serial number.

func (*Card) SetManKey

func (card *Card) SetManKey(manKey []byte)

SetManKey sets the management key

func (*Card) SetPIN

func (card *Card) SetPIN(pin string)

SetPIN sets the card pin.

func (*Card) SetPUK

func (card *Card) SetPUK(puk string)

SetPUK sets the card puk.

func (*Card) SlotKeys

func (card *Card) SlotKeys() []string

SlotKeys returns the card slot keys.

func (*Card) Slots

func (card *Card) Slots() ([]*Slot, error)

Slots returns the card slots.

func (*Card) SlotsByKey

func (card *Card) SlotsByKey(slotKeys []string) ([]*Slot, error)

SlotsByKey returns the card slots by the given slot keys.

func (*Card) Unblock

func (card *Card) Unblock(puk, newPIN string) error

Unblock unblocks the PIN, setting it to a new value.

func (*Card) VerifyPIN

func (card *Card) VerifyPIN(pin string) error

VerifyPIN attempts to authenticate against the card with the provided PIN.

func (*Card) Version

func (card *Card) Version() string

Version returns the card firmware version.

type GenerateKeyOpts

type GenerateKeyOpts struct {
	Overwrite   bool
	Algorithm   Algorithm
	PINPolicy   PINPolicy
	TouchPolicy TouchPolicy
	ManKey      []byte
}

GenerateKeyOpts represents the options which can be used for generating a key.

type PINPolicy

type PINPolicy int

PINPolicy represents a slot PIN policy.

const (
	// PINPolicyUnknown represents the unknown PIN policy.
	PINPolicyUnknown PINPolicy = 0
	// PINPolicyNever represents the "never" PIN policy.
	PINPolicyNever PINPolicy = 1
	// PINPolicyOnce represents the "once" PIN policy.
	PINPolicyOnce PINPolicy = 2
	// PINPolicyAlways represents the "always" PIN policy.
	PINPolicyAlways PINPolicy = 3
)

func (PINPolicy) String

func (pinPolicy PINPolicy) String() string

String returns the policy name.

type Slot

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

Slot represents a YubiKey smart card slot.

func CardSlot

func CardSlot(serial, slot, pin string) (*Slot, error)

CardSlot returns a card slot by the given card serial, slot and pin.

func (*Slot) GenerateKey

func (slot *Slot) GenerateKey(opts GenerateKeyOpts) error

GenerateKey generates an asymmetric key by the given slot name and options.

func (*Slot) HasKey

func (slot *Slot) HasKey() bool

HasKey returns whether the slot has a key or not.

func (*Slot) IsGenerated

func (slot *Slot) IsGenerated() bool

IsGenerated returns whether the slot key is generated (secure) or not.

func (*Slot) IsImported

func (slot *Slot) IsImported() bool

IsImported returns whether the slot key is imported (may not be secure) or not.

func (*Slot) Key

func (slot *Slot) Key() string

Key returns the slot key.

func (*Slot) PINPolicy

func (slot *Slot) PINPolicy() PINPolicy

PINPolicy returns the slot PIN policy.

func (*Slot) PublicKey

func (slot *Slot) PublicKey() []byte

PublicKey returns the public key of the slot if any.

func (*Slot) PublicKeyAlgorithm

func (slot *Slot) PublicKeyAlgorithm() Algorithm

PublicKeyAlgorithm returns the public key algorithm of the slot.

func (*Slot) SharedKey

func (slot *Slot) SharedKey(peerPublicKey []byte) ([]byte, error)

SharedKey returns a shared key by the given peer public key (compressed).

func (*Slot) TouchPolicy

func (slot *Slot) TouchPolicy() TouchPolicy

TouchPolicy returns the slot touch policy.

type TouchPolicy

type TouchPolicy int

TouchPolicy represents a slot touch policy.

const (
	// TouchPolicyUnknown represents the unknown touch policy.
	TouchPolicyUnknown TouchPolicy = 0
	// TouchPolicyNever represents the "never" touch policy.
	TouchPolicyNever TouchPolicy = 1
	// TouchPolicyAlways represents the "always" touch policy.
	TouchPolicyAlways TouchPolicy = 2
	// TouchPolicyCached represents the "cached" touch policy.
	TouchPolicyCached TouchPolicy = 3
)

func (TouchPolicy) String

func (touchPolicy TouchPolicy) String() string

String returns the policy name.