diff options
| -rw-r--r-- | src/content/docs/guides/file-operations.md | 124 | ||||
| -rw-r--r-- | src/content/docs/guides/text-operations.md | 200 |
2 files changed, 283 insertions, 41 deletions
diff --git a/src/content/docs/guides/file-operations.md b/src/content/docs/guides/file-operations.md index 65825a9..d31f580 100644 --- a/src/content/docs/guides/file-operations.md +++ b/src/content/docs/guides/file-operations.md @@ -121,24 +121,126 @@ the name before you click. ## Encrypt, Decrypt, Sign, or Verify a File -Once a file is selected in the File Panel, pick the right key in the **Key -Toolbox** and click the matching toolbar button: +The buttons are the same as for text: **Encrypt**, **Decrypt**, **Sign** and +**Verify** on the toolbar, or the same items in the **Operations** menu. They +act on the file you selected in the File Panel. See +[Find the Buttons](/guides/text-operations/#find-the-buttons) for the full list +and shortcuts. -- **Encrypt**: choose the recipient's **public key**, then click **Encrypt**. -- **Decrypt**: make sure your **private key** is in your keyring, then click - **Decrypt**. You don't need to pick a key; GpgFrontend finds the right one. -- **Sign**: choose your **private key**, then click **Sign**. -- **Verify**: make sure the sender's **public key** is in your keyring, then click - **Verify**. +GpgFrontend never changes your original file. It always writes a **new file** +next to it, in the same folder. The new file's name tells you what it is: -GpgFrontend checks your choice of keys before it starts. For example, it tells -you why a key cannot be used to encrypt. See -[Encryption Safety](/guides/encryption-safety/). +| Task | You select | New file made | Example | +| ------- | ---------------- | ---------------------- | ---------------- | +| Encrypt | `report.pdf` | name + `.gpg` | `report.pdf.gpg` | +| Sign | `report.pdf` | name + `.sig` | `report.pdf.sig` | +| Decrypt | `report.pdf.gpg` | name without `.gpg` | `report.pdf` | +| Verify | `report.pdf.sig` | nothing, only a result | | + +If you turned on ASCII output, encrypting and signing make `.asc` files +instead. See [Choose ASCII or Binary Output](#choose-ascii-or-binary-output). + +If a file with the new name is already there, GpgFrontend asks first. It only +replaces the old file after the task has worked. If the task fails, no new file +is left behind. + +### Encrypt a File + +You need the **recipient's public key**. + +1. **Select the file.** In the File Panel, click the file once so it is + highlighted. +2. **Pick the recipient.** In the **Key ToolBox** on the right, tick the box in + front of the recipient's public key. Tick your own key too if you want to + open the file later yourself. +3. **Click Encrypt.** +4. **Answer any questions.** GpgFrontend may stop to check your recipients. See + [Encryption Safety](/guides/encryption-safety/). +5. **Find the new file.** It appears in the same folder, for example + `report.pdf.gpg`. The **Status Panel** shows whether it worked. +6. **Send the new file**, not the original. ![][img-3] +:::caution + +If you tick **no key** and click **Encrypt**, GpgFrontend asks for a password +and encrypts with that instead +([symmetric encryption](/guides/symmetric-encrypt-decrypt/)). If you meant to +encrypt for a person, click **Cancel** and tick their key first. + +::: + +### Decrypt a File + +You need **your private key**. + +1. **Select the encrypted file** in the File Panel, for example + `report.pdf.gpg`. +2. **Click Decrypt.** You do not need to tick a key. GpgFrontend finds the + right one. +3. **Enter your passphrase** when asked. +4. **Find the new file.** It appears in the same folder, with `.gpg` (or + `.asc`) taken off the end: `report.pdf`. If the name has no such ending, + GpgFrontend adds `.out` instead. + +If the file was also signed, use **Decrypt & Verify** from the **Operations** +menu (or the **Decrypt** button's list) to check the signature at the same +time. + ![][img-4] +### Sign a File + +Signing makes a small, separate signature file. The original file stays as it +is. You send both files together. You need **your private key**. + +1. **Select the file** in the File Panel. +2. **Pick your key.** In the **Key ToolBox**, tick the box in front of **your + own** key. If you tick no key, GpgFrontend shows **No Key Checked** and + stops. +3. **Click Sign.** +4. **Enter your passphrase** when asked. +5. **Find the signature file.** It appears next to the original, for example + `report.pdf.sig`. +6. **Send both files**: `report.pdf` and `report.pdf.sig`. Keep their names as + they are. + +:::caution + +After signing, do not change the original file, not even by saving it again +without edits. If it changes, the signature no longer matches. + +::: + +### Verify a File + +You need **the sender's public key**, and both files: the original and its +signature. + +1. **Put both files in the same folder**, with their names unchanged, for + example `report.pdf` and `report.pdf.sig`. +2. **Select the signature file** (`report.pdf.sig` or `report.pdf.asc`) in the + File Panel. Select the signature, not the original. +3. **Click Verify.** You do not need to tick a key. +4. **Read the result** in the **Status Panel**: green means the file is + unchanged and signed by the key shown; red means it was changed or the + signature does not match. + +GpgFrontend finds the original by taking `.sig` or `.asc` off the signature's +name. If it cannot find that file, a window called **File to be Verified** +asks for the full path of the original: + +- Type or paste the full path to the original file and click **OK**. +- Leave the box **empty** and click **OK** if the file you selected holds the + data and the signature together in one file. + +If you select a `.gpg` or `.pgp` file, GpgFrontend treats it as one file that +holds both the data and the signature. + +If the sender's public key is missing, the **Missing Keys** window opens. See +[If the Sender's Key Is Missing](/guides/text-operations/#if-the-senders-key-is-missing). + ## Drag and Drop Files The File Panel supports drag-and-drop, an easy way to bring files into your diff --git a/src/content/docs/guides/text-operations.md b/src/content/docs/guides/text-operations.md index abf63b5..df3a042 100644 --- a/src/content/docs/guides/text-operations.md +++ b/src/content/docs/guides/text-operations.md @@ -24,25 +24,67 @@ So before you begin, [make your own key pair](/guides/generate-key/) and swap public keys with the people you write to. You encrypt with their public key; they decrypt with their private key. +## Find the Buttons + +Every task on this page works on the text in the current **Text Editor** tab. +You can start each task in three ways. They all do the same thing: + +| Task | Toolbar button | **Operations** menu | Shortcut | +| ------------------ | -------------------------------- | -------------------- | ------------ | +| Encrypt | **Encrypt** | **Encrypt** | Ctrl+E | +| Encrypt and sign | in the **Encrypt** button's list | **Encrypt & Sign** | Ctrl+Shift+E | +| Decrypt | **Decrypt** | **Decrypt** | Ctrl+D | +| Decrypt and verify | in the **Decrypt** button's list | **Decrypt & Verify** | Ctrl+Shift+D | +| Sign | **Sign** | **Sign** | Ctrl+Shift+I | +| Verify | **Verify** | **Verify** | Ctrl+Shift+V | + +On macOS, press Cmd instead of Ctrl. + +To see a button's list, right-click the button, or press and hold it. See +[Buttons With More Than One Action](/guides/understand-interface/#buttons-with-more-than-one-action). + +To pick a key, tick the box in front of it in the **Key ToolBox**, the key list +on the right side of the main window. + ## Encrypt Text -To hide a message so only one person can read it, encrypt it with **their public -key**. Only their private key can open it. +Encrypting hides a message so that only the person you write to can read it. +You need **their public key** in your key list. -This way: +1. **Open a text tab.** Click **File**, then **Workspace**, then + **New Text Editor** (or press Ctrl+N). A new, empty tab opens. +2. **Write your message.** Type it, or paste it in. +3. **Pick the recipient.** In the **Key ToolBox**, tick the box in front of the + person's public key. To send to several people, tick each of their keys. +4. **Click Encrypt.** Or press Ctrl+E. +5. **Answer any questions.** GpgFrontend may stop to check your recipients, for + example when a key has expired. See [Checks Before Encrypting](#checks-before-encrypting). +6. **See the result.** The text in the tab is replaced by a block that starts + with `-----BEGIN PGP MESSAGE-----`. The **Status Panel** at the bottom shows + whether it worked. +7. **Send it.** Copy the whole block, from the `BEGIN` line to the `END` line, + and paste it into your email or chat. Or save it with **File**, **Save**. -- The result is short. -- It does **not** reveal who sent it, which is good when you want to stay - anonymous. +![][img-2] + +:::caution + +If you tick **no key at all** and click **Encrypt**, GpgFrontend does not stop. +It asks you for a password instead and encrypts with that. This is called +[symmetric encryption](/guides/symmetric-encrypt-decrypt/). If you meant to +encrypt for a person, click **Cancel** and tick their key first. + +::: :::tip -Don't encrypt with your own public key unless the message is meant for you. Use -the recipient's public key, or only you will be able to read it. +Tick your **own** key too if you want to be able to read the message later. +Without it, only the recipient can open it, not you. ::: -![][img-2] +The encrypted message does not show who sent it. If you also want to prove that +it came from you, use [Encrypt and Sign](#encrypt-and-sign-at-once). ### If You Are Asked to Pick a Subkey @@ -68,45 +110,143 @@ more than one person. See [Encryption Safety](/guides/encryption-safety/). ## Decrypt Text -To read an encrypted message sent to you, paste or load the ciphertext into -GpgFrontend. The tool then: - -- Picks the correct **private key** for you. -- Tells you if it can't find a matching key. +Decrypting turns an encrypted message sent to you back into readable text. You +need **your private key**, the one that matches the public key the sender used. -You don't need to choose a key by hand. GpgFrontend matches it for you. +1. **Open a text tab.** Click **File**, then **Workspace**, then + **New Text Editor** (or press Ctrl+N). +2. **Paste the message.** Paste the whole block, including the + `-----BEGIN PGP MESSAGE-----` and `-----END PGP MESSAGE-----` lines. +3. **Click Decrypt.** Or press Ctrl+D. You do **not** need to tick any key. + GpgFrontend finds the right private key by itself. +4. **Enter your passphrase.** A window asks for the passphrase that protects + your private key. Type it and confirm. +5. **Read the message.** The block in the tab is replaced by the readable text. + The **Status Panel** shows whether it worked. ![][img-3] -## Sign Text +If it fails, the **Status Panel** turns red and says why. The most common +reasons: + +- **You don't have the right private key.** The message was encrypted for + someone else, or for a key you no longer have. +- **Part of the block is missing.** Copy the message again, from the very first + `-----BEGIN` line to the very last `-----END` line. +- **The message was changed on the way.** GpgFrontend will not show text it + cannot trust. See [Encryption Safety](/guides/encryption-safety/). + +:::note + +If the message was also signed, the plain **Decrypt** does not check the +signature. Use [Decrypt and Verify](#decrypt-and-verify-at-once) instead. -To prove a message came from you, sign it with **your private key**. The text stays -readable; signing adds proof, not secrecy. +::: + +## Sign Text -- It confirms you wrote it. -- Anyone with your public key can check it. +Signing proves that a message came from you and that nobody changed it. It does +**not** hide the message: anyone can still read it. You need **your private +key**. -Before you sign, look at the key's `Usage` column for an `S`, which means the key -can sign. +1. **Open a text tab** and write your message. +2. **Pick your key.** In the **Key ToolBox**, tick the box in front of **your + own** key. Pick a key that can sign: its **Usage** column shows an `S`. +3. **Click Sign.** Or press Ctrl+Shift+I. +4. **Choose a key, if asked.** If you ticked no key that can sign, or your key + has more than one signing subkey, a window called **Select Signing Key(s)** + opens. Tick the key or subkey to use and click **Confirm**. +5. **Enter your passphrase.** Type the passphrase of your private key. +6. **See the result.** Your text now sits between two lines: + `-----BEGIN PGP SIGNED MESSAGE-----` at the top and a + `-----BEGIN PGP SIGNATURE-----` block at the bottom. Your message stays + readable in the middle. +7. **Send it.** Copy everything, from the first `-----BEGIN` line to the last + `-----END` line, and send it. ![][img-4] +:::caution + +After signing, do not change anything in the text, not even a space or an empty +line. Any change, however small, makes the signature fail. + +::: + ## Verify a Signature -To check that a signed message is genuine, use the **sender's public key**. Paste -or load the signed message, and GpgFrontend will: +Verifying checks that a signed message really came from the person it claims, +and that nobody changed it. You need **the sender's public key** in your key +list. -- Check that the message wasn't changed. -- Report any mismatch or a missing public key. +1. **Open a text tab.** Click **File**, then **Workspace**, then + **New Text Editor** (or press Ctrl+N). +2. **Paste the signed message.** Paste all of it, from + `-----BEGIN PGP SIGNED MESSAGE-----` down to `-----END PGP SIGNATURE-----`. +3. **Click Verify.** Or press Ctrl+Shift+V. You do not need to tick any key. +4. **Read the result in the Status Panel.** + - **Green**: the signature is good. The message is unchanged and was signed + by the key shown. + - **Orange**: the signature is good, but there is something to check, for + example a key you have not marked as trusted. + - **Red**: the signature is bad. The message was changed, or it was not + signed by that key. Do not trust it. -:::note +The text in the tab is not changed when you verify. + +![][img-5] + +### If the Sender's Key Is Missing + +If you don't have the sender's public key, a window called **Missing Keys** +opens. It lists the fingerprints of the missing keys and asks whether to fetch +them from the key server. + +- Click **Yes** to search the key server for the key. +- Click **No** to stop. You can + [import the key](/guides/import-export-key-pair/) yourself and verify again. -If you don't have the sender's public key yet, GpgFrontend asks you to import it -first. +:::tip + +Check the name and fingerprint shown in the result against what you know about +the sender. A good signature only proves the message matches **that** key. It +does not prove the key belongs to the person you think. ::: -![][img-5] +## Encrypt and Sign at Once + +This makes a message that is both **secret** and **proven to be from you**. It is +the best choice for private messages. + +1. **Open a text tab** and write your message. +2. **Pick the recipient.** Tick the box in front of the recipient's public key + in the **Key ToolBox**. +3. **Start it.** Open the **Operations** menu and choose **Encrypt & Sign**, or + press Ctrl+Shift+E. On the toolbar, it is in the **Encrypt** button's list. +4. **Choose your signing key.** The **Select Signing Key(s)** window always + opens here. Tick **your own** key and click **Confirm**. +5. **Enter your passphrase.** +6. **See the result.** The text becomes a `-----BEGIN PGP MESSAGE-----` block, + just like normal encryption. The signature is hidden inside it. + +Unlike plain **Encrypt**, this one needs at least one ticked recipient key. + +## Decrypt and Verify at Once + +Use this when you receive a message that was encrypted **and** signed. + +1. **Paste the message** into a text tab. +2. **Start it.** Open the **Operations** menu and choose **Decrypt & Verify**, + or press Ctrl+Shift+D. On the toolbar, it is in the **Decrypt** button's + list. +3. **Enter your passphrase.** +4. **Read the result.** The readable text appears in the tab. The **Status + Panel** shows both results: whether decryption worked, and whether the + signature is good. + +If the sender's public key is missing, the same **Missing Keys** window opens as +when you [verify](#if-the-senders-key-is-missing). ## Your Text Is Kept Exactly as Typed |