Policy Specifications

The following example illustrates an hypothetical entry in the boot policy for a Linux OS:

{
    "artifacts": [
        {
            "category": 1,
            "_comment": "0x0001 -> LinuxKernel",
            "requirements": {
                "min_version": "v6.14.0-29",
                "tainted": false,
                "build_args": {
                    "CONFIG_STACKPROTECTOR_STRONG": "y"
                }
            }
        },
        {
            "category": 2,
            "_comment": "0x0002 -> Initrd",
            "requirements": {
                "tainted": false
            }
        }
    ],
    "signatures": {
        "signers": [
            {
                "name": "signatory I",
                "pub_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIP5rbNcIOcwqBHzLOhJEfdKFHa+pIs10idfTm8c+HDnK"
            },
            {
                "name": "signatory II",
                "pub_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0zV5fSWzzXa4R7Kpk6RAXkvWsJGpvkQ+9/xxpHC49J"
            }
        ],
        "quorum": 2
    }
}

A "basic" policy with this single entry, would authorize only artifact bundles that includes:

• a Linux kernel that meets the following requirements:

  • it is more recent than a certain version (e.g. 6.14.0-29)
  • it is not tainted
  • it has been compiled with a given configuration option (CONFIG_STACKPROTECTOR_STRONG=y)

• an init ram disk that meets the following requirement:

  • it is not containing any tainted module

• both artifact categories have been claimed in the log

• the claims have been signed by a sufficient number of trusted signers to satisfy the required quorum (e.g. 2)

Any boot bundle which is including artifacts falling into these two categories (i.e. LinuxKernel and Initrd) that are claiming properties not aligned with the policy are not allowed.

If a proven statement includes claims (i.e. JSON keys) that are not covered by the policy, such properties are ignored.

In general, the policy array could contain more than one single per-bundle entry. During the policy verification process, the policy array is traveled starting from index 0, similarly to a chain of rules for iptables, for example.

The first encountered ruleset that is matching the properties claimed in the boot bundle statement will take the precedence, allowing the boot of such bundle.

The support for multiple per-bundle entries could be leveraged, for example, to manage fallback scenarios.

By appending to the policy an entry like the one illustrated below, the library will authorize the boot to every kernel, but only a given "trusted" init ram disk. In other words, every boot bundle which includes an init ram disk that is matching the one claimed in a log that must to be signed by a sufficient number of trusted signers to satisfy the required quorum (e.g. 2):

{
    "artifacts": [
        {
            "category": 2,
            "_comment": "0x0002 -> Initrd",
            "requirements": {
                "file_name": "fallback-initrd.img-6.14.0-29-generic",
                "file_hash": "9f5db8bc106c426a6654aa53ada75db307adb6dcb59291aa0a874898bc197b3dad8d2ebef985936bba94e9ae34b52a79e8f9045346cde2326baf4feba73ab66c"
            }
        }
    ],
    "signatures": {
        "signers": [
            {
                "name": "signatory I",
                "pub_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIP5rbNcIOcwqBHzLOhJEfdKFHa+pIs10idfTm8c+HDnK"
            },
            {
                "name": "signatory II",
                "pub_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0zV5fSWzzXa4R7Kpk6RAXkvWsJGpvkQ+9/xxpHC49J"
            }
        ],
        "quorum": 2
    }
}

The JSON policy corresponds to the Go types documented in boot-transparency/doc/API.