Skip to content

Getting Started Sigsum

Jump to bottom
Daniele Bianco edited this page Dec 16, 2025 · 8 revisions

This document illustrates the steps to create a boot bundle, and the bootloader configuration, assuming that Sigsum is being used as transparency engine.

The following steps are required to prepare a boot bundle:

  1. sign of the claims (i.e. statement) for the given bundle of artifacts
  2. submit of the signed statement to the transparency log
  3. creation of the boot bundle by attaching to the bundle of artifacts, the signed statement and the transparency proof returned by the log.

The bundle verification and authorization implemented by boot-transaparency library assumes that the booloader incorporates, or has access to:

  • the list of trusted log, submit, cosigners public keys to verify the proof of logging
  • the transparency witness policy
  • the boot policy
  • the list of trusted statement signer public keys to verify the statement signatures, if required by the boot policy.

The same material should be configured in the library also when it is used by a user-space tool.

The document also illustrates how to:

  • verify the transparency proof for the given statement, using a user-space tool.
  • validate the submitted statement against a given boot-transparency policy using a user-space tool. Such a tool is useful to replicate the policy validation performed by the bootloader (including quorum verification of the statement signatures).

Sign a statement

To sign and verify the claims (i.e. statement) for a given bundle of artifacts, boot-transparency uses the same key format adopted by Sigsum (i.e. Ed25519 keypair in OpenSSH format - the-sigsum-key-tool).

The signing keys can be generated following the Sigsum getting started documentation.

Prior to the signing, the user can validate the correctness of the statement format using the bt-statement parse command:

$ ./cmd/bt-statement/bt-statement parse --statement=./testdata/statement/statement.json
{
	"header": {
		"description": "Linux bundle",
		"revision": "v1"
	},
	"artifacts": [
		{
			"category": 1,
			"claims": {
				"file_name": "vmlinuz-6.14.0-36-generic",
				"file_hash": "4551848b4ab43cb4321c4d6ba98e1d215f950cee21bfd82c8c82ab64e34ec9a6",
				"version": "v6.14.0-36-generic",
				"tainted": false,
				"build_args": {
					"CONFIG_STACKPROTECTOR_STRONG": "y"
				}
			}
		},
		{
			"category": 2,
			"claims": {
				"file_name": "initrd.img-6.14.0-36-generic",
				"file_hash": "337630b74e55eae241f460faadf5a2f9a2157d6de2853d4106c35769e4acf538",
				"tainted": false
			}
		}
	]
}

The bt-statement sign command allows to append a new signature to a given statement:

$ ./cmd/bt-statement/bt-statement sign \
--statement=./testdata/statement/statement.json \
--signed-statement=./testdata/statement/signed-statement.json \
--private-key=./testdata/keys/dist1-key

$ ./cmd/bt-statement/bt-statement sign \
--statement=./testdata/statement/signed-statement.json \
--signed-statement=./testdata/statement/signed-statement.json \
--private-key=./testdata/keys/dist2-key

The signatures can be verified using:

$ ./cmd/bt-statement/bt-statement verify \
--signed-statement=./testdata/statement/signed-statement.json \
--public-key=./testdata/keys/dist1-key.pub
signature is valid

$ ./cmd/bt-statement/bt-statement verify \
--signed-statement=./testdata/statement/signed-statement.json \
--public-key=./testdata/keys/dist2-key.pub
signature is valid

Before proceeding and submitting the statement to the public log, it could be useful to validate the signed statement against a given test policy. This test can be done as illustrated in Boot bundle policy verification.

Submit a statement

The submit of the signed statement to the transparency log can be performed using sigsum-submit:

$ ./sigsum-submit -p ~/.config/sigsum/trust_policy -k ../sigsum-key/submit-key ./boot-transparency/testdata/statement/signed-statement.json

This command requires the presence of a submitter key and a trust policy for the transparency log.

For further details on submitter key generation and trust policy configuration, refer to Sigsum - getting started documentation.

Proof verification

Boot-transparency authorize the boot of a given bundle of artifacts, only if both verification of the transparency proof and matching of the claims against the boot policy are successful.

These two layers are independent and can be verified separately. When Sigsum is used as transparency engine, the proof verification in boot-transparency is the same one implemented by sigsum-verify.

This command can be used to ensure that the proof, that will be included in the boot bundle, will pass the verification:

$ ./sigsum-verify -k ../sigsum-key/submit-key.pub -p ~/.config/sigsum/trust_policy ./boot-transparency/testdata/statement/signed-statement.json.proof < ./boot-transparency/testdata/statement/signed-statement.json

$ echo $?
0

In this example the signed-statement.json.proof contains the transparency proof of logging returned by the log at submit time.

Refer to Sigsum - Verify the proof of logging for further details on Sigsum proof verification.

Boot policy verification

The bt-policy tool allows to verify the matching of a given statement with a given boot-transparency policy.

The tool can be used to verify the policy format via the parse command:

$ ./cmd/bt-policy/bt-policy parse --policy-file=./testdata/policy/policy.json
[
	{
		"artifacts": [
			{
				"category": 1,
				"requirements": {
					"min_version": "v6.14.0-29",
					"tainted": false,
					"build_args": {
						"CONFIG_STACKPROTECTOR_STRONG": "y"
					}
				}
			},
			{
				"category": 2,
				"requirements": {
					"tainted": false
				}
			}
		],
		"signatures": {
			"signers": [
				{
					"name": "dist signatory I",
					"pub_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIP5rbNcIOcwqBHzLOhJEfdKFHa+pIs10idfTm8c+HDnK"
				},
				{
					"name": "dist signatory II",
					"pub_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0zV5fSWzzXa4R7Kpk6RAXkvWsJGpvkQ+9/xxpHC49J"
				}
			],
			"quorum": 2
		}
	}
]

The validation of the logged statement against the test policy can be performed as follow:

$ ./cmd/bt-policy/bt-policy validate --policy-file=./testdata/policy/policy.json --signed-statement=./testdata/statement/signed-statement.json
signed statement is matching the policy

Create the boot bundle

Defining "how" the data should be stored within the boot bundle is outside the scope of this document. Nevertheless, it is expected that such bundle always includes:

  • artifacts in their binary format, or more in general, in the format expected from the bootloader for their loading e.g. vmlinuz-6.14.0-29-generic, initrd.img-6.14.0-29-generic, ...

  • boot-transparency proof bundle file (e.g. proof-bundle.json). This file includes everything that is needed by the library to verify both the transparency layer and the matching between the logged claims and the policy requirements. Specifically, it includes:

    • the signed statement which has been submitted to the log
    • the inclusion proof of logging that has been returned by the log at submit time
    • the probe data that is required to fetch the inclusion proof for the log. Such probing data is optional and not required to perform the off-line inclusion proof verification. The probe data is required to fetch a fresh inclusion proof directly from the log.

The boot-transparency proof bundle can be created using the following command:

$ ./bt-proof-bundle create
Usage: ./bt-proof-bundle create [-h] [-e transparency-engine] [-i inclusion-proof-file] [-p probe-file] [-s signed-statement-file] [parameters ...]
 -e, --engine=transparency-engine
             Transparency engine (i.e. 1: Sigsum or 2: Tessera)
             (required)
 -h, --help  Show usage message and exit
 -i, --inclusion-proof=inclusion-proof-file
             Inclusion proof file (required)
 -p, --probe=probe-file
             Proof probe file, contains data to request the inclusion
             proof to the log (required)
 -s, --signed-statement=signed-statement-file
             Signed statement file (required)

$ ./cmd/bt-proof-bundle/bt-proof-bundle create \
--engine=1 \
--inclusion-proof=./testdata/sigsum/signed-statement.json.proof \
--probe=./testdata/sigsum/probe.json \
--signed-statement=./testdata/statement/signed-statement.json  > ./testdata/sigsum/proof-bundle.json

The probe_file does contain probing data that could be used by verifiers having network access to to request a "fresh" inclusion proof to the remote log, instead of using the one included in the proof bundle.

The following example illustrates the data contained in a probe_file:

{
	"origin": "https://test.sigsum.org/barreleye",
	"leaf_signature": ""b380a0b0df0ae1710c1a51a708d7f45c0df840047a91c820dac04fe3f2c03b40b10b3f0cbcb189de410f83ad735ccf0d8146fe0b9c1408eda2b421d1daea8101",
	"log_public_key_hash": "4e89cc51651f0d95f3c6127c15e1a42e3ddf7046c5b17b752689c402e773bb4d",
	"submit_public_key_hash": "302928c2e0e01da52e3b161c54906de9b55ce250f0f47e80e022d04036e2765c"
}

This information should be available to the submitter upon a successfully submission to the transparency log:

  • origin identifies the remote log and should match the value configured in the trust_policy file passed as argument to sigsum-submit.
  • submit_public_key_hash and leaf_signature are respectively the first and the second value in the leaf line of the .proof file.
  • log_public_key_hash is the value in the log line in the .proof file.

The bt-proof-bundle tool can be used to parse a given proof bundle and thus verify its consistency. This allows to verify the formatting of the proof bundle before the publishing.

./cmd/bt-proof-bundle/bt-proof-bundle parse -e 1 --bundle=./testdata/sigsum/proof-bundle.json

Along with the proof bundle file, the bootloader, or any user-space tool using the boot-transparency library, should have access to:

  • the public keys required to verify the quorum on the artifact signatures
  • the public keys required to verify signatures in the inclusion proof (i.e. log public key and submitter public key)
  • the witness policy required to verify the quorum on the inclusion proof co-signers. The witness policy includes the trusted public keys to verify co-signatures on the tree head present in the inclusion proof.

Clone this wiki locally