Module pgp 

OpenPGP (RFC 9580) for mail, with Sequoia and its pure-Rust cryptography.

• Your keys live in ~/.local/share/sioul/pgp/own/. A key made here keeps its revocation certificate beside it, <fingerprint>.rev, yours alone as the key is (revocation_path); revoking is not built. A key’s private part is in one of two places (Place): here, encrypted with a passphrase the system keyring keeps (sioul-sync asks it), so nothing is asked at each message; or on a security key, which signs and opens itself after its PIN (crate::securitykey), Sioul keeping only its public certificate. Keys come from an import (a file, GnuPG’s export), are made here, or are a security key’s.
• Others’ keys live in …/pgp/others/: imported, found in their messages (Autocrypt), or looked up on request.
• Signing and opening take Sequoia’s own Signer and Decryptor traits: a key here or a security key, the same way. A message a security key opened keeps its session key in memory (SessionKeys), so that it opens again without the key until Sioul closes.
• What this module does not do: talk to the network, or to the keyring. Passphrases and PINs come in as arguments.

Structs

Checked

A signature, checked.

Helper 🔒

KeySummary

A key as the window lists it.

Keys

The keys Sioul knows: yours (their secret parts here, or on a security key), others’, and your security keys.

Lent 🔒

A signer lent for one message: Sequoia’s stream takes its signer by value, and a security key’s signer borrows what it needs to reach the key.

Opened

What opening a message found.

Own

Your key for an address: its certificate, and where its private part is.

PgpView

What a protected message showed when opened, for the reader’s line.

Served 🔒

What travels beside each of others’ keys (others/<fingerprint>.toml): the addresses it was learned for (an Autocrypt header’s, a lookup’s) or, imported from a file you chose, every address bound to it. The only ones it serves (review of 19 October 2026, N2).

SessionKeys

The session keys of messages a security key opened, by message: such a message opens again, with its attachments and its answer, without the key, until Sioul closes. In memory only, never on disk.

Unlock

How your keys open what is encrypted to you.

Enums

Fingerprint

A key’s fingerprint, as the crates that do not use Sequoia themselves name it. A long identifier for certificates and keys.

Place

Where the private part of one of your keys is.

Constants

LARGEST_DECRYPTED 🔒

The most a decrypted message may hold: anyone can encrypt to your key, and a few kilobytes of compressed data can inflate to gigabytes.

OTHERS_FORMAT 🔒

The format of others/: 2 since its keys say what they serve; 1 (none said), what Sioul kept before, or what an older Sioul writes through the sharing.

Functions

armored_keys 🔒

The armored key blocks of text, in order: each from its “—–BEGIN PGP PUBLIC KEY BLOCK—–” (or PRIVATE) to the end of its “—–END PGP” line. What lies around or between them is left out, a message’s or a signature’s block among it.

autocrypt_header

The Autocrypt header for your outgoing mail: your key, smallest form (primary, encryption subkey, the user ID with your address).

autocrypt_key

Autocrypt (Level 1, §2.1): the key a message’s header carries for its sender.

bound 🔒

Whether a key holds address among its user IDs bound to it, as Sequoia’s policy sees them: a user ID with no binding signature of the key’s own, revoked, or bound under an algorithm the policy refuses, names nothing (review of 19 October 2026, F1: userids() alone counts every user ID, “even those without a binding signature”).

bound_addresses 🔒

The addresses bound to cert (bound), as written there, each once.

can_sign_with 🔒

Whether the key fingerprint of cert can sign now: valid, alive, not revoked, allowed to sign.

canonical 🔒

Lone LF become CRLF: what was signed is the canonical form (RFC 3156 §5).

certificates_in

The certificates of bytes (armored or binary), read, not kept.

certificates_of

The certificates among bytes (armored or binary, one or several), as a certificate from outside is read everywhere here (a file, GnuPG, a server, a message): read as they came, and again with their signatures’ numbers written shortest (minimal_mpis), merged by fingerprint, in the order they came; so the repair only ever adds, never takes a certificate or a part away. Sequoia’s words when neither reading reads.

decrypt

Decrypts an OpenPGP message (armored or not) with your keys, checking the signatures inside. unlock gives the passphrase of a key of yours here, the session keys kept, and your security key when you asked to use it.

email_is 🔒

embedded_shortened 🔒

A signature’s unhashed area (RFC 9580, 5.2.3.7) with each embedded signature (subpacket 32) shortened, its own unhashed area left as it came (shortened_at), its length said again; none when none needed it, or when the area does not read as subpackets.

encrypt

data encrypted to the recipients’ keys, signed by yours when given; armored.

encrypt_for_yourself 🔒

data encrypted for you alone, to yours: an encryption key of yours that expired but was not revoked still takes it, since you open it with that key, which Sequoia’s policy allows (review of 19 October 2026, F19).

encrypt_to 🔒

export_public

A key’s public part, armored, to give to others.

for_its_address 🔒

cert with only its user IDs for address, when one of them is bound to it (names); none otherwise. What a certificate brings from elsewhere (an Autocrypt header, a lookup) is kept for the address it came for alone: its other user IDs, bound or not, never make it another address’s key (review of 19 October 2026, F2).

generate

Makes a key for you: Curve25519, for signing and encrypting, valid three years; its secret parts encrypted with passphrase. Its revocation certificate, which Sequoia makes with it, is kept beside it (revocation_path): the only way to revoke the key once it is lost.

generate_at 🔒

generate into the folder root (pgp/).

header_end 🔒

Where a message’s header ends: after its first empty line.

here_signer

Your key here that signs, its secret part opened with passphrase: the signer of a key kept on this device.

import

Imports the keys of a file: armored or binary, public or secret. Someone’s key imported so serves every address bound to it: you chose the file.

import_at 🔒

import into the folder root (pgp/).

is_encrypted

Whether a message is encrypted with OpenPGP, as a whole: PGP/MIME (RFC 3156, the shape seal_message writes), or an inline message whose whole first text part is one armored message. Never a text that quotes one among its words (review of 19 October 2026, F7: a decrypted copy quoting an older armored block was taken for sealed). Nothing is opened.

judged 🔒

What a key kept without that file serves (before 19 October 2026, or written through the sharing by an older Sioul), judged as it is: the address of every user ID it carries, bound or not, revoked or not, since a Sioul before 1f9acc0 took a key on any of them (a header’s key had to name its sender in some user ID, bound by nothing if it liked). Its one address, only when every user ID names that same address and it is bound; else none (review of 19 October 2026, N2 and R1: Mallory’s key binding Jane’s address, his own carried by nothing, came from his header and named one bound address, hers). A key it serves none waits, kept, until it comes again for an address.

keep_card_certificate

Keeps the certificate of your security key with your keys: public parts only.

keep_others_for_their_addresses

Once on each device (state/pgp-others.toml): each key of others/ kept without what it serves (format 1) gets it, as it is judged now (judged): its one address when every user ID it carries names it and it is bound, else none; written as judged, not learned. Kept so, an older Sioul’s later write to it (every user ID of a header, merged) adds no address it serves. The key’s own file is never touched: one that serves none stays, to serve again once it comes for an address (its owner’s next message, a lookup). How many keys it wrote it for.

keep_others_for_their_addresses_at 🔒

keep_others_for_their_addresses in the folder root (pgp/), its mark at mark.

key_of

The key fingerprint of cert, its public part, primary or subkey.

kind_of 🔒

learn

Keeps keys found for address: public parts only, and only those naming it.

learn_at 🔒

learn into the folder root (pgp/).

learn_autocrypt

Keeps a key from an Autocrypt header: only public parts, only for its sender’s address, never one of yours (whoever sends your own key back cannot add anything to it).

learn_autocrypt_at 🔒

learn_autocrypt into the folder root (pgp/).

looks_opened

Whether raw has the head of a message open rebuilt (opened_split): what may be a copy decrypted by Sioul before 19 October 2026.

message_id 🔒

A message’s name among the session keys: SHA-256 of its encrypted bytes.

mime_split 🔒

Where the MIME-Version: 1.0 line open adds after a message’s outer headers starts, when nothing of MIME comes before it; with content, only when a content’s header follows it (what open rebuilt from an entity with headers of its own). Without, whatever follows: an entity with an empty head, or none, rebuilt so (review of 19 October 2026, N7).

minimal_mpis

bytes (armored or binary) with the numbers of each signature written in their shortest form, as RFC 9580 (3.2) asks and Sequoia insists (certificates_of reads with it). GnuPG 2.4.4, Ubuntu 24.04’s, writes about one key signature in 128 with a number one octet too long (a leading zero octet counted in its length); Sequoia then read that signature as none, and the subkey it binds, or the whole key, as missing. A signature’s numbers are not part of what it signs: written shorter they are the same numbers, and Sequoia still checks the signature. Only ever shorter: a length said too short is left as it came. Armor is read block by block, every key block kept, in order. The bytes as they came when none needed it, or when they do not read as packets of known length; armored bytes come back binary once changed, which every reader here takes.

names 🔒

Whether a key serves address: bound to it (bound) and not revoked as a whole (usable). Every choice of a key for an address goes through it (for_address, self_cert_for, own_for).

names_address

For the window’s words: whether cert holds address among the user IDs bound to it, revoked as a whole or not.

new_passphrase

A long random passphrase for a key made here: nobody types it, the keyring keeps it.

only_bound_subkeys 🔒

cert without the subkeys its own primary key does not bind under the policy (bound by nothing, or by another key): what a lookup brings of yours adds only what your key signed (review of 19 October 2026, Info: such subkeys were inert, but kept, and a security key’s travelled in its shared file).

only_for 🔒

cert cut to the user IDs of addresses.

open

Opens a protected message: PGP/MIME encrypted or signed (RFC 3156), or inline PGP. Gives back the message as it reads once decrypted (its own headers, then what was inside), when it was encrypted, and what was found; None when nothing is protected. A message encrypted to your security key opens only when unlock carries it, or from a session key kept; otherwise its view names the key it waits for.

opened_split 🔒

The head of a message as open rebuilds an encrypted one: its outer header lines (none of them Content- nor MIME-Version), the line MIME-Version: 1.0 it adds after them, then the opened entity’s own header lines, a Content- one among them. Where that line is, when the head has that shape: what a copy decrypted by Sioul before 19 October 2026 looks like (a message that came in clear may too).

opens

Whether passphrase opens the secret parts of your key fingerprint.

outer_headers 🔒

The message’s own header lines but its MIME ones, which the decrypted body brings.

own_dir 🔒

packet_at 🔒

The packet at at (RFC 9580, 4.2): its tag and where its body lies; none for one cut short, or of partial length.

pgp_dir 🔒

policy 🔒

put_packet 🔒

A packet in OpenPGP’s format: its tag, its length, its body.

put_subpacket_length 🔒

A subpacket’s length (RFC 9580, 5.2.3.7), in one, two or five octets.

read_certs 🔒

read_others 🔒

Others’ keys in dir, each cut to the addresses it serves (served_by); one that serves none is left out of every use, its signatures said as a key’s Sioul does not know (kept on the disk, it comes back once learned again for an address).

recipients_of

The keys a message is encrypted to, as its packets name them (key IDs or fingerprints, hexadecimal), in its order: whom it is for, nothing opened.

record_of 🔒

What the file beside someone’s key cert, kept in dir, says, when it reads.

remove

Removes a key; yours are kept aside in pgp/removed, never deleted, with their revocation certificate.

remove_in 🔒

remove in the folder root (pgp/).

revocation_path

Where the revocation certificate of your key made here is kept: beside the key, pgp/own/<fingerprint>.rev, readable by you alone (write_key), as GnuPG keeps its own in openpgp-revocs.d.

revocation_text 🔒

A revocation certificate as a file to keep: what it is, in a few lines, then the signature armored, a colon before its first line so that it cannot be imported by mistake (as GnuPG writes its own).

revoked_whole

Whether cert is valid but revoked as a whole, for the window’s words.

save_revocation

Copies the revocation certificate of your key fingerprint into folder, as <fingerprint>.rev (a number added when that name is taken), yours alone; none kept for that key, an error.

save_revocation_at 🔒

save_revocation from the folder root (pgp/).

seal_message

A message as it reads (opened, in clear), sealed again for to, as an encrypted message comes (PGP/MIME, RFC 3156): its own headers in clear but those of its content (From, To, Date, Subject, Message-ID: what a list of mail shows), its content and their headers encrypted inside. open gives the same message back. For the copy kept beside a draft that answers an encrypted message, never left in clear.

served_by 🔒

The addresses someone’s key cert, kept in dir, serves: those its file beside says, as they are bound to it; without that file, as it is judged (judged), at each reading.

served_path 🔒

shortened 🔒

The packets of binary with each version 4 signature’s numbers in their shortest form; none when none needed it, or when binary does not read as packets of known length (a partial length is data’s, never a key’s).

shortened_at 🔒

signature_shortened, the signatures embedded in the unhashed area looked into only when descend: one level, never more. An embedded signature’s own embedded ones stay as they came: Sequoia refuses a signature embedded in an embedded one, and each level looked into would take the stack of the thread reading a file from outside (a phone’s import runs on Qt’s own, about 1 MiB), a crafted one nesting thousands.

sign_detached

A detached signature of data, armored, and the hash it used (“pgp-sha512”), for multipart/signed (RFC 3156 §5). signer is your key here (here_signer) or on a security key (securitykey::CardSigner).

signature_shortened 🔒

A version 4 signature’s body with its numbers in their shortest form (no leading zero bits, RFC 9580, 3.2), and those of a signature embedded in its unhashed area (a signing subkey’s back-signature, where GnuPG writes it); never anything in its hashed area, which the signature covers. None when nothing needed it, when its algorithm’s are not numbers (Ed25519’s own octets) or do not read whole, or when a length is said too short: only ever shorter, as GnuPG’s fault is.

stand_in_key

A key for tests, made now (Curve25519: its primary key certifies and signs, a subkey decrypts), named userid, its secret part unencrypted, armored: for the crates that do not use Sequoia themselves. Never one of yours.

store_at 🔒

Keeps a key you chose (imported, made here) in the folder root (pgp/), merged with what was known of it. Secret parts go with yours, and so does a certificate of yours.

store_from_elsewhere_at 🔒

Keeps a key that came from elsewhere for address (a lookup: its domain’s Web Key Directory, keys.openpgp.org): its user IDs for that address alone. One of yours brought again so is merged without anything it names: only what your own primary key binds (a renewal’s signatures, a subkey), never another source’s user IDs into your certificate (review of 19 October 2026, F1).

store_in 🔒

store_others 🔒

Keeps someone’s key for learned: the address it came for (a key from elsewhere comes cut to it, for_its_address) or, imported from a file you chose, every address bound to it. Merged with the one kept, it serves what it served and these (its file beside, written first), cut to their user IDs: an address a key kept before, or an older Sioul’s write, named besides is never kept nor served (review of 19 October 2026, N2), and the user IDs of an address it was learned for before stay.

summaries

Every key, yours first; a security key’s certificate names its key.

summary 🔒

usable 🔒

Whether a certificate may serve at all: valid under Sequoia’s policy and not revoked as a whole. Sequoia’s revoked(false) on a key asks that key’s own revocation, never the certificate’s: a certificate revoked as compromised still has live, unrevoked subkeys (review of 19 October 2026, N3). A revoked certificate never takes a message or a seal and never signs; it still opens what was sent to it before.

verify_detached

Checks a detached signature of data (multipart/signed).

wkd_urls

Where a domain’s Web Key Directory keeps the key of address: the advanced address, then the direct one (draft-koch-openpgp-webkey-service §3.1).

write_key 🔒

Writes a key file beside, then moves it in place. On Unix it is readable by you alone, whatever the umask: your secret keys, and whose keys you keep.

write_served 🔒

Writes what someone’s key serves beside it.

yours_at 🔒

Whether the certificate fingerprint (hexadecimal) is one of yours in the folder root (pgp/): kept with your keys, a security key’s read here, or one your other devices made known (cards/), as a phone knows your security key’s certificate: never kept among others’ keys, from wherever it comes again (your own mail’s Autocrypt header, a lookup).

zbase32 🔒

z-base-32 (RFC 6189 §5.1.6), as WKD names keys.

Type Aliases

Signing

A signer of yours, as Sequoia takes it: a key here (here_signer) or on a security key (securitykey::CardSigner).