device

package
v0.8.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 15, 2025 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrPingPongMismatch         = errors.New("device: ping/pong mismatch")
	ErrPinUvAuthTokenRequired   = errors.New("device: pinUvAuthToken required")
	ErrBuiltInUVRequired        = errors.New("device: built-in user verification required")
	ErrNotSupported             = errors.New("device: not supported")
	SyntaxError                 = errors.New("device: syntax error")
	ErrBadType                  = errors.New("device: bad type")
	ErrInvalidSaltSize          = errors.New("device: invalid salt size")
	ErrPinNotSet                = errors.New("device: pin not set")
	ErrPinAlreadySet            = errors.New("device: pin already set")
	ErrUvNotConfigured          = errors.New("device: UV not configured")
	ErrLargeBlobsIntegrityCheck = errors.New("device: large blobs integrity check failed")
	ErrLargeBlobsTooBig         = errors.New("device: size of serialized large blobs is too big that token")
)

Functions

func Enumerate 

func Enumerate(ctx context.Context) iter.Seq2[*ghid.DeviceInfo, error]

func OpenPath 

func OpenPath(ctx context.Context, path string) (dev io.ReadWriteCloser, err error)

Types

type CtxKey 

type CtxKey = string
const (
	CtxKeyUseNamedPipe CtxKey = "useNamedPipe"
)

type Device 

type Device struct {
	Path string
	// contains filtered or unexported fields
}

Device represents a physical or virtual hardware device supporting CTAP communication protocols.

func New 

func New(path string, opts ...options.Option) (*Device, error)

New creates a new Device instance from a given HID path. It also initializes a new underlying CTAP2 client with the provided options.

func (*Device) BeginEnroll 

func (d *Device) BeginEnroll(
	pinUvAuthToken []byte,
	timeoutMilliseconds uint,
) (*ctaptypes.AuthenticatorBioEnrollmentResponse, error)

BeginEnroll begins a fingerprint enrollment process and returns TemplateID, LastEnrollSampleStatus, and RemainingSamples properties. Use those properties to continue to capture the next samples or cancel it.

func (*Device) CancelCurrentEnrollment 

func (d *Device) CancelCurrentEnrollment() error

CancelCurrentEnrollment cancels a current enrollment process.

func (*Device) ChangePIN 

func (d *Device) ChangePIN(currentPin, newPin string) error

ChangePIN updates the device's PIN by using the provided current PIN and new PIN. Returns an error if the device does not support clientPin or if the PIN change process fails.

func (*Device) Close 

func (d *Device) Close() error

Close closes the underlying HID device.

func (*Device) DeleteCredential 

func (d *Device) DeleteCredential(
	pinUvAuthToken []byte,
	credentialID webauthntypes.PublicKeyCredentialDescriptor,
) error

DeleteCredential removes a specified credential from the device using the given authentication token. It returns an error if credential management is not supported or the operation fails.

func (*Device) EnableEnterpriseAttestation 

func (d *Device) EnableEnterpriseAttestation(pinUvAuthToken []byte) error

EnableEnterpriseAttestation enables enterprise attestation on the device if supported, using the provided token.

func (*Device) EnrollCaptureNextSample 

func (d *Device) EnrollCaptureNextSample(
	pinUvAuthToken []byte,
	templateID []byte,
	timeoutMilliseconds uint,
) (*ctaptypes.AuthenticatorBioEnrollmentResponse, error)

EnrollCaptureNextSample continues capturing samples from an already started enrollment process.

func (*Device) EnumerateCredentials 

func (d *Device) EnumerateCredentials(pinUvAuthToken []byte, rpIDHash []byte) iter.Seq2[*ctaptypes.AuthenticatorCredentialManagementResponse, error]

EnumerateCredentials provides a generator function to iterate over Credentials stored on the device for the specified Relying Party. It utilizes the Credential Management extension and yields results via a callback function. If the device does not support credential management, an error is yielded.

func (*Device) EnumerateEnrollments 

func (d *Device) EnumerateEnrollments(pinUvAuthToken []byte) (*ctaptypes.AuthenticatorBioEnrollmentResponse, error)

EnumerateEnrollments enumerates enrollments by returning TemplateInfos property with an array of TemplateInfo for all the enrollments available on the authenticator.

func (*Device) EnumerateRPs 

func (d *Device) EnumerateRPs(pinUvAuthToken []byte) iter.Seq2[*ctaptypes.AuthenticatorCredentialManagementResponse, error]

EnumerateRPs provides a generator function to iterate over Relying Parties stored on the device. It utilizes the Credential Management extension and yields results via a callback function. If the device does not support credential management, an error is yielded.

func (*Device) GetAssertion 

func (d *Device) GetAssertion(
	pinUvAuthToken []byte,
	rpID string,
	clientData []byte,
	allowList []webauthntypes.PublicKeyCredentialDescriptor,
	extInputs *webauthntypes.GetAuthenticationExtensionsClientInputs,
	options map[ctaptypes.Option]bool,
) iter.Seq2[*ctaptypes.AuthenticatorGetAssertionResponse, error]

GetAssertion provides a generator function to iterate over assertions stored on the device for the specified Relying Party, clientDataHash, and allowed list (in case of non-discoverable credentials). It yields results via a callback function.

func (*Device) GetBioModality 

func (d *Device) GetBioModality() (*ctaptypes.AuthenticatorBioEnrollmentResponse, error)

GetBioModality returns bio modality of authenticator. Currently, only fingerprint modality is defined in the FIDO 2.2 specification.

func (*Device) GetCredsMetadata 

func (d *Device) GetCredsMetadata(pinUvAuthToken []byte) (*ctaptypes.AuthenticatorCredentialManagementResponse, error)

GetCredsMetadata retrieves credential management metadata if the device supports it. Mainly ExistingResidentCredentialsCount and MaxPossibleRemainingResidentCredentialsCount.

func (*Device) GetFingerprintSensorInfo 

func (d *Device) GetFingerprintSensorInfo() (*ctaptypes.AuthenticatorBioEnrollmentResponse, error)

GetFingerprintSensorInfo returns three properties: 

	FingerprintKind: For touch type fingerprints, its value is 1. For swipe type fingerprints, its value is 2.
	MaxCaptureSamplesRequiredForEnroll: Indicates the maximum good samples required for enrollment.
 	MaxTemplateFriendlyName: Indicates the maximum number of bytes the authenticator will accept as a templateFriendlyName.

func (*Device) GetInfo 

func (d *Device) GetInfo() *ctaptypes.AuthenticatorGetInfoResponse

GetInfo returns the struct containing metadata and capabilities of the device.

func (*Device) GetLargeBlobs 

func (d *Device) GetLargeBlobs() ([]*ctaptypes.LargeBlob, error)

GetLargeBlobs retrieves a list of large blobs from the device that supports the large blobs option. Returns an error if the device does not support large blobs or if there is an issue with the retrieval process. Ensures integrity by validating computed and actual hashes of the retrieved data.

func (*Device) GetPINRetries 

func (d *Device) GetPINRetries() (uint, bool, error)

GetPINRetries retrieves the number of PIN retries remaining for the device, and if it requires a power cycle (after reaching the limit, you can reset remaining tries by re-connecting the token).

func (*Device) GetPinUvAuthTokenUsingPIN 

func (d *Device) GetPinUvAuthTokenUsingPIN(
	pin string,
	permission ctaptypes.Permission,
	rpID string,
) ([]byte, error)

GetPinUvAuthTokenUsingPIN obtains a pinUvAuthToken using a given PIN, permission, and in some cases optional Relying Party ID. Returns a token as a byte slice or an error if the operation fails. Checks device capabilities and permissions before proceeding.

func (*Device) GetPinUvAuthTokenUsingUV 

func (d *Device) GetPinUvAuthTokenUsingUV(permission ctaptypes.Permission, rpID string) ([]byte, error)

GetPinUvAuthTokenUsingUV obtains a pinUvAuthToken by performing user verification (UV) on a compatible device. Returns an error if the device does not support pinUvAuthToken or user verification features. Requires the permission type and optionally Relying Party ID (rpID) in some cases to execute successfully.

func (*Device) GetUVRetries 

func (d *Device) GetUVRetries() (uint, error)

GetUVRetries retrieves the number of remaining user verification retries from the device. Returns an error if the device does not support user verification.

func (*Device) Lock 

func (d *Device) Lock(seconds uint) error

Lock places an exclusive lock for one channel to communicate with the device. As long as the lock is active, any other channel trying to send a message will fail. Send 0 seconds to unlock the channel.

func (*Device) MakeCredential 

func (d *Device) MakeCredential(
	pinUvAuthToken []byte,
	clientData []byte,
	rp webauthntypes.PublicKeyCredentialRpEntity,
	user webauthntypes.PublicKeyCredentialUserEntity,
	pubKeyCredParams []webauthntypes.PublicKeyCredentialParameters,
	excludeList []webauthntypes.PublicKeyCredentialDescriptor,
	extInputs *webauthntypes.CreateAuthenticationExtensionsClientInputs,
	options map[ctaptypes.Option]bool,
	enterpriseAttestation uint,
	attestationFormatsPreference []webauthntypes.AttestationStatementFormatIdentifier,
) (*ctaptypes.AuthenticatorMakeCredentialResponse, error)

MakeCredential initiates the process of creating a new credential on a device with specified parameters and options.

func (*Device) Ping 

func (d *Device) Ping(ping []byte) error

Ping sends a ping message to the device and verifies the response matches the sent data. Returns an error on failure.

func (*Device) RemoveEnrollment 

func (d *Device) RemoveEnrollment(pinUvAuthToken []byte, templateID []byte) error

RemoveEnrollment removes existing enrollment.

func (*Device) Reset 

func (d *Device) Reset() error

Reset performs a factory reset on the device, clearing all stored user data and resetting it to its default state. Some devices require doing reset within 10 seconds after you connected the token.

func (*Device) Selection 

func (d *Device) Selection(ctx context.Context) error

Selection is a higher-level version of ctap.Selection, which cancels the command if the context is canceled.

func (*Device) SetFriendlyName 

func (d *Device) SetFriendlyName(pinUvAuthToken []byte, templateID []byte, friendlyName string) error

SetFriendlyName allows renaming/setting of a friendly fingerprint name.

func (*Device) SetLargeBlobs 

func (d *Device) SetLargeBlobs(pinUvAuthToken []byte, blobs []*ctaptypes.LargeBlob) error

SetLargeBlobs stores large blobs on the device, ensuring compatibility with its supported capabilities and limits. It validates device support, fragments the blob data if needed, and sends it in chunks to the device. Returns an error if the device does not support large blobs, the data exceeds size limits, or if any other failure occurs.

func (*Device) SetMinPINLength 

func (d *Device) SetMinPINLength(
	pinUvAuthToken []byte,
	newMinPINLength uint,
	minPinLengthRPIDs []string,
	forceChangePin bool,
	pinComplexityPolicy bool,
) error

func (*Device) SetPIN 

func (d *Device) SetPIN(pin string) error

SetPIN sets a new PIN on the device if the clientPin option is supported and no PIN exists. Returns an error if the device does not support clientPin or if it was already set with PIN.

func (*Device) ToggleAlwaysUV 

func (d *Device) ToggleAlwaysUV(pinUvAuthToken []byte) error

ToggleAlwaysUV toggles the always UV (User Verification) setting on the device if supported, using the provided token.

func (*Device) UpdateUserInformation 

func (d *Device) UpdateUserInformation(
	pinUvAuthToken []byte,
	credentialID webauthntypes.PublicKeyCredentialDescriptor,
	user webauthntypes.PublicKeyCredentialUserEntity,
) error

UpdateUserInformation updates information of an existing user credential on the device. Requires the device to support credential management features. Returns an error if the operation is not supported or fails.

func (*Device) Wink 

func (d *Device) Wink() error

Wink sends a blink command to the device to visually signal its presence to the user. It uses the CTAPHID_WINK command, which is optional and could be unsupported by some devices.

type ErrorWithMessage 

type ErrorWithMessage struct {
	Message string
	Err     error
}

func (*ErrorWithMessage) Error 

func (m *ErrorWithMessage) Error() string

func (*ErrorWithMessage) Unwrap 

func (m *ErrorWithMessage) Unwrap() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.