---
name: "voa"
section: "5"
platform: "linux"
package: "voa"
version: "0.7.6-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/voa/5"
---

# voa(5)

Configuration file format for VOA technology backends.

## NAME

**voa** - Configuration file format for VOA technology backends.

## DESCRIPTION

A YAML configuration file that encodes the *OS*-level and/or *context*-level settings for technology backends used in the *File Hierarchy for the* ***V****erification of* ***O****S* ***A****rtifacts* (**VOA**\[1\]).

Each configuration file tracks a **VOA** *OS* identifier in its file name, (e.g. “arch.yaml” for the “arch” *OS*, “debian:13.yaml” for the “debian:13” *OS* - refer to the **VOA** specification for details on the allowed character set).

Each configuration file must be a regular file to be considered.

### Directories and precedence

The handling of configuration files is based on the **Configuration Files Specification**\[2\].

For system users **voa** files are read from the system **VOA** directories “/usr/share/voa/” and “/usr/local/share/voa/”, the volatile runtime directory “/run/voa/” and the local administration directory “/etc/voa/”. For real users, in addition to the system-wide configuration directories, **voa** files are also read from “voa/” directories in “$XDG\_CONFIG\_DIRS” and from the “voa/” directory in “$XDG\_CONFIG\_HOME” (see **XDG Base Directory Specification**\[3\]).

The order of the aforementioned directories describes the order of precedence in increasing priority. A file from a directory with higher priority fully replaces one from a directory with lower priority (e.g. “/etc/voa/example.yaml” replaces “/usr/share/voa/example.yaml”, “~/.config/voa/example.yaml” replaces “/etc/voa/example.yaml”).

The **voa** configuration file format can also be used in drop-in configuration files. A drop-in is created for a specific *OS* by adding a **voa** configuration file in an override directory in one of the configuration directories (e.g. “/etc/voa/example.yaml.d/99-custom-repo.yaml” providing settings for a custom repository on the “example” *OS*, which overrides the more generic technology settings of the *OS* in “/usr/share/voa/example.yaml”). Note that drop-in configurations are read in lexicographic order, based on their file name, regardless of the directory precedence of their location.

Each **voa** configuration file can be masked by creating a symlink to /dev/null in its place (e.g. “/etc/voa/example.yaml -\> /dev/null” will cause the file “/usr/share/voa/example.yaml” to not be considered).

### Merging of built-in defaults, OS and context-level settings

When deriving *OS* or *context*-level technology settings from **voa** configuration files, built-in defaults may be considered.

After reading all configuration and drop-in configuration files, the available *OS*-level technology settings are constructed from them, with unset fields populated using already existing *OS*-level settings, or built-in defaults.

Eventually, the available *context*-level technology settings are constructed from the configuration and drop-in configuration files, with unset fields populated using - depending on availability - *OS*-level defaults, or built-in defaults.

**NOTE**: The following merging logic applies - unless stated otherwise - for all optional fields in the configuration file objects: If an optional field is omitted or set to `null`, a concrete value for it is derived either from *OS*-level, or if not provided there either, built-in defaults. While this allows for rich override and inheritance logic, it also implies the necessity to be explicit where necessary!

If an *OS* is not covered by a specific configuration or drop-in configuration file, the built-in defaults apply.

## FILE FORMAT

The file must contain valid YAML data and all of the following described required fields and values must be present. Invalid **voa** files are ignored.

### “default\_technology\_settings” object

The top-level object in the file which contains option objects for each available technology backend used in VOA.

**WARNING**: For the **voa** file as a whole to be considered valid, this object must be defined, if the **“contexts”** list is empty!

### “openpgp” object

The object describes the settings for the OpenPGP backend. Verification is based on **OpenPGP signatures**\[4\] and **OpenPGP certificates**\[5\]. Several verification methods are available.

### “num\_data\_signatures” number

The *optional* number of **OpenPGP signatures** from individual issuing **OpenPGP certificates** required for an artifact to be considered verified.

If set, the value must be a non-zero, positive integer (built-in default: *1*).

### “verification\_method” object

The method used to verify **OpenPGP signatures** using **OpenPGP certificates**. The value must be one of the following objects.

### “plain” verification method object

The “plain” verification method for **OpenPGP signatures** is a basic form of verification, that only considers *artifact verifiers* but no *trust anchors*. With it, one or more of the found *artifact verifiers* for a verification query must be used to successfully verify one or more **OpenPGP signatures**.

To constrain the set of **OpenPGP certificates** allowed as *artifact verifiers*, it can be filtered by domain name matches against valid **OpenPGP User IDs**\[6\] and/or **OpenPGP fingerprint**\[7\]. If no filters are defined, all **OpenPGP certificates** found in an *artifact verifier* location of a given *context* are considered as *artifact verifiers*.

### “identity\_domain\_matches” set

An *optional* set of valid domain names, that is used to filter *artifact verifiers*.

If the set has entries, a valid **OpenPGP certificate** found in the *artifact verifier* location of a given *context* is only considered if one of its valid **OpenPGP User IDs** matches one of the domain names.

If the set is empty (the built-in default), no filtering based on domain names occurs and any valid **OpenPGP certificate** found in the *artifact verifier* location of a given *context* is considered (assuming no other filter prevents it).

### “fingerprint\_matches” set

An *optional* set of **OpenPGP fingerprints**, that is used to filter *artifact verifiers*.

**WARNING**: The number of entries in this set must be equal to or greater than the number of required data signatures (see **“num\_data\_signatures”**) for the verification method as a whole to be considered valid!

If the set has entries, a valid **OpenPGP certificate** found in the *artifact verifier* location of a given *context* is only considered if its **OpenPGP fingerprint** matches one of the fingerprints from the set.

If the set is empty (the built-in default), no filtering based on fingerprints occurs and any valid **OpenPGP certificate** found in the *artifact verifier* location of a given *context* is considered (assuming no other filter prevents it).

### “trust\_anchor” verification method object

The “trust anchor” verification method for **OpenPGP signatures** is a basic form of *trust anchor* based verification, that considers both *artifact verifiers* and *trust anchors* when verifying a signature. With it, each *artifact verifier* must be certified by a specific number of the available *trust anchors* to be considered for the verification of **OpenPGP signatures**.

To constrain the set of valid **OpenPGP certificates** allowed as *artifact verifier*, it can be filtered by domain name matches against valid **OpenPGP User IDs**. To constrain the set of valid **OpenPGP certificates** allowed as *trust anchor*, it can be filtered by **OpenPGP fingerprints**.

### “required\_certifications” number

The *optional* number of **OpenPGP third-party certifications**\[8\] of *trust anchors* on *artifact verifiers* for an *artifact verifier* to be considered fully trusted. If set, the value must be a non-zero, positive integer (built-in default: *3*).

### “artifact\_verifier\_identity\_domain\_matches” set

An *optional* set of valid domain names, that is used to filter *artifact verifiers*.

If the set has entries, a valid **OpenPGP certificate** found in the *artifact verifier* location of a given *context* is only considered if one of its valid **OpenPGP User IDs** matches one of the domain names from the set and it has the required amount of **OpenPGP third-party certifications** from valid *trust anchors*.

If the set is empty (the built-in default), no filtering based on domain names occurs and any valid **OpenPGP certificate** found in the *artifact verifier* location which has at least one **OpenPGP User ID** with the required amount of **OpenPGP third-party certifications** from valid *trust anchors* is considered.

### “trust\_anchor\_fingerprint\_matches” set

An *optional* set of **OpenPGP fingerprints**, that is used to filter *trust anchors*.

**WARNING**: The number of entries in this set must be equal to or greater than the number of required certifications (see **“required\_certifications”**) for the verification method as a whole to be considered valid!

If the set has entries, a valid **OpenPGP certificate** found in the *trust anchor* location of a given *context* is only considered if its **OpenPGP fingerprint** matches one of the fingerprints from the set.

If the set is empty (the built-in default), no filtering based on fingerprints occurs and any valid **OpenPGP certificate** found in the *trust anchor* location of a given *context* is considered.

### “web\_of\_trust” verification method object

The **Web of Trust**\[9\] verification method for **OpenPGP signatures** is a flexible form of trust based verification, which relies on the **Berblom algorithm**\[10\]. It considers both *artifact verifiers* and *trust anchors*. With it, each *artifact verifier* must reach a configurable amount of trust to be considered for the verification of **OpenPGP signatures**. Here, the trust amount is calculated by a “Web of Trust” network, which relies on implicit or explicit trust roots and configurable trust amounts for partially trusted introducers in the network.

To constrain the set of valid **OpenPGP certificates** allowed as *artifact verifier*, it can be filtered by domain name matches against valid **OpenPGP User IDs**. To constrain the set of valid **OpenPGP certificates** allowed as *trust anchor*, it can be filtered by **OpenPGP fingerprints**.

### “flow\_amount” number

The *optional* trust amount required for a flow in a “Web of Trust” network to be considered “fully trusted”. This signifies the target trust amount that an *artifact verifier* must reach for it to be considered for the verification of **OpenPGP signatures**.

If set, the value must be a non-zero, positive integer (built-in default: *120*).

### “partial\_amount” number

The *optional* trust amount for a partially trusted introducer in a “Web of Trust” network. This signifies the trust amount of an **OpenPGP certificate** considered on a path between *trust anchor* and *artifact verifier*.

If set, the value must be an integer between *1* and *120* (built-in default: *40*).

### “roots” set of objects

An set of trust roots for the “Web of Trust. Each object in this set signifies an **OpenPGP certificate** that is considered as *trust root*, alongside its specific *trust amount*.

Each trust root is an object with the following two fields:

- •

  **“fingerprint”**: An **OpenPGP fingerprint**.

- •

  **“amount”**: The *optional* trust amount assigned to the trust root. If set, the value must be an integer between *1* and *120* (built-in default: *120*).

-

  **NOTE**: If this field is omitted, a concrete value is derived from built-in defaults.

If the set has entries, a valid **OpenPGP certificate** found in the *trust anchor* location of the VOA hierarchy for a given *context* is considered as *trust root* with the specific *trust amount* if its **OpenPGP fingerprint** matches that of a **“fingerprint”** in the set.

If the set is empty, any valid **OpenPGP certificate** found in the *trust anchor* location of the VOA hierarchy for a given *context* is considered as *trust root* with a *trust amount* of *120*.

### “artifact\_verifier\_identity\_domain\_matches” set

An *optional* set of valid domain names, that is used to filter *artifact verifiers*.

If the set has entries, a valid **OpenPGP certificate** found in the *artifact verifier* location of a given *context* is only considered if one of its valid **OpenPGP User IDs** matches one of the domain names from the set and it has the required target trust amount (see **“flow\_amount”**).

If the set is empty, no filtering based on domain names occurs and any valid **OpenPGP certificate** found in the *artifact verifier* location which has at least one **OpenPGP User ID** with the required target trust amount (see **“flow\_amount”**) is considered.

### “contexts” list of objects

A list of zero or more objects, that each provide a *context*-level override to the technology settings imposed by the *OS* (if any) or the built-in defaults.

**WARNING**: For the **voa** file as a whole to be considered valid, the **“default\_technology\_settings”** object must be defined, if this list is empty or the field is not set!

### “purpose” string

The **VOA** *purpose* of the *OS*, that is targeted. Refer to the VOA specification for details on the allowed character set.

### “context” string

The **VOA** *context* of the *OS*, that is targeted. Refer to the VOA specification for details on the allowed character set.

### “technology\_settings” object

Technology settings for the **“purpose”** and **“context”** of the *OS* targeted by the configuration file name (or drop-in directory name).

The settings in this object override the less specific *OS*-level or built-in technology settings. Refer to the **“default\_technology\_settings”** section for an overview of the expected object.

## EXAMPLES

### Defaults

The below represents the built-in defaults for technology settings.

```
default_technology_settings:
  openpgp:
    num_data_signatures: 1
    verification_method:
      trust_anchor:
        required_certifications: 3
        artifact_verifier_identity_domain_matches:
        trust_anchor_fingerprint_matches:
```

The configuration targets the basic “trust anchor” method for OpenPGP, requiring a single data signature for artifacts and at least three certifications on *artifact verifiers* from *trust anchors*.

The set of domain name matches for *artifact verifiers* and OpenPGP fingerprint matches for *trust anchors* are left empty on purpose, which means that no specific restrictions on those verifiers are imposed.

### OpenPGP “plain” verification method

The following configuration example targets the “plain” verification method for OpenPGP.

```
default_technology_settings:
  openpgp:
    num_data_signatures: 1
    verification_method:
      plain:
        identity_domain_matches:
          - example.org
          - sub.example.org
        fingerprint_matches:
          - d3b0f7c0b825ecbb0f0d7398072947e7b1537b6f
          - e242ed3bffccdf271b7fbaf34ed72d089537b42f
          - f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
```

Assuming that the above contents reside in the file “/usr/share/voa/example.yaml”, for the *OS* “example” the following verification rules apply:

A single data signature from a valid *artifact verifier* is required for artifacts to be verified. Further, the following restrictions are imposed on OpenPGP certificates found in the *artifact verifier* location of a specific *context* to be considered valid:

- •

  A valid **OpenPGP User ID** must match either the domain “example.org” or “sub.example.org”.

- •

  The **OpenPGP fingerprint** must match “d3b0f7c0b825ecbb0f0d7398072947e7b1537b6f”, “e242ed3bffccdf271b7fbaf34ed72d089537b42f”, or “f1d2d2f924e986ac86fdf7b36c94bcdf32beec15”

### OpenPGP basic “trust anchor” verification method

The following configuration example targets the basic “trust anchor” verification method for OpenPGP.

```
default_technology_settings:
  openpgp:
    num_data_signatures: 1
    verification_method:
      trust_anchor:
        required_certifications: 3
        artifact_verifier_identity_domain_matches:
          - example.org
          - sub.example.org
        trust_anchor_fingerprint_matches:
          - d3b0f7c0b825ecbb0f0d7398072947e7b1537b6f
          - e242ed3bffccdf271b7fbaf34ed72d089537b42f
          - f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
```

Assuming that the above contents reside in the file “/usr/share/voa/example.yaml”, for the *OS* “example” the following verification rules apply:

A single data signature from a valid *artifact verifier* is required for artifacts to be verified. Each *artifact verifier* must be certified by three *trust anchors*.

A valid **OpenPGP User ID** of a valid **OpenPGP certificate** found in the *artifact verifier* location of a specific *context* must match either the domain “example.org” or “sub.example.org” for the certificate to be considered as *artifact verifier*.

The **OpenPGP fingerprint** of a valid **OpenPGP certificate** found in the *trust anchor* location of a specific *context* must match either “d3b0f7c0b825ecbb0f0d7398072947e7b1537b6f”, “e242ed3bffccdf271b7fbaf34ed72d089537b42f”, or “f1d2d2f924e986ac86fdf7b36c94bcdf32beec15” for the certificate to be considered as *trust anchor*.

### OpenPGP “Web of Trust” verification method

The following configuration example targets the “Web of Trust” verification method for OpenPGP.

```
default_technology_settings:
  openpgp:
    num_data_signatures: 1
    verification_method:
      web_of_trust:
        flow_amount: 120
        partial_amount: 40
        roots:
          - fingerprint: d3b0f7c0b825ecbb0f0d7398072947e7b1537b6f
            amount: 120
          - fingerprint: e242ed3bffccdf271b7fbaf34ed72d089537b42f
            amount: 120
          - fingerprint: f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
            amount: 120
        artifact_verifier_identity_domain_matches:
          - example.org
          - sub.example.org
```

Assuming that the above contents reside in the file “/usr/share/voa/example.yaml”, for the *OS* “example” the following verification rules apply:

A single data signature from a valid *artifact verifier* is required for artifacts to be verified.

Each partially trusted introducer in the “Web of Trust” network is assigned a trust amount of 40. The trust amount required for a valid **OpenPGP certificate** found in the *artifact verifier* location of a given *context* to be considered “fully trusted” and thus for it to be considered as *artifact verifier* is 120.

The **OpenPGP fingerprint** of a valid **OpenPGP certificate** found in the *trust anchor* location of a specific *context* must match either “d3b0f7c0b825ecbb0f0d7398072947e7b1537b6f”, “e242ed3bffccdf271b7fbaf34ed72d089537b42f”, or “f1d2d2f924e986ac86fdf7b36c94bcdf32beec15” for the certificate to be considered as *trust anchor*. Each of these matching *trust anchors* is assigned a trust amount of 120.

### OS-level and context-level

The below represents an example of *OS* and *context*-level technology settings relying on the basic “trust anchor” verification method for OpenPGP. It is assumed that the contents reside in the file “/usr/share/voa/example.yaml”, thus targeting the *OS* “example”.

```
default_technology_settings:
  openpgp:
    num_data_signatures: 2
    verification_method:
      trust_anchor:
        artifact_verifier_identity_domain_matches:
          - example.org
        trust_anchor_fingerprint_matches:
          - 6132b58967cf1ebc05062492c17145e5ee9f82a8
          - 6eadeac2dade6347e87c0d24fd455feffa7069f0
          - b787a81c32997fd39a5f4c0188363902d3586e7b
          - d3b0f7c0b825ecbb0f0d7398072947e7b1537b6f
          - e242ed3bffccdf271b7fbaf34ed72d089537b42f
contexts:
  - purpose: package
    context: default
    technology_settings:
      openpgp:
        verification_method:
          trust_anchor:
            required_certifications: 4
            artifact_verifier_identity_domain_matches:
              - packages.example.org
  - purpose: image
    context: installation-medium
    technology_settings:
      openpgp:
        num_data_signatures: 1
        verification_method:
          trust_anchor:
            artifact_verifier_identity_domain_matches:
              - install.example.org
```

If a system using this configuration file does not have any other **voa** file, the built-in defaults apply for any unset fields in the *OS*-level technology settings and the *OS*-level technology settings apply for any unset fields in the *context*-level technology settings.

The above example illustrates, how *OS*-level defaults are handed down, if they are not set in the more specific *context*-level settings. For example, the **“trust\_anchor\_fingerprint\_matches”** in the *OS*-level defaults also apply to the *context*-level technology settings.

Relatedly, fields in *context*-level technology settings can override *OS*-level defaults. In the above example, the **“num\_data\_signatures”** are set to *2* on the *OS* level, but one of the *contexts* overrides it to require only *1*. Similarly, the **“required\_certifications”** in one of the *contexts* is overridden to *4* instead of the *OS*-level value of *3* (itself derived from the built-in defaults).

### Drop-ins for context-level overrides

When only providing *context*-level settings, the top-level **“default\_technology\_settings”** key can be omitted.

The following configuration example targets the “plain” verification method for OpenPGP. It is assumed that the contents reside in the file “/etc/voa/example.yaml.d/90-my-repo.yaml”, targeting the *OS* “example”.

```
contexts:
  - purpose: package
    context: my-repo
    technology_settings:
      openpgp:
        num_data_signatures: 1
        verification_method:
          plain:
            identity_domain_matches:
              - other.org
            fingerprint_matches:
              - bea43e7033e19327183416f23fe2ee1b64c25f4a
```

Assuming that also the configuration described in the **OS-level and context-level** example is present on the system, this configuration describes a specialization for a single package repository named “my-repo”. Technology settings enforced by the *OS* “example” are overridden and a different set of verification rules apply:

- •

  Only one data signature from valid *artifact verifiers* is required for each artifact.

- •

  The following restrictions are imposed by filters on the verifiers:

  - •

    Valid **OpenPGP certificates** found in relevant locations are only considered as *artifact verifiers*, if their **OpenPGP fingerprint** matches “bea43e7033e19327183416f23fe2ee1b64c25f4a”.

  - •

    Valid **OpenPGP certificates** found in relevant locations are only considered as *artifact verifiers*, if one of their valid **OpenPGP User IDs** matches the domain name “other.org”.

## SEE ALSO

[**voa**(1)](/voa/1.md)

## NOTES

- 1\.

  **VOA**

-

  ⟨https://uapi-group.org/specifications/specs/file\_hierarchy\_for\_the\_verification\_of\_os\_artifacts/⟩

- 2\.

  **Configuration Files Specification**

-

  ⟨https://uapi-group.org/specifications/specs/configuration\_files\_specification/⟩

- 3\.

  **XDG Base Directory Specification**

-

  ⟨https://specifications.freedesktop.org/basedir/latest/⟩

- 4\.

  **OpenPGP signature**

-

  ⟨https://openpgp.dev/book/signatures.html⟩

- 5\.

  **OpenPGP certificate**

-

  ⟨https://openpgp.dev/book/certificates.html⟩

- 6\.

  **OpenPGP User ID**

-

  ⟨https://openpgp.dev/book/certificates.html#user-ids⟩

- 7\.

  **OpenPGP fingerprint**

-

  ⟨https://openpgp.dev/book/certificates.html#fingerprint⟩

- 8\.

  **OpenPGP third-party certifications**

-

  ⟨https://openpgp.dev/book/signing\_components.html#third-party-certifications⟩

- 9\.

  **Web of Trust**

-

  ⟨https://codeberg.org/openpgp/wot⟩

- 10\.

  **Berblom algorithm**

-

  ⟨https://codeberg.org/Nukesor/berblom⟩