From 04400eea472f6e24af4558beb87a45a6b5b7f5a3 Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Mon, 25 Jan 2021 17:48:30 +0100 Subject: [PATCH] Add centralized secure boot documentation Move the bits from iLO and iRMC, clean them up a bit. Change-Id: I5b6da854ae0214141ae25a17b8ea3c7874636372 --- doc/source/admin/drivers/ilo.rst | 73 ++++------------------ doc/source/admin/drivers/irmc.rst | 22 +------ doc/source/admin/security.rst | 77 +++++++++++++++++++++++- doc/source/install/include/boot-mode.inc | 3 + 4 files changed, 94 insertions(+), 81 deletions(-) diff --git a/doc/source/admin/drivers/ilo.rst b/doc/source/admin/drivers/ilo.rst index fe97d94e83..24ac8c2c4c 100644 --- a/doc/source/admin/drivers/ilo.rst +++ b/doc/source/admin/drivers/ilo.rst @@ -582,69 +582,22 @@ element to the diskimage-builder command to build the image. For example:: UEFI Secure Boot Support ^^^^^^^^^^^^^^^^^^^^^^^^ -The hardware type ``ilo`` supports secure boot deploy. +The hardware type ``ilo`` supports secure boot deploy, see :ref:`secure-boot` +for details. -The UEFI secure boot can be configured in ironic by adding -``secure_boot`` parameter in the ``capabilities`` parameter within -``properties`` field of an ironic node. +iLO specific notes: -``secure_boot`` is a boolean parameter and takes value as ``true`` or -``false``. +In UEFI secure boot, digitally signed bootloader should be able to validate +digital signatures of kernel during boot process. This requires that the +bootloader contains the digital signatures of the kernel. +For the ``ilo-virtual-media`` boot interface, it is recommended that +``boot_iso`` property for user image contains the glance UUID of the boot +ISO. If ``boot_iso`` property is not updated in glance for the user image, +it would create the ``boot_iso`` using bootloader from the deploy iso. This +``boot_iso`` will be able to boot the user image in UEFI secure boot +environment only if the bootloader is signed and can validate digital +signatures of user image kernel. -To enable ``secure_boot`` on a node add it to ``capabilities`` as below:: - - baremetal node set --property capabilities='secure_boot:true' - -Alternatively see `Hardware Inspection Support`_ to know how to -automatically populate the secure boot capability. - -Nodes having ``secure_boot`` set to ``true`` may be requested by adding an -``extra_spec`` to the nova flavor:: - - nova flavor-key ironic-test-3 set capabilities:secure_boot="true" - nova boot --flavor ironic-test-3 --image test-image instance-1 - -If ``capabilities`` is used in ``extra_spec`` as above, nova scheduler -(``ComputeCapabilitiesFilter``) will match only ironic nodes which have -the ``secure_boot`` set appropriately in ``properties/capabilities``. It will -filter out rest of the nodes. - -The above facility for matching in nova can be used in heterogeneous -environments where there is a mix of machines supporting and not supporting -UEFI secure boot, and operator wants to provide a choice to the user -regarding secure boot. If the flavor doesn't contain ``secure_boot`` then -nova scheduler will not consider secure boot mode as a placement criteria, -hence user may get a secure boot capable machine that matches with user -specified flavors but deployment would not use its secure boot capability. -Secure boot deploy would happen only when it is explicitly specified through -flavor. - -Use element ``ubuntu-signed`` or ``fedora`` to build signed deploy iso and -user images from -`diskimage-builder `_. -Please refer to :ref:`deploy-ramdisk` for more information on building -deploy ramdisk. - -The below command creates files named cloud-image-boot.iso, cloud-image.initrd, -cloud-image.vmlinuz and cloud-image.qcow2 in the current working directory:: - - cd - ./bin/disk-image-create -o cloud-image ubuntu-signed baremetal iso - -.. note:: - In UEFI secure boot, digitally signed bootloader should be able to validate - digital signatures of kernel during boot process. This requires that the - bootloader contains the digital signatures of the kernel. - For the ``ilo-virtual-media`` boot interface, it is recommended that - ``boot_iso`` property for user image contains the glance UUID of the boot - ISO. If ``boot_iso`` property is not updated in glance for the user image, - it would create the ``boot_iso`` using bootloader from the deploy iso. This - ``boot_iso`` will be able to boot the user image in UEFI secure boot - environment only if the bootloader is signed and can validate digital - signatures of user image kernel. - -Ensure the public key of the signed image is loaded into bare metal to deploy -signed images. For HPE ProLiant Gen9 servers, one can enroll public key using iLO System Utilities UI. Please refer to section ``Accessing Secure Boot options`` in `HP UEFI System Utilities User Guide `_. diff --git a/doc/source/admin/drivers/irmc.rst b/doc/source/admin/drivers/irmc.rst index 20ac68c42d..460a59b757 100644 --- a/doc/source/admin/drivers/irmc.rst +++ b/doc/source/admin/drivers/irmc.rst @@ -189,30 +189,12 @@ Optional functionalities for the ``irmc`` hardware type UEFI Secure Boot Support ^^^^^^^^^^^^^^^^^^^^^^^^ -The hardware type ``irmc`` supports secure boot deploy. +The hardware type ``irmc`` supports secure boot deploy, see :ref:`secure-boot` +for details. .. warning:: Secure boot feature is not supported with ``pxe`` boot interface. -The UEFI secure boot can be configured by adding ``secure_boot`` parameter, -which is a boolean value. Enabling the secure boot is different when -Bare Metal service is used with Compute service or without Compute service. The -following sections describe both methods: - -* Enabling secure boot with Compute service: - To enable secure boot we need to set a capability on the bare metal node - and the bare metal flavor, for example:: - - baremetal node set --property capabilities='secure_boot:true' - openstack flavor set FLAVOR-NAME --property capabilities:secure_boot="true" - -* Enabling secure boot without Compute service: - Since adding capabilities to the node's properties is only used by the nova - scheduler to perform more advanced scheduling of instances, we need - to enable secure boot without nova, for example:: - - baremetal node set --instance-info capabilities='{"secure_boot": "true"}' - .. _irmc_node_cleaning: Node Cleaning Support diff --git a/doc/source/admin/security.rst b/doc/source/admin/security.rst index 846aeb82fd..d00e59e9ba 100644 --- a/doc/source/admin/security.rst +++ b/doc/source/admin/security.rst @@ -121,7 +121,7 @@ include: - installing signed firmware for BIOS and peripheral devices - using a TPM (Trusted Platform Module) to validate signatures at boot time -- booting machines in :ref:`iLO UEFI Secure Boot Support`, rather than BIOS mode, to +- booting machines in `UEFI secure boot mode`_, rather than BIOS mode, to validate kernel signatures - disabling local (in-band) access from the host OS to the management controller (BMC) - disabling modifications to boot settings from the host OS @@ -130,6 +130,81 @@ Additional references: - :ref:`cleaning` +.. _secure-boot: + +UEFI secure boot mode +===================== + +Some hardware types support turning `UEFI secure boot`_ dynamically when +deploying an instance. Currently these are :doc:`/admin/drivers/ilo` and +:doc:`/admin/drivers/irmc`. + +Support for the UEFI secure boot is declared by adding the ``secure_boot`` +capability in the ``capabilities`` parameter in the ``properties`` field of +a node. ``secure_boot`` is a boolean parameter and takes value as ``true`` or +``false``. + +To enable ``secure_boot`` on a node add it to ``capabilities``:: + + baremetal node set --property capabilities='secure_boot:true' + +Alternatively use :doc:`/admin/inspection` to automatically populate +the secure boot capability. + +.. warning:: + UEFI secure boot only works in UEFI boot mode, see :ref:`boot_mode_support` + for how to turn it on and off. + +Compatible images +----------------- + +Use element ``ubuntu-signed`` or ``fedora`` to build signed deploy ISO and +user images with `diskimage-builder +`_. + +The below command creates files named cloud-image-boot.iso, cloud-image.initrd, +cloud-image.vmlinuz and cloud-image.qcow2 in the current working directory:: + + cd + ./bin/disk-image-create -o cloud-image ubuntu-signed baremetal iso + +Ensure the public key of the signed image is loaded into bare metal to deploy +signed images. + +Enabling with OpenStack Compute +------------------------------- + +Nodes having ``secure_boot`` set to ``true`` may be requested by adding an +``extra_spec`` to the nova flavor:: + + openstack flavor set --property capabilities:secure_boot="true" + openstack server create --flavor --image instance-1 + +If ``capabilities`` is used in ``extra_spec`` as above, nova scheduler +(``ComputeCapabilitiesFilter``) will match only ironic nodes which have +the ``secure_boot`` set appropriately in ``properties/capabilities``. It will +filter out rest of the nodes. + +The above facility for matching in nova can be used in heterogeneous +environments where there is a mix of machines supporting and not supporting +UEFI secure boot, and operator wants to provide a choice to the user +regarding secure boot. If the flavor doesn't contain ``secure_boot`` then +nova scheduler will not consider secure boot mode as a placement criteria, +hence user may get a secure boot capable machine that matches with user +specified flavors but deployment would not use its secure boot capability. +Secure boot deploy would happen only when it is explicitly specified through +flavor. + +Enabling standalone +------------------- + +To request secure boot for an instance in standalone mode (without OpenStack +Compute), you need to add the capability directly to the node's +``instance_info``:: + + baremetal node set --instance-info capabilities='{"secure_boot": "true"}' + +.. _UEFI secure boot: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface#Secure_boot Other considerations ==================== diff --git a/doc/source/install/include/boot-mode.inc b/doc/source/install/include/boot-mode.inc index c528895fce..622c6cc71a 100644 --- a/doc/source/install/include/boot-mode.inc +++ b/doc/source/install/include/boot-mode.inc @@ -80,3 +80,6 @@ following way: boot modes. If the flavor doesn't contain ``boot_mode`` and ``boot_mode`` is configured for bare metal nodes, then nova scheduler will consider all nodes and user may get either ``bios`` or ``uefi`` machine. + +Some hardware support setting secure boot mode, see :ref:`secure-boot` for +details.