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
• ospkg_trust_policy: Sigsum trust policy
• decryption_identities: OS package decryption 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 one or more trusted root keys. The root keys 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”. A root certificate used to sign leaf keys must have the CA-bit set 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 one of the trusted root certificates 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. To deal with keys that ideally should be revoked (e.g., an employee that quits), one may want to increase the ospkg_signature_threshold so that no signer can act on their own, and require transparent signatures, so that unexpected key usage can be detected.

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.

Compatibility note: Support for multiple trusted root certificates was added in st-1.3.0. Previous versions require that the ospkg_signing_root.pem file contains exactly one 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.

Sigsum trust policy #

If the file ospkg_trust_policy exists, that means that all OS package signatures must include a Sigsum proof of logging. This makes signatures transparent, by enforcing public logging of all signatures. The Sigsum trust policy specifies the keys of recognized logs, the keys of trusted witnesses, and the quorum (e.g., m-of-n) of witnesses required.

The Sigsum submission key (i.e., the key used to sign an OS package, corresponding to the submitter signature and key hash in the logged entry) must chain back to one of the root certificates, as described above.

Note that enabling Sigsum signatures in the trust policy only enforces transparency for the OS package signatures, not for certificate issuance. When using Sigsum signatures, it is recommended to only include leaf certificates (no CA bit) in the list of trusted root certificates. This ensures that the set of accepted signing keys is closed, and enables log monitoring to identify all relevant signatures.

Compatibility note: this feature was added in st-1.3.0.

OS package decryption keys #

The file decryption_identities is optional. When provided, it enables mandatory decryption of both the OS package and its associated descriptor using the age tool, as an additional layer of transport encryption. Decryption applies only to OS packages and descriptors that are fetched over the network.

When present, the file must contain one or more decryption keys (identities) in the AGE X25519 recipient format with one key per line. Empty lines and ones starting with “#” are ignored. OS packages are only accepted if both files can be decrypted successfully (this means that unencrypted files are rejected).

Compatibility note: this feature was added in st-1.2.0.