hardwarekey

type AgentKeyInfo struct {
	// UnknownAgentKey indicates whether this hardware private key is known to the hardware key agent
	// process, usually based on whether a matching key is found in the process's client key store.
	//
	// For unknown agent keys, the hardware key service will check that the certificate in the same
	// slot as the key matches a Teleport client metadata certificate in order to ensure the agent
	// doesn't provide access to non teleport client PIV keys.
	UnknownAgentKey bool
	// Command is the command reported by the agent client which this agent key is being utilized to
	// complete, e.g. `tsh ssh server01`.
	Command string
}

type AttestationStatement attestationv1.AttestationStatement

type ContextualKeyInfo struct {
	// ProxyHost is the root proxy hostname that the key is associated with.
	ProxyHost string
	// Username is a Teleport username that the key is associated with.
	Username string
	// ClusterName is a Teleport cluster name that the key is associated with.
	ClusterName string
	// AgentKeyInfo contains info associated with an hardware key agent signature request.
	AgentKeyInfo AgentKeyInfo
}

type MockHardwareKeyService struct {
	// contains filtered or unexported fields
}

type PINAndPUK struct {
	// New PIN set by the user.
	PIN string
	// PUK used to change the PIN.
	// This is a new PUK if it has not been changed (from the default PUK).
	PUK string
	// PUKChanged is true if the user changed the default PUK.
	PUKChanged bool
}

type PINPromptRequirement int

type PIVSlotKey uint32

type PIVSlotKeyString string

type PrivateKeyConfig struct {
	// Policy is a prompt policy to require for the hardware private key.
	Policy PromptPolicy
	// CustomSlot is a specific PIV slot to generate the hardware private key in.
	// If unset, the default slot for the given policy will be used.
	//   - !touch & !pin -> 9a
	//   - !touch & pin  -> 9c
	//   - touch & pin   -> 9d
	//   - touch & !pin  -> 9e
	CustomSlot PIVSlotKeyString
	// Algorithm is the key algorithm to use. Defaults to [AlgorithmEC256].
	// [AlgorithmEd25519] is not supported by all hardware keys.
	Algorithm SignatureAlgorithm
	// ContextualKeyInfo contains additional info to associate with the key.
	ContextualKeyInfo ContextualKeyInfo
	// PINCacheTTL is an option to enable PIN caching for this key with the specified TTL.
	PINCacheTTL time.Duration
}

type PrivateKeyRef struct {
	// SerialNumber is the hardware key's serial number.
	SerialNumber uint32 `json:"serial_number"`
	// SlotKey is the key name for the hardware key PIV slot, e.g. "9a".
	SlotKey PIVSlotKey `json:"slot_key"`
	// PublicKey is the public key paired with the hardware private key.
	PublicKey crypto.PublicKey `json:"-"` // uses custom JSON marshaling in PKIX, ASN.1 DER form
	// Policy specifies the hardware private key's PIN/touch prompt policies.
	Policy PromptPolicy `json:"policy"`
	// AttestationStatement contains the hardware private key's attestation statement, which is
	// to attest the touch and pin requirements for this hardware private key during login.
	AttestationStatement *AttestationStatement `json:"attestation_statement"`
	// PINCacheTTL is how long hardware key prompts should cache the PIN for this key, if at all.
	PINCacheTTL time.Duration `json:"pin_cache_ttl"`
}

type Prompt interface {
	// AskPIN prompts the user for a PIN.
	// The requirement tells if the PIN is required or optional.
	AskPIN(ctx context.Context, requirement PINPromptRequirement, keyInfo ContextualKeyInfo) (string, error)
	// Touch prompts the user to touch the hardware key.
	Touch(ctx context.Context, keyInfo ContextualKeyInfo) error
	// ChangePIN asks for a new PIN.
	// If the PUK has a default value, it should ask for the new value for it.
	// It is up to the implementer how the validation is handled.
	// For example, CLI prompt can ask for a valid PIN/PUK in a loop, a GUI
	// prompt can use the frontend validation.
	ChangePIN(ctx context.Context, keyInfo ContextualKeyInfo) (*PINAndPUK, error)
	// ConfirmSlotOverwrite asks the user if the slot's private key and certificate can be overridden.
	ConfirmSlotOverwrite(ctx context.Context, message string, keyInfo ContextualKeyInfo) (bool, error)
}

type PromptPolicy struct {
	// TouchRequired means that touch is required for signatures.
	TouchRequired bool
	// PINRequired means that PIN is required for signatures.
	PINRequired bool
}

type Service interface {
	// NewPrivateKey creates a hardware private key that satisfies the provided [config],
	// if one does not already exist, and returns a corresponding [hardwarekey.Signer].
	NewPrivateKey(ctx context.Context, config PrivateKeyConfig) (*Signer, error)
	// Sign performs a cryptographic signature using the specified hardware
	// private key and provided signature parameters.
	Sign(ctx context.Context, ref *PrivateKeyRef, keyInfo ContextualKeyInfo, rand io.Reader, digest []byte, opts crypto.SignerOpts) (signature []byte, err error)
	// TODO(Joerger): DELETE IN v19.0.0
	// GetFullKeyRef gets the full [PrivateKeyRef] for an existing hardware private
	// key in the given slot of the hardware key with the given serial number.
	GetFullKeyRef(serialNumber uint32, slotKey PIVSlotKey) (*PrivateKeyRef, error)
}

type SignatureAlgorithm int

type Signer struct {
	Ref     *PrivateKeyRef
	KeyInfo ContextualKeyInfo
	// contains filtered or unexported fields
}