token2

README

go-token2

Pure-Go Token2 device support over PC/SC, USB HID feature reports and CTAPHID.

[!WARNING] This module is under active development. Its public API may change during v0.x.

Packages

• token2 contains transport-independent device models, identity lookup, response types, parsers and capability interfaces.
• token2/apdu implements the APDU subset used by Token2, including automatic GET RESPONSE chaining.
• token2/transport/pcsc opens Token2 devices through github.com/go-ctap/pcsc.
• token2/transport/hid opens the Token2 HID interface through github.com/go-ctap/hid.
• token2/transport/ctaphid reads the Token2 ATR through CTAPHID vendor command 0x41, using github.com/go-ctap/ctap.

Transport capabilities

Capability	PC/SC	Feature HID	CTAPHID
Full serial number	Yes	Yes	No
Model identification from the serial number	Yes	Yes	No
ATR-derived product ID and serial suffix	Generation-dependent	No	Yes
Token2 configuration	Yes	No	No

The PC/SC serial-number query performs the device-specific configuration query required by supported Token2 devices. On firmware such as R3.1 it also retries the serial-number command after an internal compatibility prelude. Some proprietary queries are not available on every Token2 generation. In particular, R3.3 devices may expose a generic PIV ATR without the Token2 product ID and serial suffix; ATRInfo then returns ErrInvalidATR. Serial-number retrieval is independent of ATR parsing and should not be gated on ATRInfo succeeding.

All concrete device types serialize complete logical operations. Malformed data received from a card or HID device is returned as an error. Callers are expected to pass valid reader names, HID paths, serial-number strings and APDU commands; the package does not add defensive checks for programmer misuse.

Examples

Complete runnable usage is available in the transport examples. Each example is an independent Go module, keeping transport-specific dependencies out of the root module.

Example	Purpose	Optional configuration
examples/pcsc	Read identity and configuration over PC/SC	PCSC_READER (reader-name substring)
examples/hid	Read the full serial number over HID feature reports	TOKEN2_HID_PATH
examples/ctaphid	Read ATR identity over the CTAPHID vendor command	TOKEN2_CTAPHID_PATH

The CTAPHID transport sends logical vendor command 0x41; CTAPHID framing adds the init-packet bit, so the on-wire command byte is 0xc1.

Run an example from its directory:

cd examples/pcsc
go run .

Without an environment variable, an example selects the first matching device or reader it finds. Set the corresponding variable when multiple Token2 devices are connected or when automatic HID selection is not available on the host.

Hardware tests

Hardware tests are opt-in:

TOKEN2_PCSC_TEST_READER='TOKEN2 FIDO2 Security Key(0016)' go test -run TestHardware -v ./transport/pcsc
TOKEN2_HID_TEST_PATH='platform-specific-path' go test -run TestHardware -v ./transport/hid
TOKEN2_CTAPHID_TEST_PATH='platform-specific-path' go test -run TestHardware -v ./transport/ctaphid

Documentation

Overview

Package token2 provides transport-independent Token2 device models, response parsers and identity lookup.

Concrete device implementations live under transport. All implement Device; supported operations are expressed by capability interfaces and remain available on concrete types.

Index

• Variables
• func ParseSerialNumber(response []byte) (string, error)
• type ATRDevice
• type ATRInfo
  • func ParseATR(atr []byte) (ATRInfo, error)
• type Config
  • func ParseConfig(response []byte) (Config, error)
  • func (c Config) CCIDSupported() bool
  • func (c Config) FIDO21Supported() bool
  • func (c Config) FingerprintSensorPresent() bool
  • func (c Config) HOTPSupported() bool
  • func (c Config) NFCSupported() bool
  • func (c Config) TOTPSupported() bool
• type Device
• type Identity
  • func Identify(serialNumber string) (Identity, bool)
• type Model
  • func Models() []Model
  • func (m Model) DisplayName() string
• type SerialNumberDevice
• type Version

Variables

var ErrInvalidATR = errors.New("token2: invalid ATR")

ErrInvalidATR reports an ATR that does not contain the expected Token2 historical bytes.

var ErrInvalidConfigResponse = errors.New("token2: invalid configuration response")

ErrInvalidConfigResponse reports malformed configuration data received from a Token2 device.

var ErrInvalidSerialResponse = errors.New("token2: invalid serial-number response")

ErrInvalidSerialResponse reports a malformed serial-number response received from a Token2 device.

Functions

func ParseSerialNumber

func ParseSerialNumber(response []byte) (string, error)

ParseSerialNumber parses the TAG-LENGTH-VALUE response returned by the Token2 serial-number command.

Types

type ATRDevice

type ATRDevice interface {
	Device
	ATRInfo(context.Context) (ATRInfo, error)
}

ATRDevice is a Device capable of returning Token2 ATR information.

type ATRInfo

type ATRInfo struct {
	Raw          []byte
	ProductID    uint16
	SerialSuffix string
}

ATRInfo contains Token2 identity data encoded in a PC/SC ATR.

func ParseATR

func ParseATR(atr []byte) (ATRInfo, error)

ParseATR extracts the USB product ID and decimal serial suffix from a Token2 ATR. Raw refers to the supplied ATR slice.

type Config

type Config struct {
	Raw []byte

	TransferType        byte
	DeviceConfiguration byte
	Appearance          [4]byte
	FIDOVersion         Version
	DeviceExtension     byte
}

Config describes the Token2 configuration response. Raw retains the complete response, including fields unknown to this version of the package.

func ParseConfig

func ParseConfig(response []byte) (Config, error)

ParseConfig parses either a one-byte legacy response or a modern response of at least ten bytes. Additional bytes are retained in Raw.

func (Config) CCIDSupported

func (c Config) CCIDSupported() bool

CCIDSupported reports whether the device exposes a CCID interface.

func (Config) FIDO21Supported

func (c Config) FIDO21Supported() bool

FIDO21Supported reports whether the device supports FIDO 2.1.

func (Config) FingerprintSensorPresent

func (c Config) FingerprintSensorPresent() bool

FingerprintSensorPresent reports whether the device has a fingerprint sensor.

func (Config) HOTPSupported

func (c Config) HOTPSupported() bool

HOTPSupported reports whether the device supports HOTP.

func (Config) NFCSupported

func (c Config) NFCSupported() bool

NFCSupported reports whether the device supports NFC.

func (Config) TOTPSupported

func (c Config) TOTPSupported() bool

TOTPSupported reports whether the device supports TOTP.

type Device

type Device interface {
	Close() error
}

Device is the lifecycle contract implemented by Token2 transport devices. Transport-specific capabilities are described by capability interfaces such as SerialNumberDevice and ATRDevice.

type Identity

type Identity struct {
	SerialNumber string
	Prefix       string
	CheckDigit   byte
	Suffix       string
	Model        Model
}

Identity contains the model information derived from a full Token2 serial number. Prefix, CheckDigit and Suffix are empty for range-based models.

func Identify

func Identify(serialNumber string) (Identity, bool)

Identify looks up a full Token2 serial number in the built-in model catalog.

type Model

type Model struct {
	Revision   string
	FormFactor string
	Branding   string
	Prefix     string

	SerialFrom uint64
	SerialTo   uint64
}

Model describes a Token2 hardware model identified by either a serial-number prefix or an inclusive serial-number range.

func Models

func Models() []Model

Models returns the built-in Token2 model catalog.

func (Model) DisplayName

func (m Model) DisplayName() string

DisplayName returns the canonical human-readable name of the model.

type SerialNumberDevice

type SerialNumberDevice interface {
	Device
	SerialNumber(context.Context) (string, error)
}

SerialNumberDevice is a Device capable of returning the full Token2 serial number.

type Version

type Version struct {
	Major byte
	Minor byte
	Patch byte
}

Version is a three-component firmware or protocol version.