Module securitykey

Expand description

Your security key behind the window (docs/client.md, “Your keys on a security key”): the band of the writing window and of the Reader (plug the key in, its PIN, a touch, what went wrong, in words), signing at Send before the ten seconds of “Undo”, opening a message on “Open with your security key”, the PIN held in memory for fifteen quiet minutes, the key’s setup in Accounts ▸ Encryption, and “Let GnuPG release it”; GnuPG’s own steps as buttons there (“Import from GnuPG”, “Renew for two years”) and “Send it to keys.openpgp.org”, each run on its press only, its command kept under “By hand” to copy.

Nothing here touches the key unless you asked: a message shown is never opened with it, and no lookup runs by itself. A demo profile never reaches the system’s smart card service: it has a key of its own, made of software, whose PIN is 123456.

Structs§

Band 🔒: What the band of a writing window, of the Reader or of the setup shows, as JSON.
Demo 🔒: The demo’s security key: software behind the same traits, its PIN 123456, a touch asked to sign; its certificate names the profile’s first address.
Kept 🔒: What keeping a certificate says, and what it offers.
KnownView 🔒: One known security key, as Accounts ▸ Encryption lists it.
Way 🔒: How the key is reached here, for the words: on a computer, plugged in; on a phone, in one visit (PIN first), held against it or plugged into its USB-C port, NFC perhaps missing or off.

Constants§

LOOK_EVERY 🔒: How often Sioul looks whether a key it waits for came, or whether the key whose PIN it holds went.
PIN_WAITS_AT_MOST 🔒: How long a PIN typed waits for its key: then forgotten, asked again (review of 23 October 2026, F2).
SETUP_BAND 🔒: The band of the setup, in Accounts ▸ Encryption.
WAIT_AT_MOST 🔒: How long a band waits for its key before it stops looking.

Statics§

LAST_TRY 🔒: The bands told that their key has one PIN try left: the PIN typed next there is sent (review of 23 October 2026, F1).
PIN 🔒: The PIN, held in memory for fifteen quiet minutes after its last use.
SETUP 🔒: What the setup read from the key, for “Look for it” and “Import a file…”.
WAITING 🔒: The bands waiting for the key to be plugged in, by their context, until “Not now”.
WATCHING 🔒: Whether the watch over the held PIN runs.
WINDOW 🔒: The window, told when the PIN is held or forgotten: Accounts offers “Forget the PIN now” then.

Functions§

adopt 🔒: The certificate found is the key’s: kept, the key made yours for the addresses it names among yours, and said.
as_info 🔒: What Sioul kept of a key, as the key would say it (fingerprints, no public parts).
ask_pin 🔒: The band asks for the PIN, with the tries left when fewer than the most seen.
card_for_lookup 🔒: The key to look up a certificate for: the one the setup read, else a key known already (“Look for a newer version”), from what Sioul kept of it.
closing 🔒: Sioul closes: the PIN and the session keys go with it.
confirm_last_try 🔒: What a failure does to the band, and to a PIN held that the key refused. A key not plugged in is waited for instead (wait_for). A key with one PIN try left takes the PIN only once the band said so and it was typed again; a PIN held, which the key took before, goes.
demo 🔒
describe 🔒: “YubiKey 12 345 678, Noa Ferrand. It signs (Ed25519, made on 3 March 2026) and decrypts (Curve25519).”
expired_line 🔒: What the writing window says when the security key that signs for address has an expired certificate: the date, and how to renew it.
failed 🔒
fingerprint_of 🔒: The fingerprint gpg --export takes for the key: its signing key’s, else its decryption key’s.
for_draft 🔒: The security key asked at Send, as JSON {ident, label, signs}: the one that signs the draft (signs: true), else the one that opens the encrypted message it answers, for its quote (signs: false); or {expired: …} when the signing key’s certificate expired; or {cannot: …}, nothing sent, when Send would only be refused later (review of 19 October 2026, F15): the key cannot sign here (a phone; on a computer, a key read on another computer, F18), or an encrypted message forwarded unencrypted, or where nothing opens it. “” when no security key is asked (on a phone, a reply then goes without its quote, as its window says).
forget_pin 🔒: “Forget the PIN now”.
forward_refused 🔒: Why Send refuses a forward at once (review of 19 October 2026, F15: it was refused only at the end of the ten seconds): its copy is encrypted and the forward is not, or nothing here opens it (encrypted to a key this device cannot use, or to none of yours: the words the window shows under the text, F16). None: it may go.
gnupg 🔒: GnuPG here, or why not; in a demo, none: the demo’s key stands in.
gnupg_sentence 🔒: What GnuPG did not do, in words, and what to do then.
held_for_setup 🔒: A phone, at the setup: waits for a key held to it, the band saying so, until one comes, “Not now”, or a few minutes pass; whether one came.
holder_name 🔒: The cardholder’s name as written on the key (“Ferrand<<Noa”, ISO/IEC 7501-1), in the usual order (“Noa Ferrand”).
host_of 🔒: keys.openpgp.org from https://keys.openpgp.org/vks/v1/….
import_certificate 🔒: “Import a file…”: the key’s certificate from gpg --export, checked, kept.
import_from_gnupg 🔒: “Import from GnuPG”: the key’s certificate as your GnuPG keeps it (gpg --export --armor), checked against the key, kept. A demo profile takes its own key’s certificate, as if GnuPG had it.
keep 🔒: The certificate kept for the key, the key made yours for the addresses it names among yours: what to say, and whether warmly.
keep_taken 🔒: A PIN the key took before something else failed (a touch missed, the key pulled out): held, so that “Try again” does not ask it again.
keeps_pin 🔒: Whether a PIN that worked is held for its quiet time: on a computer; on a phone never, typed for each use.
key_in 🔒: The key ident as it says itself (“”: the first one), read without its PIN.
keys_changed 🔒: Tells the window the keys’ state changed: the PIN held, or forgotten.
know_window 🔒: Remembers the window, to tell it when the PIN is held or forgotten.
known_view 🔒: Your security keys, as JSON {cards: […]}, for Accounts ▸ Encryption.
lift 🔒: A phone: once the key has done its work, the status line says it may be taken away, or unplugged.
look_for_certificate 🔒: “Look for it”, “Look for a newer version”: the key’s certificate looked up, only now that you asked, checked against the key, and kept.
may_stop 🔒: Whether “Stop using this security key” is offered, and done: for a key read here; for one another device read, only on a device that can read a security key, where reading it again takes it back. Not on a phone: it cannot read one yet, so a stop there could never be undone there, and would only stop it encrypting your own copies (N5).
not_a_pin 🔒: The band asks for the PIN again, saying the key typed a code.
not_now 🔒: “Not now”: the band stops waiting for the key.
now_unix 🔒
open_message 🔒: Opens a message encrypted to your security key (“Open with your security key”); its session key then stays in memory until Sioul closes, so that it opens again, with its attachments and its answer, without the key.
open_nfc_settings 🔒: “Open NFC settings”: Android’s own switch, on a phone.
open_now 🔒
open_quote_now 🔒: Opens the encrypted message a draft answers with the security key ident, another than the one that signs: its session key is kept in memory, and the draft goes on to its signature, whose key asks its own PIN.
pin_for 🔒: The PIN to use: the one typed, else the one held (not for a key that asks it for each signature, decision 5); with what the key says, read without its PIN. None as the PIN: the band asks for it.
pin_from 🔒: pin_for with its readers, and what Sioul knows of the key (known).
pin_waited_too_long 🔒: Whether a PIN typed has waited for its key as long as it may.
problem_line 🔒
quote_card 🔒: The security key that must open the message a draft answers or forwards, at Send: its copy is encrypted, the answer is encrypted (else it is not quoted), and neither a session key kept since you opened it nor a key here opens it now. Opened in memory only, to know.
read_for_setup 🔒: “Use a security key”: reads the key plugged in, without its PIN.
read_here_in 🔒
read_here_words 🔒: The words that say how to read your security key on this device: on a phone, held against it (<id>-phone); on a computer, plugged in.
readers 🔒: Where security keys are: the system’s smart card service; in a demo, the demo’s own key, never a real one.
release 🔒: “Let GnuPG release it”, pressed: GnuPG’s smart card daemon stopped. Returns JSON {line, done}: done, the band tries again at once.
remember 🔒: The PIN worked: held for its quiet time, watched; what the key said, kept.
renew 🔒: “Renew for two years”: GnuPG renews the key, then its subkeys (gpg --quick-set-expire, its own pinentry asking the security key’s PIN, and a touch); the certificate it then holds is checked and kept here.
renew_line 🔒: What the setup says while GnuPG renews the key: its pinentry open, the PIN typed there (then a touch, when the key may ask for one); the key’s turn, to touch it now and hold the finger a second or two, as long as GnuPG works (Touch::words); else that GnuPG renews it.
renewable 🔒: Whether GnuPG is here to renew a key: never on a phone, in a Flatpak, or a demo. Whether it holds the key is asked only on “Renew for two years”: GnuPG is never run behind your back, nor the security key woken for it.
same_key 🔒: Whether the security keys a and b open the same messages: the same key, or a copy of it (the same decryption key on both).
send_to_keys_openpgp 🔒: “Send it to keys.openpgp.org”, pressed after the sentence that says what goes public: the certificate Sioul keeps for the key, its public part only, sent; keys.openpgp.org then mails each address it names a link. A demo profile sends nothing, and says what would come.
sentence 🔒: A failure in words, a phone’s own where they differ: a key moved away, or unplugged, before it finished; a touch the key would not take over NFC; a key locked (unlocked on a computer).
sentence_in 🔒
setup_action 🔒: The setup’s button for a key that could not be read: “Let GnuPG release it”, “Open NFC settings”, else “Try again”.
setup_problem 🔒: What the setup’s band says when the key could not be read: a key another program holds offers “Let GnuPG release it”, never a dead end; one not plugged in, “Try again”.
setup_problem_in 🔒
shared_certificate 🔒: The certificate your other devices made known with the key info (read on another computer of yours, shared), when it is the key’s: what the setup keeps at once, with where it came from, rather than looking it up.
shared_in 🔒
sign_and_send 🔒: Signs a draft with your security key at Send, then schedules it with its ten seconds of “Undo”; typed is the PIN typed in the band, else “”.
sign_now 🔒
stop_using 🔒: “Stop using this security key”: it leaves Sioul’s list, its certificate is kept aside; the PIN held, if it was its, is forgotten.
take_pin 🔒: The PIN as typed, taken into Sequoia’s protected memory, and the plain copy wiped (review of 23 October 2026, F3); empty, none. The copies QML and Qt made before (the field’s text, the QString) are theirs: QML’s string is emptied at once, the QString freed by Qt, neither can be overwritten.
taps 🔒: Whether the key is used in one tap: a phone, over NFC (its PIN asked first, never held; the key held while it works; docs/android.md).
tell_band 🔒
touch_line 🔒: What the band says when the key’s slot may wait for a touch, its setting read from the key this session (Touch::words): “If your key asks for a touch…” when it could not be read. Held to a phone, the tap is the touch: keep holding it.
typed_by_the_key 🔒: What came from the PIN’s field looks like a one-time password the key typed when touched (Yubico OTP: 32 to 64 letters of its modhex alphabet, 44 most often, then Enter), not a PIN: never given to the key, which would count it as a wrong PIN.
wait_for 🔒: The key is not plugged in: the band says so, and Sioul looks, without opening any key, until it comes, “Not now”, or a few minutes pass.
waiting_action 🔒: The waiting band’s button: “Open NFC settings” while NFC is off.
waiting_in 🔒
waiting_line 🔒: What the band says while it waits for the key: plug it in; on a phone, hold it or plug it in (plug it in only, without NFC or with NFC off).
watch_pin 🔒: While a PIN is held: forgotten when its quiet time ends, or when its key is pulled out (its reader gone).
way 🔒
working 🔒
working_words 🔒: Held to a phone, the key is used while it stays there: “keep holding it”. Plugged in, the computer’s words.
your_addresses 🔒: Your mail addresses.

Type Aliases§

Resume 🔒: What goes on once the key is plugged in: sign_now for a draft (its signature, or the message it answers opened), open_now for a message.