From 182ac96e4eec9504ab1fa85bf3a1b7293199d8e2 Mon Sep 17 00:00:00 2001
From: saturneric <eric@bktus.com>
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-package.mdx | 169 ++++++++++++++++++++++++++++++
 1 file changed, 169 insertions(+)
 create mode 100644 src/content/docs/advanced/key-package.mdx

(limited to 'src/content/docs/advanced/key-package.mdx')

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.
+
+<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
+
+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_<zbase>`, where
+  `<zbase>` 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:
+
+<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_<zbase>`. 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.
+
+</Steps>
+
+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:
+
+<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.
+
+</Steps>
+
+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.
-- 
cgit v1.2.3

