Skip to main content

Root-Verity

Root data integrity verification, or root-verity, is a specific utilization of dm-verity, an integral part of the kernel that ensures that I/O for anything on the protected filesystem (in this case, root: /) is verified against a known good state. This is achieved by creating a hash tree of the root filesystem contents, which is then used to validate the integrity of the data being accessed.

The Merkle hash tree is visualized in the kernel documentation like this, where the root-hash is the root node of the hash tree:

                            [   root    ]
                           /    . . .    \
                [entry_0]                 [entry_1]
               /  . . .  \                 . . .   \
    [entry_0_0]   . . .  [entry_0_127]    . . . .  [entry_1_127]
      / ... \             /   . . .  \             /           \
blk_0 ... blk_127  blk_16256   blk_16383      blk_32640 . . . blk_32767

Trident partners with Image Customizer to deploy images that have root configured with dm-verity and a partition storing the root-hash.

Use Image Customizer to Create a COSI File​

To create a COSI file with root-verity enabled, Image Customizer provides some guidance.

At a high level, there are only a couple things that need to be configured:

  1. In addition to the typical root partition definition, a root-hash partition is needed like this:

    storage:
      disks:
      - partitionTableType: gpt
        partitions:
        - label: root-data
          id: root-data
          size: 2G
        - label: root-hash
          id: root-hash
          size: 128M

  2. The verity section is required:

    verity:
    - id: root
      name: root
      dataDeviceId: root-data
      hashDeviceId: root-hash
      dataDeviceMountIdType: part-label
      hashDeviceMountIdType: part-label

  3. Root-verity filesystems should be created as read-only:

    - deviceId: root
      type: ext4
      mountPoint:
        path: /
        options: defaults,ro

With these sections defined for root, Image Customizer will generate a COSI file containing a root-hash partition and an OS with root-verity enabled.

Use Trident to Deploy the COSI File​

Once you have a COSI file that enables root-verity, Trident can be used to deploy it during install or update.

Create a Trident Host Configuration file that aligns to the Image Customizer COSI. Specifically:

  1. Include root-data and root-hash partitions/filesystems

    storage:
      disks:
      - id: os
        device: /dev/sda
        partitionTableType: gpt
        partitions:
        - id: root-data
          type: root
          size: 4G
        - id: root-hash
          type: root-verity
          size: 1G

  2. Create verity section:

    storage:
      verity:
      - id: root
        name: root
        dataDeviceId: root-data
        hashDeviceId: root-hash