Module securitykey

Expand description

Your OpenPGP keys on a security key: an OpenPGP card, such as a YubiKey or a Nitrokey (OpenPGP card specification 3.4).

The private keys never leave the security key. Sioul hands it what must be signed (a digest) or opened (a session key, wrapped), after its PIN, and gets the result back; the key may also wait for a touch. Everything public Sioul keeps itself, the certificate above all: a security key holds no certificate, only its keys’ fingerprints and public parts.

Readers is how Sioul reaches security keys: the system’s smart card service (PC/SC) on a computer, a software stand-in (SoftReaders) in tests. A key is opened for one operation, then closed, which resets it: no other program finds it unlocked afterwards.
CardSigner and CardDecryptor are Sequoia’s own Signer and Decryptor for a key on a security key. Each opens the security key when Sequoia asks for a signature or a session key, not before. The glue follows Heiko Schaefer’s openpgp-card-sequoia, as Sequoia’s key store carries it (sequoia-keystore-openpgp-card 0.2.2, its decrypt_ciphertext and sign, MIT OR Apache-2.0).
check tells whether a certificate belongs to a security key: its fingerprints, its public keys, what each key may do, until when.
KnownCard is what Sioul remembers of a security key, in pgp/cards.toml: no secret.
PinMemory holds a PIN in memory only, kept encrypted there by Sequoia, for fifteen minutes without use.
CardError says each failure in words, with what to do.

Sioul only uses a security key: it never asks for its Admin PIN, never changes or unblocks a PIN, never loads or makes keys on it.

Structs§

CardAccess: What it takes to use a security key now: where to find it, its PIN, and what to say when it waits for a touch.
CardDecryptor: Opens session keys with the key of a security key, as Sequoia’s Decryptor: the key is opened when Sequoia asks.
CardInfo: What a security key says without its PIN.
CardSigner: Signs with the key of a security key, as Sequoia’s Signer: the key is opened when Sequoia asks for the signature, and each signature is checked with the certificate’s key before it is given back.
CardsFile 🔒
CertCheck: A certificate checked against a security key: it belongs to it.
Certificate: A certificate, as the crates that do not use Sequoia themselves name it. A collection of components and their associated signatures.
Held 🔒
KnownCard: A security key Sioul knows, in pgp/cards.toml: which keys it holds, the certificate they belong to and where it came from. No secret.
NoReaders: A build without a way to security keys: each use says so.
Part: One key of a certificate: what it is for, its fingerprint, until when (Unix seconds; none when it does not expire).
Password: A PIN, or a passphrase: kept encrypted in memory by Sequoia, wiped when dropped. Holds a password.
PinMemory: The PIN of one security key, held in memory only, encrypted there by Sequoia (Password), for PIN_QUIET after its last use. Never on disk, in the keyring or in a log. Forgotten when Sioul closes, when the key goes away (on a computer), or on “Forget the PIN now”.
Protected: Bytes kept in protected memory, wiped when dropped: what a card opened. Protected memory.
SlotInfo: One key of the security key, as it describes it.
SoftCard: A security key made of software keys, behind the same traits as a real one, for tests: Sioul itself never makes one. It counts its PIN tries, forgets a verified PIN when closed, asks the PIN again after each signature when told to, and can fail as a real key does (SoftCard::fault).
SoftReaders: Readers holding SoftCards, for tests: none, some, held by another program, or no smart card service at all.
Visited: What a visit met.

Enums§

CardError: Why a security key could not be used, each with its sentence.
CardPublic: A key’s public part as the card gives it.
HashAlgorithm: A hash, as a card’s RSA signature names it. The OpenPGP hash algorithms as defined in Section 9.5 of RFC 9580.
Mismatch: Why a certificate is not the one of a security key.
PinMode: Which check of the PIN an operation needs. A card keeps two from the one PIN: for signing (PW1 in mode 81), and for the rest (mode 82).
Purpose: What Sioul was doing with the key, for the words of a failure.
Remedy: What the window offers after a failure.
Role: What a key of a certificate is for, as said to you.
ToDecipher: What the card opens (specification §7.2.11): RSA’s ciphertext, giving the session key; or, for ECDH, the sender’s ephemeral point, giving the shared secret, from which Sioul unwraps the session key.
ToSign: What the card is given to sign: a digest as it is (EdDSA, ECDSA), or, for RSA, a digest and its hash, which openpgp-card builds into a DigestInfo (signature_for_hash, specification §7.2.10.2) before the card pads and signs it.
Touch: Whether a key on the security key waits for a touch before it works: its “user interaction flag”, the touch policy of a YubiKey.
Visit: Whether Readers::visit goes on to the next key.

Constants§

PIN_QUIET: How long a PIN stays in memory after its last use (the owner’s choice: 15 minutes).

Traits§

Card: A security key, open for one operation: what it says, its PIN, and its two private operations. The opening and the closing are the Readers’.
Readers: Where Sioul finds security keys: the system’s smart card service on a computer, a phone’s NFC or USB, a software stand-in in tests.

Functions§

adopt: Makes the security key card yours: its certificate kept with your keys (public parts only), and the key in cards.toml, signing for addresses; source says where the certificate came from. Gives what is kept.
algorithm_name: “Ed25519”, “Curve25519”, “RSA 4096”, “NIST P-256”: a key’s algorithm, as GnuPG and YubiKey Manager name it.
card_public 🔒: The card’s form of a public key (its point without OpenPGP’s 0x40).
cards: What every security key present says.
cards_path: Where the known security keys are listed.
certificate_in: The certificate of the security key card among bytes (armored or binary, one certificate or several), with what it is; else why none is.
change_known: Changes the list of known security keys: read, changed, written, one writer at a time.
change_known_at 🔒
check: Whether cert is the certificate of the security key card: each key on the card is in it, alive or expired but not revoked, allowed to do what its slot does, and its public part is the card’s own.
expired_parts: Each part that expired by now, said exactly: which, since when, and what it stops (“Its encryption subkey (B81A…BF8C) expired on 8 April 2025: nobody can encrypt to you with it.”).
expiry_line: What the certificate’s expiry says now: expired (and how to renew), soon (within a month), or valid until a date; nothing when it does not expire.
expiry_of: When a certificate stops serving a security key: the earliest expiry of its primary key and of its keys named by fingerprints (Unix seconds); None when none of them expires, or the certificate is not valid at all.
expiry_words: What a certificate says of its expiry, part by part: each part expired, exactly (“Its encryption subkey (B81A…BF8C) expired on 8 April 2025: nobody can encrypt to you with it.”), and, when its subkeys alone expired, that Renew renews them; else until when it is valid, or that it expires soon (expires, the earliest of the keys that matter). What it says, whether warmly, and whether a part expired.
forget: Stops using the security key ident: it leaves cards.toml, and its certificate leaves your keys for pgp/removed (never deleted).
full_date: “3 March 2026”, “3 mars 2026”.
hint_for_os_release 🔒: The hint for a Linux system, by its /etc/os-release (ID, then ID_LIKE).
known_cards: The security keys Sioul knows.
label: The name of a security key by its maker, then its serial number as printed on it: “YubiKey 12 345 678”, “Nitrokey 000F 1A2B”.
no_service_hint 🔒: How to start the smart card service, for the system Sioul runs on.
parts: The keys of cert that are not revoked, the primary key first, each with what it is for and until when: what is said of each, never “the key” for all of them when one part alone expired.
parts_in: The parts of the first certificate among bytes (gpg --export): none when there is none.
parts_until: Every part and until when, in a line: “primary key until 7 October 2028, encryption subkey until 7 October 2028”; “without end” for one that does not expire.
read_known 🔒
same_public 🔒: Whether a certificate’s key is the card’s: the same public part.
say 🔒
serial_text: A serial number as printed on the key. Yubico writes its serials in decimal digits inside the card’s hexadecimal ones (“12345678” reads 0x12345678), so they are shown in groups of three, as a number; others stay hexadecimal.
short_fingerprint: “B81A…BF8C”: a fingerprint as it is told apart at a glance.
subkeys_of: The subkeys of a certificate that are not revoked, by fingerprint: what “Renew for two years” names one by one.
with_card: Opens the key ident for work, given what it says; Absent when it is not there, Busy when another program holds a key Sioul could not open.

Type Aliases§

PublicKey: A public key as Sequoia holds it, whatever its role in its certificate.