KeyPackage Functionality

A KeyPackage is an encrypted file that holds a set of your OpenPGP keys. Use it to move your keys safely from one computer to another, for example when you set up a new machine or want the same identity on a second device.

Two different files, two different jobs

GpgFrontend can save two kinds of file, and they are easy to mix up:

• A KeyPackage (.gfpack) carries keys. Use it when you only want to move keys.
• A profile file (.gfp) carries a whole setup: keys, settings and saved state together. See Profiles.

If you want your new computer to look and behave exactly like the old one, use a profile file. If you only want your keys, use a KeyPackage.

The Three Pieces You Need

When you create a KeyPackage, GpgFrontend produces two files, and you set one PIN. You need all three to import the keys later:

KeyPackage file (.gfpack)

Holds your keys, encrypted.

Key file (.key)

Holds the encryption key for the KeyPackage, itself protected by your PIN. It is saved next to the KeyPackage file, unless you choose another place, such as a separate drive.

PIN

You choose it during creation. Without it, the KeyPackage cannot be opened.

Keep this in mind before you start: if you lose any one of the three, the KeyPackage is useless. That is by design. Someone who steals just the .gfpack file, or even both files but not the PIN, cannot read your keys.

Create a KeyPackage

A window called Export As Key Package walks you through three steps: Contents, Location and Protection. Click Continue to go to the next step, or Back to change something.

1. In the main window, click Manage Keys to open the KeyPair Management window. Check the box next to each key you want to pack, then click Export Key.

2. Choose Export As Key Package. The Export As Key Package window opens.

   

3. Contents: check which keys go in. A table lists each key and, in the Exported column, whether it goes in as Public, Public and private, or is Left out: no private key. Two boxes change this:

   • Only export keys with a private key: leaves out keys that are public only.
   • Include private keys: adds your private keys to the package. Only turn this on if you really need to move private keys, for example to set up the same identity on another device. A warning reminds you that anyone with the package, the key file and the PIN can then use your keys.

   Click Continue.

   

4. Location: choose where to save the files.

   • Package name: a name is already filled in, in the form KeyPackage_<random id>. Click Generate name for a different one.
   • Save to: click Browse… and choose where to save the .gfpack file.
   • Key file: the key file is saved beside the package. To keep it apart, click Browse… and choose another place. Keep next to the package puts it back beside the package.

   Click Continue.

   

5. Protection: type a PIN of at least 8 characters, and type it again under Repeat. Or click Generate a strong PIN. Pick a strong one and keep it to yourself. The PIN cannot be recovered.

   Check the summary of what you chose, then click Export key package.

   

6. The Key Package Exported window shows where both files were saved. Click Show in Folder to see them, or Done to close it.

Changed in v2.2.4

Exporting a KeyPackage is now a guided window with three steps. It used to be a single window, where you clicked Generate and Save Passphrase to make the key file. You can now also save the key file in a different place than the package.

To back up every private key at once, open Operations > Bulk in the KeyPair Management window and choose Back Up All Private Keys…. The same window opens, with all your private keys already included.

Transfer It to the Other Device

Move both files, the .gfpack file and the .key file, to the target device. Use a safe method, such as an encrypted USB drive, encrypted email, or a secure network channel.

Do not send the PIN through the same channel as the files. For example, if you email the files, tell the PIN in person or over a phone call.

Import the KeyPackage

On the target device:

1. Open the KeyPair Management window and click Import Key.

2. From the dropdown menu, select Key Package. The Import Key Package window opens. It walks you through three steps: Files, Unlock and Keys.

   

3. Files: next to Key package, click Browse… and choose the .gfpack file you transferred.

   If the key file is in the same folder, GpgFrontend finds it by itself and says Found beside the package. If not, click Browse… next to Key file and choose the matching .key file. Click Continue.

4. Unlock: enter the PIN you set when you created the KeyPackage, then click Continue. This only opens the package. Nothing is imported yet.

   If the PIN is wrong, the window says so and you can try again. Your chosen files are kept.

5. Keys: a table lists the keys in the package. The Status column says what importing each key would do:

   • New or New, with private key: the key is not here yet.
   • Adds the private key: you already have the public key, and the package adds its private key.
   • Already here: you already have this key. Importing it again can still bring newer details, such as new signatures.

   Untick any key you do not want. Select all and Select none help with long lists.

6. Click Import keys. The window closes and Key Import Details shows what was imported.

Changed in v2.2.4

Importing a KeyPackage is now a guided window with three steps. You can see the keys in a package and pick which ones to import. Before, GpgFrontend asked for the two files and the PIN one after another, then imported every key.

Clean Up After the Import

Once the keys are imported and working:

• Delete the .gfpack file and the .key file from all devices and from any place they passed through (USB drives, email attachments, cloud folders, download folders).
• Never share the files or the PIN with anyone you do not trust.

Version Compatibility

The KeyPackage format has changed between GpgFrontend versions. Create and import KeyPackages with the same major version of GpgFrontend whenever possible.

Old KeyPackages

• KeyPackages created with v2.1.9 or later cannot be imported by versions older than v2.1.9.
• KeyPackages created with v2.2.0 or later may not be compatible with v2.1.x either, because the internal format changed again.

If you still have old KeyPackages, import them before upgrading, or export your keys again with the new version after upgrading.

How KeyPackages Are Protected (Background)

You do not need this section to use the feature. It explains how the protection has improved over time:

• Before v2.1.9: KeyPackages used AES-256-ECB, which could not detect tampering, and keys were generated with QRandom. Both are no longer considered good enough for this purpose.
• Since v2.1.9: KeyPackages use authenticated encryption (AES-GCM), which protects both the secrecy and the integrity of the package. The encryption key comes from GnuPG’s random number generator, with a secure fallback if GnuPG entropy is unavailable. Package names use a strong random identifier (KeyPackage_<zbase32 id>) instead of a short number.
• Since v2.2.0: The internal cryptographic helpers moved from OpenSSL to libsodium, matching the rest of GpgFrontend’s application-managed cryptography. This is also why the format changed again.

Today the keys are encrypted with a random passphrase, 256 characters long, using XChaCha20-Poly1305 (a modern way to lock data that also detects tampering). That passphrase is then locked with your PIN, using Argon2id (a method that makes guessing the PIN slow), and written to the key file.

So the PIN does not encrypt the KeyPackage directly. It protects the key file, which in turn holds the actual encryption key. This is why the import needs both files and the PIN.