1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
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.
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.
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.
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.
|
