diff options
| author | saturneric <[email protected]> | 2025-06-27 23:10:23 +0000 |
|---|---|---|
| committer | saturneric <[email protected]> | 2025-06-27 23:10:23 +0000 |
| commit | 182ac96e4eec9504ab1fa85bf3a1b7293199d8e2 (patch) | |
| tree | 8ad194489e224cee58b5f0a9df9787ee3db6db96 | |
| parent | docs(guides): add comprehensive guide for understanding GpgFrontend interface... (diff) | |
| download | Manual-182ac96e4eec9504ab1fa85bf3a1b7293199d8e2.tar.gz Manual-182ac96e4eec9504ab1fa85bf3a1b7293199d8e2.zip | |
docs(advanced): add detailed documentation for Multi-Key Database and KeyPackage features
| -rw-r--r-- | src/content/docs/advanced/key-database.mdx (renamed from src/content/docs/advanced/key-database.md) | 40 | ||||
| -rw-r--r-- | src/content/docs/advanced/key-package.mdx (renamed from src/content/docs/advanced/key-package.md) | 73 | ||||
| -rw-r--r-- | src/content/docs/advanced/module-controller.md | 4 | ||||
| -rw-r--r-- | src/content/docs/advanced/sync-public-keys.md | 26 |
4 files changed, 84 insertions, 59 deletions
diff --git a/src/content/docs/advanced/key-database.md b/src/content/docs/advanced/key-database.mdx index ebec9d5..aba43e4 100644 --- a/src/content/docs/advanced/key-database.md +++ b/src/content/docs/advanced/key-database.mdx @@ -5,23 +5,23 @@ sidebar: order: 2 --- +import { Steps } from "@astrojs/starlight/components"; + GpgFrontend introduces **Multi-Key Database Support**, providing users with a flexible and organized way to manage multiple key databases. This feature is ideal for users who require separate cryptographic environments for different projects, organizations, or levels of security. -## Features and Benefits - -### Key Features +## Features -1. **Multiple Key Databases**: Manage distinct key databases for specific - purposes or contexts. -2. **Flexible Switching**: Easily switch between databases for different - operations without affecting other configurations. -3. **Customizable Management**: Add, edit, reorder, or remove databases as - needed. +- **Multiple Key Databases**: Manage distinct key databases for specific + purposes or contexts. +- **Flexible Switching**: Easily switch between databases for different + operations without affecting other configurations. +- **Customizable Management**: Add, edit, reorder, or remove databases as + needed. -### Benefits +## Benefits - **Improved Security**: Isolate sensitive keys in dedicated databases to minimize exposure. @@ -34,19 +34,19 @@ projects, organizations, or levels of security. To manage multiple key databases, follow these steps: -### Access the Advanced Menu +<Steps> -- Click on the **Advanced** menu in the top navigation bar. -- Select **Open GnuPG Controller** from the dropdown options. +1. Click on the **Advanced** menu in the top navigation bar. - +2. Select **Open GnuPG Controller** from the dropdown options. +  -### Navigate to the Key Database Tab +3. In the **GnuPG Controller** window, switch to the **Key Database** tab. -- In the **GnuPG Controller** window, switch to the **Key Database** tab. -- Here, you will find a list of all configured key databases. +4. Here, you will find a list of all configured key databases. +  - +</Steps> ## Managing Key Databases @@ -68,14 +68,14 @@ database paths remain valid and consistent regardless of the host environment. Right-click on a database entry to view options like: + + - **Move Up/Move Down**: Reorder the database list. - **Move to Top**: Prioritize a database by moving it to the top. If a database is at the top, it is considered as the Default Key Database. - **Edit**: Rename or modify the path of an existing database. - **Remove**: Delete a database from the configuration. - - :::caution Any changes to the key database settings will require an application diff --git a/src/content/docs/advanced/key-package.md b/src/content/docs/advanced/key-package.mdx index a841b66..72e72ed 100644 --- a/src/content/docs/advanced/key-package.md +++ b/src/content/docs/advanced/key-package.mdx @@ -5,22 +5,26 @@ sidebar: order: 3 --- +import { Steps, Aside } from "@astrojs/starlight/components"; + The KeyPackage feature is designed to securely package and transfer key data—including both public and private keys—between devices. This enables users to maintain their cryptographic identities across platforms. Starting from version 2.1.9, KeyPackage functionality has been significantly enhanced to improve security, encryption strength, and user control. -> Important: KeyPackages created with v2.1.9 and later are not compatible with -> those created in previous versions. +<Aside type="caution"> + KeyPackages created with v2.1.9 and later are not compatible with those + created in previous versions. +</Aside> ## Security Enhancements Since v2.1.9 -- Encryption Algorithm: KeyPackage data is now encrypted with AES-256-GCM - (authenticated encryption), providing both confidentiality and integrity - protection. Earlier versions used AES-256-ECB, which lacks integrity checking. +KeyPackage data is now encrypted with AES-256-GCM (authenticated encryption), +providing both confidentiality and integrity protection. Earlier versions used +AES-256-ECB, which lacks integrity checking. -Key Generation: +### Key Generation - The encryption key for the KeyPackage is generated using GnuPG’s built-in random number generator through the GPG interface. @@ -28,12 +32,11 @@ Key Generation: random generator. - Prior to v2.1.9, QRandom was used for key generation, providing weaker security guarantees. +- KeyPackage names are now generated in the format `KeyPackage_<zbase>`, where + `<zbase>` is a strong random identifier encoded in zbase32. Previous versions + used a numeric format such as `KeyPackage_41132`. -Naming Convention: KeyPackage names are now generated in the format -KeyPackage\_<zbase>, where <zbase> is a strong random identifier encoded in -zbase32. Previous versions used a numeric format such as KeyPackage_41132. - -PIN Protection: +### PIN Protection - After generating the KeyPackage, users are required to set a PIN. The actual KeyPackage encryption key is then encrypted with this PIN using modern @@ -47,15 +50,17 @@ PIN Protection: To create a KeyPackage, follow these steps: +<Steps> + 1. **Open the Key Management Interface**: Navigate to the main interface where you manage your keys. - 2. **Export Keys**: Click on the "Export Key" button to initiate the export process. - 3. **Choose KeyPackage Export**: Select the option to export keys as a KeyPackage. This will open a new dialog box for configuring the KeyPackage. +  + 4. **Configure KeyPackage**: - **KeyPackage Name**: In the first field, you will see a generated name for @@ -68,6 +73,8 @@ To create a KeyPackage, follow these steps: later be prompted to provide a PIN; make sure it is strong and confidential. +  + 5. **Optional Settings**: - **Include Secret Keys**: Check the box labeled "Include secret key (Think @@ -80,6 +87,8 @@ To create a KeyPackage, follow these steps: 6. **Export**: Once all settings are configured and reviewed, click the "OK" button to create and export the KeyPackage. +</Steps> + By following these steps, you can create a secure KeyPackage to transfer your cryptographic keys between devices. @@ -108,21 +117,29 @@ To transfer the KeyPackage: To import the KeyPackage after transferring it to the target device, follow these steps: - - -- **Initiate Import**: Open the key management tool on the target device and - click on the "Import Key" button. -- **Select KeyPackage Option**: As shown in the image, from the dropdown menu, - select the "Key Package" option. This indicates that you will be importing a - KeyPackage. -- **Select KeyPackage File**: A file selection dialog will appear. First, choose - the `.gpgpack` file that you transferred. This file contains the packaged keys. -- **Select Key File**: After selecting the `.gpgpack` file, another file - selection dialog will prompt you to choose the corresponding key file. This key - file is used to decrypt the KeyPackage. -- **Enter PIN**: You will be prompted for the PIN that was set during KeyPackage - creation. -- **Import**: Once the correct PIN is entered, your keys will be imported. +<Steps> + +1. **Initiate Import**: Open the key management tool on the target device and + click on the "Import Key" button. + +2. **Select KeyPackage Option**: As shown in the image, from the dropdown menu, + select the "Key Package" option. This indicates that you will be importing a + KeyPackage. +  + +3. **Select KeyPackage File**: A file selection dialog will appear. First, choose + the `.gpgpack` file that you transferred. This file contains the packaged keys. + +4. **Select Key File**: After selecting the `.gpgpack` file, another file + selection dialog will prompt you to choose the corresponding key file. This key + file is used to decrypt the KeyPackage. + +5. **Enter PIN**: You will be prompted for the PIN that was set during KeyPackage + creation. + +6. **Import**: Once the correct PIN is entered, your keys will be imported. + +</Steps> By following these steps, you can securely import your cryptographic keys from the KeyPackage into the key management tool on the target device. diff --git a/src/content/docs/advanced/module-controller.md b/src/content/docs/advanced/module-controller.md index db7782c..c7eea25 100644 --- a/src/content/docs/advanced/module-controller.md +++ b/src/content/docs/advanced/module-controller.md @@ -33,7 +33,7 @@ The **Module Controller** interface consists of the following tabs: The **Registered Modules** tab displays all available modules and provides tools for managing their activation, metadata, and storage. - + ### Key Features @@ -109,7 +109,7 @@ gpgme: **Navigation**: Expand nodes to explore detailed properties for modules or core components. - + ## Developing Custom Modules diff --git a/src/content/docs/advanced/sync-public-keys.md b/src/content/docs/advanced/sync-public-keys.md index 4c4b4d1..07d19a4 100644 --- a/src/content/docs/advanced/sync-public-keys.md +++ b/src/content/docs/advanced/sync-public-keys.md @@ -41,7 +41,7 @@ user-friendly interface. Here’s how to use it: your possession against the key server. If there is an updated version of a key you own, GpgFrontend will import the new details to your local keyring. - + By following these steps, you can ensure that your public keys are always up-to-date, enhancing the security and reliability of your cryptographic @@ -54,14 +54,7 @@ To know which key server GpgFrontend interacts with, follow these steps: 1. Go to the settings section of GpgFrontend. 2. The default key server configured will be listed here. - - -:::tip - -Replace the placeholder text with the actual link to the image showing -the key server settings. - -::: + If you need to use a different key server: @@ -69,6 +62,21 @@ If you need to use a different key server: 2. Add your preferred key server's details. 3. Set it as the default for future synchronizations. +:::caution[Changes (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. + +Or: [Want to restore previous behavior?](/guides/key-server-operations/#want-to-restore-previous-behavior) + +::: + ## Best Practices for Key Synchronization - **Regular Sync:** Regularly sync your keys to ensure you have the latest |