Verify Arch Linux artifacts using VOA/OpenPGP

2026-01-11·9 min·David Runge·Heiko Schaefer

Table of Contents

In the recent blog post on the work funded by Sovereign Tech Fund (STF), we provided an overview of the "File Hierarchy for the Verification of OS Artifacts" (VOA) and the voa project as its reference implementation.

VOA is a generic framework for verifying any kind of distribution artifacts (i.e. files) using arbitrary signature verification technologies.

The `voa` CLI ⌨️

The voa project offers the voa(1) command line interface (CLI) which makes use of the voa(5) configuration file format for technology backends. It is recommended to read the respective man pages to get an overview.

The following sections assume an Arch Linux system, with the voa-verifiers-arch and voa packages installed.

On other systems, it is possible to download the "voa-verifiers-arch" artifact of the latest release of archlinux-keyring and to place its contents in one of the relevant VOA load paths. Afterwards, follow the installation instructions for the voa(1) CLI.

Using VOA with the OpenPGP technology 🤝

In this article we will focus on the use of VOA with the OpenPGP technology backend for signature verification. This backend is available as part of the reference implementation of VOA in the voa project.

The big picture concepts in VOA are shared between all technology backends. However, some capabilities and details differ depending on technology.

We will start by looking at some common interactions with VOA:

Verifying the signatures of an Arch Linux package and installation medium.
Inspecting the verification configuration.
Inspecting verifiers.
Importing additional verifiers.

As an advanced usage example, we will look into setting up a custom VOA context for an unofficial package repository, with a separate policy configuration.

Additionally, we will take a brief glance at a way to verify all official Arch Linux package files for testing in a development environment.

Finally, we will provide a short overview of the state of other technology backends.

Verifying signatures 🔏

The voa-verify(1) command can be used to verify an artifact against a signature. Arch Linux relies on a configuration file for the OpenPGP technology backend (see arch.yaml) to enforce its own verification policy.

Based on this configuration, a single package file can be verified against the corresponding detached OpenPGP data signature using:

voa verify arch package default openpgp /var/cache/pacman/pkg/systemd-259-1-x86_64.pkg.tar.zst{,.sig}
✅ /var/cache/pacman/pkg/systemd-259-1-x86_64.pkg.tar.zst.sig 1766039593 02fd1c7a934e614545849f19a6234074498e9cee 0429897de5f3bdac537a30696d42bdd116e0068f

The output lists:

The detached signature file used for verification,
the signature's creation time,
the OpenPGP fingerprint of the primary key of the OpenPGP certificate, and
the OpenPGP fingerprint of the component key used for signing.

Similarly, the monthly installation medium can be verified, based on the designated verifiers:

voa verify arch image installation-medium openpgp archlinux-2026.01.01-x86_64.iso{,.sig}
✅ archlinux-2026.01.01-x86_64.iso.sig 1767267369 3e80ca1a8b89f69cba57d98a76a5ef9054449a5c 3e80ca1a8b89f69cba57d98a76a5ef9054449a5c

Inspecting the configuration of VOA technology backends 📄

In the verification examples above, the voa-verify(1) command implicitly relied on two inputs:

A voa(5) configuration file, which specifies which exact rules the OpenPGP technology is supposed to enforce in the context of the Arch Linux distribution.
A set of OpenPGP certificates that are used to determine if signatures are valid.

In this section we will look at the first point: The configuration that is active when verifying signatures with VOA in a given context.

As a uniform user-facing model for these settings, the voa project includes the voa(5) configuration file format, which defines exactly how verification with technology backends is done.

A backend technology like OpenPGP can offer a range of different approaches to package verification, such as:

Are specific identities required on valid verifiers?
Are trust anchors expected to authenticate the artifact verifiers?

Arch Linux uses the following configuration file in /usr/share/voa/arch.yaml, which describes the policy VOA uses for signature verification of Arch Linux artifacts:

default_technology_settings:
  openpgp:
    num_data_signatures: 1
    verification_method:
      trust_anchor:
        required_certifications: 3
        artifact_verifier_identity_domain_matches:
          - archlinux.org
        trust_anchor_fingerprint_matches:
          # Levente Polyak (Arch Linux Master Key) <anthraxx@master-key.archlinux.org>
          - d8afdda07a5b6edfa7d8ccdad6d055f927843f1c
          # Leonidas Spyropoulos (Arch Linux Master Key) <artafinde@master-key.archlinux.org>
          - 3572fa2a1b067f22c58af155f8b821b42a6fdcd7
          # Johannes Löthberg (Arch Linux Master Key) <demize@master-key.archlinux.org>
          - 69e6471e3ae065297529832e6ba0f5a2037f4f41
          # David Runge (Arch Linux Master Key) <dvzrv@master-key.archlinux.org>
          - 2ac0a42efb0b5cbc7a0402ed4dc95b6d7be9892e
          # Florian Pritz (Arch Linux Master Key) <florian@master-key.archlinux.org>
          - 91ffe0700e80619ceb73235ca88e23e377514e00

The voa-config(1) command allows introspection of the configuration in a given context. The command returns an explanation of the active policy:

voa config show arch
OpenPGP settings

🔏 Each artifact requires 1 valid data signature(s) from artifact verifiers to be successfully verified.

✅ Each artifact is verified using the "trust anchor" verification method.

📧 A valid certificate must have a valid User ID that uses one of the following domains and has 3 certification(s) from individual trust anchors on it for the certificate to be considered as artifact verifier:
⤷ archlinux.org

🐾 A valid certificate must match one of the following OpenPGP fingerprints to be considered as trust anchor:
⤷ 2ac0a42efb0b5cbc7a0402ed4dc95b6d7be9892e
⤷ 3572fa2a1b067f22c58af155f8b821b42a6fdcd7
⤷ 69e6471e3ae065297529832e6ba0f5a2037f4f41
⤷ 91ffe0700e80619ceb73235ca88e23e377514e00
⤷ d8afdda07a5b6edfa7d8ccdad6d055f927843f1c

📝 The following sources have been considered for the creation of the settings:
⤷ Config file: /usr/share/voa/arch.yaml
⤷ Built-in defaults

It can also be used to list the origins of all available configurations available to a user:

voa config list
🖥 arch
⤷ Config file: /usr/share/voa/arch.yaml
⤷ Built-in defaults
🖥 example
⤷ Config file: /home/user/.config/voa/example.yaml
⤷ Built-in defaults

Listing verifiers 👁️‍🗨️

VOA specifies a hierarchical directory structure. For each type of artifact, a specific subset of this structure provides a set of "verifiers" that must be used for artifact verification.

Verifiers may reside in various load paths on the system. To view a list of verifiers in a particular context, use voa-list(1).

E.g. to show the paths of all verifiers considered for package verification on an OS named "test", use:

voa list test package

To do the same for the Arch Linux distribution, use:

voa list arch package

To show the paths of all trust anchors considered for authenticating verifiers to use for signature verification of Arch Linux packages, use:

voa list arch trust-anchor-package

Importing certificates as verifiers ↩️

Using voa-import(1) it is possible to import an OpenPGP certificate into the appropriate location in a VOA hierarchy, for use as a verifier.

Note, that based on the precedence of the VOA load paths, it is possible to import versions of an existing OpenPGP certificate into different file system locations. The content of such variants will usually be merged at runtime by the VOA OpenPGP backend.

Here, the voa-openpgp crate supports the import of certificates in different formats:

An OpenPGP certificate in a single file.
A directory containing OpenPGP packets of a single OpenPGP certificate.
The custom destructured directory structure for a single OpenPGP certificate as used in archlinux-keyring.

The following examples each import an OpenPGP certificate as verifier for package files on an OS named "test" to the runtime load path of the current user.

Importing a single certificate 🔐

Assuming that alice.cert is a file that contains an OpenPGP certificate, we can import it e.g. as a verifier for package files in any repository:

voa import --runtime --input alice.cert --context default test package

Importing a split certificate 🔐

Certificates may be split up into individual files that contain OpenPGP packets, collectively stored in a directory. Here, we assume that the directory alice/ contains the split files.

ls alice/
alice.cert-000000-PublicKey alice.cert-000001-UserId  alice.cert-000002-Signature
voa import --runtime --input alice/ --context default test package

Importing a certificate from the archlinux-keyring structure 🔐

The archlinux-keyring project chose to arrange the OpenPGP packets of each tracked OpenPGP certificate in a particular directory structure.

After cloning the repository, it is possible to directly import the packets of an OpenPGP certificate from these directory structures, e.g.:

git clone https://gitlab.archlinux.org/archlinux/archlinux-keyring/
cd archlinux-keyring/
voa import --runtime --input keyring/packager/dvzrv/991F6E3F0765CF6295888586139B09DA5BF0D338/ --context default test package

Setting up a custom verification context ✨️

In the following example we will add an override voa(5) configuration file and an additional OpenPGP certificate to the VOA hierarchy. These additions will define a working signature verification policy for an unofficial repository on Arch Linux.

Here, we will define a policy for a custom package repository named "my-repo". We specify a "context" for this repository, in which we override the default Arch Linux voa(5) configuration.

By storing the following configuration as /etc/voa/arch.yaml.d/10-my-repo.yaml we provide a specific override for this unofficial package repository:

contexts:
  - purpose: package
    context: my-repo
    technology_settings:
      openpgp:
        num_data_signatures: 1
        verification_method:
          plain:
            identity_domain_matches:
              - example.org
            fingerprint_matches:
              - f1d2d2f924e986ac86fdf7b36c94bcdf32beec15

We can inspect this policy with voa-config(1), and see how it differs from the one used by Arch Linux:

voa config show --purpose package --context my-repo arch
OpenPGP settings

🔏 Each artifact requires 1 valid data signature(s) from artifact verifiers to be successfully verified.

✅ Each artifact is verified using the "plain" verification method.

📧 A valid certificate must have a valid User ID that uses one of the following domains to be considered as artifact verifier:
⤷ example.org

🐾 A certificate must match one of the following OpenPGP fingerprints to be considered as artifact verifier:
⤷ f1d2d2f924e986ac86fdf7b36c94bcdf32beec15

📝 The following sources have been considered for the creation of the settings:
⤷ Drop-in config file: /etc/voa/arch.yaml.d/10-my-repo.yaml
⤷ Built-in defaults

Assuming a valid OpenPGP certificate with the OpenPGP fingerprint f1d2d2f924e986ac86fdf7b36c94bcdf32beec15 is present (e.g. in /etc/voa/arch/package/my-repo/openpgp/f1d2d2f924e986ac86fdf7b36c94bcdf32beec15.openpgp), it is now possible to verify signatures for package files with it:

voa verify arch package my-repo openpgp my-package-1.0.0-1-x86_64.pkg.tar.zst{,.sig}
✅ my-package-1.0.0-1-x86_64.pkg.tar.zst.sig 1767267369 f1d2d2f924e986ac86fdf7b36c94bcdf32beec15 f1d2d2f924e986ac86fdf7b36c94bcdf32beec15

dev-scripts 👷

The ALPM project includes the dev-scripts testing tool for developers. It allows running tests against several targets, including the OpenPGP verification of all packages in the official repositories.

To try this out, clone the project's repository and download all packages in the official repositories.

Note: Be aware that this downloads around 100GB of data! You can limit the download amount by only targeting a specific repository (e.g. core).

git clone https://gitlab.archlinux.org/archliunx/alpm/alpm
cd alpm
cargo run --release --bin dev-scripts -- test-files download packages

Once downloaded, it is possible to verify all package files with their corresponding detached OpenPGP data signature.

cargo run --release --bin dev-scripts -- test-files test signatures
    Finished `release` profile [optimized] target(s) in 0.36s
     Running `/home/user/Downloads/alpm/.cargo/runner.sh target/release/dev-scripts test-files test signatures`
  [00:00:41] [████████████████████████████████████████] (15037/15037, ETA 0s)

Verification speed will vary depending on your available resources.

Further technology backends 🚀

VOA is designed as a generic and extensible solution for the verification of OS artifacts.

Other OSes are encouraged to use it for their respective needs.

At the time of writing, only the OpenPGP technology backend is fully specified and implemented in the voa project. The voa-openpgp crate itself is currently still awaiting the integration of the "Web of Trust" verification method based on the novel "Berblom" algorithm.

A proof of concept for an X.509 technology backend exists and we hope to progress on its full specification and integration this year.

In addition, external contributors have shown interest in adding a technology backend for signify (see voa#24).

If you are an expert in a specific signature technology, and want to collaborate, be sure to reach out! We would love to hear from you.

The voa CLI ⌨️