Claim Specifications

The content of a bootloader transparency claims is defined following the Claimant Model Tutorial.

The formal framework is applied to describe what is important to log, based on the assumption that the bootloader will act as believer while taking the booting decisions based on claimed information. Moreover, the data included in the claims must be formalized to also ease the continuous analysis by external monitors of the logs, as it is expected in a typical transparency ecosystem Certificate Transparency.

boot-transparency Claimant Model - System BOOT-BUNDLE

(Refers "only" to claims inherent in the signature over the boot binaries made by the OS vendor/developer)

Claim: OS vendor or developer claim the boot binaries are described by their manifest. The manifests contain a representative set of properties of the artifacts including a cryptographic hash of the binaries. The boot bundle includes one, or more artifacts. The artifacts are divided by category, as for example: LinuxKernel, Initrd, Dtb, UEFIBinary.

Statement: signed manifest including the claims for the boot bundle.

Claimant: the entity releasing the boot bundle, or target binary (i.e. OS or UEFI binary vendor or developer).

Believer: the bootloader, or any user-space tool, interacting with the boot-transparency library to check transparency inclusion and validate matching between claims and requirements enforced by the boot policy. Based on such evaluations, the believers decide whether, or not, perform their Action.

Action: the bootloader will decide whether, or not, authorize the boot the artifact bundle. The user-space tools will decide whether, or not, install the kernel/OS update.

Verifier: any entity that would check for any invalidation of the claims above, e.g.:

• OS vendors / developers ("has my identity been compromised?")
• other OS vendors
• AV/analysis companies/organisations with large security teams
• independent security researchers
• large organisations who already regularly look at software components for their fleet governments
• governments

Arbiters: there's no official body, but invalidated claims would affect reputation, possibly draw to further consequences not defined by this document.

boot-transparency Claimant Model - System (BOOT-BUNDLE-LOG)

(Refers "only" to claims made by the log operator(s), and is the basis for providing discoverability into System BOOT-BUNDLE above)

Claim: log operator guaranteeing that:

• the signed manifest(s) are appended-only to the log via a globally consistent mechanism
• all binaries images correspond to the signed manifests stored in the log.

Statement: log checkpoint (e.g. signed tree head)

Claimant: log operator. Possible operators might be:

• OS vendors or developers
• system integrators
• members of relevant consortia

Believer: see System BOOT-BUNDLE Believer and Verifier

Verifier: any entity that would check for any invalidation of the claims above, e.g.:

• entities included in the Claimant list
• other log operators
• independent security researchers
• log verifiers from other Transparency ecosystems (e.g. CT, golang, etc.)

Important

While picturing the claimant model for the bootloader transparency use-case, it is safe to assume that in the majority of cases the Claimant and the Log operator could be the same entity.

This simplified architecture reduces complexity around any potential partial availability of the logged artifacts, and as it is avoiding multiple potential lifecycle concerns it represent an incentive to operate the log.

The drawback is that any "split-view" attack scenario becomes more relevant, as the probability of having the log key compromised at the same moment the firmware releasing key (i.e. submitter's key) is compromised is higher compared to the situation where the log and the submitter are two distinct entities.

A feasible solution to mitigate this residual risk is represented by witnessing support, that in case of the off-line nature of boot-transparency verification became a requirement.

Statement format

The next section illustrates an example for the System BOOT-BUNDLE Statement in JSON format:

{
    "header": {
        "description": "Linux boot bundle example",
        "revision": "v1.0.0",
        "platform_id": "N/A"
    },
    "artifacts": [
        {
            "category": 1,
            "claims": {
                "file_name": "vmlinuz-6.14.0-29-generic",
                "file_hash": "8ba6bc3d9ccfe9c17ad7482d6c0160150c7d1da4b4a4f464744ce069291d6174ea9949574002f022e18585df04f57c192431794f36f40659930bd5c0b470eb59",
                "version": "v6.14.0-29-generic",
                "architecture": "x64",
                "tainted": false,
                "reproducible": true,
                "license": [
                    "GPL-2"
                ],
                "build_args": {
                    "KBUILD_BUILD_TIMESTAMP": "Thu Oct 16 12:07:21 2025 +0200",
                    "CONFIG_STACKPROTECTOR_STRONG": "y"
                },
                "tool_chain": "gcc version 13.3.0 (Ubuntu 13.3.0-6ubuntu2~24.04)",
                "metadata": {
                    "source_url": "https://bugs.launchpad.net/ubuntu/+archive/primary/+sourcefiles/linux/6.14.0-29.29/linux_6.14.0.orig.tar.gz",
                    "source_hash": "a6dd4538509560777f0f144822d490ed1c3736b915010b4de566ab2d2a7d911e",
                    "build_info": "https://bugs.launchpad.net/~canonical-kernel-team/+archive/ubuntu/ppa2/+build/31066712/+files/linux_6.14.0-29.29_amd64.buildinfo",
                }
            }
        },
        {
            "category": 2,
            "claims": {
                "file_name": "initrd.img-6.14.0-29-generic",
                "file_hash": "9f5db8bc106c426a6654aa53ada75db307adb6dcb59291aa0a874898bc197b3dad8d2ebef985936bba94e9ae34b52a79e8f9045346cde2326baf4feba73ab66c",
                "version": "v6.14.0-29-generic",
                "architecture": "x64",
                "tainted": false,
                "reproducible": true,
                "metadata": {
                    "source_url": "https://bugs.launchpad.net/ubuntu/+archive/primary/+sourcefiles/linux/6.14.0-29.29/linux_6.14.0.orig.tar.gz",
                    "source_hash": "a6dd4538509560777f0f144822d490ed1c3736b915010b4de566ab2d2a7d911e",
                    "build_info": "https://bugs.launchpad.net/~canonical-kernel-team/+archive/ubuntu/ppa2/+build/31066712/+files/linux_6.14.0-29.29_amd64.buildinfo"
                }
            }
        }
    ],
    "signatures": [
        {
            "pub_key":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIP5rbNcIOcwqBHzLOhJEfdKFHa+pIs10idfTm8c+HDnK",
            "signature":"1ebda694a4517486b4681c4c61db944a13b67d98667771ab06e2f7b1d97def682feeeb356737c39b6aeb528c8a0a15844597c50ffc4337b6167fb8af3108f101"
        },
        {
            "pub_key":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0zV5fSWzzXa4R7Kpk6RAXkvWsJGpvkQ+9/xxpHC49J",
            "signature":"42de0420040e8d4e742004b0a99c43d8fb8d0b0c817bddb96e3ca26b390d874c8e665e0b0ee860a360f27f9d1a8f306c56923e55febb9e38a36e8a2481a1dd02"
        }
    ]
}

By signing and putting this statement data into the log, the Claimant is publishing the Claims on the boot bundle and its artifacts.

The statement is made of the three sections:

1. header contains general informations about the bundle. The role of this section is to describe and uniquely identify the bundle through the {revision, platform_id} tuple. This information could be used, in future version of the boot-transparency library, to reference to the bundle log.

2. artifacts contains the claims on the artifacts included in the bundle.

3. signatures contains the signatures of the entire bundle (i.e. header and artifacts sections).

Bundle Header

• description is a human-readable description of the entire bundle
• revision is the bundle revision expressed using semantic versioning.
• platform_id is the target platform identifier. This field is optional, claimants could leverage on this field to indicate the target platform when releasing artifact bundles for embedded devices.

Artifact claims

• category defines the artifact category according to constants defined by boot-transparency library (e.g. 0x0001:LinuxKernel,·0x0002:Initrd,·0x0003:Dtb, 0x0004:UEFIBinary,·0x0005:WindowsBootmgr,·...). Further categories could be defined if needed by specific custom implementations.

• claims contains the claims that are expected to be used by the Believer while evaluating whether authorize, or not, the bundle, for boot or for installation.

  In the first artifact of the example above:

  • file_name and file_hash are the filename and the SHA-512 hash of the kernel that is supposed to be loaded by the bootloader during the booting process.
  • version is the kernel version expressed using semantic versioning
  • architecture is the binary architecture identifier using the vocabulary defined by the EFI specifications (i.e. IA32, x64, IA64, ARM, AA64, ...).
  • tainted indicates if the kernel is a Tainted kernel.
  • reproducible indicates that the kernel binary is reproducible. In general, an artifact is reproducible if given the same source code, build environment and build instructions, any party can recreate bit-by-bit identical copies of the binary artifact.
  • license indicates that the artifact is the result of compilation of components under terms of a given license(s).
  • build_args contains relevant building arguments, expressed as array of key/value pairs.
  • tool_chain contains information on the toolchain used to build the artifact.

Important

build_args and toolchain are presented at the same level of the other artifact claims, instead of being included as nested sources referenced in the metadata. This allows the Claimant to select, and expose, a restricted sub-set of building information.

Such a format should ease the Believer to access these information during the authorization process.

Furthermore, external indexing functions can directly lookup the toolchain and the build_args key/value pairs and parse them in their map-reduce implementations to support verifiable indexing.

• metadata contains the set of claims that typically used by the Verifier when performing deeper analysis on the bundle.

  While, in principle, such information could be also used by Believer(s), the main role of the metadata is to provide ancillary information to Verifier(s). As an example, the complete information required to reproduce the build of the binary artifacts could be accessible through the linked buildinfo file.

  To maximize flexibility, the metadata field is treated by the library as a "mere" key-value map. This allows the Claimant to include "arbitrary" content. Specialized Verifier(s) will be aware on how to parse, and use, such information as input of their verification logic.

Important

Every value associated with a claim key that is not supported by boot-transparency will be ignored.

Signatures

The signatures array contains the list of Ed25519 signatures in raw format for the given bundle of artifacts. Both header and artifacts sections are included in the signed data.

The System TARGET-BINARY Statement corresponds to the Go types documented in boot-transparency/README

Important

The statement signatures are not related to the log transparency signatures. These signatures are applied from the entities that release the target binary.

Any check on the claimed data is operating at a different layer from the transparency verification (inclusion and consistency of the log). In general, it is not required that the claimant is the same entity which is submitting to the log.