diff options
Diffstat (limited to 'src/content/docs/guides/key-server-operations.md')
| -rw-r--r-- | src/content/docs/guides/key-server-operations.md | 345 |
1 files changed, 194 insertions, 151 deletions
diff --git a/src/content/docs/guides/key-server-operations.md b/src/content/docs/guides/key-server-operations.md index 6c3a186..86ed472 100644 --- a/src/content/docs/guides/key-server-operations.md +++ b/src/content/docs/guides/key-server-operations.md @@ -2,165 +2,208 @@ title: Key Server Operations --- -Key servers play a pivotal role in the ecosystem of encrypted communication, -serving as a centralized repository for public key information. These servers -enable individuals to share and retrieve public keys necessary for encrypted -messaging, even when direct exchange is not feasible. Key servers are -particularly useful in scenarios where secure communication needs to be -established without prior direct contact, or when a user's public key needs to -be widely distributed or updated due to security concerns. - -When you wish to send an encrypted message but lack the recipient's public key, -key servers offer a solution by allowing you to search for and retrieve the -public key associated with the recipient's email address or key ID. This process -facilitates the encryption of messages in a way that ensures only the intended -recipient, who possesses the corresponding private key, can decrypt and read the -message. - -Moreover, key servers are integral to maintaining the integrity and -trustworthiness of the public key infrastructure. If a user's private key is -compromised, it is crucial to inform others not to use the associated public key -for encrypting messages anymore. By uploading a new public key to a key server -and marking the old one as obsolete or compromised, users can mitigate the risks -associated with the exposure of their private key. - -The functionality of key servers is enhanced by software tools such as -GpgFrontend, which simplifies the process of managing public keys. With -GpgFrontend, users can effortlessly upload their public key to key servers, -search for other users' public keys using an email address or key ID, and import -these keys for use in encrypted communication. The software's user-friendly -interface enables these operations to be performed with just a few mouse clicks, -making encrypted communication more accessible to a broader audience. - -It is important to note that once public key information is uploaded to a key -server, it is propagated across a network of key servers worldwide, making it -available to anyone who searches for it. This wide distribution ensures that -encrypted communication can be established easily across different platforms and -geographical locations. However, users should be aware that public keys uploaded -to key servers cannot be deleted, emphasizing the importance of careful key -management. In situations where a key needs to be updated, such as when adding a -subkey to a key pair, the new key information can overwrite the old one on the -server, thus maintaining the security and relevance of the key information -available to the public. - -In summary, key servers are essential for the secure and efficient exchange of -encrypted messages, offering a reliable method for sharing and retrieving public -keys. They support the integrity of secure communications by facilitating the -widespread distribution of public keys and enabling users to update or replace -keys when necessary. - -## Import Public Key From Key Server - -In the main page or in the key manager's Import key operation mode, there is a -key server option. After selecting this option you can see such an interface. - - - -You can get a list of public keys associated with a key server by searching for -Key ID, fingerprint or email address via the search box. If there is a suitable -public key in the list, you can import it by double-clicking it. - - - -When the import is complete, you can check whether the public key is actually -imported through the pop-up window (no need to import when the local public key -is newer), and you can also check some brief information about the public key. - - - -It is important to note that the public key you import may have expired or been -revoked. You can check the status of the key by navigating to the category tab -in the key management interface. In addition to the search box, you may also -notice a drop-down box that allows you to choose which key server to retrieve -the public key information from. To modify or add to this list of candidate -servers, please refer to the last section of this document: Key server related -settings. - -## Export My Public Key To The Key Server - -If the current key pair has a master key, you have the option to publish the -public key information to a key server. It is important to note that in order to -avoid confusion, GpgFrontend requires the presence of a master key for this -action to be performed. This ensures that users are aware of what they are doing -and the function being performed. - -### How To Use - -You can find the entry of this operation through the operation tab of the key -pair detail interface, as shown in the following figure. - - - -Perform the operation by clicking Upload key pair to key server. Note that the -naming of operations here is a bit confusing, but this is where your public key -information (not your private key) will be uploaded. - -### Synchronize public key information from a key server - -Sometimes, before you perform an encryption operation, you want to know if the -public key you are using is still valid. At this point, you can get the latest -information about the key from the key server (if the public key server has -one). - -As above, you can find this action in the Actions tab of the key pair details -screen, as shown in the image below. - -GpgFrontend will upload the public key information to the default key server -you set. The private key information is not uploaded and should not be manually -uploaded anywhere by the user. - -Refer to the last section of this document on how to set the default key server. - - - -The "Synchronize key pair with key server" function allows for automatic -retrieval of public key information from the key server, which is then compared -with the local key information. After the operation is completed, a pop-up -window will appear indicating whether the key has actually been updated. It -should be noted that this operation is not possible if the private key exists -locally. This is because, in such a case, you already have the key pair and -should publish the latest information for the key pair instead of accepting -outdated information from the key server. +Key servers are essential components in the ecosystem of encrypted +communication, serving as centralized repositories for public key information. +They allow users to **share, retrieve, and update** public keys, making secure +communication possible even when direct key exchange is not feasible. -### Extra Information +Key servers are especially helpful when: +- You need to encrypt a message but don't have the recipient’s public key. +- You want to make your public key available for others to use. +- You need to **update or revoke** your public key in case of a compromise. -GpgFrontend automatically communicates with the default key server that you have -set to obtain the necessary information. You can refer to the last section of -this document to learn how to set the default key server. +GpgFrontend offers a convenient graphical interface for interacting with key +servers, making key search, import, export, and synchronization operations +straightforward for all users. -## Sync ALL Public Key +## 📥 Import Public Key From Key Server -This is an advanced function provided by GpgFrontend, it can synchronize all -your local public key information at one time, if you want to know, please read -[this document](/advanced/sync-all-public-keys). +To import a public key, go to the **Import Key** section in the main page or Key +Manager, and select the **Key Server** option. -## Key Server Related Settings + -If you want to set a list of key servers or a default key server, you can do so -by accessing the Settings interface and navigating to the Key Servers tab. Here, -you will find options for managing your key server candidate list and -determining which key server is set as the default. +### How to Import: +1. Choose a key server from the drop-down list. +2. Enter a **Key ID**, **Fingerprint**, or **Email Address** into the search + field. +3. Click **Search**. +4. If results are found, double-click a record to import the public key. - +> 💡 By default, the key server list includes recommended options such as: +> - `https://keys.openpgp.org` +> - `https://keyserver.ubuntu.com` +> +> These servers are **preloaded as initial suggestions** in GpgFrontend, but you +> can fully customize this list through the **Settings → Key Servers** +> interface. -To add a candidate key server to the list, simply enter the http or https -address of the key server you wish to add into the input box and click "Add". It -is strongly recommended that users use the https protocol to prevent -man-in-the-middle attacks. If you wish to delete a candidate key server, simply -right-click on the corresponding row in the table and select "Delete" from the -pop-up menu. To edit an existing candidate key server address, double-click on -the address in the table and edit it. +### After Importing -To test the network connectivity of the servers in the key server candidate -list, click the "Test" button located at the bottom of the Key Servers tab. -However, note that the test only determines if the keyserver is reachable, not -whether the address is a valid keyserver. +Once a key is imported: +- GpgFrontend will display a confirmation message. +- If a newer version of the key already exists locally, the import is skipped. -### Set Default Key Server +You can then verify: +- Key creation date +- UID and key ID +- Whether the key is expired or revoked (using Key Manager filters) -To set a candidate key server as your default key server, you can follow these -steps. First, locate the candidate key server you want to set as the default in -the table. Then, right-click the row of the corresponding key server, and click -"Set as Default" in the pop-up menu. Once set, you can verify whether a -candidate key server is the default key server by checking the first column of -the table. +## 📤 Export My Public Key to Key Server + +To publish your public key: + +1. Open the **Key Details** interface for your key pair. +2. Go to the **Operations** tab. +3. Click **“Upload key pair to key server”**. + + + +> ⚠️ GpgFrontend only allows uploading if a **master key** is present to prevent +> accidental publishing of incomplete keys. + +Note: +- Only **public key** data is uploaded. +- Private keys are **never** uploaded. + +## 📤 Export My Public Key to Key Server + +GpgFrontend allows you to upload your public key to a key server, making it +discoverable for others who wish to send you encrypted messages. + +After v2.1.6, **GpgFrontend uses +[https://keys.openpgp.org](https://keys.openpgp.org)** for exporting public keys +by default. This server uses the **Verifying Keyserver (VKS) Interface**, which +provides extra protection against spam and key poisoning. + +### Key Points: +- 🔐 **Only public keys are uploaded**, never private keys. +- ✅ **Master key is required** to export. +- ✉️ `keys.openpgp.org` requires email verification before your key becomes + publicly searchable. +- 🧱 Uploaded keys are **propagated through the VKS protocol** and cannot be + deleted. + +To export: +1. Open the **Key Details** interface. +2. Go to the **Operations** tab. +3. Click **“Upload key pair to key server”**. + + + +## 🔄 Synchronize Public Key Information + +If you want to ensure that your local key matches what is available on the key +server, use the **“Synchronize key pair with key server”** feature. + +Like exporting, after v2.1.6, this operation also uses +**https://keys.openpgp.org** and its **VKS API**. + +GpgFrontend will: +- Query the key server using your key’s fingerprint. +- Compare the server copy with your local one. +- Indicate if any update is applied. + +> ⚠️ Synchronization is **not available** if you have the private key locally. +> In this case, you are expected to **publish** updates, not pull them. + +## ⚙️ Key Server Related Settings + +You can configure your key server preferences in: + +> **Settings → Key Servers** + + + +### Features: +- **Add a Server**: Enter the `https://` or `http://` address and click **Add**. +- **Edit a Server**: Double-click an address to edit it. +- **Delete a Server**: Right-click a row and select **Delete**. +- **Test Connection**: Click **Test** to check if the server is reachable. + +> ✅ **Recommended**: Always use HTTPS to prevent man-in-the-middle attacks. + +### 🌐 Set Default Key Server + +To set a key server as your **default** for public key **search/import** +operations: + +1. Right-click the desired server in the list. +2. Select **“Set as Default”**. +3. The default server will be marked in the first column of the table. + +> ⚠️ **Important (v2.1.6 and later)**: +> +> Setting a default key server **only affects key searches/imports**. +> +> - **Export** and **Sync** operations are no longer affected by this setting. +> - These operations **always use `https://keys.openpgp.org`**, which implements +> the Verifying Keyserver (VKS) API. +> +> This behavior ensures improved security and global consistency in public key +> management. + +## Tips about Key Servers + +| Key Server | Fuzzy Search | VKS Interface | Notes | +|-------------------------|--------------|---------------|-------------------------------------------| +| `keys.openpgp.org` | ❌ No | ✅ Yes | Requires exact match (email, fingerprint) | +| `keyserver.ubuntu.com` | ✅ Yes | ❌ No | Traditional HKP server, less strict | + +> 🔎 `keys.openpgp.org` does **not** support fuzzy search — you must use the +> **exact email**, **full fingerprint**, or **full key ID**. + +> ⚠️ **Don't confuse search servers with export/sync servers** — even if you +> perform key searches using a custom server like `keyserver.ubuntu.com`, +> **Export** and **Sync** operations will still use `keys.openpgp.org` by +> default in **GpgFrontend v2.1.6 and later**. + +> 🛠️ **Want to restore previous behavior?** +> You can disable the `KeyServerSync` module in the advanced settings. +> This will prevent GpgFrontend from forcing export/sync operations to use +> `keys.openpgp.org`, allowing custom server logic to take effect again. + +## 🔍 Automatically Check Key Publish Status + +GpgFrontend v2.1.6 introduces a feature that automatically checks whether your +public key has been published on [keys.openpgp.org](https://keys.openpgp.org), +helping users keep track of their key visibility on the VKS-based keyserver. + +### ✅ Feature Overview + +- When enabled, GpgFrontend will fetch the **publish status** of a key from the + key server. +- If the key is found to be published on `keys.openpgp.org`, a message like the + following will be shown in the **Key Details** tab: + + + +### ⚙️ How to Enable + +To activate this: + +1. Go to `Settings → Network` tab. +2. Under **Network Ability**, check the box: + - ✅ **Automatically fetch key publish status from key server** +3. Restart GpgFrontend to apply the change. + + + +### ⚠️ Important Notes + +- This feature **only works with `keys.openpgp.org`**, which supports the + **Verifying Keyserver (VKS) API**. +- If the `KeyServerSync` plugin is **disabled**, the publish status will **not + be fetched**, and no notice will appear in the UI. +- It is purely a **read-only status check**, and does not modify or upload + anything to the server. + +## 🔒 Final Notes + +- Public keys uploaded to key servers are **distributed globally** and **cannot + be deleted**. +- Always verify imported keys before using them. +- Maintain proper key hygiene: revoke and update keys when compromised. +- Never upload private key material to any server.
\ No newline at end of file |