Swanmail

GPG Encryption ​

Swanmail signs, encrypts, decrypts and verifies OpenPGP mail, in the PGP/MIME layout (RFC 3156) that other mail clients expect or in the older inline layout. All key material is stored on your device: the private key is encrypted at rest with Swanmail's credentials key (see Privacy), and the public key is stored alongside it in your data directory.

Setting up a keypair ​

Generate a new keypair ​

  1. Open Settings → GPG Encryption.
  2. Enter your name and email, then click Generate Keypair.
  3. Once generated, the key fingerprint is displayed. You can clear the key at any time with the Clear button.

Keys are generated without a passphrase so they can be used automatically for encryption and decryption; the private key is protected by Swanmail's credentials key.

Import an existing keypair ​

If you already have a PGP keypair, paste the armored public key and private key into the Import keypair form and click Import. Swanmail validates that the two keys share the same fingerprint before storing them.

Import from system GPG ​

If you have gpg installed and a secret key in your system keyring, click Load available keys under Import from system GPG. Select the key you want to use and click Import. Swanmail will export the public and private parts from gpg and store them in its own key file.

PGP format ​

Settings → GPG Encryption → PGP format decides how a signed or encrypted message is laid out:

  • PGP/MIME (recommended), the default. The whole message — HTML, plain text and every attachment — is signed or encrypted as one MIME part. A signed message is multipart/signed with a detached signature (signature.asc); an encrypted one is multipart/encrypted holding a Version: 1 control part and the ciphertext (encrypted.asc). Subject, sender and recipients stay outside the protection, where mail servers need them.
  • Inline. Only the plain-text body is armoured (-----BEGIN PGP MESSAGE----- or a clear-signed text). The composer must be in plain-text mode, and attachments are sent unprotected. Use it only for a correspondent whose client cannot read PGP/MIME.

Sending a signed or encrypted message ​

  1. Compose a message. With PGP/MIME it can be HTML or plain text; inline needs Plain Text mode.
  2. Turn on Encrypt, Sign, or both in the composer footer. Both switches appear only once a key exists.
  3. When you send, Swanmail signs with your key and encrypts to every recipient's public key and your own, so the copy in Sent stays readable. Signing and encrypting together produces one OpenPGP message that is both.

Encryption needs a public key for every recipient. If one is missing the send stops and names the address. A message with OpenPGP turned on skips S/MIME, even if the S/MIME switches are on. Scheduled sends and rule replies are protected the same way, because they are finished by the same code.

Finding a recipient's key ​

Encrypting needs each recipient's public key. Swanmail can find one on the network:

  • Web Key Directory (WKD). The recipient's own domain publishes the key at a well-known HTTPS address derived from the email address. Swanmail asks the advanced location (openpgpkey.<domain>) first and the direct one (<domain>/.well-known/openpgpkey/) second.
  • keys.openpgp.org. Asked when WKD has nothing. It only lists an address after its owner has confirmed it by mail.

A key counts only if one of its user IDs is the address that was asked for. Requests go over HTTPS only, time out after a few seconds, are capped in size, and are never sent to a private or loopback host. A key that is found is added to Swanmail's keyring (pgp-public-keys.json in the user data directory; it holds only public keys).

In the composer, turning on Encrypt lists every recipient without a known key. Each one is looked up once on its own; Look up key asks again. In Settings → GPG Encryption, Look up key for address… does the same for any address and shows the fingerprint that was added and where it came from.

Looking a key up tells the recipient's domain, or keys.openpgp.org, that someone is about to write to that address. Nothing is looked up until Encrypt is on or you ask.

Autocrypt ​

Swanmail speaks Autocrypt Level 1, which lets mail clients swap keys without anyone looking them up.

  • Sending your key. Once you have a key, every message from an address the key carries gets an Autocrypt: header holding a minimal copy of your public key (the primary key, the user ID for that address and one encryption subkey). Turn it off under Settings → GPG Encryption → Autocrypt. A message sent from an address the key does not name gets no header.
  • Learning their keys. When Swanmail reads a message's headers — during sync or when a message is opened — it remembers the key and preference in a valid Autocrypt: header from the sender. Only a newer message can replace what it remembers, so mail arriving out of order never rolls a key back. This never touches the network. The key goes into your keyring the first time you encrypt to that address.
  • Encrypting by default. Turn on Prefer encrypted mail (prefer-encrypt=mutual) to say you want encrypted mail. When you and every recipient of a message have said so, Encrypt starts switched on and the composer says why. Switching it off is always your call. If you leave your preference off, the header omits prefer-encrypt, which Autocrypt reads as no preference.

Reading signed and encrypted mail ​

Swanmail recognises both layouts on its own:

  • A PGP/MIME encrypted message is decrypted with your key when you open it. Its body shows in place of the ciphertext, and its attachments appear above the body; click one to save it. A Decrypted chip appears next to the sender.
  • An inline message (a body starting with -----BEGIN PGP MESSAGE-----) is decrypted the same way. If it cannot be opened, the older banner with a Decrypt button is still shown.
  • A signature, detached (PGP/MIME), clear-signed (inline) or inside an encrypted message, is checked against the exact bytes that were signed. The chip reads Signed by … when it verifies against a key you hold, Invalid signature when the key is known but the message was altered, and Signed with an unknown key when the signing key is not in your keyring. Both layouts show the same three states.

Nothing decrypted is written to disk. The database keeps the ciphertext it received, and the cleartext exists only for as long as the message is on screen.