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.
Marks 🔒: This device’s own marks and list of security keys stopped here.
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.
SharedCard: One of your security keys as it travels: what a computer that read it knows of it, and its certificate (armored, public parts only).
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).
SHARED_CARDS: The folder of shared_cards_dir in pgp/.

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. Read as GnuPG writes it (pgp::certificates_of).
change_known: Changes the list of known security keys: read, changed, written, one writer at a time; then what your other devices know of them follows (share_cards).
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 on this device, for good: it is listed as stopped here (pgp/stopped.toml, never shared), so that another device’s file for it is never taken back here (review of 19 October 2026, F4). Read here: it also leaves cards.toml, its certificate leaves your keys for pgp/removed (never deleted), and its shared file goes; your other computers that read it keep using it until they stop it, and share it again when what they know of it changes. Known here only from another device: stopped here alone (Ok(false)).
forget_in 🔒: forget in the folder root (pgp/).
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, read on this device (cards.toml).
known_cards_in: known_cards from the file path.
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”.
mark_shared 🔒
marks_path: Where this device marks the security keys it shared once: in its state, never shared.
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. Read as GnuPG writes it (pgp::certificates_of).
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 🔒
read_marks 🔒
revoked_encryption: The fingerprint of a revoked encryption subkey of cert, when no other can take encryption: what the window says instead of an expiry.
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.
set_stopped_in 🔒: ident added to (or, read again here, taken from) the list of security keys stopped on this device.
share_cards: What your other devices learn of your security keys, written from this device’s own (cards.toml, and their certificates kept with your keys): only the keys this device read itself, never one it learnt from another device. Each certificate merged with the one shared already, so that a renewal made on another computer is never undone. A file is written only when what it says changed. Keys this device does not know are left as they are (another computer’s).
share_cards_at_exchange: Before each exchange: each security key read here and not shared yet from this device is shared once (an existing setup’s first sharing), and marked so on this device (state/security-keys.toml, never shared); once marked, a file another device took out (it stopped using the key) is never made again here by this pass (review of 19 October 2026, F4), and a file there is written again only when this device’s certificate adds to it (a renewal the other computer’s older write missed: F5).
share_cards_in: share_cards with its three places: cards.toml, your keys’ folder (pgp/own/), the shared folder; missing: only the files not there.
share_cards_marked_in: share_cards_at_exchange with its places: cards.toml, your keys’ folder, the shared folder, the marks’ file.
share_one 🔒: One security key’s shared file written from this device: what cards.toml says of it, and its certificate merged with the one shared already, so that a renewal made on another computer is never undone. Written only when it changed; with adds, only when this device’s certificate adds to the shared one (the record itself left as written).
shared_cards: Your security keys as your other devices made them known here (data/pgp/cards/), each with its certificate when that is the key’s (vouched); a file that does not read, or whose certificate is not the key’s, is passed over.
shared_cards_dir: Where your security keys travel to your other devices, sealed with the sharing (data/pgp/cards/): one file per key, what cards.toml says of it and its certificate, public parts only. Never pgp/own/, which holds the secret parts of keys kept on a device; a security key’s private keys never leave it.
shared_cards_in: shared_cards from the folder dir.
shared_name 🔒: A shared key’s file name: its identifier, - for : (“0006-12345678.toml”).
short_fingerprint: “B81A…BF8C”: a fingerprint as it is told apart at a glance.
stopped_in: The security keys this device stopped using (pgp/stopped.toml, never shared): another device’s file for one of them is never taken back here.
subkeys_of: The subkeys of a certificate that are not revoked, by fingerprint: what “Renew for two years” names one by one.
unshare_card 🔒: The shared file of the security key ident taken away: this device stopped using it (forget).
vouched: The certificate of a shared security key, when it is the key’s: its primary key’s fingerprint is the one the key’s record names, and it holds the keys the security key holds (signing, decryption). Anything else (a certificate replaced, another key’s, one missing a key the security key holds) is never taken for yours.
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.