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 Verification of OS Artifacts (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)
NOTES
-
VOA
https://uapi-group.org/specifications/specs/file_hierarchy_for_the_verification_of_os_artifacts/
-
Configuration Files Specification
https://uapi-group.org/specifications/specs/configuration_files_specification/
-
XDG Base Directory Specification
-
OpenPGP signature
-
OpenPGP certificate
-
OpenPGP User ID
-
OpenPGP fingerprint
-
OpenPGP third-party certifications
https://openpgp.dev/book/signing_components.html#third-party-certifications
-
Web of Trust
-
Berblom algorithm