systemd-report-sign-tpm2@.service

systemd

systemd-report-sign-tpm2.socket

systemd-report-sign-tpm2

Sign system reports with a set of signed TPM2 attestations

systemd-report-sign-tpm2@.service

systemd-report-sign-tpm2.socket

/usr/lib/systemd/systemd-report-sign-tpm2

Description

systemd-report-sign-tpm2@.service is a system service that signs system reports generated by systemd-report(1). It is a signing backend for the --sign= logic of that tool: it implements the io.systemd.Report.Signer.Sign() Varlink method and is reached via a socket linked into the /run/systemd/report.sign/ directory, named tpm2.

The service is socket-activated (one instance per connection) via systemd-report-sign-tpm2.socket. Rather than returning a single signature, it uses a TPM2 device to generate a set of signed attestations that also bind the report digest passed to it, together providing a verifier with evidence about the state of the system that produced the report.

The returned report consists of several components. Some of these carry a JSON encoded attestation structure (TPMS_ATTEST) and its corresponding signature. The signature is provided as a JSON encoded TPMT_SIGNATURE structure and in PEM encoded form. The components are:

A PCR quote, generated with TPM2_Quote. This contains the JSON encoded attestation and the corresponding signature.
One attestation per NvPCR, generated with TPM2_NV_Certify. Each of these contain the JSON encoded attestation structure and its signature. In addition to this, each one also includes the readable name of the NvPCR, the NV index public area (as a JSON encoded TPMS_NV_PUBLIC structure), and a JSON blob of authenticated data (the NvPCR name and priority) that is digested and supplied as the qualifying data to the certify command.
A certification of the TPM's storage root key (SRK), generated with TPM2_Certify. This contains the JSON encoded attestation and the corresponding signature. The component also includes the public area of the SRK, as a JSON encoded TPMT_PUBLIC structure. Marshalled into a TPM2B_PUBLIC structure, this is the format accepted by the --tpm2-device-key= switch of systemd-cryptenroll(1) and systemd-repart(8). The certification proves to a verifier that the SRK resides in the same TPM as the attestation key, so that secrets sealed to it, sealing to which requires no access to the TPM, can only be unsealed by the reporting system. As TPM2_Clear replaces the SRK, a certification of the same SRK in a later report is also evidence that the TPM has not been cleared in between. If no SRK exists yet, one is created and persisted at the usual handle, which requires the authorization value of the TPM's owner hierarchy to be empty. If the SRK cannot be acquired, or the object at its handle cannot be authorized with an empty password, the report is generated without this component. The same applies if the object lacks the noDA attribute, as a failed authorization attempt would then count towards the TPM's dictionary attack protection. Checking that the attributes of the certified key are those of a storage key that cannot leave the TPM is up to the verifier.
One component per reported TPM property, generated with TPM2_GetCapability. Each of these contain the property and its value as a JSON encoded TPMS_TAGGED_PROPERTY structure, as well as a boolean indicating the value of the moreData parameter returned from the TPM. These components contain no signature of their own, but the response is included in the audit session digest.
One component per reported TPM permanent handle authorization policy, generated with TPM2_GetCapability. Each of these contain the handle, the policy digest algorithm, and the policy digest (if the algorithm is not NULL) as a JSON encoded TPMS_TAGGED_POLICY structure, as well as a boolean indicating the value of the moreData parameter returned from the TPM. These components contain no signature of their own, but the response is included in the audit session digest. Note that these components are omitted on TPMs that don't support TPM_CAP_AUTH_POLICIES.
An audit session attestation, generated with TPM2_GetSessionAuditDigest. This is always the last component. The report digest passed in via Varlink is supplied as its qualifying data. All other components are generated using this audit session.

The report additionally includes the measurement event log, and the public area of the signing key. The public area is provided as a JSON encoded TPMT_PUBLIC structure, and in PEM encoded form.

The preceding components are all executed under the audit session, and the report is only generated if that session remains exclusive throughout. Because the audit session attestation records whether the session was still exclusive when it was signed, this provides evidence to a verifier that the report is a single, consistent snapshot of the system, with no other TPM commands interleaved while it was generated.

The set of attested PCRs, NvPCRs, TPM properties and permanent handle authorization policies is currently fixed. It covers all firmware PCRs except PCR 6, all other S-RTM PCRs except the IMA PCR (which is not useful without the IMA log), all defined NvPCRs, the TPM_PT_PERMANENT, TPM_PT_MAX_AUTH_FAIL, TPM_PT_LOCKOUT_INTERVAL and TPM_PT_LOCKOUT_RECOVERY TPM properties, and the authorization policies for the storage, endorsement and lockout hierarchies. Note that authorization policies are omitted on TPMs that don't support TPM_CAP_AUTH_POLICIES

Signing key

The attestation signing key is stored as a JSON file named default.key in /var/lib/systemd/report.sign.tpm2/. Three kinds of key are supported: an ordinary object protected by an existing persistent object such as the SRK or EK, a persistent object, and a primary object that is recreated from a template on each use. In all cases the key must be a restricted signing key. If no key exists, an ordinary key is generated automatically on first use.

For ordinary and primary keys, the loaded object context is cached in the service's runtime directory as /run/systemd/report.sign.tpm2/default.context and reused on subsequent invocations, avoiding a repeated TPM2_Load (which requires authorization with the parent key) or primary key recreation.

The key may optionally have an associated voucher, stored alongside it as default.voucher. This is an opaque credential — for example one issued by a CA during onboarding — that is attached to the signed report and presented to a verifier as proof that the attestation key is authentic. It is deliberately not required to be any particular format (such as an X.509 certificate).