Multi-Key Database Support

A key database is the place where GpgFrontend keeps your keys. Normally you have just one. GpgFrontend also lets you set up several key databases, each one fully separate from the others.

Why would you want more than one? A few common reasons:

• Keep work keys and personal keys apart, so you never mix them up.
• Give each project, team, or customer its own set of keys.
• Keep test keys away from the keys you really use.
• Try the experimental rPGP engine (for example, for OpenPGP v6 keys) without touching your normal GnuPG keys.

If one key database is enough for you, you can skip this page. GpgFrontend works fine without ever opening these settings.

Note

Since GpgFrontend v2.2.0, key databases are managed in the main Settings dialog. The old GnuPG Controller window no longer exists.

Open the Key Database Settings

1. Open Settings from the main menu.

2. Choose Key Databases, under Keys & Engines.

You now see a list of all your key databases, with the name you gave each one, the engine it uses, its folder, and whether it is working. A database whose folder has been moved or deleted shows as Inactive.

The first database in the list is the default. It is the one GpgFrontend uses when you start the application. On a normal setup, it points to your GnuPG home directory.

You can have up to eight databases.

Add a New Key Database

1. In the Key Databases settings, click Add New Key Database.

2. Give it a clear name, such as Work, Personal, or rPGP Test. A good name helps you pick the right database later.

3. If the option is shown, choose the engine (GnuPG or rPGP). If you are not sure, keep GnuPG. It is the standard choice and works with everything.

4. Choose a Mode:

   • Automatic: GpgFrontend picks a safe place to keep it. Just give it a name and you are done. Use this unless you have a reason not to.
   • Manual: you pick the folder yourself. Use this only for special setups, such as pointing at an existing GnuPG home directory.

The new database starts empty. Any key you generate or import while it is selected goes into this database only.

What is the Relative Path option?

In Manual mode you can turn on Convert to Relative Path. GpgFrontend then remembers where the folder is in relation to the application, instead of as a full path. Use this in Portable Mode, or when you move GpgFrontend between computers, so the path keeps working everywhere.

Keys can live inside a profile

If you make a profile that holds its own keys, its key database travels with it. That is what lets you save a whole setup to one file and open it on another computer.

Automatic mode puts the database inside the profile, so it travels. Manual mode usually points somewhere else, so it usually does not. See Which Databases Travel below.

Switch Between Databases

You do not need to open Settings to change databases:

1. In the main window, open the dropdown at the top of the Key Toolbox.

2. Pick the database you want. The key list now shows only the keys in that database.

From then on, everything you do (generate, import, export, encrypt, sign, verify) uses the keys in the selected database.

Tip

Before you generate or import a key, glance at the dropdown to make sure the right database is selected. This is the easiest way to avoid putting a key in the wrong place.

Edit, Reorder, or Remove a Database

In the Key Databases settings, right-click a database (or use the buttons) to:

• Edit: Change its name, path, or other settings.
• Move Up / Move Down / Move to Top: Change the order of the list. Remember, the first entry is the default database.
• Remove: Take the database out of GpgFrontend’s list. This does not delete the keys on disk. It only removes the entry from the configuration.

Caution

Every change here needs a restart. GpgFrontend tells you when you click OK and offers to restart for you.

Understand Engines (GnuPG vs rPGP)

Each key database uses exactly one engine:

• GnuPG: The standard engine. Recommended for daily use. Keys are stored in a GnuPG keyring.
• rPGP: An experimental engine. Useful for testing newer OpenPGP features, such as OpenPGP v6 or some post-quantum algorithms. Keys are stored in a file named gf_keydb.sqlite.

The important part: these two stores can live in the same folder, but they are completely separate. GpgFrontend only reads the store that belongs to the database’s current engine. It never merges them.

What happens when you change a database’s engine

Say your default database points to your GnuPG home directory:

• You set its engine to rPGP and restart. GpgFrontend now creates and reads a gf_keydb.sqlite file in that folder, and shows only rPGP keys. Your GnuPG keys are still on disk, but they are not shown.
• You set the engine back to GnuPG and restart. GpgFrontend reads the GnuPG keyring again. Now the rPGP keys are the ones not shown.

Switching engines hides keys, it does not delete them

Changing the engine never moves, converts, or deletes any keys. Keys that belong to the other engine are simply not shown. To see them again, switch back to their engine and restart.

If you want GnuPG keys and rPGP keys available at the same time, do not keep switching one database back and forth. Instead, create two databases, one per engine, and switch between them from the Key Toolbox dropdown.

The gf_keydb.sqlite File

Starting with the 2.2 series, GpgFrontend may create a file named gf_keydb.sqlite inside a key database folder. What it holds depends on the engine:

• rPGP database: This file holds the actual key material, including private keys. Treat it as sensitive.
• GnuPG database: GnuPG itself still holds all key material. Here the file only stores GpgFrontend’s own metadata and may be empty.

For a full explanation of where each engine keeps your keys, see How Keys Are Stored (GnuPG vs rPGP).

Back Up Your Databases

Back up each database based on its engine:

• GnuPG database: Back up the GnuPG home directory it points to, plus your revocation certificates.
• rPGP database: Back up the whole database folder, including gf_keydb.sqlite. Remember that this file can contain private keys.

Store backups in a safe, encrypted place.

Which Databases Travel

If you save a profile to a .gfp file to move it to another computer, some key databases come along and some do not.

What decides it is where the folder is, not which mode you chose:

• A database in a folder inside the profile travels. Its keys are packed into the file. Automatic mode always puts it there.
• A database in a folder anywhere else does not travel. Manual mode normally points somewhere else, such as your system GnuPG home directory.

A database that does not travel is still listed in the file by name, but its keys stay on the old computer.

When you open the profile on the other computer, GpgFrontend tells you which databases were left behind. Each one shows as Inactive in the Key Databases settings until you edit it and point it at a folder on the new computer.

This is easy to miss when you export

The export window only mentions this in small grey text under What goes in, so it is easy to overlook.

If you want your keys to travel with the profile, check that the database is in Automatic mode, or that the folder you picked in Manual mode sits inside the profile.

If it does not, and you still want those keys on the other computer, move them across separately with a KeyPackage.

Tips

• Name databases by purpose: Personal, Work, Project Alpha, rPGP Test. Avoid names that only make sense today.
• Check the dropdown first: Always confirm which database is active before you generate, import, encrypt, or sign.
• Keep experiments separate: Do daily work in GnuPG databases. Use a dedicated rPGP database for testing new features.
• Clean up now and then: Remove keys you no longer use, check expiry dates, and make sure each key lives in the database you meant it for.