diff options
| -rw-r--r-- | src/content/docs/email/accounts-sending.md | 254 | ||||
| -rw-r--r-- | src/content/docs/email/compose-protect.md | 268 | ||||
| -rw-r--r-- | src/content/docs/email/overview.md | 79 | ||||
| -rw-r--r-- | src/content/docs/email/reading-imap.md | 154 | ||||
| -rw-r--r-- | src/content/docs/email/verify-inspect.md | 214 | ||||
| -rw-r--r-- | src/content/docs/guides/email-operations.md | 174 |
6 files changed, 969 insertions, 174 deletions
diff --git a/src/content/docs/email/accounts-sending.md b/src/content/docs/email/accounts-sending.md new file mode 100644 index 0000000..2770fe0 --- /dev/null +++ b/src/content/docs/email/accounts-sending.md @@ -0,0 +1,254 @@ +--- +title: Mail Accounts and Sending +description: "Add your email account to GpgFrontend, test the connection, and send a signed or encrypted message through your own mail server." +sidebar: + label: Accounts and Sending + order: 4 +--- + +To send email, or to read it from your mail server, GpgFrontend needs to know +your mail account. This page shows how to add one and how to send a message. + +You only need an account to send and fetch mail. Everything else in GpgFrontend +works without one. + +:::note[New in v2.2.3] + +Mail accounts and sending are new. Before, you had to send messages with a +separate email app. + +::: + +## Two Words You Will See + +Your mail provider runs two kinds of servers: + +- **IMAP** is the server that keeps your mailbox. GpgFrontend uses it to + **read** your mail. +- **SMTP** is the server that sends mail out. GpgFrontend uses it to **send**. + +Your mail provider's help pages list the address of each server. They often +look like `imap.example.com` and `smtp.example.com`. + +## Open the Mail Accounts Page + +1. Click **Edit** > **Settings**. +2. In the **Features** group, click **Mail Accounts**. + +If you have no account yet, the page says **No mail accounts yet**. Click +**Add an Account** to start. + +## Add an Account + +1. Click **Add** (or **Add an Account** if the list is empty). +2. Fill in the three sections described below. +3. Type your password in the **Password** box. +4. Click **Test Connection** in each section to check it works. +5. Click **OK** at the bottom of the Settings window to save. + +Nothing is saved until you click **OK**. If you click **Cancel**, your changes +are thrown away. + +### Identity + +This is how you appear to others. + +- **Display name**: your name, as people will see it. For example, `Alice Smith`. +- **Email address**: your email address. This is required. +- **Reply-To**: where replies should go, if not to your email address. Leave + it empty if you are not sure. It shows **Optional**. + +### Receiving (IMAP) + +1. Check **Use this account to receive**. +2. **Server**: the IMAP server address from your mail provider. +3. **Connection**: how to protect the connection. See + [Connection Choices](#connection-choices) below. +4. **Username**: usually your full email address. +5. **Sent folder**: leave it empty. It shows **Discovered automatically**. Type + a folder name only if your copies of sent mail end up in the wrong place. + +### Sending (SMTP) + +1. Check **Use this account to send**. +2. **Server**: the SMTP server address from your mail provider. +3. **Connection**: see [Connection Choices](#connection-choices) below. +4. **Username**: usually your full email address. + +You can turn on receiving, sending, or both. An account that does neither +cannot be used. + +### Connection Choices + +The **Connection** list decides how your password and mail are protected on +the way to the server. Both choices use **TLS**, which is the standard way to +encrypt the connection between your computer and the server. + +| Choice | When to use it | Port it uses | +| ---------------------------- | ---------------------------------------------------------------- | ------------------ | +| **TLS (recommended)** | The best choice. Use it unless your provider says otherwise. | IMAP 993, SMTP 465 | +| **STARTTLS** | When your provider asks for it. It also encrypts the connection. | IMAP 143, SMTP 587 | +| **None (this machine only)** | Only for a mail server on your own computer. Not encrypted. | IMAP 143, SMTP 25 | + +You do not type a port number. The port follows your choice, and GpgFrontend +shows it next to the list, for example **Port 993**. + +**None (this machine only)** only shows up when the server is your own +computer, such as `localhost`. For any other server, the connection is always +encrypted. + +### Password + +Type the password for your mail account in the **Password** box. + +When you come back later, the box is empty and shows **Leave blank to keep the +stored one**. Leave it empty to keep your saved password. Type a new one only +to change it. + +### No Sign-In Through a Web Page + +Some providers let other apps sign in through their own web page. This is +called **OAuth2**. GpgFrontend does not support it yet. + +If your provider needs it, use an **app password** instead. An app password is +a separate password that your provider makes for one app. You create it in +your provider's account or security settings, then paste it into the +**Password** box. It works only for mail, and you can cancel it at any time +without changing your main password. + +## Test the Connection + +1. Click **Test Connection** in the **Receiving (IMAP)** or **Sending (SMTP)** + section. +2. Wait. It shows **Testing...**. Click **Stop** if it takes too long. +3. Read the result below the button: + - **Connected successfully.** means it works. + - Otherwise, you see what went wrong and a hint. For example, **Check the + user name and password.** or **Check the server address for a typo.** + +The test uses what is on screen right now, even before you click **OK**. + +## Trust a Server You Run Yourself + +If you run your own mail server, its certificate may not be signed by a known +authority. This is called a **self-signed certificate**. A certificate is how a +server proves who it is. + +When the test meets such a server, GpgFrontend asks **Trust This +Certificate?** The window shows the certificate details and its SHA-256 +fingerprint. + +- Click **Yes** only if this is your own server and the fingerprint matches. +- Click **Cancel** if you are not sure. An unknown certificate can also mean + that someone is trying to listen in. + +If you click **Yes**, GpgFrontend trusts **only this exact certificate** for this +account. Any other certificate, even a new one from the same server, is still +refused. Click **Test Connection** again to confirm it works. + +The section then says **Trusting one certificate**, followed by the +fingerprint. Click **Stop trusting it** to undo this. + +## Manage Your Accounts + +- **Add**: make a new account. +- **Remove**: delete the selected account. GpgFrontend asks first. Its saved + password is deleted too. +- **Set as Default**: make the selected account the first choice when you send. + The default account shows **(default)** after its name. + +GpgFrontend checks your accounts before it saves them. It tells you if, for +example, an email address is missing, a server is not filled in, or two +accounts use the same address. + +## Where Your Password Is Kept + +Your mail password is never saved as plain text in the settings file. It is +kept in GpgFrontend's protected storage, which is encrypted with the +[Application Secure Key](/advanced/app-secure-key/). + +Your password is only as safe as that key. For the best protection, guard that +key with your system's keychain or a PIN. + +## Send a Message + +1. Write your message. See [Write and Protect a Message](/email/compose-protect/). +2. Sign or encrypt it if you like. +3. Click **Send...** (or press Ctrl+Enter; Cmd+Enter on a Mac). + +If **Send...** is grayed out, hover over it to see what is missing. + +### The Send Message Window + +The **Send message** window lets you check everything before the message +leaves. At the top it says: "Ready to send. Nothing has left this computer +yet." + +- **Send using**: pick the account to send from. Below it you see the server, + the port and the connection type. +- **Message**: a summary of what you are sending: + - **From** and **To**. + - **Blind copies**: your Bcc people, if any. These addresses go to the mail + server only. They are not written in the message, so no other reader can + see them. + - **Contains**: the size, and how many attachments. + +When you are ready, click **Send**. To stop, click **Cancel**. + +### Read the Result + +While sending, the window says "Sending. This window will say what happened." +The **Result** section then shows two lines: + +- **Submission**: did the mail server take the message? + - **Yes, accepted by the outgoing mail server** means it is on its way. + - If it failed, this line shows the reason, and the top of the window says + **Not sent.** +- **Copy in Sent**: was a copy put in your Sent folder? + - **Yes, saved to ...** names the folder. + - Many mail servers do not keep a copy of what you send. So GpgFrontend puts + one in your Sent folder itself, using your **Receiving (IMAP)** settings. + - If the account only sends, there is no mailbox, so no copy is kept. The + message was still sent. + +Click **Details** to see more, or **Copy details** to copy them. + +When all went well, the window closes by itself after a few seconds. The +**Close** button counts down. Click anywhere in the window to stop the +countdown. + +### When the Result Is Unknown + +Sometimes the connection drops just after the message went out. Then the +window says: "It is not known whether this was sent." + +This means the server may or may not have the message. Before you send it +again: + +1. Look in your Sent folder. +2. Or ask the person if they got it. + +If you send it again without checking, they may get it twice. + +### Closing While Sending + +If you close the window while a message is still being sent, GpgFrontend asks +**Still sending**. The server may already have the message. If you close now, +you will not find out if it was delivered. + +- Click **Keep Waiting** to stay and see the result. This is the safe choice. +- Click **Close Anyway** to close the window. + +To stop a send on purpose, click **Stop** next to **Submission** instead. + +## If Something Goes Wrong + +- **"No outgoing account is configured."** Add an account with **Use this + account to send** checked. +- **"No password is stored for this account..."** Open **Mail Accounts**, select + the account, type the password in the **Password** box, and click **OK**. +- **The test says the password is wrong.** Check the username. If your provider + uses web sign-in, make an app password. See + [No Sign-In Through a Web Page](#no-sign-in-through-a-web-page). +- **The test says the certificate is expired or not yet valid.** Check that the + clock on your computer is right. diff --git a/src/content/docs/email/compose-protect.md b/src/content/docs/email/compose-protect.md new file mode 100644 index 0000000..20337ec --- /dev/null +++ b/src/content/docs/email/compose-protect.md @@ -0,0 +1,268 @@ +--- +title: Write and Protect a Message +description: "Write an email in GpgFrontend, then sign it, encrypt it, or both. Covers the header fields, replies, attachments, the raw source and the Security menu." +sidebar: + label: Write and Protect + order: 2 +--- + +This page shows how to write an email in GpgFrontend and how to protect it. + +- **Signing** proves the message came from you and was not changed on the way. +- **Encrypting** hides the message so only the people you choose can read it. + +You can do one, the other, or both. Everything happens on your own computer. + +On a Mac, press Cmd where this page says Ctrl, and Option where it says Alt. + +## Start a New Message + +1. Click **File** > **Workspace** > **Mail Editor**. +2. A new tab opens with an empty message. + +Each message is an `.eml` file. You can save it with **File** > **Save File** or +**File** > **Save As...**, like any other file. + +## Fill In the Header Fields + +The header fields sit at the top of the message: + +- **From:** who the message is from. This is you. +- **To:** who the message is for. +- **Subject:** what the message is about. + +To add more people: + +1. Click **Cc/Bcc** at the end of the **To:** row (or press Ctrl+Shift+C). +2. Two more rows appear: **Cc:** and **Bcc:**. + +What these mean: + +- **Cc** (carbon copy) sends a copy to someone. Everyone can see who was in Cc. +- **Bcc** (blind carbon copy) sends a copy in secret. The other people do not + see this name. + +To add several people in one field, put a semicolon (`;`) between the +addresses. For example: `[email protected]; [email protected]`. + +Each address can be written as `[email protected]` or as +`Alice <[email protected]>`. + +### Address Suggestions + +As you type an address, GpgFrontend suggests matching addresses: + +- In **From:**, it suggests your mail accounts first, then the addresses on + your own private keys. +- In **To:**, **Cc:** and **Bcc:**, it suggests the addresses on the keys in + your key database. + +### About Bcc + +Names in **Bcc:** are never written into the message itself. If they were, +every reader could see who got a secret copy. + +GpgFrontend still uses them in two ways: + +- When you encrypt, it can use them to pick the keys to encrypt to. +- When you send, it gives them to your mail server, so they still get the + message. + +They are not saved in the `.eml` file. + +:::note[New in v2.2.3] + +The header fields are now part of the message tab. The old pop-up window that +asked for From, To and Subject is gone. + +::: + +## Write the Body + +Click in the large area below the header fields and type your message. It shows +**Write your message here.** until you start typing. + +## Attach Files + +1. Click **Attach File...** (or press Ctrl+Shift+A). +2. Pick one or more files and confirm. + +You can also drag files from your computer and drop them onto the message. + +Each file can be up to 48 MiB. Folders cannot be attached. If a file is refused, +a window tells you which one and why. + +Your attachments are listed under the message. To learn more about the list, see +[Work With Attachments](/email/reading-imap/#work-with-attachments). + +## Reply, Reply All and Forward + +When you open a message you received, the action row shows three buttons: + +- **Reply** (Ctrl+R): write back to the sender. +- **Reply All** (Ctrl+Shift+R): write back to + the sender and everyone else who was addressed. People in Bcc are not + included. +- **Forward** (Ctrl+L): pass the message on to someone + else, with its attachments. + +Each one opens a **new tab** with a new message. The original message is not +changed. + +On a message you are still writing, these buttons are not on the row. You find +**Send...** and **Attach File...** there instead. Other actions are under +**More**. + +## Message and Raw Source + +Above the body you can switch between two views: + +- **Message** (Alt+1): the normal view, with header + fields, body and attachments. +- **Raw Source** (Alt+2): the full message as plain text, + exactly as it is stored in the file. + +The raw source is read-only at first. To change it by hand: + +1. Switch to **Raw Source**. +2. Click **Edit Raw Source**. +3. Make your changes. What you type here is the message itself. +4. Click **Stop Editing** when you are done. + +Most people never need the raw source. It is there for checking or fixing a +message by hand. + +## Sign or Encrypt the Message + +First pick your keys in the [Key Toolbox](/guides/understand-interface/#key-toolbox) +on the right: + +- **To sign:** check your own private key. +- **To encrypt:** check the public key of each person who should read the + message. Check your own key too if you want to read it later. + +Then use the **Security menu**: + +1. Find the status button at the right end of the action row. On a new message + it says **Not signed or encrypted**. +2. Click it. A menu opens. +3. Choose one: + - **Sign...**: sign the message. + - **Encrypt...**: encrypt the message. + - **Encrypt and Sign...**: do both at once. This is the best choice for a + private message. + +The result shows in the **Status Panel**. The status button changes to tell you +what the message is now, for example **Encrypted**. + +You can also use the **Sign**, **Encrypt** and **Encrypt & Sign** buttons on +the main toolbar. They do the same thing. + +### What the Security Menu Offers + +The menu changes with the message. This is what you see: + +| The message is... | The menu offers | +| ----------------------- | ----------------------------------------------------------------------------------------------------------- | +| Not signed or encrypted | **Sign...**, **Encrypt...**, **Encrypt and Sign...** | +| Signed | **Verify Signature**, **Signature Details...**, **Sign Again With Another Key...**, **Remove Signature...** | +| Encrypted | **Decrypt**, **Decrypt and Verify**, **Encryption Details...** | +| Encrypted and signed | **Decrypt and Verify**, **Decrypt**, **Details...**, **Remove Signature...** | +| Broken | **What Is Wrong With This Message?**, **Try to Verify Anyway**, **Try to Decrypt Anyway** | + +"Broken" means the message says it uses OpenPGP, but it is not built the right +way. To learn how to check a message you received, see +[Verify and Inspect a Message](/email/verify-inspect/). + +## Signed and Encrypted Messages Are Locked + +Once a message is signed or encrypted, you cannot edit it. A notice above the +body tells you why: + +- **Signed:** a change under a signature would look like a forgery. To edit, + first remove the signature with **Remove Signature...** in the Security menu. +- **Encrypted:** decrypt it first. +- **Encrypted and signed:** decrypt it, then remove the signature. + +If you try to change a signed message anyway, GpgFrontend asks: **Remove the +signature and make it an ordinary message?** Click **Yes** to remove it, or +**Cancel** to keep it. + +Removing a signature cannot be undone. The text of the message is kept as it +is. + +### Lock a Message Yourself + +You can also lock a message you received, so nobody changes it by accident: + +1. Click **More**. +2. Click **Read-only**. + +A **Read-only** label appears. **Reply** and **Forward** still work, and they +make new messages. To unlock, click **More** > **Read-only** again. + +## Send or Save the Message + +You have two choices: + +- **Send it from GpgFrontend.** Click **Send...** (or press + Ctrl+Enter). You need a mail account for this. See + [Mail Accounts and Sending](/email/accounts-sending/). +- **Send it with another email app.** Save the message as an `.eml` file with + **File** > **Save As...**. Then open or import that file in your usual email app + and send it from there. + +Before the file is saved, GpgFrontend takes a last look at the message. If +something looks risky, it shows a **Check before exporting** window. See +[Check Before Exporting](/email/verify-inspect/#check-before-exporting). + +## Understand the Results + +After you sign, encrypt, verify or decrypt, the **Status Panel** shows the +result as a set of cards: + +- **E-Mail**: the message headers: **From**, **To**, **Subject**, **CC**, + **BCC** and **Date**. +- **OpenPGP**: two technical values about the signature: + - **Digest of Signed MIME Entity (SHA-256)**: a fingerprint of the exact part + of the message that the signature covers. If two copies show the same + value, the signed part is the same in both. + - **Declared Signature Hash (micalg)**: the hash method the message says its + signature uses. This is only what the message claims. +- **Attachments**: each file in the message. It also says when a file is an + OpenPGP key, or when it is **not covered by the signature**. +- **Recipient Check**: for encrypted mail, whether each person in the headers + can really read it. A warning here means someone was addressed but not + encrypted to, so they cannot open it. +- **Encryption Recipient**: who each copy was encrypted to, shown as the key's + name and **Key ID**. + +## Tips and Troubleshooting + +- **Send... is grayed out.** Hover over it. It tells you what is missing, for + example a subject or a recipient. +- **A signature shows as bad, but the text looks fine.** A signature covers the + exact bytes of the message. Some programs change line endings or re-encode a + message when they save or forward it. When you can, save the original `.eml` + file instead of a copy. +- **You cannot decrypt a message.** Check that the matching private key is in + the key database you are using right now. +- **The reader cannot open your message.** Make sure their email app supports + PGP/MIME. Apps that only know older "inline PGP" may not open it. +- **Keep private keys safe.** Never upload them to an email provider. + +## Good to Know (Technical Details) + +You can skip this section. + +- GpgFrontend follows the OpenPGP standards ([RFC 4880][rfc4880] and + [RFC 3156][rfc3156]). The messages work with Thunderbird and other OpenPGP + email apps. +- It makes **PGP/MIME** messages, not inline PGP. A signed message has its + signature in a separate part. An encrypted message is wrapped as one + encrypted part. This keeps the body, attachments and formatting intact. +- `.eml` files work almost everywhere. You can always move a message to or from + another email app. + +[rfc4880]: https://www.rfc-editor.org/rfc/rfc4880 +[rfc3156]: https://www.rfc-editor.org/rfc/rfc3156 diff --git a/src/content/docs/email/overview.md b/src/content/docs/email/overview.md new file mode 100644 index 0000000..3f30ade --- /dev/null +++ b/src/content/docs/email/overview.md @@ -0,0 +1,79 @@ +--- +title: Email Overview +description: "What the Email feature in GpgFrontend can do, where to find it, and which page to read for each task." +sidebar: + label: Overview + order: 1 +--- + +GpgFrontend has its own email tools. With them you can write a message, sign +it, encrypt it, and send it. You can also read messages from your mail server +and check them. + +:::note[New in v2.2.3] + +GpgFrontend can now send email and read it from your mail server. Before, it +could only work with email files, and your normal email app had to do the +sending and receiving. + +::: + +## What You Can Do + +- **Write** a message, with From, To, Cc, Bcc, Subject and attachments. +- **Sign** it, so the reader can tell it came from you and was not changed. +- **Encrypt** it, so only the people you choose can read it. +- **Send** it through your own mail account. +- **Read** messages from your mail server. +- **Check** a message you received: is the signature good, and can you open it? + +Every email is kept as an `.eml` file. This is a common email file format. Most +email apps can open it and save it. So you can still move messages between +GpgFrontend and your usual email app if you like. + +All signing, encrypting, checking and decrypting happens on your own computer. +Your private keys never leave it. + +## Where to Find It + +There are two ways in: + +- **To write a new message:** click **File** > **Workspace** > **Mail Editor**. + A new tab opens with an empty message. +- **To read messages from your mail server:** click **Advanced** > **Open IMAP + Controller**. A window opens where you can browse your folders. + +You can also open an `.eml` file you already have, for example from the +[File Panel](/guides/understand-interface/#file-panel). It opens in a mail tab, +the same kind of tab as a new message. + +Before you can send or read mail from a server, you need to add your mail +account. See [Mail Accounts and Sending](/email/accounts-sending/). + +:::note[Don't see Open IMAP Controller?] + +The **Advanced** menu is hidden in sandboxed builds, such as Flatpak or the Mac +App Store edition. In those builds, **Open IMAP Controller** is not available. + +If no account has receiving turned on, the app tells you to set one up in +Settings first. + +::: + +## The Status Panel in Mail Tabs + +In a mail tab, the **Status Panel** at the bottom starts small, as a thin bar. +This leaves more room for the message, its headers and its attachments. The +panel opens by itself when there is a new result to show, for example after +you sign or verify a message. + +## Which Page Do I Need? + +- **I want to write, sign or encrypt a message.** Read + [Write and Protect a Message](/email/compose-protect/). +- **I got a message and want to know if I can trust it.** Read + [Verify and Inspect a Message](/email/verify-inspect/). +- **I want to set up my mail account, or send a message.** Read + [Mail Accounts and Sending](/email/accounts-sending/). +- **I want to read messages from my mail server, or work with attachments.** + Read [Read Mail from Your Server](/email/reading-imap/). diff --git a/src/content/docs/email/reading-imap.md b/src/content/docs/email/reading-imap.md new file mode 100644 index 0000000..70a8538 --- /dev/null +++ b/src/content/docs/email/reading-imap.md @@ -0,0 +1,154 @@ +--- +title: Read Mail from Your Server +description: "Browse the folders on your mail server with the IMAP Controller, open a message in GpgFrontend, and save or open its attachments safely." +sidebar: + label: Read Mail + order: 5 +--- + +GpgFrontend can fetch messages from your mail server, so you can check and +decrypt them right away. It does this with the **IMAP Controller**. + +**IMAP** is the way email apps talk to the server that keeps your mailbox. + +:::note[New in v2.2.3] + +The IMAP Controller is new. Before, you had to save each message as a file in +another email app first. + +::: + +## Before You Start + +You need a mail account with receiving turned on. See +[Mail Accounts and Sending](/email/accounts-sending/). In short: check **Use +this account to receive**, fill in the server, and save a password. + +## Open the IMAP Controller + +1. Click **Advanced** > **Open IMAP Controller**. +2. The **IMAP Controller** window opens and connects to your account. + +If you have no account with receiving turned on, GpgFrontend says **No mail +account** and asks you to set one up in Settings first. + +The **Advanced** menu is hidden in sandboxed builds, such as Flatpak or the Mac +App Store edition. There, the IMAP Controller is not available. + +## It Only Reads + +The IMAP Controller is for looking, not for changing. It does not delete, move +or send anything. Opening a message here does not mark it as read on the +server. + +To answer, sort or delete mail, use your usual email app. + +## Find a Message + +At the top of the window: + +- **Account**: pick the mail account to look in. +- **Folder**: pick a folder, such as your inbox. +- **Search subject or sender**: type a word to find matching messages. +- The refresh button (**Reload this folder from the server**) fetches the + folder again. + +The message list shows the subject, the sender and the date. Click a message +to see its details on the right: subject, sender, date, size, **Message-ID** +and **Folder**. + +Messages come in pages of 50. Use **Previous** and **Next** to move between +pages. The bottom of the window shows where you are, for example **Page 1 of +4**. + +If a search finds very many messages, only the first ones are shown. Type more +words to narrow it down. + +### Remembered Folder Lists + +When you open an account again, GpgFrontend first shows the list from your +last visit, so you do not stare at an empty window. It says **Shown from the +previous visit to this account; refreshing.** while it gets the newest list +from the server. + +## Open a Message + +1. Select a message in the list. +2. Click **Open**. + +The message is downloaded and opens in a **new tab**. The window says **Opened +in a new tab.** + +From there you can check and decrypt it like any other message. See +[Verify and Inspect a Message](/email/verify-inspect/). You can also save it as +an `.eml` file. + +Right-click a message for more: **Open**, **Copy Subject**, **Copy Sender** and +**Copy Message-ID**. + +While something is loading, the **Close** button turns into **Stop**. Click it +to stop. + +### Very Large Messages + +A message larger than 64 MiB cannot be opened. If you select one, the details +say: "This message is too large for this application to open, so it cannot be +imported." Use your usual email app for such a message. + +## Work With Attachments + +Attachments are listed under the message, with their **Name**, **Type**, +**Size**, and whether they are **Signed**. Click **Expand** to see every file, +or **Collapse** to show only a summary. + +The **Signed** column tells you if a file is covered by the message's +signature: + +- **signed**: covered, and the signature is good. +- **signed, not checked**: covered, but the signature has not been checked yet. +- **signed, could not be checked**: covered, but the check gave no answer. +- **signature not good**: covered by a signature that failed. Do not trust it. +- **unsigned**: not covered. Anyone could have added this file. + +### Attachment Actions + +Click **Attachments** on the action row, or right-click a file in the list: + +- **Open**: open the file with the app your computer uses for it. +- **Save...**: save the selected files to a folder. +- **Save All...**: save every attachment to a folder. +- **Import Key**: import the file into your key database. This shows only when + the file is an OpenPGP key. +- **Remove**: take the selected files out of the message. This only works on a + message you can edit. +- **Copy Name**: copy the file name. + +With **Save All...**, a file never replaces one that is already in the folder. +If a name is taken, GpgFrontend saves the file under a new name and tells you. + +Removing an attachment from a message you received cannot be undone. Save it +first if you might need it. + +### Which Files It Will Open + +GpgFrontend opens only files that are safe to look at: + +- **Documents**: such as PDF, text, Word, Excel, PowerPoint, OpenDocument, + CSV, RTF and EPUB. +- **Pictures**: such as PNG, JPEG, GIF, WebP and HEIC. +- **Sound and video**: such as MP3, WAV, MP4 and MKV. +- **Plain data files**: such as JSON, XML, YAML, calendar (`.ics`) and contact + (`.vcf`) files, and other emails (`.eml`). + +Everything else is refused, for example programs, scripts, shortcuts, +installers, archives such as ZIP, and SVG images. A file from a stranger that +"opens" might really **run**, and that could harm your computer. An archive is +refused because you cannot tell what is inside until it is unpacked. + +When a file is refused, GpgFrontend explains why. You can still click +**Save...**, then open the file yourself if you are sure where it came from. + +### Size Limit When Attaching + +When you add a file to your own message with **Attach File...**, each file can +be up to 48 MiB. Bigger files are refused with a message that names them. diff --git a/src/content/docs/email/verify-inspect.md b/src/content/docs/email/verify-inspect.md new file mode 100644 index 0000000..18b5562 --- /dev/null +++ b/src/content/docs/email/verify-inspect.md @@ -0,0 +1,214 @@ +--- +title: Verify and Inspect a Message +description: "Check a message you received in GpgFrontend: what each security badge means, whether you can open it, and what the Message Details window shows." +sidebar: + label: Verify and Inspect + order: 3 +--- + +When you get a message, you want to know two things: + +- **Can I trust it?** Did it really come from the sender, and was it changed on + the way? +- **Can I read it?** If it is encrypted, do you have the key to open it? + +This page shows where GpgFrontend answers these questions. + +On a Mac, press Cmd where this page says Ctrl. + +## Open the Message + +Open the message in a mail tab. You can: + +- open an `.eml` file, for example from the + [File Panel](/guides/understand-interface/#file-panel), or +- fetch it from your mail server. See + [Read Mail from Your Server](/email/reading-imap/). + +## Read the Security Badge + +At the right end of the action row there is a status button. We call it the +**badge**. It tells you, in a few words, what kind of message this is. Click it +to open the Security menu. + +| Badge | What it means | +| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | +| **Not signed or encrypted** | An ordinary message. Nothing proves who sent it. This is normal for most email. | +| **Encrypted** | The message is hidden. It has no signature. | +| **Signature not checked** | The message has a signature, but it has not been checked yet. This says nothing good or bad so far. | +| **Encrypted, signature not checked** | The same, for an encrypted message. | +| **Signature verified** | The signature was checked and it is good. The message was not changed since it was signed. | +| **Encrypted, signature verified** | The same, for an encrypted message. | +| **Signed by a different address** | The signature is good, but the key belongs to a different address than the one in **From**. Be careful. | +| **Signature or key expired** | The signature matches, but the signature or the key has expired. | +| **Signed by an unknown key** | You do not have the sender's public key, so the signature cannot be checked. Import their key, then check again. | +| **Signature could not be checked** | The check ran, but it could not give an answer. Trying again may help. | +| **Signing key not authorized** | The signature is correct, but the key that made it is not allowed to sign. Do not trust it. | +| **Bad signature** | The signature does not match the message, or the key was revoked. The message may have been changed. Do not trust it. | +| **Malformed OpenPGP structure** | The message says it uses OpenPGP, but it is not built the right way. It may not verify or decrypt. | + +### Check the Signature + +A signature is not checked by itself when you open a message. To check it: + +1. Click the badge. +2. Click **Verify Signature**. + +For an encrypted and signed message, click **Decrypt and Verify** instead. + +The badge changes to show the result. The details also appear in the **Status +Panel**. + +## Can I Open This Encrypted Message? + +When a message is encrypted, the body is hidden. In its place you see a panel +that says **This message is encrypted** (or **This message is encrypted and +signed**). Below it, GpgFrontend tells you what it knows: + +- **Addressed to ...**: who the message was sent to, from its headers. +- Whether you hold the right private key. For example: "You hold the private + key for [email protected], so this message can be opened here." +- If you do not: "This message is encrypted to keys you do not hold the private + half of, so it cannot be opened on this computer." +- Sometimes it cannot tell. Some senders hide who the message is for. Then the + only way to know is to try. + +To open it, click **Decrypt** on the panel. + +## The Message Details Window + +The **Message Details** window shows everything GpgFrontend knows about a +message. To open it, do one of these: + +- Click **More** > **Details...**. +- Press Ctrl+Shift+D. +- Click the badge, then a details item, such as **Signature Details...** or + **Encryption Details...**. + +The window has three tabs. + +### Security + +The top line says what the message is, for example **This message carries a +signature.** Below it are up to four groups: + +- **Signatures**: each signature, who made it, and whether it is good. You also + see the key **Fingerprint**, when it was signed (**Signed at**), and the hash + method used. +- **Recipients**: for an encrypted message, who it was encrypted to. +- **Keys for these addresses**: for each address in the message, which keys + you have for it and whether they are usable. **no key found** means you have + no key for that address. +- **What stands out**: things worth knowing about this message. See the list + below. + +Right-click a row for more actions: + +- **Copy Value**, **Copy Fingerprint**, **Copy Address**. +- **Import the Key in This Message**: when you have no key for an address, but + the message carries one. +- **Verify Signatures** (or **Verify Again**): check the signatures now. + +### Structure + +An email is built from parts: the text, any attachments, and the signature. +This tab lists every part, with its **Name**, **Size** and **Encoding**. + +The **Covered by** column says which signature protects each part. **not +covered** means that part is outside the signature. Anyone could have added or +changed it. + +Right-click a part to **Save Part...**, **Import This Key** (if it is a key), +**Copy Content-Type**, **Copy Name** or **Copy SHA-256**. + +### Headers + +Headers are the lines at the top of an email, such as From, To, Date and +Subject. This tab lists all of them, with their **Name** and **Value**. + +Type in **Filter headers** to show only the headers that contain some text. +Right-click a header to **Copy Value** or **Copy Whole Field**. + +### Warnings in "What Stands Out" + +These are the warnings you may see, in plain words: + +- **Signed part no longer in canonical form**: a program changed the message + after it was signed, usually the line endings. The signature may fail even + though nobody meant harm. +- **Duplicate ... header**: a header that should appear once appears more than + once. Different email apps may show different values. +- **Address may be disguised**: an address uses letters that can look like a + different, familiar address. Check it closely. +- **Replies go somewhere else**: if you reply, your answer goes to a different + domain than the sender's. +- **Malformed signed section** or **Malformed encrypted section**: the message + is not built the right way. +- **Not everything is signed**: some parts are outside the signature. Anyone + could have added them. +- **Signature covers the encrypted data only**: the signature shows who sent + the encrypted block, not who wrote what is inside. Anyone can sign a copy of + someone else's encrypted message. +- **Public key attached**: the message carries a public key. A key in a message + proves nothing about who sent it. Anyone can make a key with any name. +- **Detached signature attached**: the message carries a signature file for + something else. Opening the message does not check it. +- **Blind recipients are visible**: the message has a Bcc header, so every + reader can see who got a secret copy. + +## Check Before Exporting + +When you save a message to an `.eml` file, GpgFrontend takes a last look at it. +If it finds a real risk, a **Check before exporting** window opens. It says: +"Something about this message is worth checking before you save it." and lists +what it found. + +It can warn you about: + +- **Bcc header present**: the message has a Bcc header. Sending it would tell + every reader who got a secret copy. +- **Recipient may be disguised**: an address uses letters that can look like a + different address. Check it before sending. + +Smaller notes, such as **Some parts are not signed** or **No recipients**, are +under the details button in the same window. + +You decide what to do: + +- Click **Save** to save the file anyway. +- Click **Cancel** to go back and fix the message. + +**Cancel** is the default, so pressing Enter does not save by accident. + +## HTML Messages Are Shown as Source + +Some messages are written in HTML, the language of web pages. GpgFrontend +never draws them as a web page. It shows the HTML code as plain text instead, +with this notice: "This message was written in HTML. It is shown as its source +rather than rendered: nothing here loads images or follows links." + +This is safer: + +- **No hidden tracking.** Images in an email can tell the sender when and where + you opened it. Here, no images are loaded. +- **No surprise links.** Nothing opens a website on its own. +- **What you see is what is there.** HTML can hide text, or make one link look + like another. As plain text, nothing is hidden. + +## Messages Are Checked Again When Your Keys Change + +A check result depends on the keys you have. So GpgFrontend checks open +messages again when: + +- you import a key, for example the sender's public key, or +- you switch or reload your [key databases](/advanced/key-database/). + +For example, a message that said **Signed by an unknown key** can turn into +**Signature verified** right after you import the sender's key. + +:::note[New in v2.2.3] + +Open messages are now checked again by themselves after your key databases are +reloaded. + +::: diff --git a/src/content/docs/guides/email-operations.md b/src/content/docs/guides/email-operations.md deleted file mode 100644 index 280c8a7..0000000 --- a/src/content/docs/guides/email-operations.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Email Functionality -description: "Sign, encrypt, verify, and decrypt emails offline in GpgFrontend using the .eml format and the built-in OpenPGP Email module." -sidebar: - label: Email Operations - order: 8 ---- - -GpgFrontend can **sign**, **encrypt**, **verify**, and **decrypt** email, all on -your own computer. It does this with `.eml` files, a standard email file format -that almost every email app understands. - -## How It Works - -The key thing to understand: **GpgFrontend does not send or receive email.** It -only does the encryption and signing part, offline. Your normal email app still -handles sending and receiving. Your private keys never leave your computer. - -So the flow is simple: - -- **To send a secure email**: write and protect it in GpgFrontend, save it as an - `.eml` file, then open that file in your email app and send it. -- **To read a secure email**: save the email as an `.eml` file from your email app, - then open it in GpgFrontend to decrypt or verify it. - -## Open the Email Tools - -Email support comes from the built-in **Email module**, which ships with the -regular GpgFrontend desktop edition and loads on its own. There is nothing to set -up in Settings. - -There are two ways in: - -- Click **New E-Mail** to write a message, protect it, and save it as an `.eml` - file. -- Open an existing `.eml` file (for example, one saved from your email app) to - verify or decrypt it. GpgFrontend shows the email headers (From, To, Subject, - Date) next to the OpenPGP result. - -:::note[Don't see the email buttons?] - -You are probably running an edition without the Email module, or a build with -modules excluded. - -::: - -## Write and Send a Secure Email - -### Step 1: Write and Sign - -1. Click **New E-Mail** to open a blank message. -2. Type your message in the editor. -3. Pick your **private key** in the **Key Toolbox**. -4. Click **Sign**. -5. In the dialog, fill in **From**, **To**, and **Subject**. Use the **CC** and - **BCC** buttons to show those fields if you need them. - -GpgFrontend fills in **From** for you, taken from your signing key. When you -encrypt, it can also suggest recipients from the encryption keys you picked. - -:::note[Address format] - -Each address must be a plain address (`[email protected]`) or the -`Name <[email protected]>` form. Separate several recipients in **To**, **CC**, or -**BCC** with a semicolon (`;`). Bad entries are flagged before the email is built. - -::: - -![][img-1] - -![][img-2] - -![][img-3] - -![][img-4] - -### Step 2: Encrypt (Optional) - -To hide the content so only the recipient can read it: - -1. Pick the recipient's **public key** in the **Key Toolbox**. -2. Click **Encrypt**. - -You can sign and encrypt together for a message that is both private and proven to -be from you. - -![][img-5] - -### Step 3: Save and Send - -1. Save the message as an `.eml` file with **File > Save As**. -2. In your email app or webmail, open that `.eml` file (for example, drop it into - your drafts), then send it as usual. - -Remember, GpgFrontend doesn't send the email. Your email app does. - -## Read a Secure Email - -1. In your email app, save or export the message as an `.eml` file (or copy the raw - email source). -2. Open the `.eml` file in GpgFrontend. -3. Choose what to do: - - **Decrypt Verify**: decrypt and check the signature at the same time. - - **Verify**: check the signature only, without decrypting. - - **Decrypt**: decrypt only, without checking the signature. - -A signed email shows a **Good Digital Signature** message. An encrypted email is -shown decrypted. - -![][img-6] - -### Understand the Results - -After you verify or decrypt an `.eml` file, GpgFrontend shows the outcome as a set -of result cards: - -- **E-Mail card**: the message headers, including **From**, **To**, **Subject**, - **CC**, **BCC**, and **Date**. -- **OpenPGP card**: details of the OpenPGP/MIME structure, including the **Signed - EML Data Hash (SHA1)** that the signature covered, and the **Message Integrity - Check Algorithm** (the `micalg` named in the message). -- **Encryption Recipient cards**: for encrypted mail, who each copy was encrypted - to, shown as the key's user ID and **Key ID**. - -These cards let you confirm that the signature covers the message you actually -received, and that it was encrypted to the keys you expect. - -## Tips and Troubleshooting - -- **Signature shows as invalid.** A PGP/MIME signature covers the exact bytes of - the signed part. If a mail server or app rewraps or re-encodes the message in - transit, the check can fail even when the text looks fine. When you can, save the - original `.eml` source rather than a re-rendered copy. -- **The email buttons are missing.** The email tools come from the Email module. If - they aren't there, you are likely running an edition without it, such as - GpgFrontend Lite. See [Open the Email Tools](#open-the-email-tools). -- **An address is rejected.** Make sure each address is `[email protected]` or - `Name <[email protected]>`, and separate several recipients with a semicolon - (`;`). -- **Can't decrypt a received email.** Check that the matching private key is in the - active key database, and that you picked the database whose keys match the - recipients. -- **The recipient can't read your message.** Make sure your app kept the `.eml` - exactly as is, and that their email app supports PGP/MIME. Apps that only support - inline PGP may not be able to read it. -- **Use trusted keys.** Import public keys only from sources you trust, and check - them before you rely on them. -- **Keep private keys safe.** Never upload them to email providers; store them on - encrypted storage. - -## Good to Know (Technical Details) - -You can skip this section. It explains the formats and choices behind the email -tools. - -- **Standards**: GpgFrontend follows the OpenPGP standards (RFC 4880 and RFC 3156), - so the output works with Thunderbird and other OpenPGP email apps. -- **PGP/MIME, not inline**: it produces **PGP/MIME** messages. A signed message is - wrapped as `multipart/signed` with a detached signature; an encrypted one as - `multipart/encrypted`. This keeps the body, attachments, and formatting intact, - and it is the format modern clients like Thunderbird expect. -- **Why `.eml` and not IMAP/SMTP**: `.eml` is supported almost everywhere and is - easy to export, import, and process offline. Building in full mail protocols - would add complexity and risk, and pull the app away from its focus on local - encryption. -- **Offline by design**: every operation runs on your computer. Your private keys - and message contents are never sent to outside servers. - -[img-1]: https://image.cdn.bktus.com/i/2025/06/24/84f732220b3a967aa5d3986f79475bdfcf53454e.webp -[img-2]: https://image.cdn.bktus.com/i/2025/06/24/610ba60f2cd8eeddbcfbbc57aa602cff61197065.webp -[img-3]: https://image.cdn.bktus.com/i/2025/06/24/fea933e12bf46516d6a1385698b6afa94e7543a0.webp -[img-4]: https://image.cdn.bktus.com/i/2025/06/24/ee90e5bb25c7accdccf70f17c1986e53e0b4e81f.webp -[img-5]: https://image.cdn.bktus.com/i/2025/06/24/f8fe32d6e3502a1ba3503189fa40e4348bd4cc81.webp -[img-6]: https://image.cdn.bktus.com/i/2025/06/24/64b84451fd044cfd0c081161dad3057c5fde25a4.webp |