yubico

README

go-ctap/yubico

Pure-Go support for Yubico-specific device information and identity.

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

Packages

• yubico contains transport-independent device-information models, response parsing and canonical model naming.
• yubico/transport/ctaphid reads device information through Yubico's CTAPHID vendor command 0x42, using github.com/go-ctap/ctap.
• yubico/transport/pcsc reads device information through the Yubico management application on an exact PC/SC reader.
• yubico/resolver identifies a smart-card target and distinguishes a missing Yubico management application from transport or protocol failures.

The CTAPHID transport can open a FIDO HID collection by path and owns the resulting connection until Close. GetDeviceInfo also accepts an existing vendor-command channel without taking ownership of it. Both forms send logical command 0x42; CTAPHID framing adds the init-packet bit, so the on-wire command byte is 0xc2.

The PC/SC management AID, commands and status handling follow Yubico's Configuration Reference and the official yubikey-manager implementation.

Installation

go get github.com/go-ctap/yubico@latest

See go.mod for the required Go version.

Testing

go test ./...
go vet ./...

The test suite does not require hardware.

Documentation

Overview

Package yubico provides transport-independent Yubico device information, response parsing and identity naming.

CTAPHID access lives under transport/ctaphid.

Index

• Variables
• type Capability
  • func (i Capability) String() string
• type DeviceInfo
  • func ParseDeviceInfo(data []byte) (DeviceInfo, error)
  • func ParseDeviceInfoPages(pages ...[]byte) (DeviceInfo, error)
  • func (info DeviceInfo) EffectiveFirmwareVersion() FirmwareVersion
  • func (info DeviceInfo) HasNFC() bool
  • func (info DeviceInfo) ModelName(fallback string) string
• type FirmwareVersion
  • func (v FirmwareVersion) String() string
• type FormFactor
  • func (i FormFactor) String() string
• type ReleaseType
• type VersionQualifier

Variables

var ErrInvalidDeviceInfo = errors.New("yubico: invalid device information")

Types

type Capability

type Capability uint16

Capability is a bitmap of applications exposed by a YubiKey interface.

const (
	CapabilityOTP     Capability = 0x0001
	CapabilityU2F     Capability = 0x0002
	CapabilityCCID    Capability = 0x0004
	CapabilityOpenPGP Capability = 0x0008
	CapabilityPIV     Capability = 0x0010
	CapabilityOATH    Capability = 0x0020
	CapabilityHSMAuth Capability = 0x0100
	CapabilityCTAP2   Capability = 0x0200
)

func (Capability) String

func (i Capability) String() string

type DeviceInfo

type DeviceInfo struct {
	SupportedUSBCapabilities Capability
	Serial                   *uint32
	EnabledUSBCapabilities   Capability
	FormFactor               FormFactor
	IsFIPS                   bool
	IsSecurityKey            bool
	FirmwareVersion          FirmwareVersion
	VersionQualifier         *VersionQualifier
	AutoEjectTimeout         uint16
	ChallengeResponseTimeout byte
	DeviceFlags              byte
	Locked                   bool
	PartNumber               *string
	FIPSCapable              Capability
	FIPSApproved             Capability
	PinComplexity            bool
	NFCRestricted            bool
	ResetBlocked             Capability
	FPSVersion               *FirmwareVersion
	STMVersion               *FirmwareVersion
	SupportedNFCCapabilities *Capability
	EnabledNFCCapabilities   *Capability
	UnknownFields            map[byte][]byte
}

DeviceInfo is returned by Yubico's GET DEVICE INFORMATION command. UnknownFields preserves tags introduced by newer firmware.

func ParseDeviceInfo

func ParseDeviceInfo(data []byte) (DeviceInfo, error)

ParseDeviceInfo parses TOTAL-LENGTH followed by TAG-LENGTH-VALUE fields.

func ParseDeviceInfoPages

func ParseDeviceInfoPages(pages ...[]byte) (DeviceInfo, error)

ParseDeviceInfoPages parses and merges one or more paginated device-info responses. Fields from later pages replace fields with the same tag from earlier pages.

func (DeviceInfo) EffectiveFirmwareVersion

func (info DeviceInfo) EffectiveFirmwareVersion() FirmwareVersion

EffectiveFirmwareVersion returns the version used for behavioral checks. Alpha and beta firmware report this version through VersionQualifier.

func (DeviceInfo) HasNFC

func (info DeviceInfo) HasNFC() bool

HasNFC reports whether NFC capability data is valid for this form factor and firmware generation.

func (DeviceInfo) ModelName

func (info DeviceInfo) ModelName(fallback string) string

ModelName returns the canonical marketing name derived from Yubico device information. fallback is returned for firmware generations whose naming rules are not known.

type FirmwareVersion

type FirmwareVersion struct {
	Major byte
	Minor byte
	Build byte
}

FirmwareVersion is the major.minor.build version reported by the device.

func (FirmwareVersion) String

func (v FirmwareVersion) String() string

String formats a non-zero firmware version as major.minor.build.

type FormFactor

type FormFactor byte

FormFactor describes the physical shape and connector type of a YubiKey.

const (
	FormFactorUnknown               FormFactor = 0
	FormFactorUSBAKeychain          FormFactor = 1
	FormFactorUSBANano              FormFactor = 2
	FormFactorUSBCKeychain          FormFactor = 3
	FormFactorUSBCNano              FormFactor = 4
	FormFactorUSBCLightning         FormFactor = 5
	FormFactorUSBABiometricKeychain FormFactor = 6
	FormFactorUSBCBiometricKeychain FormFactor = 7
)

func (FormFactor) String

func (i FormFactor) String() string

type ReleaseType

type ReleaseType byte

ReleaseType identifies the release stage of qualified firmware.

const (
	ReleaseTypeAlpha ReleaseType = iota
	ReleaseTypeBeta
	ReleaseTypeFinal
)

type VersionQualifier

type VersionQualifier struct {
	Version     FirmwareVersion
	ReleaseType ReleaseType
	Iteration   uint32
}

VersionQualifier contains the behavioral firmware version reported by development firmware.