yubikey

Documentation

Index

• Constants
• Variables
• type DecryptOTPFunc
  • func (f DecryptOTPFunc) DecryptOTP(otp OTP) (Token, error)
• type Decrypter
• type EncryptTokenFunc
  • func (f EncryptTokenFunc) EncryptToken(token Token) (OTP, error)
• type Encrypter
• type KSM
• type OTP
  • func ParseInternationalOTP(s string) (otp OTP, err error)
  • func ParseOTP(s string) (otp OTP, err error)
  • func (otp OTP) Decrypt(secret []byte) (token Token, err error)
  • func (otp OTP) PublicID() PublicID
  • func (otp OTP) String() string
• type PublicID
  • func (pid PublicID) String() string
• type Secret
• type Token
  • func (token Token) Bytes() []byte
  • func (token Token) CalcCRC() uint16
  • func (token Token) CheckCRC() bool
  • func (token Token) Encrypt(secret []byte) (otp OTP, err error)
  • func (token Token) UsedCapslock() bool
• type Verifier
• type VerifyFunc
  • func (f VerifyFunc) VerifyOTP(request VerifyRequest) (VerifyResponse, error)
• type VerifyRequest
  • func ParseVerifyRequest(request *http.Request) (VerifyRequest, error)
  • func (request VerifyRequest) Encode() string
  • func (request VerifyRequest) IsSigned() bool
  • func (request VerifyRequest) Request(client *http.Client, api string) (VerifyResponse, error)
  • func (request VerifyRequest) VerifySignature(key []byte) bool
• type VerifyResponse
  • func ParseVerifyResponse(response *http.Response) (VerifyResponse, error)
• type VerifyStatus
  • func (err VerifyStatus) Error() string

Constants

const (
	// MinNonceLen is the minimal size of a nonce (in bytes).
	MinNonceLen = 16

	// MaxNonceLen is the maximum size of a nonce (in bytes).
	MaxNonceLen = 40

	// VerifyAPIPath is the HTTP API path for Validation Protocol Version 2.0.
	VerifyAPIPath = "/wsapi/2.0/verify"

	// DefaultAPI is the default HTTP API.
	DefaultAPI = "https://api.yubico.com"
)

Variables

var (
	// ErrCRC is returned if the Token CRC is incorrect.
	ErrCRC = errors.New("yubikey: CRC mismatch")

	// ErrKey is returned if the secret key is not 16-bytes.
	ErrKey = errors.New("yubikey: invalid secret")
)

Types

type DecryptOTPFunc

type DecryptOTPFunc func(OTP) (Token, error)

DecryptOTPFunc is a function that implements the Decrypter interface.

func (DecryptOTPFunc) DecryptOTP

func (f DecryptOTPFunc) DecryptOTP(otp OTP) (Token, error)

DecryptOTP calls the wrapped function.

type Decrypter

type Decrypter interface {
	// DecryptOTP requests decryption of a One Time Pad (OTP).
	DecryptOTP(OTP) (Token, error)
}

Decrypter can decrypt YubiKey One Time Pads (OTP).

type EncryptTokenFunc

type EncryptTokenFunc func(Token) (OTP, error)

EncryptTokenFunc is a function that implements the Encrypter interface.

func (EncryptTokenFunc) EncryptToken

func (f EncryptTokenFunc) EncryptToken(token Token) (OTP, error)

EncryptToken calls the wrapped function.

type Encrypter

type Encrypter interface {
	// EncryptToken requests encryption of a Token.
	EncryptToken(Token) (OTP, error)
}

Encrypter can encrypt tokens into YubiKey One Time Pads (OTP).

type KSM

type KSM interface {
	Decrypter
	Encrypter
}

KSM is an implementation of the YubiKey Key Storage Module (HSM).

type OTP

type OTP [otpLen]byte

OTP is a YubiKey One Time Pad (OTP).

func ParseInternationalOTP

func ParseInternationalOTP(s string) (otp OTP, err error)

ParseInternationalOTP accepts alternate (international) keyboard layouts.

func ParseOTP

func ParseOTP(s string) (otp OTP, err error)

ParseOTP parses a One Time Pad (OTP).

func (OTP) Decrypt

func (otp OTP) Decrypt(secret []byte) (token Token, err error)

Decrypt the token values using the provided 16-byte secret (AES) key.

func (OTP) PublicID

func (otp OTP) PublicID() PublicID

PublicID is the public portion of the One Time Pad.

func (OTP) String

func (otp OTP) String() string

type PublicID

type PublicID [publicIDLen]byte

PublicID is a public identifier.

func (PublicID) String

func (pid PublicID) String() string

type Secret

type Secret [secretLen]byte

Secret is the token secret.

type Token

type Token struct {
	Public  PublicID
	Secret  Secret
	Counter uint16
	Low     uint16
	High    uint8
	Use     uint8
	Random  uint16
	CRC     uint16
}

Token is a decrypted token.

func (Token) Bytes

func (token Token) Bytes() []byte

func (Token) CalcCRC

func (token Token) CalcCRC() uint16

CalcCRC calculates the token check sum.

func (Token) CheckCRC

func (token Token) CheckCRC() bool

CheckCRC verifies the token check sum.

func (Token) Encrypt

func (token Token) Encrypt(secret []byte) (otp OTP, err error)

Encrypt the token values using the provided 16-byte secret (AES) key.

func (Token) UsedCapslock

func (token Token) UsedCapslock() bool

UsedCapslock checks if the token was generated using the caps lock key.

type Verifier

type Verifier interface {
	// VerifyOTP requests the verification of a One Time Pad (OTP).
	VerifyOTP(VerifyRequest) (VerifyResponse, error)
}

Verifier for YubiKey Validation Protocol Version 2.0.

type VerifyFunc

type VerifyFunc func(VerifyRequest) (VerifyResponse, error)

VerifyFunc is a function that implements the Verifier interface.

func (VerifyFunc) VerifyOTP

func (f VerifyFunc) VerifyOTP(request VerifyRequest) (VerifyResponse, error)

VerifyOTP calls the wrapped function.

type VerifyRequest

type VerifyRequest struct {
	// ID is the requester (used for selecting the correct HMAC secret).
	ID string

	// OTP is the One Time Pad that's being verified.
	OTP OTP

	// Signature is the request signature (optional).
	Signature []byte

	// Timestamp requests the timestamp to be returned (optional).
	Timestamp bool

	// Nonce with unique random data (optional, typically 16 to 40 bytes).
	Nonce []byte

	// Sync configures the synchronization percentage in range [0, 100].
	Sync int

	// Timeout configures how long (in seconds) the server should spend waiting for sync responses.
	Timeout int
}

VerifierRequest is a request payload for the YubiKey Validation Protocol Version 2.0. This is not valid for version 1.x implementations.

func ParseVerifyRequest

func ParseVerifyRequest(request *http.Request) (VerifyRequest, error)

ParseVerifyRequest parses a verify request from a HTTP request.

func (VerifyRequest) Encode

func (request VerifyRequest) Encode() string

Encode the request as URL values.

func (VerifyRequest) IsSigned

func (request VerifyRequest) IsSigned() bool

IsSigned returns if the request was signed with an HMAC.

func (VerifyRequest) Request

func (request VerifyRequest) Request(client *http.Client, api string) (VerifyResponse, error)

Request sends a request using the provided HTTP client. The api is the base URL for the Validation Server API. If the client is nil, the default HTTP client will be used. If the api is empty, the default API will be used.

func (VerifyRequest) VerifySignature

func (request VerifyRequest) VerifySignature(key []byte) bool

VerifySignature verifies the HMAC signature. If the request is not signed, this function will always return true. To check if the request was signed, use IsSigned.

type VerifyResponse

type VerifyResponse struct {
	// OTP from the request.
	OTP OTP

	// Nonce from the request.
	Nonce []byte

	// Signature for the response.
	Signature []byte

	// Time stamp in UTC.
	Time time.Time

	// SessionCounter is how often the YubiKey has been powered up.
	SessionCounter uint16

	// SessionUse is how often the YubiKey button has been pressed.
	SessionUse uint8

	// Sync percentage in range [0, 100].
	Sync int
}

func ParseVerifyResponse

func ParseVerifyResponse(response *http.Response) (VerifyResponse, error)

type VerifyStatus

type VerifyStatus string

const (
	OK                     VerifyStatus = "OK"
	ErrBadOTP              VerifyStatus = "BAD_OTP"
	ErrReplayedOTP         VerifyStatus = "REPLAYED_OTP"
	ErrBadSignature        VerifyStatus = "BAD_SIGNATURE"
	ErrMissingParameter    VerifyStatus = "MISSING_PARAMETER"
	ErrNoSuchClient        VerifyStatus = "NO_SUCH_CLIENT"
	ErrOperationNotAllowed VerifyStatus = "OPERATION_NOT_ALLOWED"
	ErrBackend             VerifyStatus = "BACKEND_ERROR"
	ErrSync                VerifyStatus = "NOT_ENOUGH_ANSWERS"
	ErrReplayedRequest     VerifyStatus = "REPLAYED_REQUEST"
)

func (VerifyStatus) Error

func (err VerifyStatus) Error() string