u2ftoken

Documentation

Overview

Package u2ftoken implements the FIDO U2F raw message protocol used to communicate with U2F tokens.

Index

• Variables
• type AuthenticateRequest
• type AuthenticateResponse
• type Device
• type RegisterRequest
• type Request
• type Response
• type Token
  • func NewToken(d Device) *Token
  • func (t *Token) Authenticate(req AuthenticateRequest) (*AuthenticateResponse, error)
  • func (t *Token) CheckAuthenticate(req AuthenticateRequest) error
  • func (t *Token) Message(req Request) (*Response, error)
  • func (t *Token) Register(req RegisterRequest) ([]byte, error)
  • func (t *Token) Version() (string, error)

Variables

var ErrPresenceRequired = errors.New("u2ftoken: user presence required")

ErrPresenceRequired is returned by Register and Authenticate if proof of user presence must be provide before the operation can be retried successfully.

var ErrUnknownKeyHandle = errors.New("u2ftoken: unknown key handle")

ErrUnknownKeyHandle is returned by Authenticate and CheckAuthenticate if the key handle is unknown to the token.

Types

type AuthenticateRequest

type AuthenticateRequest struct {
	// Challenge is the 32-byte SHA-256 hash of the Client Data JSON prepared by
	// the client.
	Challenge []byte

	// Application is the 32-byte SHA-256 hash of the application identity of
	// the relying party requesting authentication.
	Application []byte

	// KeyHandle is the opaque key handle that was provided to the relying party
	// during registration.
	KeyHandle []byte

	// The U2F 1.2 spec allows authentication requests to be made without enforcing
	// user presence. If set to true, this will request that the token not require
	// user presence. Tokens which are only compliant with earlier versions of the
	// spec will return an error.
	DoNotEnforceUserPresence bool
}

An AuthenticateRequires is a message used for authenticating to a relying party

type AuthenticateResponse

type AuthenticateResponse struct {
	// Counter is the value of the counter that is incremented by the token
	// every time it performs an authentication operation.
	Counter uint32

	// Signature is the P-256 ECDSA signature over the authentication data.
	Signature []byte

	// RawResponse is the raw response bytes from the U2F token.
	RawResponse []byte
}

An AuthenticateResponse is a message returned in response to a successful authentication request.

type Device

type Device interface {
	// Message sends a message to the device and returns the response.
	Message(data []byte) ([]byte, error)
}

Device implements a message transport to a concrete U2F device. It is implemented in package u2fhid.

type RegisterRequest

type RegisterRequest struct {
	// Challenge is the 32-byte SHA-256 hash of the Client Data JSON prepared by
	// the client.
	Challenge []byte

	// Application is the 32-byte SHA-256 hash of the application identity of
	// the relying party requesting registration.
	Application []byte
}

A RegisterRequest is a message used for token registration.

type Request

type Request struct {
	Command uint8
	Param1  uint8
	Param2  uint8
	Data    []byte
}

A Request is a low-level request to the token.

type Response

type Response struct {
	Data   []byte
	Status uint16
}

A Response is a low-level response from the token.

type Token

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

A Token implements the FIDO U2F hardware token messages as defined in the Raw Message Formats specification.

func NewToken

func NewToken(d Device) *Token

NewToken returns a token that will use Device to communicate with the device.

func (*Token) Authenticate

func (t *Token) Authenticate(req AuthenticateRequest) (*AuthenticateResponse, error)

Authenticate peforms an authentication operation and returns the response to provide to the relying party. It returns ErrPresenceRequired if the call should be retried after proof of user presence is provided to the token and ErrUnknownKeyHandle if the key handle is unknown to the token.

func (*Token) CheckAuthenticate

func (t *Token) CheckAuthenticate(req AuthenticateRequest) error

CheckAuthenticate checks if a key handle is known to the token without requiring a test for user presence. It returns ErrUnknownKeyHandle if the key handle is unknown to the token.

func (*Token) Message

func (t *Token) Message(req Request) (*Response, error)

Message sends a low-level request to the token and returns the response.

func (*Token) Register

func (t *Token) Register(req RegisterRequest) ([]byte, error)

Register registers an application with the token and returns the raw registration response message to be passed to the relying party. It returns ErrPresenceRequired if the call should be retried after proof of user presence is provided to the token.

func (*Token) Version

func (t *Token) Version() (string, error)

Version returns the U2F protocol version implemented by the token.