snapshot of https://github.com/ory/kratos.git (master, 2026-09-15; blobs > 131072B omitted)

selfservice/strategy/deviceauthn/key.go

@@ -0,0 +1,198 @@
+// Copyright © 2026 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package deviceauthn
+
+import (
+	"time"
+)
+
+// The valid values (Android, iOS) are pinned as an enum via the OpenAPI patch
+// in .schema/openapi/patches/schema.yaml. (Detached from the doc comment to
+// stay out of the generated API description.)
+
+// DeviceType is the platform the key was enrolled on.
+//
+// "Android" and "iOS" use different attestation and signature encodings.
+type DeviceType string
+
+const (
+	DeviceTypeAndroid DeviceType = "Android"
+	DeviceTypeIOS     DeviceType = "iOS"
+)
+
+// The valid values (initial, confirmed, locked) are pinned as an enum via the
+// OpenAPI patch in .schema/openapi/patches/schema.yaml. (Detached from the doc
+// comment to stay out of the generated API description.)
+
+// KeyState is the lifecycle state of an enrolled key.
+//
+// Only a "confirmed" key can be used to authenticate. A "locked" key was
+// disabled after too many wrong-PIN attempts; rotating its pin_secret unlocks
+// it.
+type KeyState string
+
+const (
+	KeyStateInitial   KeyState = "initial"
+	KeyStateConfirmed KeyState = "confirmed"
+	// KeyStateLocked marks a PIN key disabled after too many wrong-PIN attempts.
+	KeyStateLocked KeyState = "locked"
+)
+
+// The schema name stays UpperCamelCase on purpose: it is part of the published
+// DeviceAuthn schema family (DeviceAuthnKey, DeviceType, KeyState, PINConfig),
+// which all use UpperCamelCase. Renaming it to the lowerCamelCase the core
+// naming convention prefers would be a breaking change to the public SDK and
+// would split the family's casing, so the deliberate exception is kept.
+// The valid values (pin, platform, none) are pinned as an enum via the OpenAPI
+// patch in .schema/openapi/patches/schema.yaml. (Detached from the doc comment
+// to stay out of the generated API description.)
+
+// UserVerification records how the key's holder is verified at use time.
+//
+// "pin" means the holder proves knowledge of a PIN via pin_proof at login;
+// "platform" means the device gates key use behind platform biometrics or an
+// equivalent lock screen; "none" marks a possession-only key, usable as a
+// second factor but never as the sole first factor. The empty value marks a
+// legacy key from before user verification existed; such keys are rejected at
+// login and must be re-enrolled.
+type UserVerification string
+
+const (
+	UserVerificationPIN      UserVerification = "pin"
+	UserVerificationPlatform UserVerification = "platform"
+	// UserVerificationNone marks a possession-only key: usable as a second
+	// factor (step-up) but never as a first factor, which login enforces.
+	// Unlike JWT's alg=none the value strictly reduces what the key may do —
+	// it bypasses no verification. It covers keys deliberately enrolled
+	// without PIN or platform verification.
+	UserVerificationNone UserVerification = "none"
+)
+
+// PINConfig holds only scalar fields, so it is safe to shallow copy; the pointer
+// on Key.PIN encodes optionality (nil means no PIN), not copy safety.
+//
+// The schema name stays UpperCamelCase: it belongs to the published DeviceAuthn
+// schema family (DeviceAuthnKey, DeviceType, KeyState, UserVerification), and
+// renaming it would break the public SDK.
+// (Detached from the doc comment to stay out of the generated API description.)
+
+// PINConfig is the per-key PIN state.
+//
+// The pin_secret field holds only the at-rest ciphertext; the plaintext
+// exists transiently in server memory during verification and is invalidated
+// once the key locks.
+type PINConfig struct {
+	// pin_secret holds ciphertext of the kratos cipher (hex) and must never be
+	// returned to or logged by clients; the OpenAPI patch in
+	// .schema/openapi/patches/schema.yaml marks it write-only.
+	// (Detached from the doc comment to stay out of the API description.)
+
+	// The at-rest ciphertext of the pin_secret. It never leaves the server and
+	// is cleared once the key locks.
+	PINSecret string `json:"pin_secret"`
+	// A negative stored value must be a decode error instead of silently
+	// extending the attempt budget, hence uint. (Detached from the doc comment
+	// to stay out of the generated API description.)
+
+	// The number of consecutive wrong-PIN attempts so far; the key locks when
+	// it reaches the configured maximum (pin_max_attempts, default 5).
+	FailedAttempts uint `json:"failed_attempts"`
+	// When the pin_secret was first issued.
+	CreatedAt time.Time `json:"created_at"`
+
+	// When the pin_secret was last rotated. Omitted if the secret was never
+	// rotated.
+	RotatedAt time.Time `json:"rotated_at,omitzero"`
+}
+
+// Key is safe to shallow copy as long as the shared reference fields (PublicKey,
+// PIN, Attestation, RelaxedAttestationExpiresAt) are treated as read-only:
+// in-place mutation goes through a *Key into the backing slice, and the merge
+// copies PIN rather than aliasing it. Kept out of the doc comment so it stays
+// out of the generated API description.
+
+// An enrolled device authentication (DeviceAuthn) key.
+//
+// Represents a hardware-backed signing key enrolled from a mobile device.
+// The private key resides inside the device and never exists on the server.
+//
+// To list the identity's enrolled keys, fetch a settings flow: each key's
+// remove button (a `ui.nodes` entry named `deviceauthn_remove` in group
+// `deviceauthn`) carries the key, with its PIN state redacted, in the node
+// label's `context`.
+//
+// swagger:model DeviceAuthnKey
+type Key struct {
+	// We intentionally avoid storing the cryptographic algorithm a la JWT/TLS to
+	// avoid security issues and algorithm negotiation; a future v2 may use
+	// ML-DSA (post-quantum) once Android/iOS support it. (Detached from the doc
+	// comment to stay out of the generated API description.)
+
+	// The cryptography version of the key. Version 1 uses ECDSA with SHA-256
+	// on an elliptic curve (P-224, P-256, P-384, or P-521); further versions
+	// are reserved for future signature suites.
+	Version int `json:"version"`
+
+	// A human-readable name for the device, helping the user tell this key
+	// apart from others.
+	DeviceName string `json:"device_name"`
+	// The device's public key (an elliptic-curve key on P-224, P-256, P-384,
+	// or P-521 in version 1) in PKIX, ASN.1 DER (SubjectPublicKeyInfo) form,
+	// base64-encoded. Signatures are verified against this key.
+	//
+	// swagger:strfmt byte
+	PublicKey []byte `json:"public_key,omitempty"`
+
+	// The key's stable id, unique per identity. Submit it as the
+	// `client_key_id` when logging in with the key, deleting it, or rotating
+	// its pin_secret.
+	//
+	// The device can also compute the id without reading it back from the
+	// server: it is the lowercase-hex SHA-256 of `public_key` (the key's
+	// PKIX, ASN.1 DER encoding). Keys enrolled before the server derived the
+	// id keep their original client-chosen value, so prefer reading this
+	// field over recomputing it for older keys.
+	ClientKeyID string `json:"client_key_id"`
+	// When the key was enrolled. Only used for troubleshooting and UI.
+	CreatedAt time.Time `json:"created_at"`
+
+	// The platform the key was enrolled on, "Android" or "iOS". The two
+	// platforms use different attestation and signature encodings.
+	DeviceType DeviceType `json:"device_type"`
+
+	// Auto-confirmation vs. an admin confirmation call (for out-of-band KYC,
+	// e.g. a physical letter with a code) is not configurable yet; keys are
+	// auto-confirmed at creation time. (Detached from the doc comment to stay
+	// out of the generated API description.)
+
+	// The lifecycle state of the key. Only a "confirmed" key can be used to
+	// authenticate; a "locked" key was disabled after too many wrong-PIN
+	// attempts.
+	State KeyState `json:"state"`
+
+	// How the key's holder is verified at use time: "pin", "platform", or
+	// "none". Empty for legacy keys enrolled before user verification existed;
+	// such keys are rejected at login and must be re-enrolled.
+	UserVerification UserVerification `json:"user_verification,omitempty"`
+	// The per-key PIN state. Absent unless the key is PIN-protected.
+	PIN *PINConfig `json:"pin,omitempty"`
+
+	// The platform-specific attestation captured at enrollment. Useful for
+	// telling keys apart in the UI (e.g. OS version, manufacturer) and for
+	// forensics.
+	Attestation *Attestation `json:"attestation,omitempty"`
+
+	// Set only when the key's attestation chain was accepted under relaxed
+	// rules (software roots, expired certificates, software security level)
+	// rather than strict hardware attestation. Such keys are refused at login
+	// after this time, or immediately once relaxed attestation is turned off.
+	// Absent for hardware-attested keys that pass strict validation.
+	RelaxedAttestationExpiresAt *time.Time `json:"relaxed_attestation_expires_at,omitempty"`
+}
+
+// CredentialsDeviceAuthnConfig is the JSON shape stored in
+// `identity_credentials.config` for the `deviceauthn` credential type.
+type CredentialsDeviceAuthnConfig struct {
+	Credentials []Key `json:"credentials"`
+}