provider

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Apr 22, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package provider defines the interface for cryptkey authentication providers.

Each provider can produce a deterministic 32-byte secret during enrollment and re-derive it during key reconstruction. The secret is used to encrypt that provider's Shamir share; it never leaves the provider boundary.

Index

Constants

This section is empty.

Variables

View Source 
var ErrSkipped = errors.New("provider skipped by user")

ErrSkipped signals that the user declined to participate in the current provider derivation (e.g. by pressing Escape on a PIN prompt). The derive command treats this as a deliberate skip rather than a failure, so the provider is omitted from Shamir share recovery and the threshold check continues with the remaining providers.

Functions

func GetProgressFunc 

func GetProgressFunc(ctx context.Context) func(string)

GetProgressFunc returns the progress callback stored on ctx (set by the CLI or TUI to route status updates), or a no-op func when no callback is set. Providers call this to surface interim status without having to branch on whether a callback is present. Callers that want a stderr fallback when no callback is set (e.g. passkey's browser flow) should implement that locally.

func List 

func List() []string

List returns all registered provider type names, sorted.

func Register 

func Register(p Provider)

Register adds a provider to the global registry. Called from init().

func WithEnrollOptions 

func WithEnrollOptions(ctx context.Context, options map[string]string) context.Context

WithEnrollOptions returns a context with each option stored under CtxEnrollOption(key). Centralizing the loop keeps call sites tidy and means the "nested context in loop" pattern only appears here, once.

Types

type ConfigurableProvider 

type ConfigurableProvider interface {
	// EnrollOptions returns the configurable options for this provider.
	EnrollOptions() []EnrollOption
}

ConfigurableProvider is an optional interface for providers that have options the user can configure during enrollment (e.g., FIDO2 UV mode).

type ContextKey 

type ContextKey string

ContextKey is the type for provider context keys. Exported so that provider packages can define their own keys of the same type. 

const (
	// CtxPassphrase carries a []byte passphrase collected by the TUI.
	CtxPassphrase ContextKey = "passphrase"

	// CtxArgonTime carries the Argon2id time/iterations parameter.
	CtxArgonTime ContextKey = "argon_time"

	// CtxArgonMemory carries the Argon2id memory parameter in KiB.
	CtxArgonMemory ContextKey = "argon_memory"

	// CtxArgonThreads carries the Argon2id parallelism parameter.
	CtxArgonThreads ContextKey = "argon_threads"

	// CtxFIDO2UV carries the FIDO2 user verification preference.
	// Values: "discouraged", "preferred", "required".
	CtxFIDO2UV ContextKey = "fido2_uv"

	// CtxFIDO2DevicePath carries the selected FIDO2 device path (e.g., "/dev/hidraw3").
	CtxFIDO2DevicePath ContextKey = "fido2_device_path"

	// CtxFIDO2PIN carries the FIDO2 PIN as a string.
	CtxFIDO2PIN ContextKey = "fido2_pin"

	// CtxSSHAgentKeyFingerprint carries the selected SSH agent key fingerprint.
	CtxSSHAgentKeyFingerprint ContextKey = "sshagent_key_fingerprint"

	// CtxSSHKeyPath carries the absolute path to the SSH private key file.
	CtxSSHKeyPath ContextKey = "sshkey_path"

	// CtxSSHKeyPassphrase carries the SSH key passphrase ([]byte).
	CtxSSHKeyPassphrase ContextKey = "sshkey_passphrase" //nolint:gosec // not a credential, just a context key name

	// CtxPIVPIN carries the PIV PIN as a string.
	CtxPIVPIN ContextKey = "piv_pin"

	// CtxPIVSerial carries the pre-selected PIV device serial number.
	CtxPIVSerial ContextKey = "piv_serial"

	// CtxPIVOverwrite carries a bool indicating the user confirmed
	// overwriting existing PIV slot key material during enrollment.
	CtxPIVOverwrite ContextKey = "piv_overwrite"

	// CtxSilent suppresses stderr output from providers. Set by the TUI
	// since it controls all display.
	CtxSilent ContextKey = "silent"

	// CtxProgressFunc carries a func(string) that providers call to report
	// progress (e.g., "Touch again to derive secret..."). The TUI uses this
	// to update status while enrollment runs in a goroutine.
	CtxProgressFunc ContextKey = "progress_func"

	// CtxPromptPassword carries a func(providerType, label, hint string) (string, error)
	// for reading secrets inline with progress output during derive. The
	// display masks each keystroke with a bullet on a TTY; hint (optional)
	// renders in dim text next to the label (e.g. "esc to skip").
	CtxPromptPassword ContextKey = "prompt_password"

	// CtxPromptLine carries a func(providerType, label, hint string) (string, error)
	// for reading lines (with echo) inline with progress output during derive.
	// hint (optional) renders in dim text next to the label.
	CtxPromptLine ContextKey = "prompt_line"

	// CtxProgressLink carries a func(prefix, url string) that providers
	// call to emit a labeled URL line with the URL rendered in dim text
	// on interactive terminals (e.g. the passkey browser open message).
	CtxProgressLink ContextKey = "progress_link"

	// CtxUpdateWaitingDetail carries a func(string) that a hardware
	// provider can call to set a right-aligned dim detail string on the
	// derive command's existing waiting line — e.g. passkey surfacing the
	// local auth URL as a fallback in case auto-browser-open fails. The
	// caller (derive command) repaints the line with the new detail so
	// no extra lines appear.
	CtxUpdateWaitingDetail ContextKey = "update_waiting_detail"
)

func CtxEnrollOption 

func CtxEnrollOption(key string) ContextKey

CtxEnrollOption returns a ContextKey for a provider-specific enrollment option.

type EnrollOption 

type EnrollOption struct {
	Key         string            // internal key (e.g., "uv")
	Label       string            // display label (e.g., "User Verification")
	Shortcut    string            // TUI key shortcut (e.g., "u")
	Values      []string          // allowed values in cycle order
	Default     string            // default value
	Description string            // short description shown in TUI
	ValueHelp   map[string]string // optional per-value help text shown when focused
}

EnrollOption describes a configurable option for a provider during enrollment.

type EnrollResult 

type EnrollResult struct {
	Secret  []byte            // exactly 32 bytes
	Params  map[string]string // metadata to store in the profile config
	Message string            // optional message to display after enrollment (e.g. recovery code)
}

EnrollResult is returned by a successful Enroll call.

type HardwareProvider 

type HardwareProvider interface {
	DeriveTimeout() time.Duration
}

HardwareProvider is an optional interface for providers that block on physical user interaction (touch, browser). These get automatic timeouts during derivation.

type InteractiveProvider 

type InteractiveProvider interface {
	InteractiveDerive() bool
}

InteractiveProvider is an optional interface that providers can implement to indicate whether their Derive method reads from the terminal (e.g., prompting for a passphrase or PIN). When true, no timeout is applied during derivation since the user is actively providing input. Providers that do not implement this interface are assumed interactive.

type OptionWarner 

type OptionWarner interface {
	// EnrollWarning returns a warning string for the current option values,
	// or "" if no warning applies.
	EnrollWarning(values map[string]string) string
}

OptionWarner is an optional interface for configurable providers that can warn about potentially problematic option combinations (e.g., high Argon2 cost).

type PreDeriver 

type PreDeriver interface {
	PreDerive(ctx context.Context, params map[string]string) (context.Context, error)
}

PreDeriver is an optional interface for providers that need interactive setup (e.g., PIN collection) before the timeout-wrapped hardware call. The returned context should carry any collected values (e.g., PIN). This runs BEFORE the timeout starts, so there's no tty conflict.

type Provider 

type Provider interface {
	// Type returns the provider type name (e.g. "passphrase", "fido2").
	Type() string

	// Description returns a short human-readable description.
	Description() string

	// Enroll performs interactive enrollment and returns the 32-byte secret
	// along with provider-specific metadata to persist in the config file.
	Enroll(ctx context.Context, id string) (*EnrollResult, error)

	// Derive re-derives the 32-byte secret from stored metadata.
	Derive(ctx context.Context, params map[string]string) ([]byte, error)
}

Provider is the interface all authentication providers implement.

func All 

func All() []Provider

All returns all registered providers, sorted by type name.

func Get 

func Get(name string) (Provider, bool)

Get returns a registered provider by type name.

Source Files

View all Source files

Directories

Path Synopsis
Package fido2 implements a provider that derives a 32-byte secret from a FIDO2 hardware key using the hmac-secret extension.
 Package fido2 implements a provider that derives a 32-byte secret from a FIDO2 hardware key using the hmac-secret extension.
Package passkey implements a provider that uses the WebAuthn PRF extension via the user's browser to derive a deterministic 32-byte secret from a passkey (platform authenticator, security key, or cross-device via phone).
 Package passkey implements a provider that uses the WebAuthn PRF extension via the user's browser to derive a deterministic 32-byte secret from a passkey (platform authenticator, security key, or cross-device via phone).
Package passphrase implements a provider that derives a 32-byte secret from a user-supplied passphrase using Argon2id.
 Package passphrase implements a provider that derives a 32-byte secret from a user-supplied passphrase using Argon2id.
Package piv implements a provider that derives a 32-byte secret from a PIV-compatible hardware token (e.g., YubiKey) using the go-piv library.
 Package piv implements a provider that derives a 32-byte secret from a PIV-compatible hardware token (e.g., YubiKey) using the go-piv library.
Package recovery implements a provider that generates a high-entropy recovery code, displays it once, and derives a 32-byte secret from it via Argon2id.
 Package recovery implements a provider that generates a high-entropy recovery code, displays it once, and derives a 32-byte secret from it via Argon2id.
Package sshagent implements a provider that derives a 32-byte secret by having the SSH agent sign a deterministic challenge.
 Package sshagent implements a provider that derives a 32-byte secret by having the SSH agent sign a deterministic challenge.
Package sshkey implements a provider that derives a 32-byte secret from an SSH private key.
 Package sshkey implements a provider that derives a 32-byte secret from an SSH private key.
Package tpm implements a provider that derives a 32-byte secret using a TPM 2.0 HMAC key.
 Package tpm implements a provider that derives a 32-byte secret using a TPM 2.0 HMAC key.

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.