Skip to content

Pinning what the module trusts

The signing secrets, and the CA certificates of the timestamp authorities, are configuration. Configuration lives in the database. So somebody who can write the database can add a signing secret of their own, rewrite entries, sign them again with it, and verification accepts them. The same person can swap in a CA of their own and issue timestamps over the rewritten chain.

settings.php is out of their reach. Listing there what you trust closes both doors. This is optional: without it, the module trusts everything configured, as it always did, and the status report warns about it.

Pin the signing secrets

  1. Print the lines for the secrets you have now (the values below are an example):
drush audit_trail:secret-fingerprints
$settings['audit_trail_trusted_secrets'] = [
  '4da5b88e' => '4da5b88e6c0f2a91d3b47e58c1f09a2b6e7d3c48a5f19b20c7e64d8a3b51f0e2',
  '21425c58' => '21425c58e8b0a7f3c2d91e46b5a0f7c3d18e92b4a6c05f71e3d8b29a40c6e7f1',
];

The same lines are on the secrets page, under the list, and on the status report while nothing is pinned.

  1. Paste them into settings.php and deploy.

  2. Check the status report: Audit Trail: trusted secrets reads Pinned in settings.php, and the secrets page shows Yes for each secret.

Each line is a secret id and its fingerprint. The id is the short name rows carry. The fingerprint is a 64-character HMAC computed from the secret, which reveals nothing about it. The id is its first eight characters: four bytes, few enough to be matched by trying random keys, which is why the whole fingerprint is pinned.

Once pinned, a secret that is not listed, or whose Key holds other bytes than its fingerprint says:

  • verifies nothing: every entry, checkpoint, segment and acknowledgment it signed is reported as broken;
  • signs nothing: it cannot be put in the signing role.

The same goes for an id no secret carries at all: a row naming one is a forgery, not a row whose secret is missing.

Rotating with pinned secrets

List the new secret before it signs:

  1. Add the new secret on its Key, as usual. It is pending. Note its ID on the secrets page.
  2. Run drush audit_trail:secret-fingerprints --add=<ID> and replace the block in settings.php with what it prints. Deploy.
  3. Put the new secret in the signing role.

Once pinned, the lines offered hold only the secrets already trusted, plus the ones you name with --add. A secret that merely appears in the configuration may have been added through the database, so it is never offered on its own: the status report warns about it instead.

Done the other way round, the signing role is refused with a message naming the setting, and nothing changes.

Keep the retired secrets in the list. Their entries are still verified with them. A secret whose Key is gone has no fingerprint to offer: restore its Key from backup before pinning, or what it signed reads as broken.

Pin the timestamp authorities' certificates

With the audit_trail_tsa submodule, the providers page shows the lines for every provider holding a CA certificate:

$settings['audit_trail_tsa_trusted_ca_certs'] = [
  'example_tsa' => '9c2e4b17a0d58f3e6c21b94a7d08e5f3c6b19a2d47e80f5c3a96d1b2e7f04a58',
];

The key is the provider's machine name, the value the SHA-256 of its certificate. Once pinned, a timestamp whose provider is not listed, or whose certificate changed, or was removed, fails verification instead of passing or reading as unchecked.

Changing a provider's certificate, for a renewed CA chain, means pasting its new line too.

What pinning does not cover

  • Somebody who can change settings.php or the code can change the list. That is the compromised host in the threat model.
  • The bytes of a pinned secret still have to be kept out of reach. With the configuration Key provider they are in the database, readable by anyone who can read it; prefer a file, an environment variable or a key manager.