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:

1. The KeyPackage file (.gfpack): Holds your keys, encrypted.
2. The key file (.key): Holds the encryption key for the KeyPackage, itself protected by your PIN.
3. Your 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

1. In the main window, open the key management interface and click Export Key.

2. Choose the option to export as a KeyPackage. A dialog opens.

   

3. Fill in the three fields:

   • Name: A name is already generated for you, in the form KeyPackage_<random id>. Click Generate Key Package Name if you want a different one.

   • Output path: Click Select Output Path and choose where to save the .gfpack file.

   • Passphrase: Click Generate and Save Passphrase. This creates the key file. You will be asked to set a PIN. Pick a strong one and keep it to yourself.

     

4. Check the optional settings:

   • Include secret key (Think twice before acting): 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.
   • Exclude keys that do not have a private key: Leaves out keys that are public-only.

5. Review everything, then click OK. GpgFrontend creates the KeyPackage and confirms that it is encrypted (for example with AES-256-GCM) and safe to transfer.

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 key management interface and click Import Key.

2. From the dropdown menu, select Key Package.

   

3. In the file dialog, choose the .gfpack file you transferred.

4. In the next file dialog, choose the matching .key file.

5. Enter the PIN you set when you created the KeyPackage.

6. GpgFrontend decrypts the package and imports your keys.

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.

Caution

• 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.

The PIN you set does not encrypt the KeyPackage directly. Instead, it protects the key file, which in turn holds the actual encryption key. This is why the import needs both files and the PIN.