|
| 1 | +.. _auth_boot_guide: |
| 2 | + |
| 3 | +############################# |
| 4 | +Authenticated Boot User Guide |
| 5 | +############################# |
| 6 | + |
| 7 | +************ |
| 8 | +Introduction |
| 9 | +************ |
| 10 | + |
| 11 | +As we head into a new world of security requirements and regulations, secure boot is the first and most essential step. Secure boot is a process that ensures only authenticated software is selected and loaded, protecting systems from unauthorized or malicious code trying to load a unknown bootloader or OS on your device. |
| 12 | + |
| 13 | +Secure boot is achieved by verifying digital signatures of each software layer involved during boot before executing that code. This requires that the design of hardware and software is prepared and developed with security in mind. |
| 14 | + |
| 15 | +******** |
| 16 | +Learning |
| 17 | +******** |
| 18 | + |
| 19 | +Root of Trust (RoT) |
| 20 | +=================== |
| 21 | + |
| 22 | +The Root of Trust is the foundation of authenticated boot. It is the first component in the system that is inherently trusted and is responsible for verifying all subsequent components in the boot process. The RoT is usually implemented in hardware, firmware, or a combination of both. |
| 23 | + |
| 24 | +There are two main types of RoT: |
| 25 | + |
| 26 | + - *Hardware Root of Trust*: Typically embedded in a secure element (such as a Trusted Platform Module [TPM], Hardware Security Module [HSM], or Secure Boot ROM). It is immutable and performs the first-stage verification. |
| 27 | + |
| 28 | + - *Firmware/Software Root of Trust*: This is the first code that runs on the system, typically stored in Read-Only Memory (ROM) or write-protected storage. |
| 29 | + |
| 30 | +Chain of Trust (CoT) |
| 31 | +==================== |
| 32 | + |
| 33 | +The Chain of Trust extends the RoT by ensuring that every stage of the boot process verifies the next stage before executing it. Each stage is cryptographically signed, and verification is performed using public key cryptography. |
| 34 | + |
| 35 | +Process: |
| 36 | + |
| 37 | + 1. Boot ROM - Verifies the Primary Bootloader using a cryptographic signature. |
| 38 | + |
| 39 | + 2. Primary Bootloader - Verifies the Secondary Bootloader (U-Boot, GRUB, etc.) before executing it. |
| 40 | + |
| 41 | + 3. Secondary Bootloader - Verifies the Kernel before booting the operating system. |
| 42 | + |
| 43 | + 4. Kernel - Verifies the Initramfs and Root Filesystem using mechanisms like dm-verity or signatures. |
| 44 | + |
| 45 | +Each step in the chain must be verified to maintain system integrity. If any stage fails verification, the system will refuse to boot or attempt recovery. |
| 46 | + |
| 47 | +Device Mapper |
| 48 | +============= |
| 49 | + |
| 50 | +Device Mapper (dm) is a Linux kernel subsystem that provides an abstraction layer for managing block devices. It enables advanced features like encryption (dm-crypt) and integrity verification (dm-verity) at the block device level. |
| 51 | + |
| 52 | +dm-verity |
| 53 | +--------- |
| 54 | + |
| 55 | +dm-verity is a kernel feature designed to ensure that a block device remains read-only and has not been tampered with. It is commonly used in Android Verified Boot (AVB) and Linux-based secure boot systems. |
| 56 | + |
| 57 | +The root filesystem is hashed block by block, creating a hash tree (Merkle tree). The root hash of the hash tree is signed by a trusted key. During boot, the kernel verifies the hash tree before mounting the root filesystem. If any block is modified, the hash verification will fail, preventing tampered data from being used. |
| 58 | + |
| 59 | +While dm-verity guarantees data integrity, it does not promise confidentiality and works only on read-only filesystems. |
| 60 | + |
| 61 | +dm-crypt |
| 62 | +-------- |
| 63 | + |
| 64 | +dm-crypt is a device-mapper target used for transparent disk encryption. It ensures data confidentiality by encrypting the entire partition or block device. |
| 65 | + |
| 66 | +A user provides an encryption key (stored securely in a TPM or entered manually). dm-crypt encrypts each block before writing it to disk. When reading data, dm-crypt decrypts blocks on the fly. Only authorized users with the correct key can access the decrypted data. |
| 67 | + |
| 68 | +Before encrypting a drive, it is recommended to perform a secure erase by overwriting the entire device with random data. This can be done by following this `guide <https://wiki.archlinux.org/title/Dm-crypt/Drive_preparation>`_. |
| 69 | + |
| 70 | +***** |
| 71 | +Setup |
| 72 | +***** |
| 73 | + |
| 74 | +.. Image:: /images/Auth_default_bootflow.png |
| 75 | + :align: center |
| 76 | + |
| 77 | +.. note:: |
| 78 | + |
| 79 | + A new Yocto layer is in the works to automate all of the below steps |
| 80 | + |
| 81 | +The following steps describe how to build user-space tools and configuration on Yocto. Please use :ref:`Processor SDK - Building the SDK with Yocto <building-the-sdk-with-yocto>` as reference. |
| 82 | + |
| 83 | +#. Use the latest :ref:`oe-config file <yocto-layer-configuration>`. Build the default image and flash onto a 32GB+ SD card: |
| 84 | + |
| 85 | + .. code-block:: console |
| 86 | +
|
| 87 | + MACHINE=<machine> bitbake -k tisdk-default-image |
| 88 | +
|
| 89 | +#. For this demo, the root filesystem is copied from the default rootfs into the encrypted partition on a 32GB+ SD card. Hence, the SD card needs to be partitioned accordingly. It is recommended to create 2 additional ext4 partitions bringing the total to 4 partitions: |
| 90 | + |
| 91 | + +-----------------+----------------+-------+--------------+ |
| 92 | + | Partition Label | /dev partition | Size | Comments | |
| 93 | + +=================+================+=======+==============+ |
| 94 | + | boot | /dev/mmcblk1p1 | 128MB | Default | |
| 95 | + +-----------------+----------------+-------+--------------+ |
| 96 | + | root | /dev/mmcblk1p2 | 10GB | Default | |
| 97 | + +-----------------+----------------+-------+--------------+ |
| 98 | + | crypt | /dev/mmcblk1p3 | 10GB | Same as root | |
| 99 | + +-----------------+----------------+-------+--------------+ |
| 100 | + | verity | /dev/mmcblk1p4 | 1GB | 10% of crypt | |
| 101 | + +-----------------+----------------+-------+--------------+ |
| 102 | + |
| 103 | +#. On the host machine, build the Linux Kernel with support for these configs: |
| 104 | + |
| 105 | + .. code-block:: kconfig |
| 106 | +
|
| 107 | + CONFIG_BLK_DEV_DM=y |
| 108 | + CONFIG_DM_CRYPT=y |
| 109 | + CONFIG_DM_VERITY=y |
| 110 | +
|
| 111 | + These configs can be added using a separate .cfg file or the kernel can be edited using |
| 112 | + |
| 113 | + .. code-block:: console |
| 114 | +
|
| 115 | + MACHINE=<machine> bitbake -c menuconfig linux-ti-staging |
| 116 | +
|
| 117 | +#. Edit :file:`sources/meta-arago/meta-arago-distro/recipes-core/images/tisdk-tiny-initramfs.bb` to add *dm-crypt* and *dm-verity* support: |
| 118 | + |
| 119 | + .. code-block:: console |
| 120 | +
|
| 121 | + PACKAGE_INSTALL += " cryptsetup lvm2 e2fsprogs-mke2fs" |
| 122 | +
|
| 123 | +#. Build the initramfs image: |
| 124 | + |
| 125 | + .. code-block:: console |
| 126 | +
|
| 127 | + MACHINE=<machine> bitbake -k tisdk-tiny-initramfs |
| 128 | +
|
| 129 | +#. Extract the initramfs .cpio file and add a :file:`pass_key` file |
| 130 | + |
| 131 | + .. code-block:: console |
| 132 | +
|
| 133 | + # Create a random pass key |
| 134 | + tr -dc '[:alnum:]' </dev/urandom | head -c64 > <initramfs_root>/home/pass_key |
| 135 | +
|
| 136 | +#. Package the initramfs into the kernel by using the :code:`menuconfig` and build the kernel. |
| 137 | + |
| 138 | + .. code-block:: kconfig |
| 139 | +
|
| 140 | + General setup -> |
| 141 | + Initial RAM filesystem and RAM disk (initramfs/initrd) support -> |
| 142 | + Initramfs source file(s) |
| 143 | + /path/to/initramfs |
| 144 | +
|
| 145 | +#. Replace the :file:`root/boot/Image` with the updated Image and boot. |
| 146 | + |
| 147 | +#. Run the following commands in initramfs to setup the crypt and verity partitions |
| 148 | + |
| 149 | + .. code-block:: console |
| 150 | +
|
| 151 | + # Unmount encrypted partitions |
| 152 | + umount /dev/mmcblk1p3 |
| 153 | + umount /dev/mmcblk1p4 |
| 154 | +
|
| 155 | + # Mount default root |
| 156 | + mount /dev/mmcblk1p2 /old_mnt |
| 157 | +
|
| 158 | + # Setup the encrypted partition |
| 159 | + # The default cipher at the time of writing this guide is aes-xts-plain64 |
| 160 | + # To use the hardware accelerator, use --cipher aes-cbc-plain --key-size 256 --hash 256 |
| 161 | +
|
| 162 | + cryptsetup luksFormat /dev/mmcblk1p3 --key-file=/home/pass_key --batch-mode |
| 163 | + cryptsetup luksOpen /dev/mmcblk1p3 crypt_root --key-file=/home/pass_key |
| 164 | +
|
| 165 | + # Format and copy rootfs inside encrypted partition |
| 166 | + mkfs.ext4 /dev/mapper/crypt_root |
| 167 | + mount /dev/mapper/crypt_root /mnt |
| 168 | + cp -r /old_mnt /mnt |
| 169 | + umount /mnt |
| 170 | +
|
| 171 | + # Setup verity |
| 172 | + veritysetup format /dev/mapper/crypt_root /dev/mmcblk1p4 > /home/verity.hash |
| 173 | +
|
| 174 | +#. Back on the host machine, add this init file at the root of the initramfs: |
| 175 | + |
| 176 | + .. code-block:: bash |
| 177 | +
|
| 178 | + #!/bin/sh |
| 179 | +
|
| 180 | + sleep 5 # For mmcblk1 to populate |
| 181 | + chown root:root /bin/mount.util-linux # Provide correct ownership |
| 182 | +
|
| 183 | + # Mount dev, procfs and sysfs |
| 184 | + /bin/mount -t devtmpfs none /dev |
| 185 | + /bin/mount -t proc none /proc |
| 186 | + /bin/mount -t sysfs none /sys |
| 187 | +
|
| 188 | + # Decrypt |
| 189 | + # If the cipher was previously changed, add --cipher aes-cbc-plain |
| 190 | + /sbin/cryptsetup luksOpen --key-file=/home/pass_key /dev/mmcblk1p3 crypt_root |
| 191 | +
|
| 192 | + #Verify |
| 193 | + /sbin/veritysetup open /dev/mapper/crypt_root verity_root /dev/mmcblk1p4 $(cat /home/verity.hash) |
| 194 | +
|
| 195 | + mount -o ro /dev/mapper/verity_root /mnt |
| 196 | +
|
| 197 | + # Jump to secure root FS |
| 198 | + exec switch_root /mnt/ /sbin/init |
| 199 | +
|
| 200 | + and give it the appropriate permissions to run: |
| 201 | + |
| 202 | + .. code-block:: console |
| 203 | +
|
| 204 | + chmod +x init |
| 205 | +
|
| 206 | +#. Repackage the initramfs into the kernel, build and replace the :file:`root/boot/Image` and boot. |
| 207 | + |
| 208 | +.. Image:: /images/Auth_secure_bootflow.png |
| 209 | + :align: center |
| 210 | + |
| 211 | +********** |
| 212 | +Next steps |
| 213 | +********** |
| 214 | + |
| 215 | +This guide showcases the authenticated boot flow on TI devices and is not meant to be directly used in production. The demo utilizes a pass_key to secure the encrypted partition and is placed in the initramfs in a non-secure manner. |
| 216 | + |
| 217 | +******** |
| 218 | +See Also |
| 219 | +******** |
| 220 | + |
| 221 | +- `dm-crypt <https://wiki.archlinux.org/title/Dm-crypt>`__ |
| 222 | +- `dm-verity <https://wiki.archlinux.org/title/Dm-verity>`__ |
0 commit comments