diff --git a/source/_static/boards/vck190-jtag-boot.png b/source/_static/boards/vck190-jtag-boot.png deleted file mode 100644 index 97c2d6f0..00000000 Binary files a/source/_static/boards/vck190-jtag-boot.png and /dev/null differ diff --git a/source/_static/boards/vck190-sd-boot.png b/source/_static/boards/vck190-sd-boot.png deleted file mode 100644 index 36ca937c..00000000 Binary files a/source/_static/boards/vck190-sd-boot.png and /dev/null differ diff --git a/source/_static/boards/vck190-slot.png b/source/_static/boards/vck190-slot.png deleted file mode 100644 index 94db42b0..00000000 Binary files a/source/_static/boards/vck190-slot.png and /dev/null differ diff --git a/source/_static/boards/vck190.png b/source/_static/boards/vck190.png deleted file mode 100644 index a6e0851f..00000000 Binary files a/source/_static/boards/vck190.png and /dev/null differ diff --git a/source/conf.py b/source/conf.py index 2b95e847..c6443ec0 100644 --- a/source/conf.py +++ b/source/conf.py @@ -191,7 +191,6 @@ 'https://www.nxp.com/docs/en/application-note/AN12312.pdf', r'https://sourceforge.net/.*', # 403 error 'https://www.nsa.gov/portals/75/documents/what-we-do/cybersecurity/professional-resources/csi-uefi-lockdown.pdf', # 403 error - 'https://www.xilinx.com/products/silicon-devices/acap/versal', r'https://source.foundries.io/factories/.*', ] # Time in seconds to wait for a response. May result in false errors, but also keeps things from timing out @@ -473,6 +472,12 @@ "reference-manual/security/boot-software-updates-stm32mp1": "../boards/boards.html", "reference-manual/boards/stm32mp15-eval": "boards.html", "reference-manual/boards/stm32mp15-disco": "boards.html", + "reference-manual/boards/kv260": "boards.html", + "reference-manual/boards/uz3eg-iocc": "boards.html", + "reference-manual/boards/versal": "boards.html", + "reference-manual/security/secure-boot-zynq": "../boards/boards.html", + "reference-manual/security/boot-software-updates-zynqmp": "..boards/boards.html", + "reference-manual/security/tee-on-versal-acap": "../boards/boards.html", "howto/zephyr-mcuboot-keys": "../index.html", "howto/linux-net-debug": "../reference-manual/linux/linux-net-debug.html", "howto/": "index.html", diff --git a/source/glossary/index.rst b/source/glossary/index.rst index 0e8901cc..eb2b3f00 100644 --- a/source/glossary/index.rst +++ b/source/glossary/index.rst @@ -114,7 +114,6 @@ Glossary This allows for smaller keys than otherwise, but with an equivalent security level. * :ref:`Security, Secure Element ` - * :ref:`Security, OP-TEE on the Versal Adaptive Computer Acceleration Platform ` ECIES Elliptic Curve Integrated Encryption Scheme @@ -125,8 +124,6 @@ Glossary The first step in a security process used to trust code; always trusted. Includes HSM/TPM and Secure Boot. - * :ref:`Security, OP-TEE on the Versal Adaptive Computer Acceleration Platform ` - HSM Hardware Security Module A physical device generally used for managing digital keys and encrypting and decrypting data. diff --git a/source/reference-manual/boards/boards.rst b/source/reference-manual/boards/boards.rst index 7dbd4639..977d8a99 100644 --- a/source/reference-manual/boards/boards.rst +++ b/source/reference-manual/boards/boards.rst @@ -32,6 +32,3 @@ Select your board below to view flashing instructions. jetson-agx-orin-devkit jetson-agx-xavier-devkit x86 - versal - uz3eg-iocc - kv260 diff --git a/source/reference-manual/boards/kria_kv260.png b/source/reference-manual/boards/kria_kv260.png deleted file mode 100644 index 05be0f64..00000000 Binary files a/source/reference-manual/boards/kria_kv260.png and /dev/null differ diff --git a/source/reference-manual/boards/kv260.rst b/source/reference-manual/boards/kv260.rst deleted file mode 100644 index 505ff075..00000000 --- a/source/reference-manual/boards/kv260.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. _ref-rm_boards_kv260: - -Kria KV260 Vision AI Starter Kit -=================================================== - -.. include:: generic-prepare.rst - -Hardware Preparation --------------------- - -|Image of Kria board| - -#. Ensure that the power code is disconnected. - -#. Connect the Micro-USB cable to the **J4** connector for serial console - output. - - -Flashing and Boot ------------------ - -Flashing an SD Card -~~~~~~~~~~~~~~~~~~~ - -.. note:: Device names and IDs can slightly differ from the steps below. - -.. include:: generic-flashing.rst - -Flashing QSPI Boot Images -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The SoM Starter Kits use a two stage boot process: - -- The primary boot firmware is pre-installed at the factory on the QSPI device. - -- The secondary boot device is an SD card containing the Linux kernel and - system root. - -The Xilinx Starter Kit carrier card hardware design sets and factory-locks the MPSoC boot mode to QSPI32. -The SoM boots to U-Boot using the QSPI contents, and U-Boot then does a hand-off to the secondary boot device. -To replace the boot image on a QSPI device with LmP boot images, manually flash to QSPI using the pre-installed U-Boot bootloader shell. -The shell is automatically booted on first boot: -:: - - > sf probe; setenv bootseq 1; mmc dev ${bootseq}; - > setenv loadaddr 0x8000000; - > fatload mmc ${bootseq}:1 ${loadaddr} boot0001.bin; - > sf update ${loadaddr} 0x200000 ${filesize}; - > sf update ${loadaddr} 0xF80000 ${filesize}; - > fatload mmc ${bootseq}:1 ${loadaddr} u-boot0001.itb; - > sf update ${loadaddr} 0x300000 ${filesize}; - > sf update ${loadaddr} 0x1080000 ${filesize}; - > sf erase 0x2200000 0x20000 - > sf erase 0x2220000 0x20000 - > reset - -After rebooting, the LmP U-Boot serial output is shown: - -:: - - U-Boot SPL 2022.01+xlnx+g37fad64d18 (Apr 19 2022 - 15:29:09 +0000) - PMUFW: v1.1 - Loading new PMUFW cfg obj (2200 bytes) - Silicon version: 3 - EL Level: EL3 - Multiboot: 1 - Trying to boot from MMC2 - SPL: Booting u-boot0001.itb - ## Checking hash(es) for config config-1 ... OK - ## Checking hash(es) for Image atf ... sha256+ OK - ## Checking hash(es) for Image uboot ... sha256+ OK - ## Checking hash(es) for Image ubootfdt ... sha256+ OK - ## Checking hash(es) for Image optee ... sha256+ OK - ## Checking hash(es) for Image fpga ... sha256+ OK - - U-Boot 2022.01+xlnx+g37fad64d18 (Apr 19 2022 - 15:29:09 +0000) - -Recovery --------- - -If boot images become corrupted, the Kria KV260 Vision AI Starter Kit provides an Image Recovery application. -The Image Recovery is a baremetal application that uses a web-browser user interface. -It can be invoked when the FW-update (**FWUEN**) button is pressed at power-on. -This can happen automatically, when both A and B images becomes un-bootable. -It can be used to directly update the A/B images, and persistent register states. - -Read the `Boot Firmware Image Recovery`_ page for more details on this application. - -.. |Image of Kria board| image:: kria_kv260.png -.. _Boot Firmware Image Recovery: https://xilinx.github.io/kria-apps-docs/bootfw/build/html/docs/bootfw_image_recovery.html diff --git a/source/reference-manual/boards/uz3eg-iocc.rst b/source/reference-manual/boards/uz3eg-iocc.rst deleted file mode 100644 index 2359046d..00000000 --- a/source/reference-manual/boards/uz3eg-iocc.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _ref-rm_boards_uz3eg-iocc: - -Avnet UltraZed SOM with UltraZed-EG IO Carrier Card -=================================================== - -.. include:: generic-prepare.rst - -Hardware Preparation --------------------- - -#. Ensure that the power switch is off (**SW8** switch is off). - -#. Install UltraZed SOM on UltraZed-EG carrier. - -#. Connect the Micro-USB cable to the **J11** (**DUAL USB UART** label) connector. - -#. Connect the power cord. - -#. Set the boot switch located on the SOM at **[1:4]** to **OFF,ON,OFF,ON**. - This will cause it to boot from the SD by default. - - -Flashing and Boot ------------------ - -.. note:: Device names and IDs can differ slightly from the steps below. - -.. include:: generic-flashing.rst diff --git a/source/reference-manual/boards/versal-prepare.rst b/source/reference-manual/boards/versal-prepare.rst deleted file mode 100644 index 21c8ba00..00000000 --- a/source/reference-manual/boards/versal-prepare.rst +++ /dev/null @@ -1,37 +0,0 @@ -Preparation ------------ - -.. important:: - Replace ```` with the name of your Factory. - -#. Download the necessary files from ``https://app.foundries.io/factories//targets``: - - a. Click the latest :guilabel:`Target` with the ``platform`` trigger. - - b. Expand the :guilabel:`Runs` section corresponding with the board. - **Download the Factory image.** For example, ``lmp-factory-image-.wic.gz``. - - .. note:: - For reference on how to boot using the JTAG port, download ``boot.bin`` from the **other** folder. - -#. Extract the file ``lmp-factory-image-.wic.gz``:: - - gunzip lmp-factory-image-.wic.gz - -#. Write the file to an SD card:: - - dd if=lmp-factory-image-.wic of=/dev/xxx bs=1M status=progress - -#. Plug the SD card in the Micro SD Versal slot. - - .. figure:: /_static/boards/vck190-slot.png - :width: 400 - :align: center - -#. Set the boot switches to SD mode. - - .. figure:: /_static/boards/vck190-sd-boot.png - :width: 400 - :align: center - -#. Power up the board. diff --git a/source/reference-manual/boards/versal.rst b/source/reference-manual/boards/versal.rst deleted file mode 100644 index 37609125..00000000 --- a/source/reference-manual/boards/versal.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. _ref-rm_board_versal: - -Versal AI Core Series VCK190 Evaluation Kit -=========================================== - -.. include:: versal-prepare.rst - -Hardware Preparation: Console/JTAG ----------------------------------------- - -Set up the board for accessing the console or using the JTAG interface: - -.. figure:: /_static/boards/vck190.png - :width: 800 - :align: center - -#. Using a USB Type-C cable, connect the board to the PC host. - -#. Four UART connections will appear on the PC: including a JTAG interface and a console. - - On a Linux® host, for example, you will see:: - - usb 1-14.4.4.3: new high-speed USB device number 117 using xhci_hcd - usb 1-14.4.4.3: New USB device found, idVendor=0403, idProduct=6011, bcdDevice= 8.00 - usb 1-14.4.4.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 - usb 1-14.4.4.3: Product: VCK190 - usb 1-14.4.4.3: Manufacturer: Xilinx - usb 1-14.4.4.3: SerialNumber: 532143136405 - ftdi_sio 1-14.4.4.3:1.0: FTDI USB Serial Device converter detected - usb 1-14.4.4.3: Detected FT4232H - usb 1-14.4.4.3: FTDI USB Serial Device converter now attached to ttyUSB4 - ftdi_sio 1-14.4.4.3:1.1: FTDI USB Serial Device converter detected - usb 1-14.4.4.3: Detected FT4232H - usb 1-14.4.4.3: FTDI USB Serial Device converter now attached to ttyUSB5 - ftdi_sio 1-14.4.4.3:1.2: FTDI USB Serial Device converter detected - usb 1-14.4.4.3: Detected FT4232H - usb 1-14.4.4.3: FTDI USB Serial Device converter now attached to ttyUSB6 - ftdi_sio 1-14.4.4.3:1.3: FTDI USB Serial Device converter detected - usb 1-14.4.4.3: Detected FT4232H - usb 1-14.4.4.3: FTDI USB Serial Device converter now attached to ttyUSB7 - - Inspection of these new devices will show:: - - $ ls -la /dev/serial/by-id/ - total 0 - lrwxrwxrwx 1 root root 13 sep 5 10:48 usb-Xilinx_VCK190_532143136405-if00-port0 -> ../../ttyUSB4 - lrwxrwxrwx 1 root root 13 sep 5 10:48 usb-Xilinx_VCK190_532143136405-if01-port0 -> ../../ttyUSB5 - lrwxrwxrwx 1 root root 13 sep 5 10:48 usb-Xilinx_VCK190_532143136405-if02-port0 -> ../../ttyUSB6 - lrwxrwxrwx 1 root root 13 sep 5 10:48 usb-Xilinx_VCK190_532143136405-if03-port0 -> ../../ttyUSB7 - -Console Hardware Configuration ------------------------------- - -#. Power off the board. - -#. Using a serial terminal program like minicom, - connect to the port with ``usb-Xilinx_VCK190_532143136405-if01-port0`` in the name. - In this example that would be ``ttyUSB5``. - Apply the following configuration:: - - - Baud rate: 115200 - - Data bits: 8 - - Stop bit: 1 - - Parity: None - - Flow control: None - -#. Power on the board. - -#. You should see the Versal console printing out the boot sequence. - -JTAG Hardware Preparation ----------------------------- - -.. important:: - The following steps assume that the `Xilinx Serial Software Comamnd-Line Tool`_ is installed on the system. - -#. Configure the boot switches in the VCK190 for JTAG mode: - - .. figure:: /_static/boards/vck190-jtag-boot.png - :width: 600 - :align: center - -#. Prepare the boot script:: - - $ cat boot.tcl - connect - after 1000 - target 1 - rst - targets -set -nocase -filter {name =~ "*Versal*"} - device program "/tmp/boot.bin" - -#. Power up the board. - -#. Boot the image by executing the tcl script:: - - $ xsct boot.tcl - -This will boot the system up to the U-boot shell. - -.. tip:: - If an LmP ready SD card is already in the Versal SD slot, you can continue booting the Linux kernel from it. - -.. _Xilinx Serial Software Comamnd-Line Tool: - https://docs.xilinx.com/v/u/en-US/ug1208-xsct-reference-guide diff --git a/source/reference-manual/linux/linux-layers.rst b/source/reference-manual/linux/linux-layers.rst index 4d86f22c..f1c50f76 100644 --- a/source/reference-manual/linux/linux-layers.rst +++ b/source/reference-manual/linux/linux-layers.rst @@ -61,9 +61,6 @@ Layer Description (not officially supported by ``meta-freescale`` maintainers). `meta-tegra`_ Board support layer for NVIDIA based devices. `meta-ti`_ Board support layer for Texas Instruments based devices. -`meta-xilinx`_ Provides support for Xilinx BSPs (e.g. ZynqMP). -`meta-xilinx-tools`_ Provides support for using Xilinx tools on supported - architectures (e.g. ZynqMP). ================================== ============================================================ @@ -174,7 +171,3 @@ An example for enabling only the ``meta-intel`` BSP layer:: https://github.com/OE4T/meta-tegra .. _meta-Ti: https://git.yoctoproject.org/meta-ti/ -.. _meta-Xilinx: - https://github.com/Xilinx/meta-xilinx -.. _meta-Xilinx-Tools: - https://github.com/Xilinx/meta-xilinx-tools diff --git a/source/reference-manual/security/boot-software-updates-zynqmp.rst b/source/reference-manual/security/boot-software-updates-zynqmp.rst deleted file mode 100644 index 40c444c9..00000000 --- a/source/reference-manual/security/boot-software-updates-zynqmp.rst +++ /dev/null @@ -1,520 +0,0 @@ -.. highlight:: sh -.. title:: U-Boot Linux Software Updates on Zynq UltraScale+ MPSoC -.. meta:: - :description: U-Boot Linux software updates on Zynq UltraScale+ MPSoC step by step instruction guide for FoundriesFactory. Learn more. - -.. _ref-boot-software-updates-zynqmp: - -Boot Software Updates on Zynq UltraScale+ MPSoC -=============================================== - -Boot Artifacts --------------- - -Boot Image -~~~~~~~~~~ - -The boot image is generated by the **bootgen** tool. -It contains PEK keys (if secure boot is enabled), Platform Management Unit (PMU) firmware, and Secondary Program Loader (SPL) obtained from a U-Boot build. - -U-Boot FIT Image -~~~~~~~~~~~~~~~~ - -"U-boot FIT-image" is a generic name for the signed FIT-image that contains U-Boot proper (``u-boot.bin``) and a host of other firmware. -This file is verified by SPL via a public key stored in SPL's dtb. - -- ``U-boot-nodtb.bin`` -- ``U-boot.dtb`` -- OP-TEE -- Arm Trusted Firmware (ARMv8) -- FPGA firmware -- Boot script (``bootscr``) - -If the CI signing key has been rotated since the last OTA, then the ``SPL.dtb`` verification data needs to be updated prior to booting the new U-Boot FIT-image. - -Boot Media ----------- - -Boot software updates are supported on both MMC and QSPI boot media. -However, note that this requires different boot image layouts for each case. - -Golden Image Search -~~~~~~~~~~~~~~~~~~~ - -The "golden image search" is a mechanism which BootROM uses to search for a valid boot header to load and run a boot image. -For boot header validation, the BootROM looks for the identification string ``XLNX`` (or ``XNLX`` in newer revisions). -When a valid identification string is found in the boot header, the checksum for the boot header is checked. -If the checksum is valid, the rest of the header and boot image—including the SPL—are loaded into the RPU or APU memory for processing. - -If an image header is invalid, the BootROM increments the image header address register by **32 KB** and tries again. -The offset used by BootROM for loading the boot image can be also be enforced by the user. -This is achieved by writing the boot offset value into the ``CSU_MULTI_BOOT`` register and issuing a system reset (not a ``POR``). - -Based on boot media used, ``CSU_MULTI_BOOT`` may indicate the following: - -* In the case of **QSP** boot, the multi boot value represents a multiple of 32 KB, as the boot image should be placed on 32 KB boundary. - To force BootROM to boot the image from the ``0x60000`` offset on QSPI, ``CSU_MULTI_BOOT`` needs to be set to ``0xC`` (``12`` in dec). - This is because ``0x60000 = 0x8000 * 0xC`` where ``0x8000`` is the 32KB boundary, and ``0xC`` is the multiboot value. - -* In the case of **MMC** boot, BootROM requires boot images to be stored on the first FAT partition, with a specific naming convention. - The filenames of the boot images should contain the multiboot offset, represented by 4 figures, i.e., ``boot0005.bin``. - BootROM would boot this file if ``CSU_MULTI_BOOT`` was set to ``5``. - -The boot image search mechanism is only available for the Quad-SPI, NAND, SD and eMMC boot modes. - -MMC Boot Image Layout -~~~~~~~~~~~~~~~~~~~~~ - -All boot images (both ``boot.bin`` and FIT images) are stored in the first FAT partition on MMC with the following naming convention: - -:: - - boot0001.bin - primary boot image - boot0002.bin - secondary boot image - u-boot0001.itb - primary FIT image - u-boot0002.itb - secondary FIT image - - - -QSPI Boot Image Layout -~~~~~~~~~~~~~~~~~~~~~~ - -All boot images (both ``boot.bin`` and FIT images) are written as raw images using these predetermined offsets: - -:: - - 0x0 - primary boot.bin - 0x60000 - secondary boot.bin - 0x100000 - primary u-boot.itb - 0xaa0000 - secondary u-boot.itb - -Boot Flow ---------- - -PMU BootROM -~~~~~~~~~~~ -#. Reset and initialize CSU, prepare for the configuration stage -#. Release the reset of CSU -#. Enter a servicing mode - -CSU BootROM -~~~~~~~~~~~ -#. Determine the boot mode -#. Activate golden image search mechanism -#. Load a boot image -#. Perform verification of boot image (in case secure boot is enabled) -#. Extract SPL and PMU firmware from boot image -#. Load PMU firmware -#. Load and jump to SPL - -SPL -~~~ - -#. Initialize DDR -#. Calculate filename (MMC boot)/ QSPI offset for the FIT image -#. Load U-Boot FIT-image -#. Perform verification -#. Extract components -#. Load FPGA firmware -#. Jump to ATF / OP-TEE - -ATF (ARMv8) -~~~~~~~~~~~ - -#. Perform memory permission setup -#. Drop to EL-2 non-secure -#. Jump to OP-TEE - -OP-TEE -~~~~~~ - -#. Perform secure world setup -#. Driver init -#. Load TAs -#. Drop to EL-2 secure world -#. Jump to ``u-boot.bin`` - -U-Boot -~~~~~~ - -#. Driver init -#. Boot script -#. Load kernel FIT-image -#. Perform verification -#. Extract components -#. Jump to Linux kernel - -Update Procedure ----------------- - -Primary vs Secondary Boot Paths -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As mentioned under Golden Image Search, the offset used by BootROM for loading the boot image can also be enforced by the user. -This implies that multiple boot images can be stored on the media. -This gives the possibility to use the A/B approach in Over The Air updates. -This is where "A" (primary boot path)represents stable boot image set, and "B" (secondary boot path) is the newly updated, not-validated-yet, images. - -Libaktualizr and Aktualizr-lite -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Aktualizr-lite makes the decision if boot firmware needs to be updated based on the contents of ``${ostree\_root}/usr/lib/firmware/version.txt``,. - Here, ``ostree\_root`` is root of the newly deployed ostree sysroot. - Example of contents: ``bootfirmware\_version=10`` -2. After parsing ``bootfirmware\_version``, it compares the version number with the existing one, obtained via ``fiovb`` or ``ubootenv``. -3. If ``bootfirmware\_version`` from ``version.txt`` is higher than the existing one, aktualizr-lite sets ``bootupgrade\_available`` via ``fiovb`` or ``ubootenv``. -4. Reboot should be performed. - -U-Boot ``boot.cmd`` Script -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. figure:: boot-software-updates/upgrade-flow-zynqmp.png - :alt: Boot firmware upgrade flow for QSPI boot - - Boot firmware upgrade flow for QSPI boot - -1. The actual update is done via the U-Boot ``boot.cmd`` script. -2. ``boot.cmd`` checks if primary path is booted. -3. If ``upgrade\_available`` is set, check if boot firmware upgrade is needed by checking the ``bootupgrade\_available`` flag. - If both are true, boot firmware images are obtained from the newly deployed ostree sysroot, then written to the secondary boot path offsets. - The multiboot offset value is then set, and a system reset is issued to enforce BootROM to boot secondary boot path. -4. After reboot, the secondary boot path is executed, the condition verification from step 2 is being checked again. - This time it is not true, so the regular boot of Linux is done. -5. After Linux is booted, aktualizr-lite confirms a successful update by clearing ``upgrade\_available``. - At this point, new boot firmware images have been validated and are ready to be flashed to the stable primary path. - An additional reboot is needed after this step. -6. Regular reset - -Add a New Board ---------------- - -U-Boot -~~~~~~ - -SPL: FIT Filename Calculation During MMC Boot -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -U-Boot SPL automatically detects what next image to boot based on the ``CSU_MULTI_BOOT`` register value. -In MMC boot, BootROM expects all boot images to be stored on the first FAT partition. -We need to boot the FIT image which corresponds to the multiboot offset. -Below is an example of how the final filename of the FIT image is calculated on ZynqMP SoCs -(extract from ``board/xilinx/zynqmp/zynqmp.c``): - -:: - - int spl_mmc_get_uboot_payload_filename(char *filename, size_t len, - const u32 boot_device) - { - int ret; - u32 multiboot; - - if (!filename) - return -1; - - multiboot = multi_boot_get(); - - if (multiboot) - ret = snprintf(filename, len, "u-boot%04d.itb", multiboot); - else - ret = snprintf(filename, len, "u-boot.itb"); - - if (ret < 0) { - printf("Can't construct SPL payload filename"); - return ret; - } - - printf("SPL: Booting %s\n", filename); - - return 0; - } - - -SPL: FIT Offset Calculation During QSPI Boot -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The offset for the FIT image is calculated from the current value of the ``CSU_MULTI_BOOT`` register. -The multiboot value is multiplied by ``0x8000`` (32 Kb boundary), and the final value is used as offset of the raw FIT image on QSPI. -Below is an example of how final offset is calculated on ZynqMP SoCs (extract from ``board/xilinx/zynqmp/zynqmp.c``): - -:: - - unsigned int spl_spi_get_uboot_offs(struct spi_flash *flash) - { - int ret; - u32 multiboot; - u32 payload_offset = 0; - u32 boot_image_offset = 0x0; - - multiboot = multi_boot_get(); - boot_image_offset = golden_image_boundary * multiboot; - - /* - * Default values are: - * Primary boot.bin offset - 0x0 (multiboot == 0) - * Secondary boot.bin offset - 0x50000 (multiboot == 10, - * as 10 * 32KB == 0x50000) - */ - if (boot_image_offset == CONFIG_SYS_SPI_BOOT_IMAGE_OFFS) { - payload_offset = CONFIG_SYS_SPI_U_BOOT_OFFS; - } else if (boot_image_offset == CONFIG_SYS_SPI_BOOT_IMAGE_OFFS2) { - payload_offset = CONFIG_SYS_SPI_U_BOOT_OFFS2; - } else { - printf("Invalid value of multiboot register, value = %d\n", - multiboot); - hang(); - } - - printf("SPL: Booting next image from 0x%x SPI offset\n", - payload_offset); - - return payload_offset; - } - -``meta-lmp`` -~~~~~~~~~~~~ - -The ``lmp.cfg`` File: QSPI boot -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To enable support of multiboot, adjust ``lmp.cfg`` for your board. -Add the following config options: - -:: - - CONFIG_SYS_SPI_BOOT_IMAGE_OFFS=0x0 - CONFIG_SYS_SPI_BOOT_IMAGE_OFFS2=0x60000 - CONFIG_SYS_SPI_U_BOOT_OFFS=0x100000 - CONFIG_SYS_SPI_U_BOOT_OFFS2=0xaa0000 - -These values correspond to the offsets of primary and secondary boot image sets (``boot.bin`` and ``u-boot.itb``). - -Pre-Load ``boot.cmd`` With SPL -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As ``boot.cmd`` depends on U-Boot commands for booting Linux, it should align with the U-Boot version. -In regular setups without boot firmware update support, ``boot.cmd`` is stored in the first FAT partition in eMMC/SD. -To get ``boot.cmd`` updates together with other boot software images, it should be moved from the FAT partition to the U-Boot FIT image. -To do this, edit ``lmp-machine-custom.inc``, adding this line for your board: - -:: - - BOOTSCR_LOAD_ADDR:sota = "0x21000000" - -This change will include ``boot.cmd`` into the U-Boot FIT image, alongside the TF-A/OP-TEE/U-Boot proper/U-Boot dtb images. -When SPL parses the U-Boot FIT image (u-boot.itb), it will pre-load ``boot.itb`` (compiled and wrapped ``boot.cmd``) to the address specified in ``BOOTSCR\_LOAD\_ADDR`` variable. - -To let U-Boot know where to get the boot script from, adjust the ``CONFIG\_BOOTCOMMAND`` param in your U-Boot ``lmp.cfg`` for the board. - -:: - - CONFIG_BOOTCOMMAND="setenv verify 1; source 0x44800000; reset" - -Test Basic API -~~~~~~~~~~~~~~ - -After applying updates from the previous steps, we should validate that everything is in place. -This consists of two steps: - -- Check that the multi boot U-Boot command is functional -- Obtain board security state (open/closed states). - -To test booting the primary/secondary boot path, use the two U-Boot commands ``multi\_boot`` and ``reset``. - -Example of test: - -:: - - U-Boot SPL 2022.01+xlnx+g9039256f80 (Jan 24 2022 - 14:57:34 +0000) - ... - Chip ID: zu3eg - Multiboot: 0 - Trying to boot from SPI - SPL: Booting next image from 0x100000 SPI offset - ..... - ZynqMP> multi_boot 0xc && reset - Set multiboot register to: 0xc (dec: 12) - QSPI boot offset to be used after reboot: 0x60000 - resetting ... - - U-Boot SPL 2022.01+xlnx+g9039256f80 (Jan 24 2022 - 14:57:34 +0000) - .... - Multiboot: 12 - Trying to boot from SPI - SPL: Booting next image from 0xaa0000 SPI offset - -From the output, you can see that after setting the secondary boot (``multi_boot 12`` or ``multi_boot 0xc``; both dec and hex values are supported), -and performing a reset, BootROM boots images from secondary boot path (``SPL: Booting next image from 0xaa0000 SPI offset``). - -To check if the security status of your board is detected correctly, use the ``is\_boot\_authenticated`` command: - -:: - - ZynqMP> is_boot_authenticated - Board is in open state - -``boot.cmd`` -~~~~~~~~~~~~ - -LmP uses a template-based generation for the final ``boot.cmd``. -It is constructed from common boot files (``./meta-lmp-base/recipes-bsp/u-boot/u-boot-ostree-scr-fit``). -These contain SoC agnostic DEFINEs, common functionality, and a board specific ``boot.cmd``, which includes common scripts. - -Example of board ``boot.cmd`` -(``./meta-lmp-bsp/recipes-bsp/u-boot/u-boot-ostree-scr-fit/uz/boot.cmd``): - -:: - - # set default fdt_file - setenv fdt_file system-top.dtb - echo "Using ${fdt_file}" - - # Default boot type and device - setenv bootlimit 3 - setenv devtype mmc - setenv devnum ${bootseq} - setenv bootpart 1 - setenv rootpart 2 - - setenv loadaddr 0x10000000 - setenv fdt_addr 0x40000000 - setenv optee_ovl_addr 0x22000000 - setenv fdt_file_final ${fdt_file} - setenv fit_addr ${ramdisk_addr_r} - - setenv bootloader_image "boot.bin" - setenv bootloader_s_image ${bootloader_image} - setenv bootloader2_image "u-boot.itb" - setenv bootloader2_s_image ${bootloader2_image} - - setenv check_board_closed "is_boot_authenticated" - setenv check_secondary_boot "multi_boot" - - if test "${modeboot}" = "qspiboot"; then - # Use SD for open boards, and eMMC for closed - run check_board_closed - - if test -n "${board_is_closed}"; then - # Use eMMC for further loading/booting Linux FIT image - setenv devnum 0 - else - # Use SD for further loading/booting Linux FIT image - setenv devnum 1 - fi - - setenv qspi_bootloader_offset 0x0 - setenv qspi_bootloader_s_offset 0x60000 - - setenv qspi_bootloader2_offset 0x100000 - setenv qspi_bootloader2_s_offset 0xaa0000 - - setenv setup_update 'sf probe && setenv update_cmd "sf update ${loadaddr}"' - - # Boot images (primary and secondary) - setenv bootloader_image_update '${qspi_bootloader_offset}' - setenv bootloader_s_image_update '${qspi_bootloader_s_offset}' - - # FIT image (primary and secondary) - setenv bootloader2_image_update '${qspi_bootloader2_offset}' - setenv bootloader2_s_image_update '${qspi_bootloader2_s_offset}' - - setenv set_primary_boot "multi_boot 0" - setenv set_secondary_boot "multi_boot 12" - - else - setenv setup_update 'setenv update_cmd "mmc dev ${devnum} && fatwrite mmc ${devnum}:${bootpart} ${loadaddr}"' - - # Boot images (primary and secondary) - setenv bootloader_image_update 'boot0001.bin' - setenv bootloader_s_image_update 'boot0002.bin' - - # FIT image (primary and secondary) - setenv bootloader2_image_update 'u-boot0001.itb' - setenv bootloader2_s_image_update 'u-boot0002.itb' - - setenv set_primary_boot "multi_boot 1" - setenv set_secondary_boot "multi_boot 2" - fi - - # Writing images - run setup_update - setenv update_primary_image 'echo "${fio_msg} writing ${image_path} ..."; setenv run_update "${update_cmd} ${bootloader_image_update} ${filesize}"; run run_update' - setenv update_secondary_image 'echo "${fio_msg} writing ${image_path} ..."; setenv run_update "${update_cmd} ${bootloader_s_image_update} ${filesize}"; run run_update' - setenv update_primary_image2 'echo "${fio_msg} writing ${image_path} ..."; setenv run_update "${update_cmd} ${bootloader2_image_update} ${filesize}"; run run_update' - setenv update_secondary_image2 'echo "${fio_msg} writing ${image_path} ..."; setenv run_update "${update_cmd} ${bootloader2_s_image_update} ${filesize}"; run run_update' - - setenv do_reboot "reset" - - @@INCLUDE_COMMON@@ - - -Sysroot and Signed Boot Artifacts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All boot artifacts (``boot.bin`` and U-Boot FIT) are automatically deployed to sysroot during build time. -However, for closed boards where the initial boot image must be signed in advance by a private key, there is way to add the signed binary instead. - -To do that, add ``lmp-boot-firmware.bbappend`` to your ``meta-subscriber-overrides`` layer. -You will add the path and the signed binary itself. - -Then define the boot firmware version number by setting the ``LMP_BOOT_FIRMWARE_VERSION`` global variable in ``lmp-factory-custom.inc``. -Boot firmware version information wil be added automatically to ``${osroot}/usr/lib/firmware/version.txt`` and the U-Boot Device Tree Blob. - -Example: - -:: - - diff --git a/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend - new file mode 100644 - index 0000000..6c11380 - --- /dev/null - +++ b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend - @@ -0,0 +1,7 @@ - +FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" - + - +SRC_URI = " \ - + file://SPL \ - +" - diff --git a/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/SPL b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/SPL - new file mode 100644 - index 0000000..50f5013 - Binary files /dev/null and b/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/SPL differ - --- a/conf/machine/include/lmp-factory-custom.inc - +++ b/conf/machine/include/lmp-factory-custom.inc - @@ -22,4 +22,4 @@ UEFI_SIGN_KEYDIR = "${TOPDIR}/conf/factory-keys/uefi" - # TF-A Trusted Boot - TF_A_SIGN_KEY_PATH = "${TOPDIR}/conf/factory-keys/tf-a/privkey_ec_prime256v1.pem" - - +LMP_BOOT_FIRMWARE_VERSION:uz3eg-iocc-sec = "3" - -.. note:: - - ``LMP_BOOT_FIRMWARE_VERSION`` is now the preferred way to set boot firmware version. - Defining ``PV`` in ``lmp-boot-firmware.bbappend`` is deprecated and should not be used. - To switch, remove the ``PV = ""`` line from ``lmp-boot-firmware.bbappend``. - Then define ``LMP_BOOT_FIRMWARE_VERSION`` with the appropriate version value, as shown in the example above. - - -Deploy Boot Images to QSPI Flash --------------------------------- - -If QSPI is chosen as the main boot media, you can use the U-Boot shell—loaded via serial console mode or other boot media—for image provisioning with corresponding offsets on QSPI: - -:: - - ZynqMP> sf probe; setenv loadaddr 0x8000000; mmc dev ${bootseq}; fatload mmc ${bootseq}:1 ${loadaddr} boot0001.bin; sf update ${loadaddr} 0x0 ${filesize}; sf update ${loadaddr} 0x60000 ${filesize}; fatload mmc ${bootseq}:1 ${loadaddr} u-boot0001.itb; sf update ${loadaddr} 0x100000 ${filesize}; sf update ${loadaddr} 0xaa0000 ${filesize}; - SF: Detected n25q256ax1 with page size 512 Bytes, erase size 128 KiB, total 64 MiB - switch to partitions #0, OK - mmc1 is current device - 280752 bytes read in 37 ms (7.2 MiB/s) - device 0 offset 0x0, size 0x448b0 - 0 bytes written, 280752 bytes skipped in 0.405s, speed 709851 B/s - device 0 offset 0x60000, size 0x448b0 - 0 bytes written, 280752 bytes skipped in 0.405s, speed 709851 B/s - 7179209 bytes read in 505 ms (13.6 MiB/s) - device 0 offset 0x100000, size 0x6d8bc9 - 0 bytes written, 7179209 bytes skipped in 7.433s, speed 1025601 B/s - device 0 offset 0xaa0000, size 0x6d8bc9 - 0 bytes written, 7179209 bytes skipped in 7.433s, speed 1025601 B/s - -.. seealso:: - * :ref:`ref-authentication-xilinx` diff --git a/source/reference-manual/security/secure-boot-zynq.rst b/source/reference-manual/security/secure-boot-zynq.rst deleted file mode 100644 index c4b58c50..00000000 --- a/source/reference-manual/security/secure-boot-zynq.rst +++ /dev/null @@ -1,310 +0,0 @@ -.. highlight:: sh - -.. _ref-authentication-xilinx: - -Secure Boot on Zynq UltraScale+ MPSoC -===================================== - -This page covers provisioning a device to enable the bootloader hardware authentication. - -.. note:: - - Helper scripts are also available in the `lmp-tools`_ repository. - -Get the PMU Firmware --------------------- - -Get a valid version of the PMU firmware for the hardware, ``pmu-firmware-MACHINE.bin``. -This can be found in the deploy folder. - -Replace ``MACHINE`` with the machine name (e.g. ``pmu-firmware-uz3eg-iocc-sec.bin``). - -Build the Bootloader --------------------- - -Build U-boot for the ZynqMP SoC platform with Secondary Program Loader (SPL) support. -This will produce a file called ``u-boot-spl.bin``. - -Note that this file can also be found in the deploy folder when building LmP for secure targets. -This is because with secure targets, the variable ``SPL_BINARY`` is set to ``spl/u-boot-spl.bin``. -This causes the build to assume that the final ``boot.bin`` will be manually generated and signed by the user. - -On normal (open) targets, the LmP build process only publishes the final ``boot.bin`` binary. -Without any signing requirements, the image can be created and published as part of the build process. - -Create the Primary and Secondary Keys -------------------------------------- - -Create a set of PEM keys for the hardware to authenticate the bootloader:: - - $ cat keys.bif - keys: - { - [ppkfile] - [pskfile] - [spkfile] - [sskfile] - } - - $./bootgen -arch zynqmp -image keys.bif -generate_keys pem - -Create the Bootable Image -------------------------- - -Create the bootable image requesting only authentication, by using the following BIF. -In this example, the PMUFW and SPL would be loaded at specific locations. -It is worth mentioning that whenever authentication is enabled for the bootloader, the PMUFW will also be signed:: - - $ cat bootloader.bif - the_ROM_image: - { - [pskfile] PSK.pem - [sskfile] SSK.pem - [pmufw_image, load=0xffdc0000] pmu.bin - [bootloader, authentication=rsa, destination_cpu=a53-0, load=0xfffc0000] u-boot-spl.bin - } - - $ ./bootgen -arch zynqmp -image bootloader.bif -w on -o boot.bin -efuseppkbits fuse-ppk.txt - -Besides ``boot.bin``, bootgen will also generate a SHA-384 of the PPK ``fuse-ppk.txt``. -This will need to be written to the PPK fuse so that the hardware can authenticate the image with the public primary key. - -Check the Bootable Image ------------------------- - -Check the integrity of the generated image:: - - $ ./bootgen -arch zynqmp -image boot.bin -verify - -The layout of the bootable image can be read as follows:: - - $ ./bootgen -arch zynqmp -read boot.bin - -Fuse the Primary Public Key SHA-384 ------------------------------------ - -Currently, there is no open source solution to read/write to the ZynqMP SoC eFUSEs. -An alternative to other GUI based tools from Xilinx is the Xilinx Lightweight Provisioning Tool. -It allows requests to be scripted: use this tool to write the content of ``fuse-ppk.txt`` to the PPK eFUSE. - -.. important:: - The Xilinx LIghtweight Provisiong Tool is only shared on demand from your Xilinx support representative. - -For more information on how to program the eFUSEs, please have a look at `XAPP1319`_. - -If you want to roll-out your own solution to read or write to the eFUSES, please have a look at the `Xilskey service`_ and the relevant `documentation`_. -Be aware however that these registers are only accessible from exception level 3 (EL3). - -If you want to pass some of those eFUSE values to TF-A or OP-TEE, a solution would be to read them from SPL, and then add them to the ``secure-chosen`` node in the device tree. -This would then be shared with those executables. - -Program the Bootable Image --------------------------- - -Unless you are booting from SD or eMMC, you will need to use the JTAG interface for the first write to QSPI. -However, JTAG accessibility requires using the Xilinx VIVADO SDK, which is big commitment in terms of storage. - -One alternative to a full SDK install is running Vivado in a container from a Linux® machine. -During development, we used the following `vivado_docker`_ repository. - -Sign the FPGA Fitstream ------------------------ - -When authentication is enabled in the bootable image, the CSU will also authenticate the FPGA bistream before allowing it to load. -Because of this, the bitstream must also be signed before adding it to the FIT image. -It can be found inside the target ``xsa`` file (e.g. ``uz3eg_iocc_base.bit``):: - - $ cat fpga.bif - the_ROM_image: - { - [auth_params] ppk_select=0; spk_id=0x00000000 - [pskfile] PSK.pem - [sskfile] SSK.pem - [destination_device=pl, authentication=rsa] uz3eg_iocc_base.bit - } - - $ ./bootgen -arch zynqmp -image fpga.bif -w on -o uz3eg_iocc_base.bit.bin - -Now extend the `bitstream-signed`_ recipe to include your signed bitstream. -Select it as the preferred provider for ``virtual/bitstream``, and specify the correct binary and compatible string:: - - $ cat meta-lmp-bsp/conf/machine/uz3eg-iocc-sec.conf - - # Signed FPGA bitstream is needed on secure/closed targets - PREFERRED_PROVIDER_virtual/bitstream = "bitstream-signed" - SPL_FPGA_BINARY = "bitstream-signed.bit.bin" - SPL_FPGA_COMPATIBLE = "u-boot,zynqmp-fpga-ddrauth" - -Booting SPL ------------ - -Applying this `patch`_ to U-boot, you should see the following on a successful boot:: - - U-Boot SPL 2021.07+xlnx+gb9b970209c (Jul 22 2021 - 10:50:54 +0000) - PMUFW: v1.1 - Loading new PMUFW cfg obj (1992 bytes) - Silicon version: 3 - EL Level: EL3 - Chip ID: zu3cg - Multiboot: 0 - Secure Boot: authenticated, not encrypted - Trying to boot from SPI - ## Checking hash(es) for config config-1 ... OK - FPGA image loaded from FIT - ## Checking hash(es) for Image atf ... sha256+ OK - ## Checking hash(es) for Image uboot ... sha256+ OK - ## Checking hash(es) for Image ubootfdt ... sha256+ OK - ## Checking hash(es) for Image optee ... sha256+ OK - - NOTICE: ATF running on XCZU3CG/silicon v4/RTL5.1 at 0xfffe5000 - NOTICE: BL31: v2.4(release):xlnx_rebase_v2.4_2021.1 - NOTICE: BL31: Built : 15:34:08, Jul 9 2021 - - I/TC: - I/TC: Non-secure external DT found - I/TC: OP-TEE version: 3.10.0-106-g60c99179 (gcc version 10.2.0 (GCC)) #1 Fri Jul 9 15:34:48 UTC 2021 aarch64 - I/TC: Primary CPU initializing - I/TC: Primary CPU switching to normal world boot - - U-Boot 2021.07+xlnx+gb9b970209c (Jul 22 2021 - 10:54:24 +0000) - [...] - - -.. note:: - Booting a secure image disables the JTAG interface, even if no JTAG related fuses were written. - Use the SPL configuration option `CONFIG_SPL_ZYNQMP_RESTORE_JTAG`_ to re-enable it on boot. - -Integrating the Signed ``boot.bin`` in LmP ------------------------------------------- - -Now that you validated the signed ``boot.bin`` file, make sure to integrate it as part of the LmP publishing process. -This is needed in order to support boot firmware updates:: - - meta-lmp-bsp/conf/machine/uz3eg-iocc-sec.conf:PREFERRED_PROVIDER_virtual/boot-bin = "lmp-boot-firmware" - - meta-lmp-bsp/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware/uz3eg-iocc-sec/boot.bin - - $ cat meta-lmp-bsp/recipes-bsp/lmp-boot-firmware/lmp-boot-firmware.bbappend - FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" - PROVIDES:uz3eg-iocc-sec = "virtual/boot-bin" - PV:uz3eg-iocc-sec = "1" - SRC_URI:uz3eg-iocc-sec = "file://boot.bin" - -With ``lmp-boot-firmware`` integration, the signed ``boot.bin`` file will be deployed under ``deploy/lmp-boot-firmware/``. - -For more information about boot firmware updates on Xilinx-based targets, see :ref:`Boot Software Updates on Zynq UltraScale+ MPSoC `. - -Secure Storage (RPMB) using the PUF ------------------------------------ - -The PUF can be used to generate a hardware unique key (HUK) at OP-TEE for secure storage via the eMMC RPMB partition. -For PUF to be functional you will need to fuse PPK and RSA_EN (for secure boot), register the PUF and program the Syndrome data (via Red AES key). -We recommend using the XLWPT tool (as described at `XAPP1319`_) for registering PUF:: - - ___ ___ _ __ _ ____ - / /\ /| |\ \ / / _ \ - /___/ \/ | | \ \ /\ / /| |_) | - \ \ | |__\ | | / | __/ - \ \ \_____\_/\_/ |_| - / / Zynq UltraScale+ MPSoC: ZU3EG - /__ / Lightweight Provisioning Tool - \ \ /\ XLWP Tool Version: 1.9 - \___\/__\ ::: PUF Menu ::: - _________________________________________ - - 1. Register the PUF - 2. Encrypt Red AES Key w/ PUF Key - 3. Display Bootheader Mode PUF Data - 4. Program PUF-related eFUSEs - 5. Read & Display PUF-related eFUSEs - - x. Exit sub-menu - - Please make a selection -> 1 (registering the PUF) - - Please make a selection -> 2 (encrypting red AES key w/ PUF key) - - > Enter the 256-bit Red AES key (64 hex characters): - ---------------------------------------------------------------- - 0123456789012345678901234567890123456789012345678901234567890123 - Is the key correct?! (y/[n]) -> y - - > Enter the 96-bit AES IV (24 hex characters): - ------------------------ - 012345678901234567890123 - Is the IV correct?! (y/[n]) -> y - - *** Red AES Key and IV for Black Key Captured OK! *** - *** Black Key Created OK! *** - - Press any key to continue... - - Please make a selection -> 4 (program PUF-related eFUSEs) - - 1. Syndrome, AUX, CHASH & Black Key eFUSEs - 2. SYN_INVLD eFUSE - 3. SYN_WR_LOCK eFUSE - 4. REG_DIS eFUSE - - Please make a selection -> 1 - - Program Syndrome, AUX, CHASH & Black Key eFUSEs...are you sure?! (y/[n]) -> y - - *** Syndrome, AUX, CHASH & Black Key eFUSEs programmed OK! *** - - Press any key to continue... - - PUF syndrome (helper data) read from eFUSEs: - ---------------------------------------------------------------- - C6F960D575ACB5E2BCDDFF4BEE586E8F35EB2231BA7F9A55263431BF382673AE - 0E774B4FA35165166025228F8F6A699D469AF76409D789A0C35F7D12B74A9AB8 - 2CCD677BF770DBA0522431806955EE7614E5795FACB28F4CAED5B27206737968 - 45F367953804F46626D6D69003F68EAFA0653E79FBAEAD854369F7959858117A - 169D11305DEF45F54056F2C39714FEB36364E1F9C82C6861ADB0B83FE59F0585 - C69E4CE96DB4328FA98E9CB0CAF9DCE50F793582160AD6E6CB9A9E54D24F82D8 - 30A22ECEE5AA24AF4B689D53F76D89B1ADA695FC5AA722967F20B6D827F5E18C - 13D76F08D34EFC7E2C0FFB261E0AC2A310B4E88BFACAED6C2E964EFF2701ED15 - 2825CA046B159FA63470166DF82912A7F983733AA73C03A6ED6F63CB70CC9761 - 791B5BD5BE7EB2681C95F447C707B416F688DA5C34C627113F8DABB0AA2A6424 - 72F57E9CF797574402BFFDBFBCC947BD9EACC18BB0A55CF0B2D024BE25B81022 - 69CDD2EAE3BACF415B28AA310AA9941ACCA5E7C64BBAA1878D55FB7666B93B46 - BFDA36E8E8B49DF5243F6B217970408ED101DD6977933474AD5178B41517D825 - 868A5DB679E66752AA7CBA300B700C0BD1DDE6A7E3528BD2FBFA24031D971CCE - 0BA2944FA09AD655204068744F3D401033BACBE849A69360A4077F5DB230E01D - 9278AF71941D711215FFA89CD3F73DC976EC2DC8D5B6BB1AD0618B3F - - PUF AUX value read from eFUSEs : 0x0062C179 - PUF CHASH value read from eFUSEs : 0x8D22500B - -For more information on registering the PUF, and how it is used by OP-TEE for generating a hardware unique key, -see `XAPP1333`_ and https://github.com/OP-TEE/optee_os/pull/4874. - -.. seealso:: - * :ref:`ref-boot-software-updates-zynqmp` - -.. _vivado_docker: - https://github.com/ldts/petalinux-docker - -.. _CONFIG_SPL_ZYNQMP_RESTORE_JTAG: - https://lists.denx.de/pipermail/u-boot/2021-July/455132.html - -.. _patch: - https://lists.denx.de/pipermail/u-boot/2021-July/455752.html - -.. _Xilskey service: - https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_services/xilskey - -.. _documentation: - https://docs.xilinx.com/r/en-US/oslib_rm/Xilinx-BSP-and-Libraries-Overview -.. _XAPP1319: - https://docs.xilinx.com/v/u/oneDJ6tvSJXI~6tBKk1ZxA - -.. _XAPP1333: - https://docs.xilinx.com/r/aN5KSVyHt9jE~xaIBaKGSg/root - -.. _bitstream-signed: - https://github.com/foundriesio/meta-lmp/blob/main/meta-lmp-bsp/dynamic-layers/xilinx-tools/recipes-bsp/bitstream/bitstream-signed.bb - -.. _lmp-tools: - https://github.com/foundriesio/lmp-tools/tree/master/security/zynqmp - diff --git a/source/reference-manual/security/security.rst b/source/reference-manual/security/security.rst index 63e5c28d..9e479b58 100644 --- a/source/reference-manual/security/security.rst +++ b/source/reference-manual/security/security.rst @@ -77,7 +77,6 @@ Secure Boot specifics of select hardware platforms are described below. secure-boot-imx-habv4 secure-boot-imx-ahab secure-boot-ti-am62x - secure-boot-zynq secure-boot-uefi More information around the Secure Boot aspects supported by LmP can be found in: @@ -87,7 +86,6 @@ More information around the Secure Boot aspects supported by LmP can be found in secure-machines revoke-imx-keys - tee-on-versal-acap See how to implement the `Secure Boot Firmware Updates`_ further below. @@ -138,7 +136,6 @@ Secure Boot Firmware update specifics for select hardware platforms are describe boot-software-updates-imx boot-software-updates-imx8qm - boot-software-updates-zynqmp Anti-rollback protection, which prevents downgrading of boot firmware, can be enabled by following the guide below. diff --git a/source/reference-manual/security/tee-on-versal-acap.rst b/source/reference-manual/security/tee-on-versal-acap.rst deleted file mode 100644 index d9747c3a..00000000 --- a/source/reference-manual/security/tee-on-versal-acap.rst +++ /dev/null @@ -1,354 +0,0 @@ -.. highlight:: sh - -.. _ref-tee-on-versal-acap: - - -OP-TEE on the Versal Adaptive Compute Acceleration Platform -=========================================================== - -A Trusted Execution Environment (TEE) is the security architecture cornerstone for the ARM® platforms that we support at Foundries.io; this is the reason why as part of the partnership agreements between Foundries.io and AMD/Xilinx, we brought `OP-TEE support`_ to the Versal™ Adaptive Compute Acceleration Platform (ACAP) platform. - -Among the many features included (TRNG, eFUSE access, GPIO controls, secure storage, etc), Versal ACAP users are able to use hardware supported cryptographic operations from the ARM Trusted Zone. - -.. _overview: - -Overview -******** - -The OP-TEE support for the `Versal ACAP`_ delegates most of its functionality to the `PLM firmware`_ executing in the MicroBlaze™ processor. -In the case of cryptographic operations, ciphers, and keys not supported by the hardware will be routed to the `Libtomcrypt`_ software based implementation. - -The services offered by the PLM firmware are decided at build time: it is therefore important that the PLM firmware build configuration enables the services that OP-TEE will require. - -As an example, if OP-TEE is configured to generate a hardware unique key, it will need access to the PLM Physical Unclonable Function and NVM services. - -.. note:: - Communication between OP-TEE and the PLM uses the IPI mailbox controller. The IPI used is selectable via the ``CFG_VERSAL_MBOX_IPI_ID`` variable. - -As described in the documentation for the Versal ACAP `boot-flow`_, the BootROM handles loading the PLM, while the PLM will handle loading the rest of the images, including OP-TEE. - -A reference BIF file supporting an OP-TEE instance capable of loading the FPGA pdi can be seen below. In this example OP-TEE should be configured with ``CFG_DT=y`` and ``CFG_DT_ADDR=0x00001000``. -If enabled, the platform expects the FPGA bitstream at 0x40000000; the location is configurable using ``CFG_VERSAL_FPGA_DDR_ADDR``. - -.. code-block:: none - - ROM_image: - { - image { - { type=bootimage, file=vpl_gen_fixed.pdi } - { type=bootloader, file=plm.elf } - { core=psm, file=psmfw.elf } - } - image { - id = 0x1c000000, name=apu_subsystem - { type=raw, load=0x00001000, file=versal-vck190-revA-x-ebm-01-revA.dtb } - { type=raw, load=0x40000000, file=fpga.pdi } - { core=a72-0, exception_level=el-3, trustzone, file=bl31.elf } - { core=a72-0, exception_level=el-2, file=u-boot.elf } - { core=a72-0, exception_level=el-1, trustzone, load=0x60000000, startup=0x60000000, file=tee-raw.bin } - } - } - - -To build the boot-able image, AMD/Xilinx uses the `bootgen tool`_. -This tool aggregates all the images into a single binary. - -The available configuration options depend on the architecture. -In the case of Versal ACAP using the previously mentioned BIF file, the BOOT.BIN would be generated as follows: - -.. code-block:: none - - $ bootgen -arch versal -image file.bif -o BOOT.BIN - - -Cryptographic driver -******************** - -The Versal ACAP cryptography driver rests on the PLM's `xilsecure`_ service. -It provides hardware assisted support for: - - 1. SHA3-384 - 2. RSA 2048, 4096 - 3. ECC sign/verify - 4. AES-GCM - -Other drivers -************* - -The ``Versal ACAP eFUSE`` driver uses the PLM `xilnvm`_ service. -Access to certain eFuses require specific PLM configuration flags not selectable at run-time. - -.. note:: - It is left to the user to ensure that the PLM has been configured as expected. - -The ``Versal ACAP PUF`` driver uses the PLM `xilpuf`_ service. - -At the time of v88, the platform support includes three native drivers: - - 1. ``Mailbox driver`` - 2. ``TRNG driver`` - 3. ``GPIO driver`` - -Hardware Unique Key -******************* - -The calculation of the Hardware Unique Key —used to derive the RPMB secret— is similar to the Zynqmp platform: a digest is generated from the DNA eFUSE identifier and then GCM-AES encrypted. -However, the symmetric key for the AES-GCM encryption engine can be selected at build time using the configuration option ``CFG_VERSAL_HUK_KEY``. - -Contrary to the Zynqmp platform, the PUF KEK is available on non-secured boards (i.e: boards not booting signed images). - -This means that the driver has no mechanism for restricting the generation of the HUK from using data based on information ``only available`` to secured systems. - -.. note:: - The security of the platform will depend on the process used to generate and lock the keys. - -Working Effectively With the Boot Firmware -****************************************** - -One of the features that make the `Versal AI Core Series VCK190 Evaluation Kit`_ a friendly platform to develop on is its integrated JTAG support: a single USB cable provides the different consoles as well as the JTAG port. - -The FoundriesFactory™ Platform CI builds and delivers a WIC image that allows Versal ACAP platforms to boot securely. -This way you can flash the WIC image on a uSD card, plug it in the corresponding slot, and boot to a secured and functional system. - -Imagine that Xilinx/AMD releases a new version of the PLM firmware, the firmware controls the actual cryptographic operations requested by OP-TEE. - -Without having to rebuild the complete WIC image, a developer can update and rebuild OP-TEE and PLM, including these new binaries in the BOOT.BIN image using the BIF file previously mentioned. Then the Xilinx Software Command Line Tool (xsct) can be used to boot it: - -.. code-block:: none - - $ xsct load_boot_bin.tcl - - -The xsct script would look like follows: - -.. code-block:: none - - $ cat load_boot_bin.tcl - - connect - after 1000 - target 1 - rst - targets -set -nocase -filter {name =~ "*Versal*"} - device program "/path/to/BOOT.BIN" - - -Execution of that command would boot to the U-boot shell. -Note we did not need to modify U-boot. This means if the uSD card with a FoundriesFactory LmP image was plugged into a device, the Linux kernel would continue booting to the final shell from which the developer could validate the new PLM/OP-TEE features. - -.. code-block:: none - - [0.015]**************************************** - [0.072]Xilinx Versal Platform Loader and Manager - [0.131]Release 2022.1 Apr 11 2022 - 09:29:50 - [0.190]Platform Version: v2.0 PMC: v2.0, PS: v2.0 - [0.256]BOOTMODE: 0x0, MULTIBOOT: 0x0 - [0.310]**************************************** - [0.541]Non Secure Boot - [3.487]PLM Initialization Time - [3.537]***********Boot PDI Load: Started*********** - [3.600]Loading PDI from SBI - [3.649]Monolithic/Master Device - [4.153]0.527 ms: PDI initialization time - [4.211]+++Loading Image#: 0x1, Name: lpd, Id: 0x04210002 - [4.280]---Loading Partition#: 0x1, Id: 0xC - [55.514] 51.147 ms for Partition#: 0x1, Size: 2880 Bytes - [60.374]---Loading Partition#: 0x2, Id: 0x0 - [64.757] 0.516 ms for Partition#: 0x2, Size: 48 Bytes - [68.908]---Loading Partition#: 0x3, Id: 0x0 - [107.863] 35.087 ms for Partition#: 0x3, Size: 58912 Bytes - [110.190]---Loading Partition#: 0x4, Id: 0x0 - [115.764] 1.620 ms for Partition#: 0x4, Size: 5888 Bytes - PSM Firmware version: 2022.1 [Build: Apr 11 2022 09:29:50 ] - [124.377]+++Loading Image#: 0x2, Name: pl_cfi, Id: 0x18700000 - [129.731]---Loading Partition#: 0x5, Id: 0x3 - [955.552] 821.867 ms for Partition#: 0x5, Size: 1258736 Bytes - [958.137]---Loading Partition#: 0x6, Id: 0x5 - [1847.061] 884.970 ms for Partition#: 0x6, Size: 1335632 Bytes - [1849.762]+++Loading Image#: 0x3, Name: aie_subsys, Id: 0x0421C005 - [1855.536]---Loading Partition#: 0x7, Id: 0x7 - [1862.473] 2.897 ms for Partition#: 0x7, Size: 864 Bytes - [1864.660]+++Loading Image#: 0x4, Name: fpd, Id: 0x0420C003 - [1869.838]---Loading Partition#: 0x8, Id: 0x8 - [1874.286] 0.410 ms for Partition#: 0x8, Size: 1552 Bytes - [1879.189]+++Loading Image#: 0x5, Name: apu_subsystem, Id: 0x1C000000 - [1884.947]---Loading Partition#: 0x9, Id: 0x0 - [1900.269] 11.283 ms for Partition#: 0x9, Size: 23296 Bytes - [1902.684]---Loading Partition#: 0xA, Id: 0x0 - [2358.623] 451.899 ms for Partition#: 0xA, Size: 707616 Bytes - [2361.208]---Loading Partition#: 0xB, Id: 0x0 - [2405.954] 40.707 ms for Partition#: 0xB, Size: 67536 Bytes - [2408.370]---Loading Partition#: 0xC, Id: 0x0 - [3482.773] 1070.362 ms for Partition#: 0xC, Size: 1647504 Bytes - [3485.532]---Loading Partition#: 0xD, Id: 0x0 - [3778.339] 288.766 ms for Partition#: 0xD, Size: 452640 Bytes - - NOTICE: BL31: v2.4(debug):xlnx_rebase_v2.4_2021.1_update1-24-g7174d24f7-dirty - NOTICE: BL31: Built : 11:17:24, Aug 31 2022 - INFO: GICv3 with legacy support detected. - INFO: ARM GICv3 driver initialized in EL3 - INFO: BL31: Initializing runtime services - INFO: setting up optee service.. - WARNING: BL31: cortex_a72: CPU workaround for 859971 was missing! - WARNING: BL31: cortex_a72: CPU workaround for 1319367 was missing! - INFO: BL31: cortex_a72: CPU workaround for cve_2017_5715 was applied - INFO: BL31: cortex_a72: CPU workaround for cve_2018_3639 was applied - INFO: BL31: Initializing BL32 - INFO: executing opteed_init I/TC: - - I/TC: Non-secure external DT found - I/TC: pl011: device parameters ignored (115200) - I/TC: Switching console to device: /axi/serial@ff000000 - I/TC: OP-TEE version: 3.18.0-93-gf893d5703-dev (gcc version 7.3.1 20180425 [linaro-7.3-2018.05 revision d29120a424ecfbc167ef90065c0eeb7f91977701] (Linaro GCC 7.3-2018.05)) #1 Fri Sep 2 13:59:25 UTC 2022 aarch64 - I/TC: WARNING: This OP-TEE configuration might be insecure! - I/TC: WARNING: Please check https://optee.readthedocs.io/en/latest/architecture/porting_guidelines.html - I/TC: Primary CPU initializing - I/TC: Platform Versal: Silicon Revision v2 - I/TC: Hardware Root of Trust: Asymmetric NOT Enabled, Symmetric NOT Enabled - I/TC: Using Development HUK - I/TC: Primary CPU switching to normal world boot - INFO: BL31: Preparing for EL3 exit to normal world - INFO: Entry point address = 0x8000000 - INFO: SPSR = 0x3c9 - - U-Boot 2022.01-17188-g3334d79c23-dirty (Jul 21 2022 - 11:50:46 +0200) - CPU: Versal - Silicon: v2 - Model: Xilinx Versal vck190 Eval board revA (QSPI) - DRAM: 8 GiB - EL Level: EL2 - MMC: mmc@f1050000: 0 - Loading Environment from nowhere... OK - In: serial@ff000000 - Out: serial@ff000000 - Err: serial@ff000000 - Bootmode: JTAG_MODE - Net: - - [...] - Hit any key to stop autoboot: 0 - - 2055 bytes read in 13 ms (154.3 KiB/s) - ## Executing script at 20000000 - sha256+ 566 bytes read in 22 ms (24.4 KiB/s) - 14889652 bytes read in 1015 ms (14 MiB/s) - ## Loading kernel from FIT Image at 10000000 ... - Using 'conf-system-top.dtb' configuration - Verifying Hash Integrity ... OK - Trying 'kernel-1' kernel subimage - Description: Linux kernel - Type: Kernel Image - Compression: gzip compressed - Data Start: 0x10000110 - Data Size: 9252712 Bytes = 8.8 MiB - Architecture: AArch64 - OS: Linux - Load Address: 0x18000000 - Entry Point: 0x18000000 - Hash algo: sha256 - Hash value: a83cc2eacc021dc6f84c481f6ca8238ed755c702b20f5c3c3dd1e8a31b6cb2f0 - Verifying Hash Integrity ... sha256+ OK - ## Loading ramdisk from FIT Image at 10000000 ... - Using 'conf-system-top.dtb' configuration - Verifying Hash Integrity ... OK - Trying 'ramdisk-1' ramdisk subimage - Description: initramfs-ostree-lmp-image-vck190-versal - Type: RAMDisk Image - Compression: uncompressed - Data Start: 0x108db168 - Data Size: 5602258 Bytes = 5.3 MiB - Architecture: AArch64 - OS: Linux - Load Address: unavailable - Entry Point: unavailable - Hash algo: sha256 - Hash value: 6d6f902bb14fc30faee41ab9dc8821a57e6ebfbccd8b0781d7d964bc0f7630a5 - Verifying Hash Integrity ... sha256+ OK - ## Loading fdt from FIT Image at 10000000 ... - Using 'conf-system-top.dtb' configuration - Verifying Hash Integrity ... OK - Trying 'fdt-system-top.dtb' fdt subimage - Description: Flattened Device Tree blob - Type: Flat Device Tree - Compression: uncompressed - Data Start: 0x108d3188 - Data Size: 32506 Bytes = 31.7 KiB - Architecture: AArch64 - Hash algo: sha256 - Hash value: 3a2720ff2aa10e889ee2ff6a419fdf69c3b031e08135ad3800b7ddc6d9df445c - Verifying Hash Integrity ... sha256+ OK - Booting using the fdt blob at 0x108d3188 - Uncompressing Kernel Image - Loading Ramdisk to 7d972000, end 7dec9bd2 ... OK - Loading Device Tree to 000000007d967000, end 000000007d971ef9 ... OK - - Starting kernel ... - - [ 0.000000] Booting Linux on physical CPU 0x0000000000 [0x410fd083] - [ 0.000000] Linux version 5.15.64-lmp-standard (oe-user@oe-host) (aarch64-lmp-linux-gcc (GCC) 11.3.0, GNU ld (GNU Binutils) 2.38.20220708) #1 SMP Thu Sep 1 02:40:19 UTC 2022 - [ 0.000000] Machine model: Xilinx Versal vck190 Eval board revA (QSPI) - [ 0.000000] earlycon: pl11 at MMIO32 0x00000000ff000000 (options '115200n8') - [ 0.000000] printk: bootconsole [pl11] enabled - [ 0.000000] efi: UEFI not found. - [ 0.000000] Zone ranges: - [ 0.000000] DMA32 [mem 0x0000000000000000-0x00000000ffffffff] - [ 0.000000] Normal [mem 0x0000000100000000-0x000000097fffffff] - [ 0.000000] Movable zone start for each node - [ 0.000000] Early memory node ranges - [ 0.000000] node 0: [mem 0x0000000000000000-0x000000005fffffff] - [ 0.000000] node 0: [mem 0x0000000060000000-0x000000006fffffff] - [ 0.000000] node 0: [mem 0x0000000070000000-0x000000007fffffff] - [ 0.000000] node 0: [mem 0x0000000800000000-0x000000097fffffff] - [ 0.000000] Initmem setup node 0 [mem 0x0000000000000000-0x000000097fffffff] - [ 0.000000] cma: Reserved 256 MiB at 0x0000000050000000 - [ 0.000000] psci: probing for conduit method from DT. - [ 0.000000] psci: PSCIv1.1 detected in firmware. - [ 0.000000] psci: Using standard PSCI v0.2 function IDs - - [...] - - [ 12.287689] macb ff0c0000.ethernet eth0: PHY [ff0c0000.ethernet-ffffffff:01] driver [TI DP83867] (irq=POLL) - [ 12.297444] macb ff0c0000.ethernet eth0: configuring for phy/rgmii-id link mode - [ 12.313947] pps pps0: new PPS source ptp0 - [ 12.318721] macb ff0c0000.ethernet: gem-ptp-timer ptp clock registered. - [ OK ] Started containerd container runtime. - [ 17.439954] macb ff0c0000.ethernet eth0: Link is Up - 1Gbps/Full - flow control tx - [ 17.454684] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready - - Linux-microPlatform 4.0.3-1721-77-506-g22e6cd6 vck190-versal - - vck190-versal login: - - - -.. _boot-flow: - https://docs.xilinx.com/r/en-US/ug1304-versal-acap-ssdg/Boot-Flow - -.. _bootgen tool: - https://github.com/Xilinx/bootgen - -.. _Libtomcrypt: - https://optee.readthedocs.io/en/latest/architecture/crypto.html?highlight=libtomcrypt#libtomcrypt - -.. _OP-TEE support: - https://github.com/OP-TEE/optee_os/pull/5426 - -.. _PLM firmware: - https://github.com/Xilinx/embeddedsw - -.. _Versal ACAP: - https://www.xilinx.com/products/silicon-devices/acap/versal.html - -.. _Versal AI Core Series VCK190 Evaluation Kit: - https://www.xilinx.com/products/boards-and-kits/vck190.html - -.. _xilnvm: - https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_services/xilnvm - -.. _xilpuf: - https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_services/xilpuf - -.. _xilsecure: - https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_services/xilsecure - - -