ctaphid

README

go-ctaphid

go-ctaphid is an idiomatic Go library implementing the CTAPHID transport protocol to interact with FIDO2 authenticators, featuring a clean, modern API with multiple layers of abstraction.

[!WARNING] Work in progress! API may change during v0.x!

Current Status

Library supports almost entire CTAP 2.2 specification, except few extensions which are not yet seen in the wild (hmac-secret-mc, dedicated largeBlob, not to be confused with largeBlobKey which is supported).

My current priorities are to write better tests and completely replace sstallion/go-hid with the own cgo-free alternative.

Key Features and Architecture

The library exposes several abstraction levels, allowing you to choose the API that best suits your needs:

1. Transport Layer (ctaphid)

   Direct access to the raw CTAPHID transport protocol. If you need maximum control, you can communicate with devices at the frame level.

2. Protocol Layer (ctap)

   Implements CTAP 2.2 protocol messaging atop the transport, letting you work with high-level commands and CBOR-encoded messages.

3. Device Abstraction (device)

   Provides a convenient wrapper over the ctap package, managing device descriptor and abstracting channel (CID) management, so you don’t have to handle these low-level details manually.

4. Scenario Helpers (sugar) (Mostly TODO now)

   A growing set of utility functions for common use-cases. These helpers streamline trivial or repetitive scenarios, letting you get started quickly without deep protocol knowledge.

Highlights

• Implements major FIDO2 commands: MakeCredential, GetAssertion, ClientPIN (with both PIN/UV methods), Reset, CredentialManagement, and more.
• Both low-level access and ergonomic, high-level APIs.
• Modern Go design, making use of language features like iterators.
• cgo is currently used only for macOS version (for HID transport), but FIDO2 protocol logic is pure Go.

Feature Matrix

CTAP 2.2

• MakeCredential
• GetAssertion / GetNextAssertion
• GetInfo
• ClientPIN
  • getPINRetries
  • getKeyAgreement
  • setPIN
  • changePIN
  • getPinToken
  • getPinUvAuthTokenUsingUvWithPermissions
  • getUVRetries
  • getPinUvAuthTokenUsingPinWithPermissions
• Reset
• BioEnrollment
  • enrollBegin
  • enrollCaptureNextSample
  • cancelCurrentEnrollment
  • enumerateEnrollments
  • setFriendlyName
  • removeEnrollment
  • getFingerprintSensorInfo
• CredentialManagement
  • getCredsMetadata
  • enumerateRPsBegin / enumerateRPsGetNextRP
  • enumerateCredentialsBegin / enumerateCredentialsGetNextCredential
  • deleteCredential
  • updateUserInformation
• Selection
• LargeBlobs
  • raw get
  • raw set
  • get serialized large-blob array
  • set serialized large-blob array
• Config
  • enableEnterpriseAttestation
  • toggleAlwaysUv
  • setMinPINLength
• Prototype BioEnrollment
• Prototype CredentialManagement

Extensions

CTAP

• credProtect
• credBlob
• largeBlobKey
• largeBlob
• minPinLength
• pinComplexityPolicy
• hmac-secret
• hmac-secret-mc
• thirdPartyPayment

WebAuhn

• credProps
• prf
• largeBlob

Crypto

• PIN/UV Auth Protocol One
• PIN/UV Auth Protocol Two
• Encrypt/Decrypt using LargeBlobsKey extension

Build Dependencies

Linux

For Linux systems, you'll need to install the following packages to build:

• libudev-dev: udev device management library
• libusb-1.0-0-dev: USB device access library

Planned Improvements

• Better tests (using virtual authenticator?)
• Extended "sugar" helpers for common use-cases.
• cgo-free version for macOS. See go-hid.