verity type

Specifies the configuration for dm-verity integrity verification.

Note: Currently root partition (/) and usr partition (/usr) are supported.

Note: The filesystem item pointing to this verity device, must include the ro option in the mountPoint.options.

There are multiple ways to configure a verity enabled image. For recommendations, see Verity Image Recommendations.

Example of enabling root Verity:

storage:
  bootType: efi
  disks:
  - partitionTableType: gpt
    partitions:
    - id: esp
      type: esp
      size: 8M

    - id: boot
      size: 1G

    - id: root
      size: 2G

    - id: roothash
      size: 100M

    - id: var
      size: 2G

  verity:
  - id: verityroot
    name: root
    dataDeviceId: root
    hashDeviceId: roothash
    corruptionOption: panic

  filesystems:
  - deviceId: esp
    type: fat32
    mountPoint:
      path: /boot/efi
      options: umask=0077

  - deviceId: boot
    type: ext4
    mountPoint: /boot

  - deviceId: verityroot
    type: ext4
    mountPoint:
      path: /
      options: ro

  - deviceId: var
    type: ext4
    mountPoint: /var

os:
  bootloader:
    resetType: hard-reset

Example of enabling usr Verity:

storage:
  bootType: efi
  disks:
  - partitionTableType: gpt
    partitions:
    - id: esp
      type: esp
      size: 8M

    - id: boot
      size: 1G

    - id: root
      size: 2G

    - id: usr
      size: 2G

    - id: usrhash
      size: 100M

  verity:
  - id: verityusr
    name: usr
    dataDeviceId: usr
    hashDeviceId: usrhash
    corruptionOption: panic

  filesystems:
  - deviceId: esp
    type: fat32
    mountPoint:
      path: /boot/efi
      options: umask=0077

  - deviceId: boot
    type: ext4
    mountPoint: /boot

  - deviceId: root
    type: ext4
    mountPoint: /

  - deviceId: verityusr
    type: ext4
    mountPoint:
      path: /usr
      options: ro

os:
  bootloader:
    resetType: hard-reset

Example of enabling verity on existing partitions in the base image:

storage:
  verity:
  - id: verityusr
    name: usr
    dataDevice:
      idType: part-label
      id: usr
    hashDevice:
      idType: part-label
      id: usrhash
    corruptionOption: panic

Added in v0.7.

id [string]

Required.

The ID of the verity object. This is used to correlate verity objects with filesystem objects.

Added in v0.7.

name [string]

Required.

The name of the device mapper block device.

The value must be:

  • root for root partition (i.e. /).

    Added in v0.7.

  • usr for the usr partition (i.e. /usr).

    Added in v0.11.

Added in v0.7.

dataDevice [verityPartition]

The existing partition within the base image to use as the verity data partition.

Must be used with hashDevice.

Added in v0.13.

dataDeviceId [string]

The ID of the new partition to use as the verity data partition.

Must be used with hashDeviceId.

If dataDeviceId and hashDeviceId are set to the same value, then the verity hash tree is placed at the end of partition behind the filesystem. The sizes of the filesystem and verity hash tree are automatically calculated to fill the entire partition.

Added in v0.7.

dataDeviceMountIdType [string]

How the verity data partition is referenced in the OS. For example, within the /etc/fstab and within the kernel command-line args.

Supported values:

  • uuid: Identify the partition by filesystem UUID.
  • part-uuid: Identify the partition by partition UUID.
  • part-label: Identify the partition by partition label.

Added in v0.7.

hashDevice [verityPartition]

The existing partition within the base image to use as the verity hash partition.

Must be used with dataDevice.

Added in v0.13.

hashDeviceId [string]

The ID of the new partition to use as the verity hash partition.

Must be used with dataDeviceId.

Added in v0.7.

hashDeviceMountIdType [string]

How the verity hash partition is referenced in the OS. For example, within the /etc/fstab and within the kernel command-line args.

Supported values:

  • uuid: Identify the partition by filesystem UUID.
  • part-uuid: Identify the partition by partition UUID.
  • part-label: Identify the partition by partition label.

Added in v0.7.

corruptionOption [string]

Optional.

Specifies how a mismatch between the hash and the data partition is handled.

Supported values:

  • io-error: Fails the I/O operation with an I/O error.
  • ignore: Ignores the corruption and continues operation.
  • panic: Causes the system to panic (print errors) and then try restarting.
  • restart: Attempts to restart the system.

Default value: io-error.

Added in v0.7.

hashSignaturePath [string]

Optional.

Specifies the path where the signed verity hash file should be injected into the image. This path is typically used by the systemd-veritysetup module to verify the verity hash against a signature at boot time.

This path must be located under the boot partition. (This restriction may be lessened in the future.) For example, if the boot partition is mounted at /boot, then hashSignaturePath: /boot/usr.hash will result in a destination of /usr.hash relative to the boot partition during injection.

When this field is specified, Image Customizer will output the corresponding unsigned hash file (verity-hash) as an artifact if the output.artifacts API is configured.

The generated inject-files.yaml will include an entry to inject the signed hash file to the specified path inside the boot partition.

If hashSignaturePath is not configured for a given Verity entry, the verity hash file will not be output even if verity-hash is listed in the output.artifacts.items. Only Verity entries with hashSignaturePath defined will produce a verity-hash artifact.

Added in v0.16.