From 182ac96e4eec9504ab1fa85bf3a1b7293199d8e2 Mon Sep 17 00:00:00 2001 From: saturneric Date: Sat, 28 Jun 2025 01:10:23 +0200 Subject: docs(advanced): add detailed documentation for Multi-Key Database and KeyPackage features --- src/content/docs/advanced/key-database.md | 115 ----------------- src/content/docs/advanced/key-database.mdx | 115 +++++++++++++++++ src/content/docs/advanced/key-package.md | 152 ---------------------- src/content/docs/advanced/key-package.mdx | 169 +++++++++++++++++++++++++ src/content/docs/advanced/module-controller.md | 4 +- src/content/docs/advanced/sync-public-keys.md | 26 ++-- 6 files changed, 303 insertions(+), 278 deletions(-) delete mode 100644 src/content/docs/advanced/key-database.md create mode 100644 src/content/docs/advanced/key-database.mdx delete mode 100644 src/content/docs/advanced/key-package.md create mode 100644 src/content/docs/advanced/key-package.mdx diff --git a/src/content/docs/advanced/key-database.md b/src/content/docs/advanced/key-database.md deleted file mode 100644 index ebec9d5..0000000 --- a/src/content/docs/advanced/key-database.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Multi-Key Database Support -sidebar: - label: Multi-Key Database - order: 2 ---- - -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 - -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. - -### Benefits - -- **Improved Security**: Isolate sensitive keys in dedicated databases to - minimize exposure. -- **Enhanced Organization**: Maintain separate databases for better operational - clarity. -- **Streamlined Workflows**: Quickly switch between databases for various - projects or encryption tasks. - -## Accessing the Multi-Key Database Feature - -To manage multiple key databases, follow these steps: - -### Access the Advanced Menu - -- Click on the **Advanced** menu in the top navigation bar. -- Select **Open GnuPG Controller** from the dropdown options. - -![](https://image.cdn.bktus.com/i/2024/11/29/abfaa919-2945-1acc-eb35-5c86828a97ca.webp) - -### Navigate 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. - -![](https://image.cdn.bktus.com/i/2025/06/24/2a5cefe92a56b851de8ecd1661961592a7d3bc6c.webp) - -## Managing Key Databases - -The Key Database tab allows you to perform the following operations: - -### Adding a New Key Database - -- Click the Add New Key Database button. -- Specify a name and path for the new database. This will create an isolated - environment for newly generated or imported keys. - -**Relative Path Support:** If you enable the Relative Path option, the specified -absolute path will be automatically converted to a path relative to the -GpgFrontend application directory. This is particularly useful for Portable Mode -or when moving the application between different systems, as it ensures that key -database paths remain valid and consistent regardless of the host environment. - -### Editing and Reordering Key Databases - -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. - -![](https://image.cdn.bktus.com/i/2025/06/24/a012d736e4b116feb45d3c6af3e1b39ce8124c4f.webp) - -:::caution - -Any changes to the key database settings will require an application -restart to take effect. - -::: - -### Switching Between Databases - -- Use the **Key Toolbox** dropdown in the main interface to switch between - configured databases. -- Select the desired database, and the corresponding keys will be displayed. - -![](https://image.cdn.bktus.com/i/2024/11/29/dd783ee0-df5e-2b6f-428f-784c68246186.webp) - -## Use Cases for Multi-Key Databases - -- Project Isolation: Maintain separate databases for different projects to - avoid accidental cross-use of keys. -- Organizational Separation: Keep departmental or team-specific keys isolated - to ensure they are only accessible to authorized personnel. -- Enhanced Security for Sensitive Keys: Store high-security keys in a dedicated - database, minimizing the risk of exposure during routine operations. - -## Tips for Effective Multi-Key Database Usage - -- Name Databases Clearly: Use descriptive names for each database to make it - easier to identify their purpose. -- Regular Backups: Backup each database regularly to prevent loss of critical - keys. Store backups in secure, encrypted locations. -- Audit Database Usage: Periodically review the contents and usage of each - database to ensure proper organization and security. -- Isolate Sensitive Operations: For highly sensitive keys, consider using a - dedicated device or environment to manage their database. -- Avoid Overloading Databases: Distribute keys evenly across multiple databases - instead of overloading a single one. This enhances performance and - organization. diff --git a/src/content/docs/advanced/key-database.mdx b/src/content/docs/advanced/key-database.mdx new file mode 100644 index 0000000..aba43e4 --- /dev/null +++ b/src/content/docs/advanced/key-database.mdx @@ -0,0 +1,115 @@ +--- +title: Multi-Key Database Support +sidebar: + label: Multi-Key Database + 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 + +- **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 + +- **Improved Security**: Isolate sensitive keys in dedicated databases to + minimize exposure. +- **Enhanced Organization**: Maintain separate databases for better operational + clarity. +- **Streamlined Workflows**: Quickly switch between databases for various + projects or encryption tasks. + +## Accessing the Multi-Key Database Feature + +To manage multiple key databases, follow these steps: + + + +1. Click on the **Advanced** menu in the top navigation bar. + +2. Select **Open GnuPG Controller** from the dropdown options. + ![](https://image.cdn.bktus.com/i/2024/11/29/abfaa919-2945-1acc-eb35-5c86828a97ca.webp) + +3. In the **GnuPG Controller** window, switch to the **Key Database** tab. + +4. Here, you will find a list of all configured key databases. + ![](https://image.cdn.bktus.com/i/2025/06/24/2a5cefe92a56b851de8ecd1661961592a7d3bc6c.webp) + + + +## Managing Key Databases + +The Key Database tab allows you to perform the following operations: + +### Adding a New Key Database + +- Click the Add New Key Database button. +- Specify a name and path for the new database. This will create an isolated + environment for newly generated or imported keys. + +**Relative Path Support:** If you enable the Relative Path option, the specified +absolute path will be automatically converted to a path relative to the +GpgFrontend application directory. This is particularly useful for Portable Mode +or when moving the application between different systems, as it ensures that key +database paths remain valid and consistent regardless of the host environment. + +### Editing and Reordering Key Databases + +Right-click on a database entry to view options like: + +![](https://image.cdn.bktus.com/i/2025/06/24/a012d736e4b116feb45d3c6af3e1b39ce8124c4f.webp) + +- **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 +restart to take effect. + +::: + +### Switching Between Databases + +- Use the **Key Toolbox** dropdown in the main interface to switch between + configured databases. +- Select the desired database, and the corresponding keys will be displayed. + +![](https://image.cdn.bktus.com/i/2024/11/29/dd783ee0-df5e-2b6f-428f-784c68246186.webp) + +## Use Cases for Multi-Key Databases + +- Project Isolation: Maintain separate databases for different projects to + avoid accidental cross-use of keys. +- Organizational Separation: Keep departmental or team-specific keys isolated + to ensure they are only accessible to authorized personnel. +- Enhanced Security for Sensitive Keys: Store high-security keys in a dedicated + database, minimizing the risk of exposure during routine operations. + +## Tips for Effective Multi-Key Database Usage + +- Name Databases Clearly: Use descriptive names for each database to make it + easier to identify their purpose. +- Regular Backups: Backup each database regularly to prevent loss of critical + keys. Store backups in secure, encrypted locations. +- Audit Database Usage: Periodically review the contents and usage of each + database to ensure proper organization and security. +- Isolate Sensitive Operations: For highly sensitive keys, consider using a + dedicated device or environment to manage their database. +- Avoid Overloading Databases: Distribute keys evenly across multiple databases + instead of overloading a single one. This enhances performance and + organization. diff --git a/src/content/docs/advanced/key-package.md b/src/content/docs/advanced/key-package.md deleted file mode 100644 index a841b66..0000000 --- a/src/content/docs/advanced/key-package.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: KeyPackage Functionality -sidebar: - label: KeyPackage - order: 3 ---- - -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. - -## 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. - -Key Generation: - -- The encryption key for the KeyPackage is generated using GnuPG’s built-in - random number generator through the GPG interface. -- If GPG entropy is unavailable, the system falls back to OpenSSL’s secure - random generator. -- Prior to v2.1.9, QRandom was used for key generation, providing weaker - security guarantees. - -Naming Convention: KeyPackage names are now generated in the format -KeyPackage\_, where is a strong random identifier encoded in -zbase32. Previous versions used a numeric format such as KeyPackage_41132. - -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 - authenticated encryption. -- This means that, in addition to the KeyPackage file itself, a separate “key - file” is generated and must be kept together with the KeyPackage. Both are - required, along with the PIN, for a successful import. -- Without the correct PIN, the KeyPackage cannot be decrypted or used. - -## Creating a KeyPackage - -To create a KeyPackage, follow these 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 - the KeyPackage, such as `KeyPackage_`. You can click the button - labeled "Generate Key Package Name" to generate a new name if desired. - - **Output Path**: In the second field, click the button labeled "Select - Output Path" to choose where to save the KeyPackage file. - - **Passphrase**: In the third field, click the button labeled "Generate and - Save Passphrase" to generate and save a key for the KeyPackage. You will - 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 - twice before acting)" if you want to include private keys in the - KeyPackage. This is generally not recommended unless necessary. - - **Exclude Keys without Private Parts**: Check the box labeled "Exclude keys - that do not have a private key" to exclude keys that do not have associated - private keys. - -6. **Export**: Once all settings are configured and reviewed, click the "OK" - button to create and export the KeyPackage. - -By following these steps, you can create a secure KeyPackage to transfer your -cryptographic keys between devices. - -## Security Notice - -When the KeyPackage is successfully created, a message will inform you that the -package is protected with encryption algorithms (e.g., AES-256-GCM) and is safe -to transfer. - -Never disclose the KeyPackage or key file to untrusted parties. After transfer, -delete all copies from intermediate storage locations. - -## Transferring the KeyPackage - -To transfer the KeyPackage: - -1. Use a secure transfer method to move the `.gpgpack` file to the target - device. Use a secure transfer method (e.g., encrypted USB drive, encrypted - email, or a secure network channel) to move both the `.gpgpack` file and its - associated `.key` file to the target device. -2. Once transferred, import the KeyPackage into the key management tool on the - target device using the passphrase set during the creation process. - -## After Transfer: Importing - -To import the KeyPackage after transferring it to the target device, follow -these steps: - -![](https://image.cdn.bktus.com/i/2024/06/15/a086df66-bdac-74fb-9a2c-35cddd224564.webp) - -- **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. - -By following these steps, you can securely import your cryptographic keys from -the KeyPackage into the key management tool on the target device. - -## Compatibility Notice - -- KeyPackages created with v2.1.9 or later are not compatible with previous - versions. Attempting to import a v2.1.9 KeyPackage into an older GpgFrontend - release will fail. -- Legacy KeyPackages: If you need to migrate old KeyPackages, do so before - upgrading, or export and repackage your keys after upgrading to v2.1.9. - -## Security Notice - -- KeyPackage encryption is now much stronger, using modern, authenticated - cryptography and a PIN-protected key hierarchy. -- Both the `.gpgpack` file and its `.key` file are required for import, in - addition to your PIN. -- Always delete KeyPackage files and key files from all devices and - intermediaries after transfer is complete. - -## Best Practices - -- Always transfer key data via secure, encrypted channels. -- Choose a strong, unique PIN and do not share it. -- Delete all KeyPackage and key files after successful import, including any - backup or email attachments. diff --git a/src/content/docs/advanced/key-package.mdx b/src/content/docs/advanced/key-package.mdx new file mode 100644 index 0000000..72e72ed --- /dev/null +++ b/src/content/docs/advanced/key-package.mdx @@ -0,0 +1,169 @@ +--- +title: KeyPackage Functionality +sidebar: + label: KeyPackage + 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. + + + +## Security Enhancements Since v2.1.9 + +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 + +- The encryption key for the KeyPackage is generated using GnuPG’s built-in + random number generator through the GPG interface. +- If GPG entropy is unavailable, the system falls back to OpenSSL’s secure + 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_`, where + `` is a strong random identifier encoded in zbase32. Previous versions + used a numeric format such as `KeyPackage_41132`. + +### 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 + authenticated encryption. +- This means that, in addition to the KeyPackage file itself, a separate “key + file” is generated and must be kept together with the KeyPackage. Both are + required, along with the PIN, for a successful import. +- Without the correct PIN, the KeyPackage cannot be decrypted or used. + +## Creating a KeyPackage + +To create a KeyPackage, follow these 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. + + ![](https://image.cdn.bktus.com/i/2025/06/28/b0e9d21290681e6f61415b80ee51b90b47b1c04b.webp) + +4. **Configure KeyPackage**: + + - **KeyPackage Name**: In the first field, you will see a generated name for + the KeyPackage, such as `KeyPackage_`. You can click the button + labeled "Generate Key Package Name" to generate a new name if desired. + - **Output Path**: In the second field, click the button labeled "Select + Output Path" to choose where to save the KeyPackage file. + - **Passphrase**: In the third field, click the button labeled "Generate and + Save Passphrase" to generate and save a key for the KeyPackage. You will + later be prompted to provide a PIN; make sure it is strong and + confidential. + + ![](https://image.cdn.bktus.com/i/2025/06/28/0c304b476b436063970398593a82116029bc0e95.webp) + +5. **Optional Settings**: + + - **Include Secret Keys**: Check the box labeled "Include secret key (Think + twice before acting)" if you want to include private keys in the + KeyPackage. This is generally not recommended unless necessary. + - **Exclude Keys without Private Parts**: Check the box labeled "Exclude keys + that do not have a private key" to exclude keys that do not have associated + private keys. + +6. **Export**: Once all settings are configured and reviewed, click the "OK" + button to create and export the KeyPackage. + + + +By following these steps, you can create a secure KeyPackage to transfer your +cryptographic keys between devices. + +## Security Notice + +When the KeyPackage is successfully created, a message will inform you that the +package is protected with encryption algorithms (e.g., AES-256-GCM) and is safe +to transfer. + +Never disclose the KeyPackage or key file to untrusted parties. After transfer, +delete all copies from intermediate storage locations. + +## Transferring the KeyPackage + +To transfer the KeyPackage: + +1. Use a secure transfer method to move the `.gpgpack` file to the target + device. Use a secure transfer method (e.g., encrypted USB drive, encrypted + email, or a secure network channel) to move both the `.gpgpack` file and its + associated `.key` file to the target device. +2. Once transferred, import the KeyPackage into the key management tool on the + target device using the passphrase set during the creation process. + +## After Transfer: Importing + +To import the KeyPackage after transferring it to the target device, follow +these 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. + ![](https://image.cdn.bktus.com/i/2025/06/28/aec995410df49d0b532329a611ef68f10cd1885f.webp) + +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. + + + +By following these steps, you can securely import your cryptographic keys from +the KeyPackage into the key management tool on the target device. + +## Compatibility Notice + +- KeyPackages created with v2.1.9 or later are not compatible with previous + versions. Attempting to import a v2.1.9 KeyPackage into an older GpgFrontend + release will fail. +- Legacy KeyPackages: If you need to migrate old KeyPackages, do so before + upgrading, or export and repackage your keys after upgrading to v2.1.9. + +## Security Notice + +- KeyPackage encryption is now much stronger, using modern, authenticated + cryptography and a PIN-protected key hierarchy. +- Both the `.gpgpack` file and its `.key` file are required for import, in + addition to your PIN. +- Always delete KeyPackage files and key files from all devices and + intermediaries after transfer is complete. + +## Best Practices + +- Always transfer key data via secure, encrypted channels. +- Choose a strong, unique PIN and do not share it. +- Delete all KeyPackage and key files after successful import, including any + backup or email attachments. 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. -![](https://image.cdn.bktus.com/i/2024/11/29/b35d35f9-4ae2-0d3b-917d-a6fb815711f9.webp) +![](https://image.cdn.bktus.com/i/2025/06/28/543b81d81b4adf03f039aeca2176247b2a1be705.webp) ### Key Features @@ -109,7 +109,7 @@ gpgme: **Navigation**: Expand nodes to explore detailed properties for modules or core components. -![](https://image.cdn.bktus.com/i/2024/11/29/e4a74c1d-c81a-166f-abd8-4f3f4f92f4d0.webp) +![](https://image.cdn.bktus.com/i/2025/06/28/5a7e617a2d9f1a0efd3e939075c5074e1bd40043.webp) ## 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. -![](https://image.cdn.bktus.com/i/2024/06/15/8771cd76-1a46-321e-8bf9-93d8db2a9f78.webp) +![](https://image.cdn.bktus.com/i/2025/06/28/38eefac3220f864b5e4a1fe98681f8cef817ef21.webp) 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. -![](https://image.cdn.bktus.com/i/2024/06/15/03471d32-54f2-2be7-53a3-eeee03f74372.webp) - -:::tip - -Replace the placeholder text with the actual link to the image showing -the key server settings. - -::: +![](https://image.cdn.bktus.com/i/2025/06/28/86bc996c90eb449dee681a86be15797015128f5c.webp) 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 -- cgit v1.2.3