Module securitykey 

Your security key where it meets the world: its certificate looked up when you ask, and GnuPG asked to let the key go when you press “Let GnuPG release it”. What is checked and kept is the core’s (sioul_core::securitykey).

• The certificate. A security key holds no certificate, only its keys’ fingerprints and public parts. Sioul looks for it only when you ask (at setup, and “Look for a newer version”), since each lookup tells a server that someone wants your key: the address written on the key (HTTPS only), then the Web Key Directory of your addresses’ domains, then keys.openpgp.org by fingerprint. Each certificate found is checked against the key, and one that is not the key’s is never kept.
• GnuPG’s hold. GnuPG’s smart card daemon keeps the key for itself after any use (scdaemon connects exclusively unless pcsc-shared is set in scdaemon.conf). “Let GnuPG release it” runs gpgconf --kill scdaemon, on that click only: gpg starts it again when it needs the key, and asks its PIN again then. Sioul never changes GnuPG’s settings.
• GnuPG’s own steps, on a press (Gnupg): “Import from GnuPG” runs gpg --export --armor for the key’s fingerprint; “Renew for two years” runs gpg --quick-set-expire for the key, then its subkeys, GnuPG’s own pinentry asking the card’s PIN. The person’s GnuPG, its home as GnuPG finds it; never a setting changed, never a key made or deleted.
• keys.openpgp.org (send_to_keys_openpgp): the public certificate sent on “Send it to keys.openpgp.org”, over HTTPS, then a confirmation asked for each address it names that is not published yet: the server mails each a link, and publishes the address once the link is opened.
• The key itself, on a computer: the system’s smart card service, PC/SC (smartcard). On a phone, not yet.
• Logs: cap_logging, as each program starts.

Modules

smartcard

Security keys through the system’s smart card service, PC/SC: pcscd (pcsc-lite) on Linux, the Smart Card service on Windows, CryptoTokenKit on macOS. The OpenPGP card protocol is openpgp-card 0.7’s, its transport card-backend-pcsc 0.5’s (both Heiko Schaefer’s, MIT OR Apache-2.0).

Structs

Gnupg

GnuPG, as Sioul runs it on your press: the gpg program, and the home it reads (none: GnuPG’s own, GNUPGHOME or ~/.gnupg; a throwaway one in tests).

OnCard

Held while Sioul’s own GnuPG works with the security key.

Published

What keys.openpgp.org said of a certificate sent to it.

Enums

GnupgProblem

Why GnuPG did not do what was asked.

GnupgStep

Where a GnuPG step on the security key is, for what the window says.

Looked

What looking for a security key’s certificate found.

Released

What “Let GnuPG release it” did.

Status

A line of GnuPG’s status (--status-fd), as far as Sioul needs it.

Constants

GNUPG_WAITS 🔒

How long GnuPG may take when it asks for a PIN and a touch: then it is said as not answering, and its process is ended.

GPG_ERR_TIMEOUT 🔒

libgpg-error’s GPG_ERR_TIMEOUT: a security key that waited for a touch in vain.

KEYS_OPENPGP

keys.openpgp.org, where “Send it to keys.openpgp.org” sends.

Statics

GNUPG_ON_CARD 🔒

While Sioul’s own GnuPG works with the security key, Sioul’s own looks at the keys wait (Gnupg::renew): a key opened by Sioul between two of GnuPG’s commands, and reset when closed, would undo the PIN GnuPG gave it.

Functions

cap_logging

Caps what any crate may log at “info”, whatever level it asks, as a program starts (sioul-app, sioul). openpgp-card writes whole APDUs at “trace”, a VERIFY’s PIN included, and a card’s answers, session keys among them. Sioul installs no logger, so nothing is written anywhere; this keeps “debug” and “trace” away even if one came, and never raises the level (it starts at “off”).

export_command

The command that writes the key’s certificate into a file by hand.

find_at 🔒

find_certificate

Looks for the certificate of the security key card, only when you ask: over HTTPS, in the order of places, keeping the first that is the key’s.

gpgconf_places 🔒

Where gpgconf may be: on the PATH, then where GnuPG’s installers put it, since a window started from the desktop may not have them on its PATH.

may_look

Whether Sioul may look at the security keys now: not while its own GnuPG works with one.

places

The places to look, in order: the address written on the key (HTTPS only), the Web Key Directory of each of addresses, then keys.openpgp.org by the fingerprint of the key’s signing key (else of its decryption key).

readers

Where security keys are found: the system’s smart card service on a computer; on a phone, nowhere yet (NFC and USB come later).

release_at 🔒

gpgconf --kill scdaemon, for the GnuPG home home when given (--homedir).

release_gnupg

Asks GnuPG to let the security key go: gpgconf --kill scdaemon. Run only when you press “Let GnuPG release it”, never by itself.

release_with 🔒

renew_commands

The commands that renew the key fingerprint for two years by hand: the key, then its subkeys, each named (GnuPG’s “*” leaves the expired ones).

running 🔒

Whether the process pid still runs (its pinentry): on Linux, as /proc says; elsewhere not known, taken as running until GnuPG answers.

send_at 🔒

send_to_keys_openpgp

Sends the public certificate armored to keys.openpgp.org, only when you press its button: over HTTPS, then a link asked for each address it names that is not published yet, the mail in your language (locale, “fr”). Anyone can then find the key there by its fingerprint; by an address, only once that address’s link is opened.

status_of

A status line read, if it is one Sioul needs.