Reports now enabled by default

[davidchisnall]

As of #32, we are now generating compartment reports when we link. Our compartment model was designed to make it possible to statically audit the contents of a firmware image that contains components from different providers. Our goal was for the linker to generate a report that let external tooling audit the shape of the compartment graph. @rengolin did an initial implementation of this and I have now updated it and added support for the newer features of the ABI. It should still be regarded as experimental (there are almost certainly bugs and the format is not guaranteed to be stable!), but it's now enabled by default.

Now, near the end of the build of a firmware image, you should see a line something like this:

[ 98%]: Creating firmware report build/cheriot/cheriot/release/test-suite.json

This JSON file contains a couple of top-level things that let you identify the binary that it corresponds to, something like this:

  "file": "build/cheriot/cheriot/release/test-suite",
  "final_hash": "90e513b40ab3cbccff7a03eb5f93c1f5f7e6d6cb5c570c38503c58cb247f3549"

The file is just the path where the image was created and is not particularly useful for long-term auditing, but the final_hash lets you identify the binary by its SHA256 hash.

The rest of the file is split into two objects. The first of these, core describes the core of the TCB: the loader and the switcher. For example, you will see something like this for the switcher:

    "compartment_switcher_code": {
      "inputs": [
        {
          "file": "build/.objs/cherimcu.switcher/cheriot/cheriot/release/__/sdk/core/switcher/entry.S.o",
          "section_name": ".text",
          "sha256": "f3bab83ff1b589c2cf3d9f0db16ac2fb44f498ec754ddc696115e04c51158c9f",
          "size": 1070
        }
      ],
      "output": {
        "sha256": "7a4e2fdec24f2750cff233b8e6c87f5b1c877178d3b65d2870eba67c60132075"
      },
      "section_name": "compartment_switcher_code"
    }

The switcher is provided as a single input section and you can check the hash of this to ensure that it matches the version that you expect. If it changes, you will need to look at the audit trail for the build to understand why and may choose not to sign / trust firmware images until you have done so.

Beyond the core, there's also an entry in the top-level compartments object for each compartment or shared library. This contains a report of the contents, as for the core components, but for most compartments it will include at least one of an imports and exports section. The exports describe the things that this compartment provides. For example, looking in the allocator compartment we see this at the start of the exports array:

          {
            "export_symbol": "__export.sealing_type.alloc.MallocKey",
            "exported": true,
            "kind": "SealingKey"
          },
          {
            "export_symbol": "__export_alloc__Z20heap_quota_remainingP10SObjStruct",
            "exported": true,
            "interrupt_status": "enabled",
            "kind": "Function",
            "register_arguments": 1,
            "start_offset": 152
          },

The first entry says that this provides a sealing key and give a unique identifier for it as a sealing key kind. The second entry gives the symbol of an exported function. This function runs with interrupts enabled, takes one in-register argument, and (probably useful only if you have access to the binary) starts at offset 152 within the code section of the compartment.

Now let's look at the import tables for a compartment that uses the allocator, specifically the allocator test. The first entries look a bit like this:

        {
          "contents": "00001000 00000000 00000000 00000000 00000000 00000000",
          "kind": "SealedObject",
          "sealing_type": {
            "compartment": "alloc",
            "key": "MallocKey",
            "provided_by": "build/cheriot/cheriot/release/cherimcu.allocator.compartment",
            "symbol": "__export.sealing_type.alloc.MallocKey"
          }
        },

These are used for our software capability system, which is built on top of the hardware capability system. The allocator test compartment will receive a sealed capability to an object that only the owner of the type can unseal. The initial contents of this are listed in the contents field. This is an instance of the AllocatorCapabilityState structure and so we expect the first field to be the quota and the rest to be zeroes. The first field is a size_t, so 4 bytes: 0x00001000. This means that whoever holds this capability is permitted to allocate up to 4096 bytes of memory. The sealing_type section describes the name of the compartment and the name of the sealing key that are used to unseal this. The symbol is the unique identifier (which contains both of these values) that you can cross-reference to see which compartment may unseal this object. This corresponds to the exported sealing type from the allocator, above.

The next entry should appear only in debug builds:

        {
          "kind": "MMIO",
          "length": 256,
          "start": 268435456
        },

The start value is not very helpful in decimal, and is a lot more recognisable in hex: 0x10000000. If you look in the board description file for the sail simulator you will see that this corresponds to the UART: when debugging, we give all compartments direct access to the UART.

There are also few shared-library functions. For example:

        {
          "export_symbol": "__library_export_libcalls___atomic_load_1",
          "kind": "LibraryFunction",
          "provided_by": "build/cheriot/cheriot/release/atomic.library"
        },
        {
          "export_symbol": "__library_export_libcalls__Z6memcpyPvPKvj",
          "function": "memcpy(void*, void const*, unsigned int)",
          "kind": "LibraryFunction",
          "provided_by": "build/cheriot/cheriot/release/freestanding.library"
        },

Library functions are called directly (via a sentry capability), they don't go via the compartment switcher. Most of these will have C++ name-mangled names, but the atomic library functions do not because clang hard-codes their names in the front end. If the symbol is mangled, the function gives you a demangled name. This is not important for auditing, but is useful if you happen to be a human and are reading this output. The export_symbol lets you find the corresponding library that exports them. The provided_by key should be the same as the one found in the compartment that exports these symbols, and is provided in both places for ease of use.

There are also several cross-compartment calls, including the one exported from the allocator above:

        {
          "compartment_name": "alloc",
          "export_symbol": "__export_alloc__Z20heap_quota_remainingP10SObjStruct",
          "function": "heap_quota_remaining(SObjStruct*)",
          "kind": "CompartmentExport",
          "provided_by": "build/cheriot/cheriot/release/cherimcu.allocator.compartment"
        },

Again, this has the demangled name and the compartment file that provided it for ease of debugging, but the key information is the export_symbol, which can be cross-referenced against the entry above.

With all of this information, you can build a complete graph of which compartments call which others (and with which entry points), which compartments are able to disable interrupts (and which compartments can call those!). You can audit which software-defined capabilities any compartment has. You can check that a shared library has precisely the code that you expect.

We hope that this can be used to build very strong supply-chain integrity for embedded systems.

[rmn30]

As an example of what can be done with the linker report, here is the output of a work-in-progress compartment graph visualiser I wrote when run on the hello compartment example: