Backup and Migration

Introduction

Only using passwords for encryption? Then the following guide does not apply to you. To open your files on the new computer, all you need are the passwords. You can check this in Kleopatra: If the certificate list is empty, simply install GnuPG (VS-)Desktop® on the new computer.

GnuPG (VS-)Desktop® stores your secret keys, the certificates of your contacts, and your settings on your computer. If you replace this computer with a new device, reinstalling the software isn't enough. You also need to transfer your GnuPG data so you can keep working as usual on the new computer.

Back up your GnuPG data regularly, not just when you switch computers. Without a backup, your secret key material is lost if your computer fails. You will then no longer be able to read messages and files encrypted for your OpenPGP key.

This guide explains which data you need to back up and how to transfer it completely and securely to a new computer, including all relevant configuration files. You can use the same steps to create a backup and restore it when needed.

GnuPG stores all security-related user data in a single location: the GnuPG home directory, which corresponds to the path defined by the GNUPGHOME environment variable. No matter whether you're using Windows or Linux, working solo or managing a larger organization, this directory must be transferred in full.

Tip: Backups are platform-independent: a backup created on Windows can be restored on Linux, and vice versa.

Important for VS-NfD

Unless you use a smartcard, a backup of the GnuPG home directory contains your secret key. This key counts as VS-NfD material. Sharing and storing the backup are therefore subject to the requirements of the German VSA (Classified Information Directive).

For example, you can store the backup on an encrypted storage medium that is labeled in accordance with the VSA and protected against unauthorized access.

Backing up Important Files

To fully transfer your GnuPG user data to a new computer, back up your entire GnuPG home directory. This personal data folder contains, among other things:

  • secret keys
  • public keys (OpenPGP certificates)
  • S/MIME certificates
  • trust database
  • configuration files

The exact location of this directory depends on your operating system:

  • on Windows: %APPDATA%\gnupg
  • on Linux: ~/.gnupg or ~/.gnupg-vsd

If you have customized your Kleopatra settings, you should also back up the following configuration files. This is only necessary if they are still stored outside the GnuPG home directory in the version installed on your old computer:

  • kleopatragroupsrc: Kleopatra groups (relevant for versions prior to 3.3.x)
  • kleopatrarc: user-specific Kleopatra settings

Note: As of GnuPG VS-Desktop® 3.3.x, kleopatragroupsrc is included in the GnuPG home directory. You only need to back it up separately if you are migrating from an older version and have made significant changes to the file.

Overview: Important File Locations

Depending on the operating system, the location of relevant configuration files may vary. The following tables show where GnuPG and Kleopatra store their data by default, as of version 3.3.x.

Windows

Component Location Comment
GnuPG home %APPDATA%\gnupg includes keys, trustdb, user-specific configuration
kleopatragroupsrc %APPDATA%\gnupg\kleopatra for the Kleopatra group feature
kleopatrarc • 3.3.x: %LOCALAPPDATA%
• 3.4.x: %APPDATA%\GnuPG VS-Desktop or %APPDATA%\GnuPG Desktop
user-specific Kleopatra settings

Note: Prior to version 3.3.x (obsolete), both kleopatragroupsrc and kleopatrarc were stored in %LOCALAPPDATA%. If you are migrating from a version older than 3.3.x, check that location as well.

Linux

Component Location Comment
GnuPG home • GnuPG Desktop: ~/.gnupg
• GnuPG VS-Desktop: ~/.gnupg-vsd
includes keys, trustdb, user-specific configuration
kleopatragroupsrc • GnuPG Desktop: ~/.gnupg/kleopatra
• GnuPG VS-Desktop: ~/.gnupg-vsd/kleopatra
for the Kleopatra group feature
kleopatrarc ~/.config or $XDG_CONFIG_HOME, if set (applies to all Kleopatra versions)

Note: Prior to version 3.3.x (obsolete), kleopatragroupsrc was stored in ~/.config (or $XDG_CONFIG_HOME if set) instead of ~/.gnupg/kleopatra or ~/.gnupg-vsd/kleopatra. If you are migrating from an older version, check that location as well.

Backup and Restore on Windows

Install GnuPG (VS-)Desktop® on the new computer either before or after copying the GnuPG home directory. Start Kleopatra only after copying. Just make sure the target user account does not already have a GnuPG home. Otherwise, configuration conflicts may occur.

Copy the folder %APPDATA%\gnupg from the old computer to the new one, completely and per user, meaning into the %APPDATA% directory of the new user profile.

Note that with GnuPG VS-Desktop®, the data must be transferred in a VS-NfD-compliant manner. Unencrypted transfer over a network that is not VS-compliant is not permitted.

You can use Kleopatra to encrypt the GnuPG home with a password before the transfer. Kleopatra combines the folder into a single file, e.g., gnupg.tar.gpg. You can then transfer this file to the new computer (including over the network) and decrypt it there with Kleopatra. Kleopatra restores the entire folder in the process. Alternatively, use a storage medium labeled in accordance with the VSA (ideally encrypted) for the transfer.

You cannot use your own OpenPGP key for this encryption, because it only becomes available on the new computer after decryption.

Tip: The %APPDATA% folder is hidden by default in Windows. You can access it by entering %APPDATA% in the File Explorer address bar or by enabling the display of hidden files.

Backup and Restore on Linux

Install GnuPG (VS-)Desktop® on the new computer either before or after copying the GnuPG home directory. Start Kleopatra only after copying. Just make sure the target user account does not already have a GnuPG home. Otherwise, configuration conflicts may occur. Copy all relevant files completely and within the correct user context.

Transferring the Data

Copy the GnuPG home directory and, if applicable, kleopatrarc to the new computer, placing each in the same location within your home directory (~). Both are stored in hidden directories whose names begin with a dot. Enable the display of hidden files in your file manager, e.g., by pressing Ctrl+H.

Note that with GnuPG VS-Desktop®, the data must be transferred in a VS-NfD-compliant manner. Unencrypted transfer over a network that is not VS-compliant is not permitted.

You can use Kleopatra to encrypt the GnuPG home with a password before the transfer. Kleopatra combines the folder into a single file with the extension .tar.gpg. You can then transfer this file to the new computer (including over the network) and decrypt it there with Kleopatra. Kleopatra restores the entire folder in the process. Alternatively, use a storage medium labeled in accordance with the VSA (ideally encrypted) for the transfer.

You cannot use your own OpenPGP key for this encryption, because it only becomes available on the new computer after decryption.

Alternative: Incremental Backup using rsync

For recurring or automated backups, rsync is a great choice. The following command copies only changed files to an external medium and preserves access permissions. For GnuPG Desktop®:

rsync -av ~/.gnupg /media/backup/gnupg/

For GnuPG VS-Desktop®:

rsync -av ~/.gnupg-vsd /media/backup/gnupg/

The target medium should use a Linux file system such as ext4. File systems such as FAT32 or exFAT, which many USB sticks and external hard drives ship with, do not support Linux access permissions. In this case, rsync reports errors.

You can also use rsync to transfer the directory directly over the network to your new computer. For GnuPG Desktop®:

rsync -av ~/.gnupg user@new-machine:~/

For GnuPG VS-Desktop®:

rsync -av ~/.gnupg-vsd user@new-machine:~/

Note: When used for remote transfers, rsync uses ssh by default, so the connection is automatically encrypted.

Security Considerations

Secret keys are especially sensitive. If you no longer plan to use the old computer, you should completely and securely delete all confidential data (especially the %APPDATA%\gnupg directory on Windows and ~/.gnupg or ~/.gnupg-vsd on Linux).

If you use GnuPG VS-Desktop® in the context of VS-NfD-compliant communication, the backup of the %APPDATA%\gnupg or ~/.gnupg-vsd directory must be handled according to the German Classified Information Directive (VSA). In particular, secret keys (unless stored on a smartcard) must be saved to a suitable storage medium and protected in accordance with the VSA guidelines.

Tip: When using smartcards, no secret key material is stored on the system itself. However, you should still back up the %APPDATA%\gnupg or ~/.gnupg(-vsd) directory to preserve public keys (certificates) and configuration files.