systemd/man/systemd-report-sign-tpm2@.service.xml

<?xml version="1.0"?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="systemd-report-sign-tpm2_.service" conditional='HAVE_OPENSSL HAVE_TPM2'
          xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>systemd-report-sign-tpm2@.service</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd-report-sign-tpm2@.service</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd-report-sign-tpm2@.service</refname>
    <refname>systemd-report-sign-tpm2.socket</refname>
    <refname>systemd-report-sign-tpm2</refname>
    <refpurpose>Sign system reports with a set of signed TPM2 attestations</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><filename>systemd-report-sign-tpm2@.service</filename></para>
    <para><filename>systemd-report-sign-tpm2.socket</filename></para>
    <para><filename>/usr/lib/systemd/systemd-report-sign-tpm2</filename></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

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

    <para>The service is socket-activated (one instance per connection) via
    <filename>systemd-report-sign-tpm2.socket</filename>. 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.</para>

    <para>The returned report consists of several signed components, each carrying a JSON encoded
    attestation structure and its corresponding signature. The signature is provided as a JSON encoded
    <constant>TPMT_SIGNATURE</constant> structure and in PEM encoded form. The signed component types are:</para>

    <itemizedlist>
      <listitem><para>A PCR quote, generated with <constant>TPM2_Quote</constant></para></listitem>

      <listitem><para>One attestation per NvPCR, generated with <constant>TPM2_NV_Certify</constant>. Each
      component also includes the readable name of the NvPCR, the NV index public area (as a JSON encoded
      <constant>TPMS_NV_PUBLIC</constant> 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.</para></listitem>

      <listitem><para>An audit session attestation, generated with
      <constant>TPM2_GetSessionAuditDigest</constant>. This is always the last component. The report digest
      passed in via Varlink is supplied as its qualifying data.</para></listitem>
    </itemizedlist>

    <para>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 <constant>TPMT_PUBLIC</constant> structure, and in PEM
    encoded form.</para>

    <para>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.</para>

    <para>The set of attested PCRs and NvPCRs 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), and all defined
    NvPCRs.</para>
  </refsect1>

  <refsect1>
    <title>Signing key</title>

    <para>The attestation signing key is stored as a JSON file named <filename>default.key</filename> in
    <filename>/var/lib/systemd/report.sign.tpm2/</filename>. 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.</para>

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

    <para>The key may optionally have an associated <emphasis>voucher</emphasis>, stored alongside it as
    <filename>default.voucher</filename>. 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).</para>
  </refsect1>

  <!-- Note: we do not document the command line switches here. The systemd-report-sign-tpm2 binary itself
       should not be invoked by users, but only as a service. Use systemd-report(1) to generate signed
       reports. -->

  <refsect1>
    <title>See Also</title>
    <para><simplelist type="inline">
      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-report</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
    </simplelist></para>
  </refsect1>

</refentry>