OpenPGP CA

Installation, getting started

Mon, 01 Jan 0001 00:00:00 +0000

After you’ve familiarized yourself with OpenPGP CA’s concepts, let’s get started using it! Installation First, we install OpenPGP CA (or, alternatively, you can run OpenPGP CA in Docker). As prerequisites, we need to install: Rust and Cargo (see https://www.rust-lang.org/tools/install) The C-dependencies of Sequoia PGP (see “Building Sequoia”) (e.g. on Debian bookworm, you need at least apt install rustc cargo clang pkg-config nettle-dev libssl-dev libsqlite3-dev) libpcsclite to build OpenPGP card support: apt install libpcsclite-dev (at runtime, pcscd is used, so if you want to use cards, that service must be running)

Relying on a CA

Mon, 01 Jan 0001 00:00:00 +0000

If your organization is running an OpenPGP CA instance, or you are communicating with people at an organization that runs an OpenPGP CA instance, you probably want to rely on that CA. That is: tell your PGP software to make use of the authentication work that the CA performs. What is an OpenPGP CA instance An OpenPGP CA (certification authority) instance is a system that makes statements about cryptographic identities.

Why OpenPGP CA?

Mon, 01 Jan 0001 00:00:00 +0000

OpenPGP CA can be applied in a wide variety of scenarios. It serves two main goals: Make your organization’s keys easy to find TL;DR: OpenPGP CA helps you manage your organization’s OpenPGP public keys. You can easily publish the keys via WKD. This solves the problem of (automated) key discovery. If you use OpenPGP, you probably agree that it can be hard to find the OpenPGP key for a communication partner.

Initializing a CA instance

Mon, 01 Jan 0001 00:00:00 +0000

Now that we have installed the OpenPGP CA software, we can explore how to use it. One main aspect of initializing a CA instance is setting up the CA’s OpenPGP key. That key is used by the CA to issue certifications. Issuing reliable certifications is a central purpose of operating a CA. Appropriate handling of the CA’s key is an important consideration. Currently, two mechanisms for handling the CA’s private key material are supported:

The OpenPGP card backend

Mon, 01 Jan 0001 00:00:00 +0000

One main purpose of OpenPGP CA is issuing certifications. To issue certifications, the CA uses a private key. This private key must be accessible to the CA. The simplest way to handle the CA private key is to store it in the CA database, and use it from there. This is what the “softkey” backend does (it uses a “software-based” key). The softkey backend has the benefit that it is easy to use and doesn’t require additional hardware.

Split Mode OpenPGP CA

Mon, 01 Jan 0001 00:00:00 +0000

What is OpenPGP CA Split Mode? In some contexts, it is useful to run OpenPGP CA split into two subsystems, for example: On two distinct computers, In two separate Qubes VMs on a Qubes OS system. We call such an OpenPGP CA setup a “Split Mode CA”. Note that split mode is a specialized mode of operation! It is not appropriate or recommended for all users. One logical CA, two instances performing different roles In split mode, a logical OpenPGP CA is composed of two instances, which perform different roles, and which have different security requirements.

Importing user keys

Mon, 01 Jan 0001 00:00:00 +0000

The typical approach for managing user keys with OpenPGP CA is that users create their own keys and supply their public key to the OpenPGP CA admin. We call this workflow “decentralized key creation”, because OpenPGP keys do not get created centrally, but decentrally, by each individual user. Importing user generated keys into OpenPGP CA involves setting up certifications between the CA key and the new user key. This workflow gives users full control over their own keys.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

OpenPGP CA: a high-level overview OpenPGP CA has two aspects. It is both: A paradigm (a set of best practices) for the use of OpenPGP in organizations or groups. Concrete tooling that helps apply this paradigm in practice. This text focuses on the first aspect. We discuss the approach that OpenPGP CA proposes, independent of concrete software tools1. Concepts The OpenPGP CA paradigm touches on a number of concepts:

Support in client software

Mon, 01 Jan 0001 00:00:00 +0000

OpenPGP CA uses established features of the OpenPGP standard The mechanisms that OpenPGP CA relies on are standardized in RFC 4880. In particular, our approach relies on certifications of User IDs and on “Trust Signature” packets. For some scenarios, it is necessary to use scoped trust signatures (that is, to limit the delegation of trust to only User IDs under a particular domain name). To do this, we use “Regular Expression” packets

Centrally creating new user keys

Mon, 01 Jan 0001 00:00:00 +0000

In some cases, it may be useful and appropriate for the OpenPGP CA admin to generate new keys on behalf of users. This is the simplest workflow for both the admin and users. OpenPGP CA can automatically create all of the necessary auxiliary data structures (certifications, as well as revocation certificates) when generating new user keys. We call this workflow “centralized key creation”, because OpenPGP keys get created centrally by the OpenPGP CA admin.

Technical Details

Mon, 01 Jan 0001 00:00:00 +0000

In the previous chapter, we’ve discussed the paradigm and concepts of OpenPGP CA at a high level. Now, we’ll take a more detailed, technical look at the relevant OpenPGP mechanisms, as well as the OpenPGP CA software itself. The OpenPGP CA software OpenPGP CA is a suite of software, written in Rust. It uses Sequoia PGP. All code is Free Software under the GPLv3. The CA’s private key can be used via different mechanisms: directly as a “softkey” (the private key material is stored in the CA database and accessible to the computer that OpenPGP CA runs on), or using an OpenPGP card device (this protects the CA key from exfiltration, and even from use by attackers, depending on the configuration).

Inspecting OpenPGP CA's state

Mon, 01 Jan 0001 00:00:00 +0000

Once our OpenPGP CA database is populated with data, we may want to inspect that data. In this chapter we assume that our OpenPGP CA instance contains the two users Alice and Bob. Listing all users We can inspect the state of all users in our OpenPGP CA instance like this: $ oca -d example.oca user list OpenPGP key for 'Alice Adams' fingerprint F27CB2E92C3E01DA1C656FB21758251C75E25DDD user cert (or subkey) signed by CA: true user cert has tsigned CA: true - email alice@example.

Updating keys from WKD or a keyserver

Mon, 01 Jan 0001 00:00:00 +0000

Once you are managing a number of user keys in your CA, some of your users will eventually update their keys. For example they might extend the expiration date, add a subkey, or they might revoke their key by adding a revocation certificate to it. If your users publish such changes on a keyserver or via WKD, it is useful to obtain and merge these changes into your CA, so that your copy of their key is up-to-date.

Publishing keys as WKD or Keylist

Mon, 01 Jan 0001 00:00:00 +0000

OpenPGP CA serves as a repository of user keys within our organization. So when we want to publish OpenPGP keys for our organization, exporting those keys from OpenPGP CA is a convenient possibility. There are several ways to publish keys: Web Key Directory (WKD), GPG Sync-style Keylist, Key server (internal or public), LDAP. Of these, OpenPGP CA currently automates exporting as WKD and Keylist. Publish keys as a WKD Initialize an OpenPGP CA instance with test users If we have no OpenPGP CA instance at hand, we set up a fresh one and create two users:

Revoking a user key

Mon, 01 Jan 0001 00:00:00 +0000

Revoking a Key Revoking an OpenPGP key means that we publish a statement saying that the key should not be used anymore. The statement may include a reason why the key shouldn’t be used (e.g., it has been compromised, or the user simply has a new one), and when the revocation should come into effect. The statement is a machine readable, cryptographic artifact and is called a “revocation certificate”.

Bridging OpenPGP CA instances

Mon, 01 Jan 0001 00:00:00 +0000

Until now, we’ve shown how to use OpenPGP CA to make it easy for users (or rather, their software) in the same organization to authenticate each other’s keys. It is also possible for OpenPGP CA admins to connect their organizations so that any user at one organization can authenticate the OpenPGP keys of users at the other organization and vice versa. We call this type of setup a bridge between two OpenPGP CA instances.

Revocation certificates for a CA key

Mon, 01 Jan 0001 00:00:00 +0000

Why would a CA key need to be revoked? In the (hopefully) unlikely case that the private key material of an OpenPGP CA instance is compromised, any cryptographic statements by that CA key are suspect. No one should rely on statements by that CA key anymore (because they could be forged by a third party). To disseminate the information that the CA key has become untrustworthy, a revocation certificate needs to be published.

CA key rotation

Mon, 01 Jan 0001 00:00:00 +0000

CA key rotation Under some circumstances, you may want to start over with a fresh CA key. Maybe you want to issue a CA key with a stronger algorithm - or, key rotation would be necessary if your CA key got compromised. Note: A user-friendly mechanism for replacing the CA key is not implemented yet. Currently, the CA key can only be replaced by starting over with a fresh CA database and re-importing user keys, or by manually editing the (sqlite) CA database file.

Usage in Docker

Mon, 01 Jan 0001 00:00:00 +0000

Running in Docker You can use OpenPGP CA in container systems (such as Docker or podman). The project repository contains a build file at /Dockerfile. With docker you can build the image by running: $ docker build --tag oca ./ This command builds the image and tags it as oca. Once built, you can run the image as: $ docker run --rm oca You should see the help output.

REST service

Mon, 01 Jan 0001 00:00:00 +0000

OpenPGP CA as a REST service It may be desirable to use OpenPGP CA as a REST service (e.g. when integrating OpenPGP CA functionality into a web-frontend). For these use cases, we offer the OpenPGP CA functionality as a REST service. Building The REST daemon can be built as a binary openpgp-ca-restd from the project source (via cargo build). Container image We also offer a container image named openpgp-ca-restd, which can be built from our Dockerfile.

Using the REST service in Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Running in Kubernetes You can also use openpgp-ca-restd in Kubernetes. The OpenPGP CA repository contains kustomizations as /kustomize/ that helps you use the openpgp-ca-restd server in k8s. To get started with deploying the openpgp-ca-restd server you will need to create a kustomization file: # kustomization.yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization namespace: openpgp-ca resources: - git@gitlab.com:openpgp-ca/openpgp-ca/kustomize/restd You will also need to patch in the domain to ensure the CA is properly configured

Security/usability tradeoffs

Mon, 01 Jan 0001 00:00:00 +0000

Calibrating OpenPGP CA security/usability tradeoffs OpenPGP CA prescribes some aspects of how to use OpenPGP within an organization. However, there are also some degrees of freedom in how to deploy OpenPGP CA. Organizations need to make some decisions before rolling out OpenPGP CA. Protecting the CA key When setting up a new CA, the operator needs to choose between two modes of handling the CA key: OpenPGP card-backed, and Softkey-backed.

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

openpgp-ca-lib 0.12.1 [2023-02-14] Fixes crashes of oca’s wkd export and user list commands when user keys in the database are considered invalid by Sequoia’s StandardPolicy. OpenPGP CA 0.12 [2023-02-03] The binary was renamed from openpgp-ca to oca Support for OpenPGP card devices as a backend for the CA key was added The ‘ca init’ syntax was changed from openpgp-ca ca init <domain> to oca ca init --domain <domain> softkey (previously, software backed CA instances were the implicit default)

Preview: OpenPGP card-backed CAs

Sat, 24 Sep 2022 01:30:00 +0100

Today, we want to share our excitement about the upcoming support for OpenPGP card-backed instances of OpenPGP CA, and take a look at how an OpenPGP card-backed CA instance will be operated.

OpenPGP CA has received support from the NLnet foundation during its initial development. Now we’re receiving a second round of support through the NGI Assure Fund, to add support for hardened modes of operation.

TL;DR

With the upcoming version of OpenPGP CA, initializing a CA that is backed by an OpenPGP card takes just one step. This step automatically generates a new CA key, uploads the key material to your card, and sets up the CA database (in a file named test.oca, here):

$ openpgp-ca -d test.oca ca init example.org card FFFE:01234567 on-host

This card-backed OpenPGP CA instance can be used in exactly the same ways as a soft-key backed CA. For example, you can import and certify a user’s key like this:

$ openpgp-ca -d test.oca user import --key-file alice.pub --email alice@example.org

OpenPGP CA on IRC

Thu, 20 May 2021 12:30:00 +0100

As of today, you can meet the OpenPGP CA team - as well as other users - on the OFTC IRC network, in the channel #openpgp-ca. Come hang out with us there, and tell us about the projects you’re building on top of OpenPGP CA!

OpenPGP CA 0.10.1 released

Fri, 07 May 2021 10:30:00 +0100

Today we’re happy to announce the first release of the OpenPGP CA 0.10.x series. The code for OpenPGP CA 0.10.1 is tagged on gitlab.

crates.io

Starting with this release, we’re publishing to crates.io. So from now on, you can conveniently cargo install openpgp-ca.

Right now, we’re publishing two crates:

The openpgp-ca CLI tool: crates.io/crates/openpgp-ca
The underlying library that implements the functionality of OpenPGP CA (the CLI tool is a slim wrapper around this library): crates.io/crates/openpgp-ca-lib

Note: for the time being, there is no release of the OpenPGP CA REST daemon on crates.io, since it depends on rocket 0.5, which is not yet released.

While we’re talking crates, there’s also the related crates.io/crates/openpgp-keylist/, which is used by openpgp-ca for exporting to Keylist format.

Contact us

Mon, 01 Jan 0001 00:00:00 +0000

Come join us for any questions, feedback, or support! We’re on: Matrix The OFTC IRC network in #openpgp-ca You can contact Heiko via email (PGP key).

Features

Mon, 01 Jan 0001 00:00:00 +0000

Manage revocation certificates The design of OpenPGP CA leans strongly towards user autonomy in the handling of OpenPGP keys. In particular, we do not support key escrow (i.e. centrally managing private key material). However, as an optional feature, we support centrally managing revocation certificates in an organization’s OpenPGP CA instance. Possible use cases for this feature include: your organization can revoke the binding of the OpenPGP key to the User ID that links the key to your organization.

Pricing

Mon, 01 Jan 0001 00:00:00 +0000

OpenPGP CA is Free Software OpenPGP CA is Free Software (under the GPL v3), so you are of course always allowed to use OpenPGP CA free of charge. Paid support However, we’re happy to offer consulting, support or development work. Support contracts are a good way for organizations to financially back the project. We offer a standard package that includes one-time training and guidance for rolling out OpenPGP CA in your organization.