Multi-Key Database Support

A key database is a folder where GpgFrontend keeps your keys. Every key you make or import goes into one key database.

Most people need only one. GpgFrontend gives you one from the start, called the Built-in Key Database. You can also add more. Each one is fully separate from the others.

Why add 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 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.

Changed in v2.2.3

Changes to your key databases now take effect as soon as you click OK. GpgFrontend no longer needs to restart.

Open the Key Database Settings

1. Click Edit > Settings. On macOS, open the GpgFrontend menu and choose Preferences.

2. In the list on the left, under Keys & Engines, click Key Databases.

The page has two parts:

• At the top, a box called Built-in Key Database.
• Below it, three tabs: In Profile, Recycle Bin and Local Only.
  • In Profile and Local Only list the key databases you added yourself.
  • Recycle Bin lists key databases you removed from In Profile. Their keys are still on this computer.

![The Key Databases page in Settings][img-1]

Nothing you change on this page is saved until you click OK. If you click Cancel, every change you made in the settings window is thrown away.

The Built-in Key Database

The Built-in Key Database is the key database GpgFrontend gives you. It is always listed first. In menus and window titles it is called Built-in.

Where it lives depends on your profile:

• This computer’s built-in key database: normally your GnuPG home directory. That is the same place the gpg command line uses.
• This profile’s own built-in key database: when your profile keeps its own keys, the built-in database is a folder inside the profile.

The box shows three things:

• Key engine: the engine that opens the built-in database. The line under it says what that means. With GnuPG it reads “Uses keys in the GnuPG home directory.” With rPGP it reads “Uses the rPGP key database at this location.”
• The database’s role. You see Default in bold when it is the default database. Otherwise you see a Use as Default button. See Choose the Default Key Database.
• Location: the full path of its folder. Click Copy to copy the path.

Change the Built-in Database’s Engine

1. Open the Key Databases settings page.

2. In the Built-in Key Database box, pick an engine from Key engine:.

3. Click OK.

This choice applies only to the built-in database. Other key databases always open with their own engine.

Changed in v2.2.3

This choice used to be Default Engine: on the General page. It now lives here, as Key engine: in the Built-in Key Database box.

The built-in database was called DEFAULT before. It is now shown as Built-in.

Changing the engine hides keys, it does not delete them

GnuPG and rPGP keep their keys in different files, even in the same folder. GpgFrontend shows only the keys that belong to the engine in use. It never moves, converts, or merges them.

So if you switch the built-in database from GnuPG to rPGP, your GnuPG keys are still on disk, but you no longer see them. Switch back and they appear again.

If you want GnuPG keys and rPGP keys at the same time, do not keep switching. Add a second key database with the other engine instead.

Turn the Built-in Database Off or On

The title of the box has a checkbox. Clear it to stop using the built-in database, then click OK. Tick it again to bring it back.

You can only turn it off when you have at least one other key database.

If your computer’s OpenPGP engine does not report a key database, the box is greyed out and says so: “The OpenPGP engine on this computer does not report a key database, so there is no built-in one to use.”

Choose the Default Key Database

One key database is the default. GpgFrontend uses it when an operation does not pick a key database on its own. It is also the one the main window shows when it starts.

At first, the built-in database is the default. To make another one the default:

1. Open the Key Databases settings page.

2. Choose one:

   • For the built-in database, click Use as Default in its box.
   • For a database you added, open the In Profile or Local Only tab, click its row, then click Use as Default under the list. You can also right-click the row and choose Use as Default.

3. Click OK.

The default database shows Default in the Role column, or in bold in the Built-in Key Database box.

If you remove the default database, or turn the built-in one off, the choice goes away. GpgFrontend then falls back to the built-in database, or to the first database in the list if the built-in one is off.

Smart cards follow later

When you move the default from one GnuPG database to another, this note may appear:

“Smart cards stay with the previous default database until GpgFrontend restarts. To move them sooner, apply this change, then use “Restart All Gpg-Agents” in the Smart Card Controller.“

See Smart Card for the Smart Card Controller.

Changed in v2.2.3

Before, the first database in the list was always the default. Now you choose the default with Use as Default, and the order of the list does not decide it.

Add a Key Database

You can add a key database in two places. Choose by where the keys should live.

Tab	Where the folder is	Goes with your profile?
In Profile	Inside your profile. GpgFrontend picks the folder.	Yes. A profile package carries it.
Local Only	Any folder you choose.	No. It stays on this computer.

If you are not sure, use In Profile.

Changed in v2.2.3

The add window no longer has a Mode choice with Automatic and Manual. Automatic is now the In Profile tab. Manual is now the Local Only tab. The Path field is now called Folder.

Add One Inside Your Profile

1. Open the Key Databases settings page and click the In Profile tab.

2. Click Add Key Database. The Add Key Database window opens.

3. Type a Name, such as Work or Personal. GpgFrontend suggests a name like Key DB 1 that you can keep or change.

4. If an Engine choice is shown, pick GnuPG or rPGP. If you are not sure, keep GnuPG. You cannot change the engine later.

5. Click OK in the window, then click OK in the settings window.

You do not choose a folder. GpgFrontend makes one named after the database, inside your profile. The Folder line shows where, for example @profile/dbs/Work. Here @profile means “your profile folder”.

If a removed database with the same name is still in the Recycle Bin, you see Key Database Folder Already Exists. Restore that one, delete it for good, or pick another name.

Add One on This Computer Only

Use this to point at a folder you already have, such as an existing GnuPG home directory, or a folder on another drive.

1. Open the Key Databases settings page and click the Local Only tab.

2. Click Add Key Database On This Computer. A window with the same name opens.

3. Type a Name. GpgFrontend suggests a name like External Key DB 1.

4. Click Choose Folder… and pick the folder. It must be a folder that already exists and that you can read.

5. If you use GpgFrontend from a USB drive, tick Convert to Relative Path. See Portable Mode.

6. If an Engine choice is shown, pick GnuPG or rPGP. You cannot change it later.

7. Click OK in the window, then click OK in the settings window.

A Local Only database never goes into a profile package. It is also always opened after the databases inside your profile.

Rules for Names

• A name can use letters, numbers, spaces, - and _.
• Two key databases cannot have the same name. Upper and lower case count as the same, so Work and work clash.
• The name DEFAULT is kept for the built-in database. You cannot use it.

Edit, Rename, Reorder, or Remove a Key Database

To change the order of the list, drag a database up or down on the In Profile or Local Only tab. The order is only the order the databases are listed and opened in. It does not choose the default.

Right-click a database on one of those tabs. The menu has:

• Use as Default: make this the default database.
• Open: open its folder in your file manager.
• Copy Folder Path: copy the full path of its folder.
• Edit: change the database. See below.
• Move to Recycle Bin (on In Profile) or Remove Reference (on Local Only): take it off the list. See Remove a Database.

Changed in v2.2.4

You now drag a database to move it. The Move Up, Move Down and Move To Top menu entries are gone. The old Remove entry is now called Move to Recycle Bin or Remove Reference, depending on the tab.

Rename a Database Inside Your Profile

1. On the In Profile tab, right-click the database and choose Edit. The Rename Key Database window opens.

2. Type the new Name and click OK.

3. Click OK in the settings window.

The folder is named after the database, so GpgFrontend renames the folder too. This happens when you click OK in the settings window, not before.

If a folder with the new name is already there, GpgFrontend stops and shows Key Database Folder Already Exists. Pick another name. If that folder is in the Recycle Bin, you can also restore it or delete it for good first. See Restore or Delete a Removed Database.

Edit a Local Only Database

On the Local Only tab, right-click the database and choose Edit. The Edit Key Database window opens. You can change the Name, pick another folder with Choose Folder…, and tick Convert to Relative Path.

The Engine is shown but greyed out. A database keeps the engine it was made with.

Remove a Database

What happens depends on the tab the database is on.

1. Right-click the database:

   • On In Profile, choose Move to Recycle Bin.
   • On Local Only, choose Remove Reference.

2. A window with the same name asks you to confirm. Click Yes.

3. Click OK in the settings window.

Nothing is deleted:

• A database from In Profile goes to the Recycle Bin tab. Its folder and keys stay on this computer, and you can bring it back later.
• A database from Local Only is only forgotten. GpgFrontend stops using it, and its folder is left as it is. It does not go to the Recycle Bin.

GpgFrontend needs at least one key database, so you cannot remove the last one.

Restore or Delete a Removed Database

New in v2.2.4

Key databases you remove from In Profile now wait in the Recycle Bin tab, instead of just being dropped from the list.

Open the Recycle Bin tab. It shows each removed database with its Name, Engine, Size and Folder. The size may show … for a moment while GpgFrontend measures it.

![The Recycle Bin tab][img-3]

A database you just removed shows up here after you click OK in the settings window.

Bring a Database Back

1. On the Recycle Bin tab, click the database.

2. Click Restore. The database moves to the In Profile tab.

3. Click OK in the settings window.

You may see one of these messages:

• Key Database Name Taken: another database in the list has the same name. Rename or remove that one first, then restore.
• Choose an Engine: GpgFrontend cannot tell which engine made the database. Its Engine column says Unknown. Pick the engine from the list.
• Engine Not Available: the database was made with an engine that your copy of GpgFrontend does not have.

Delete a Database for Good

Caution

This deletes the folder and every key in it, private keys included. It happens at once. It cannot be undone, and clicking Cancel in the settings window does not bring the keys back. Make a backup first if you are not sure.

1. On the Recycle Bin tab, click the database.

2. Click Delete Permanently.

3. A warning asks if you want to delete the database and everything in it. Click Delete Permanently again.

The status bar then says Key database folder deleted.

If the folder could not be deleted, or only partly, you see Folder Not Deleted with the reason. For example, the folder may still be in use. Wait a moment and try again.

To look at a removed database’s files first, right-click it and choose Open or Copy Folder Path.

What Happens When You Click OK

GpgFrontend opens your key databases again with the new settings. It does not restart.

While it works, a small window called Applying Key Database Changes is shown, and you cannot use the program. This can take a few seconds, mostly with GnuPG on Windows.

The status bar at the bottom of the main window then says how it went:

• Key databases updated. Everything worked.
• Key databases updated, with problems. A Key Database Changes window tells you which databases could not be opened.
• Key database changes were not applied. The key databases in use stay as they were.

Operations Still Running

Sometimes a key database you changed or removed is still busy, for example with a large file being encrypted. Then GpgFrontend asks first, in a window called Operations Still Running. It lists each busy database and how many operations it is running.

• Click Apply to go ahead. The running work finishes on the key database as it was before.
• Click Cancel to keep the settings window open and change nothing yet. On macOS the Preferences window is already closing at this point, so your changes are applied anyway.

Windows Tied to a Removed Database

Some windows belong to one key database, such as a Key Details window. If you remove that database, or it can no longer be opened, the window is greyed out. Its title gets “(key database no longer available)” at the end. Close it.

If the main window was showing a database that is gone, it switches back to the default one. The status bar says: “The key database “…” is no longer available; showing the default one.“

If you started an action just as the databases changed, you may see Key Databases Changed. Nothing was done. Check the selected keys and try again.

Switch Between Key Databases in the Main Window

You do not need the settings window to change which keys you see.

1. In the main window, find the key database button above the key list. It shows the name of the database you are in.

2. Click it. A menu lists all your key databases. Each entry shows the name, the engine, and the word Default for the default one.

3. Click the database you want. The key list now shows only its keys.

![The key database menu in the main window][img-2]

Hold the mouse over the button or a menu entry to see more about that database: whether it is the default, where it is kept (for example “Kept inside your profile” or “On this computer only”), its engine, and its folder.

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

The database name also appears in other places, so you always know where you are:

• the first step of the Generate Key window, which says where the new key is saved;
• the title of a Key Details window, such as Key Details (Work);
• the list of databases when you move a key to a smart card;
• the engine part of the status bar.

Tip

Before you make or import a key, look at the key database button. It is the easiest way to avoid putting a key in the wrong place.

Engines: GnuPG and rPGP

Each key database uses exactly one engine:

• GnuPG: the standard engine. Recommended for daily use. Keys are kept in a GnuPG keyring, and the gpg command line can see them.
• rPGP: a newer engine, built into GpgFrontend. Useful for newer OpenPGP features, such as OpenPGP v6 or some post-quantum algorithms. Keys are kept in a file named gf_keydb.sqlite.

How the engine is chosen:

• The built-in database uses Key engine: in its box. You can change it.
• A database you added keeps the engine you picked when you made it. You cannot change it.

The Engine choice only shows up when your copy of GpgFrontend has both engines.

New in v2.2.3

The rPGP engine now remembers passphrases separately for each key database. A passphrase you typed for a key in one database is never used for another database.

For where each engine keeps its keys, and what that means for safety and backups, see How Keys Are Stored.

Limits and Error Messages

• You can have up to 8 key databases, counting the built-in one. Adding a ninth shows Maximum Key Database Limit Reached. Remove one first.
• You need at least one key database. Trying to remove the last one, or to turn off the built-in one when it is the only one, shows Key Database Required.
• Two key databases cannot use the same folder. Trying shows Duplicate Key Database Paths.
• When the folder you pick cannot be used, you see Illegal GnuPG Key Database Path, Invalid Key Database Paths, or Failed to Create Key Database Directory. Pick another folder.
• If GpgFrontend cannot read your saved list of key databases, you see Unreadable Key Database Settings when you click OK. Click Save to replace it with the list on screen, or Cancel to keep it. The old list cannot be brought back after you save.
• At start, Invalid Key Databases lists any database that could not be opened. On the Key Databases page, such a database shows Inactive in the Status column. Edit it to point at the right folder, or remove it.

Long Folder Paths With GnuPG

On Linux and macOS, GnuPG cannot work in a folder whose path is very long. When that happens, GpgFrontend quietly makes a short link to the folder in a temporary place and gives GnuPG that link instead. Your keys stay where they are. You do not need to do anything.

Only if that short link cannot be made do you see Key Database Path Too Long. Then pick a folder with a shorter path. This does not affect rPGP databases.

What Travels in a Profile Package

When you save your profile to a .gfp file to move it to another computer:

• In Profile databases travel. Their keys go into the file.
• Local Only databases never travel. Their keys stay on this computer.
• Databases in the Recycle Bin never travel.
• The built-in database travels only when it is this profile’s own built-in key database. When it is this computer’s GnuPG home directory, the person who opens the file uses their own built-in database instead.

Your default choice travels too, if the database it names travels or is the built-in one. If not, the other computer picks its own default.

If you want keys from a database that does not travel, send them separately with a KeyPackage.

Sandbox Builds (Flatpak and Mac App Store)

Sandboxed builds can only keep key databases inside the profile. So in the Flatpak and Mac App Store builds:

• the Local Only tab is hidden;
• Choose Folder… and Convert to Relative Path are not shown;
• the Built-in Key Database box has no checkbox, so the built-in database is always on;
• Edit is not in the right-click menu.

The Recycle Bin tab works the same as in other builds.

Back Up Your Key Databases

Back up each database according to its engine:

• GnuPG database: back up the folder it uses, plus your revocation certificates.
• rPGP database: back up the whole folder, including gf_keydb.sqlite. This file can contain private keys.

To find a folder, right-click the database and choose Open or Copy Folder Path. For the built-in database, use Copy next to Location:.

Keep backups in a safe, encrypted place.

Tips

• Name databases by purpose: Personal, Work, Project Alpha, rPGP Test.
• Check the key database button first: make sure you are in the right database before you make, import, encrypt, or sign.
• Keep experiments apart: do daily work in a GnuPG database. Use a separate rPGP database for trying new features. [img-1]: https://image.cdn.bktus.com/i/2026/10/29/a9397ad0e7372f52f5c26b0ee963cded51b480e4.webp [img-2]: https://image.cdn.bktus.com/i/2026/10/29/125d52b6f4300258e3df3516804d2a3a7a030e77.webp [img-3]: https://image.cdn.bktus.com/i/2026/10/29/e0543f5ccc9d3dab5aab6ce69dd17e266dcb0e6b.webp