OpenPGP

This page shows how to turn on OpenPGP: reading signed and encrypted mail, and signing and encrypting what you send. Tilde uses the gpg program and the keyring of your system. The secret keys and the passphrases stay in gpg-agent, and Tilde never holds a key. The complete list of keys is in config.toml: cache, pgp.

Turn it on

You need GnuPG installed and a key for your address. Add this to config.toml:

[pgp]
enabled = true

OpenPGP is off by default, because the plugin runs a program. Without a gpg path, Tilde looks for the program in this order: the install folder of Gpg4win (Windows), the PATH, then /opt/homebrew/bin and /usr/local/bin. If it finds none, it logs one error and starts without OpenPGP.

The settings

[pgp]
enabled = true
gpg = "/usr/bin/gpg"
home = "/home/ada/.gnupg"
keyserver = "hkps://keys.openpgp.org"
auto_locate = true
encrypt_to_self = true
default_sign = false
default_encrypt = false

Key	Meaning	Default
gpg	The path of gpg, when it is not in a standard place.	looked for
home	The GnuPG home folder (--homedir). Write an absolute path.	the one of the system
keyserver	The keyserver to ask.	the one in dirmngr.conf of GnuPG
auto_locate	Look for the key of an address on the keyserver when its domain has no Web Key Directory.	true
encrypt_to_self	Encrypt to your own key too, so you can read your sent copy.	true
default_sign	Sign a message that does not say what to do.	false
default_encrypt	Encrypt a message that does not say what to do.	false

A key on a keyserver is vouched for by nobody. With auto_locate = false, only the domain of an address can give a key. With default_encrypt = true, a message to someone without a key is not sent.

Choose the key of an account

The key that signs, and that your own copy is encrypted to, is the key of the address you write from. To name another, set gpg_key on the account:

[[accounts.mail]]
id = "work"
name = "Work"
address = "ada@example.org"
gpg_key = "0xFE67774DF63A2BB6"

gpg_key is a fingerprint (spaces allowed, as gpg --fingerprint prints it), a long key id of 16 digits, with or without 0x, or an address. A short key id of 8 digits is refused when the file is read.

To name the key by sender address in one place, use [pgp.keys]:

[pgp.keys]
"ada@example.org" = "0123456789ABCDEF0123456789ABCDEF01234567"

The order is: the key the message names, then gpg_key of the account, then the [pgp.keys] entry of the From address, then the key of the From address.

Send protected mail

tcli send email --to ann@example.org --subject "Plan" --sign --encrypt < plan.txt

• Signing makes a multipart/signed message. Encrypting makes a multipart/encrypted message for the To and Cc recipients and, with encrypt_to_self, for you.
• Each Bcc recipient gets a separate copy, encrypted to them alone.
• Nothing goes out in the clear. A recipient without a usable key stops the send and the error names the address.
• The subject and the other headers stay in the clear.

Read and manage keys

When you open an encrypted or signed message with tcli read or in the reader of tt, it is decrypted and the result of the signature check is shown. The commands of the plugin are pgp.keys, pgp.import, pgp.export, pgp.delete, pgp.fetch, pgp.search and pgp.refresh. They exist only while [pgp] is on. Type one at the command line of tt, for example:

:pgp.keys

Trust, the creation of keys and the passphrase prompt stay with gpg. Make the keys with gpg itself.

Proton Bridge

Proton Bridge builds a message again from what it gets. A signed or encrypted message that Tilde hands to it arrives as a multipart/mixed with an empty body and the OpenPGP parts as attachments, so a mail client does not show it as a message. To send protected mail from such an account, use an SMTP server that sends the message as it is.