Trust policy #

A trust policy is a directory of files. For example, trusted root keys and the number of signatures needed to consider an OS package valid are defined in it. The location of the trust policy is defined by the components that require it, see the stboot and stprov system documentation.

Overview #

The following files are part of the trust policy directory:

• trust_policy.json: general settings in key-value format
• ospkg_signing_root.pem: OS package signing keys
• tls_roots.pem: TLS signing keys

Each of these files, their formats, and meanings are described next.

General settings #

The general trust policy settings are expressed as key-value pairs in JSON format. These settings are stored in a file named trust_policy.json.

ospkg_signature_threshold #

The number of signatures needed to consider an OS package valid. Each valid signature needs to correspond to a distinct OS package signing key.

The OS package signature threshold must be larger than zero.

ospkg_fetch_method #

Determines how OS packages are located. The following values are supported:

• “initramfs”: read the OS package from the initramfs
• “network”: read OS packages from a web server using HTTP(S)

The exact initramfs location or web server URL(s) are configured in a separate host configuration, see the OS package pointer setting for details.

Example #

{
  "ospkg_signature_threshold": 2,
  "ospkg_fetch_method": "network"
}

OS package signing keys #

The OS package signing keys are organized into a hierarchy starting with a single trusted root key. The root key can be used to sign OS packages directly, or to sign leaf keys that in turn sign OS packages. Intermediate keys are not supported, which means that the maximum certificate length is two.

The keys in the OS package signing hierarchy are encapsulated as X.509 certificates in PEM format. The PEM header must use the label “CERTIFICATE”. For successful chain building, the root certificate must set the cA-bit in the basic constraints extension. The maximum path length is irrelevant because intermediate certificates are anyway not supported. If the key-usage bits are set (optional), the root certificate must contain the keyCertSign bit.

For a certificate chain to be valid, it must chain back to the trusted root stored in ospkg_signing_root.pem. All certificates also need to be unexpired, as specified by the NotBefore and NotAfter timestamps.

There is no revocation mechanism. The only way to rotate keys is to provision a new trust policy, or to rely on the system time and the configured certificate expiry dates. Another way to deal with churn (e.g., an employee that quits) is to increase the ospkg_signature_threshold so no signer can act on their own.

Only Ed25519 keys and signatures are supported. How to sign a certificate in a chain using Ed25519 is defined by RFC 8410. Please note that signing of an OS package with a leaf key is different from signing a certificate.

TLS roots #

The file tls_roots.pem contains one or more trusted X.509 root certificates in PEM format. These root certificates are used to establish secure TLS connections while downloading OS packages over a network.

If the OS package web servers use Let’s Encrypt, then their root certificate in PEM format could be downloaded and stored as tls_roots.pem. If all of the web’s certificate authorities should be configured, files like ca-certificates.crt from the ca-certificates package on Debian could be used instead. Nothing prevents users from deploying their own self-signed certificates to side-step the web’s certificate authorities.