#open-pgp #sequoia #pgp

app openpgp-ca

OpenPGP CA is a tool for managing and certifying OpenPGP keys

8 releases

0.13.1 Jan 27, 2024
0.13.0 Aug 18, 2023
0.13.0-alpha.1 Apr 23, 2023
0.12.0 Feb 3, 2023
0.10.1 May 7, 2021

#113 in Cryptography

Download history 8/week @ 2023-10-30 1/week @ 2023-11-13 11/week @ 2023-11-20 21/week @ 2023-11-27 7/week @ 2023-12-04 7/week @ 2023-12-18 14/week @ 2023-12-25 7/week @ 2024-01-01 2/week @ 2024-01-15 29/week @ 2024-01-22 20/week @ 2024-01-29 2/week @ 2024-02-05 37/week @ 2024-02-12

88 downloads per month



What is OpenPGP CA?

OpenPGP CA (certification authority) is a tool to handle OpenPGP keys in groups or organizations - it makes the OpenPGP experience of users easier and safer, at the same time.

Imagine this: Carol is the technical expert in her group. The need for protecting the group's communication has come up, and they are thinking about how to improve this. Carol knows about OpenPGP. In fact, she's not only used OpenPGP herself, she's helped out at a few crypto parties. So, she knows: normal users, even those who are worried about their security, have a very hard time using OpenPGP securely; there are too many details to worry about.

This is where OpenPGP CA helps. The members of Carol's group trust her. She is already their sysadmin. So, it is sensible that Carol acts as a certification authority (CA) for her group. This is exactly what OpenPGP CA helps Carol do. Using OpenPGP CA, only Carol has to verify fingerprints. Her users need to be taught to recognize whether a message has been authenticated, and how to make sure encryption is enabled. However, users don't need to validate the fingerprints of their communication partners, because the CA (operated by Carol) performs this task on their behalf. This significantly lowers the threshold to using OpenPGP correctly, which gives Carol and her colleagues a real chance of communicating securely.

Setting up your OpenPGP CA instance

OpenPGP CA is a flexible tool is designed to integrate usefully with a wide range of environments. There are many ways to make OpenPGP CA work for you. Here, we show one typical workflow. Please read our documentation for more details, or talk to us if you're unsure if OpenPGP CA is a good fit for your use case.

Installing OpenPGP CA

To run an OpenPGP CA instance for your organization, first, you need to install the oca tool on your machine.

Currently, you can either build OpenPGP CA on your machine, run it as a container image or deploy it to a Kubernetes cluster.

Initializing your CA

Then you can create an OpenPGP CA instance for your organization:

$ oca -d example.oca ca init --domain example.org softkey

In this initialization step, OpenPGP CA creates an OpenPGP key for your CA. The key's User ID is set to openpgp-ca@example.org (you should make sure that the CA email address is configured in your email setup to forward mail to you).

The parameter -d <filename> specifies where OpenPGP CA will store the information of the CA. In softkey mode, this includes the private OpenPGP key of your CA and the public keys of members of your organization. In this example, we use the file example.oca as storage for our CA's data.

Manage user's keys in your CA

Once the CA is set up, users can supply their public keys to Carol, so she can keep track of the group's keys in their OpenPGP CA instance.

Many users will have pre-existing OpenPGP keys that they'll want to keep using, others will make new ones on their own computer (possibly with Carol's guidance).

Alternatively, in some cases it can be appropriate to generate user keys centrally, using OpenPGP CA, but we won't cover this scenario, here.

Let's say Carol wants to import the public keys of her colleagues Alice and Bob in the CA. She obtains copies of their public keys and temporarily stores them in the files alice.pub and bob.pub. Carol can obtain the public keys in any of a number of ways: Alice and Bob might have handed their keys to Carol on USB storage, sent them to Carol by email, or Carol might have pulled them from a public keyserver.

However, before proceeding, it's Carols responsibility to verify the fingerprints of the keys. That is, she needs to make sure the fingerprints of the keys she has obtained match with the keys that Alice and Bob have on their machines. A typical approach is for Carol to meet Alice and Bob and read out and compare the fingerprints. Different organizations will follow different procedures. The main point is that Carol needs to make sure that she didn't obtain the wrong keys (either from a malicious third party - or by making a mistake, such as getting an old key for Bob from a keyserver, for which Bob has lost access to the private key material).

Once Carol has obtained and verified the keys, she can import them into the group's OpenPGP CA instance. The CA will certify user keys (based on Carol's verification), and based on these certifications, everyone else in the organization can rely on getting the correct keys without having to personally verify every single one. Normally, users will only need to verify the CA's key.

To import the keys into the CA, Carol will perform the following steps:

oca -d example.oca user import -e alice@example.org --key-file alice.pub
oca -d example.oca user import -e bob@example.org -e bob.baker.39472384@gmail.com --key-file bob.pub

(Recall that -d example.oca specifies the location of your CA database, in this example workflow - in your setup, you could configure your CA database in your environment and omit this parameter)

Note that Carol explicitly provides email addresses for Alice and Bob's keys while importing them.

By specifying these email addresses, Carol instructs the OpenPGP CA instance to know which email addresses Carol considers to be appropriately associated with each key. In this example, Carol instructs the CA to certify (using a digital signature) that the identity alice@example.org is correctly linked to the key in alice.pub.

Alice and Bob's keys may contain User IDs that Carol chooses not to certify with the CA. For example because those User IDs specify email addresses that are not relevant for the group's shared objectives. Or because Carol cannot verify those digital identities and thus opts not to certify them.

Simplifying key discovery with WKD

OpenPGP CA can also significantly simplify key discovery: once you manage the keys with OpenPGP CA, you can automatically output the keys to serve as a Web Key Directory (WKD).

To publish your CA as a WKD, you can export all public keys for your domain, like this:

oca -d example.oca wkd export /tmp/wkd/

When you serve the contents of this directory with a webserver under the hostname openpgpkey.example.org (note that you also need to configure https), your OpenPGP keys will be conveniently accessible to the general public. Most client software can retrieve keys from WKD, and will automatically find your WKD.

Note, however, that this approach only works for keys that have User IDs in your domain (example.org, here). Because WKD relies on the domain name system (DNS) for lookup, you cannot publish keys that only have User IDs that are external to your domain, via WKD.

Users can rely on a CA for authentication

One major goal of OpenPGP CA is to make it simple for end users to use keys for their main communication partners with confidence - without having to manually verify each key. By relying on a CA, users delegate checking of keys to a party they explicitly trust.

When relying on a CA, users in the group instantly see each other's keys as authenticated - as soon as their OpenPGP implementations obtain copies of other users' keys, they can be certain that they have obtained the correct key.

Users never need to manually check fingerprints of group members anymore (or sign each other's keys). Instead, they rely on Carol performing the verification task for them - and that Carol formalizes the resulting knowledge as certifications by the group's CA.

This means that, for example, Thunderbird/Enigmail will show green header bars for received email from contacts that the OpenPGP CA admin has authenticated. So when Alice gets email from Bob, there is visual confirmation in her email software that the key that Bob used to sign his email has been verified to actually be Bob's key.

Relying on your CA with GnuPG

To take advantage of a CA, users need to obtain and verify the CA's key, and tell their OpenPGP software to rely on that CA. "Relying on a CA" means that users need to issue a trust signature for the CA key - by doing this, they instruct their OpenPGP software that they want to take advantage of certifications that the CA makes.

A user can configure their GnuPG installation to rely on a CA as follows. First, the user retrieves the CA's key via WKD, then they set up a local trust signature (tlsign) and make sure to verify the CA fingerprint they use is correct (they need to get the correct fingerprint from Carol - for example in printed form, or in a phone call):

$ gpg --locate-external-keys --auto-key-locate wkd openpgp-ca@example.org
$ gpg --edit-key '1234 5678 9ABC DEF0 1234  5678 9ABC DEF0 1234 5678'
gpg> tlsign
gpg> 2
gpg> 1
gpg> example.org
gpg> save

(The fingerprint 1234 5678 9ABC DEF0 1234 5678 9ABC DEF0 1234 5678 above needs to be replaced with the correct fingerprint for your CA's key)

By supplying example.org as a domain-restriction, we tell our GnuPG installation to only rely on the CA regarding certifications on identities in your domain example.org (depending on the nature of your organization, it might be more appropriate to configure an unconstrained trust signature instead).

Testing authentication based on our CA

Anyone who has configured their OpenPGP environment to rely on our CA as shown above will automatically see our users' keys as "trusted":

$ gpg --locate-external-keys --auto-key-locate wkd alice@example.org

uid           [  full  ] Alice <alice@example.org>

Federation between organizations that use OpenPGP CA

OpenPGP CA not only makes it easy for users within an organization to authenticate each other, but provides support to create so-called bridges between organizations. In this case, the CA admins from two OpenPGP CA using organizations sign each others CA key using a scoped trust signature.

See the section on how bridges allow for authentication between organizations in our background documentation for more details.

Running a CA backed by an OpenPGP card

As an alternate, advanced mode of operation, you can initialize your CA instance to use an OpenPGP card device (e.g. Gnuk, Nitrokey, or YubiKey) for all operations that require private key material. Compared to softkey-mode, this has the advantage that the private key material of your CA is not directly accessible to the computer that runs the CA (and thus can't be exfiltrated in case of attack).

To initialize an OpenPGP card for use with OpenPGP CA, the card needs to be in a blank state. A freshly bought card will work. To use a card that has already been used in a different context, you need to factory reset it first (e.g. using the opgpcard tool: opgpcard factory-reset -c <ident>).

In the process of setting up a card, OpenPGP CA sets the User PIN to a random 8-digit number (the Admin PIN is set to the same number). The new PIN is printed after initialization of the CA. The PIN is also stored in the CA database (the PIN is automatically supplied to the card during regular CA operation). The PIN can also be checked in the output of oca -d <database> ca show.

Currently, the default key type in OpenPGP CA is RSA 4096. Most modern cards support such keys.

Once a CA is initialized in card-mode, all CA operations work exactly like a CA in softkey-mode does.

Initializing a new card-backed CA instance

To create a new OpenPGP CA instance that is backed by an OpenPGP card, run:

$ oca -d example.oca ca init --domain example.org card

OpenPGP CA will automatically choose the card to use, if exactly one blank card is connected to the system. Otherwise, you can explicitly select a card via an identity parameter (like 0123:01234567).

This command generates the CA key material on your host computer and imports it onto the OpenPGP card. The private key material for the CA is printed to the console, but not otherwise stored.

For a production CA, you will probably want to copy this private key to a safe place, and to keep it sufficiently confident. You should consider performing this initialization step on an air-gapped system.

Finally, the initialization process shows status information about your newly set up CA:

Initialized OpenPGP CA instance:

    CA Domain: example.org
  Fingerprint: E8A8E047F61B2C3C011F7AA245776DAE2FE0E255
Creation time: 2022-11-22 13:49:23 UTC
   CA Backend: OpenPGP card 0123:01234567 [User PIN 14199138]

The last line shows that the card-backend is used for this CA, and the newly set User PIN for the card is displayed (the Admin PIN is set to the same value).

Learn more

To get a deeper understanding of the ideas behind OpenPGP CA, you can read our documentation about the background and concepts.

Or you can read our hands on documentation about how to run an OpenPGP CA instance.

End users can read our client documentation to learn how to take advantage of an existing CA.

Version history

  • openpgp-ca 0.12:
    • Support for OpenPGP card-backed operation was added
    • The binary program has been renamed oca, for brevity (previously the binary was named openpgp-ca)

Get in touch for support

If you are interested in deploying OpenPGP CA in your organization, please contact heiko@schaefer.name (68C8B3725276BEBB3EEA0E208ACFC41124CCB82E). We can consult, help you with your setup, or even add features.

For non-profit organizations reduced rates are available. This is also a useful way for companies to support the project.


~1M SLoC