From 80fe12fbe598d1cfc029d2ce331dd9806afccf05 Mon Sep 17 00:00:00 2001 From: Ron Stone Date: Tue, 25 Jul 2023 11:48:43 +0000 Subject: [PATCH] Reformat file (r8, r7, r6. r5, dsR8, dsR7, dsR6) This file required an editorial scrub. Poorly structured and formatted. Several instances of uncommented narrative text in code-blocks. Grammer and punct. errors. Etc. Signed-off-by: Ron Stone Change-Id: I3fdb3982b162fdc4ce50d4b034a649d0589648df --- .../kubernetes/use-uefi-secure-boot.rst | 317 ++++++++++-------- 1 file changed, 177 insertions(+), 140 deletions(-) diff --git a/doc/source/security/kubernetes/use-uefi-secure-boot.rst b/doc/source/security/kubernetes/use-uefi-secure-boot.rst index 7831233ff..658df4917 100644 --- a/doc/source/security/kubernetes/use-uefi-secure-boot.rst +++ b/doc/source/security/kubernetes/use-uefi-secure-boot.rst @@ -9,10 +9,14 @@ Use UEFI Secure Boot Secure Boot is supported in |UEFI| installations only. It is not used when booting |prod| as a legacy boot target. +.. contents:: |minitoc| + :local: + :depth: 1 + |prod| currently does not support switching from legacy to |UEFI| mode after a -system has been installed. Doing so requires a reinstall of the system. This -also means that upgrading from a legacy install to a secure boot install -\(UEFI) is not supported. +system has been installed. Doing so requires a reinstallation of the system. +This also means that upgrading from a legacy install to a secure boot install +(|UEFI|) is not supported. When upgrading a |prod| system from a version which does not support secure boot to a version that does, do not enable secure boot in |UEFI| firmware until @@ -26,24 +30,24 @@ node before starting installation. You may need to work with your hardware vendor to have the certificate installed. -There is often an option in the UEFI setup utility which allows a user to +There is often an option in the |UEFI| setup utility which allows a user to browse to a file containing a certificate to be loaded in the authorized -database. This option may be hidden in the UEFI setup utility unless UEFI +database. This option may be hidden in the |UEFI| setup utility unless |UEFI| mode is enabled, and secure boot is enabled. Many motherboards ship with Microsoft secure boot certificates pre-programmed in the |UEFI| certificate database. These certificates may be required to boot |UEFI| drivers for video cards, RAID controllers, or NICs -\(for example, the |PXE| boot software for a NIC may have been signed by a +(for example, the |PXE| boot software for a NIC may have been signed by a Microsoft certificate). While certificates can usually be removed from the -certificate database (again, this is UEFI implementation specific) it +certificate database (again, this is |UEFI| implementation specific) it may be required that you keep the Microsoft certificates to allow for complete system operation. Mixed combinations of secure boot and non-secure boot nodes are supported. For example, a controller node may secure boot, while a worker node may not. Secure boot must be enabled in the |UEFI| firmware of each node for that node -to be protected by secure boot. +to be protected. .. only:: partner @@ -65,62 +69,65 @@ to be protected by secure boot. The following environmental variables should be defined before attempting to request a secure boot signing: - .. code-block:: none + .. code-block:: bash export SIGNING_SERVER= export SIGNING_USER= export SIGNING_SERVER_SCRIPT= - 'build-pkgs' further requires that "$USER" == "jenkins", and - - export FORMAL_BUILD=1 + ``build-pkgs`` further requires that ``$USER`` be set to "jenkins", and + :command:`export FORMAL_BUILD=1``. If the above criteria is met, it calls into ``sign-secure-boot``. This is an example of the call sequence: - .. code-block:: none + .. code-block:: bash - # Set up the server side directory for files transfers. + # 1. Set up the server side directory for files transfers. UPLOAD_PATH=`ssh $SIGNING_USER@$SIGNING_SERVER sudo $SIGNING_SCRIPT -r` - # upload the original package + # 2. upload the original package scp -q $FILE $SIGNING_USER@$SIGNING_SERVER:$UPLOAD_PATH - # Request that the package be signed + # 3. Request that the package be signed ssh $SIGNING_USER@$SIGNING_SERVER sudo $SIGNING_SCRIPT -v -i $UPLOAD_PATH/$(basename $FILE) $UNSIGNED_OPTION -t $TYPE > $TMPFILE - # Download the file from the signing server + # 4. Download the file from the signing server DOWNLOAD_FILENAME=$(basename $OUTPUT_FILE) scp -q $SIGNING_USER@$SIGNING_SERVER:$OUTPUT_FILE $(dirname $FILE) - Within the signing server there are two keys used for signing, known as - the `boot` key and the `shim` key. The public half of the `boot` key - must be manually added to the secure boot keychain in the firmware. The - `boot` key signs the first executable loaded, contained in the `shim` - package. The first executable must then install the public half of the - `shim` key (automatically) before passing control to the grub, and - ultimately the kernel, both of which are signed by the private `shim` - key. + Within the signing server there are two keys used for signing, known as the + `boot` key and the `shim` key. The public `boot` key file must be manually + added to the secure boot keychain in the firmware. The `boot` key signs the + first executable loaded, contained in the `shim` package. The first + executable must then install the public `shim` key file (automatically) + before passing control to the grub, and ultimately the kernel, both of + which are signed by the private `shim` key. - Three packages need to be passed to the signing server. The RPMs need - to be unpacked, the relevant binaries signed with the correct keys, and - the RPMs reassembled. + Three packages need to be passed to the signing server. The RPMs need to be + unpacked, the relevant binaries signed with the correct keys, and the RPMs + reassembled. - .. code-block:: none + .. table:: + :widths: auto - package key files to sign - ========= ==== =========================== - shim boot BOOTX64, shim, shimx64 - shim MokManager, fallback, mmx64, fbx64 - grub shim grubx64.efi, gcdx64.efi - kernel shim + +---------+------+------------------------------------+ + | Package | Key | Files to sign | + +=========+======+====================================+ + | shim | boot | BOOTX64, shim, shimx64 | + | | shim | MokManager, fallback, mmx64, fbx64 | + +---------+------+------------------------------------+ + | grub | shim | grubx64.efi, gcdx64.efi | + +---------+------+------------------------------------+ + | kernel | shim | | + +---------+------+------------------------------------+ .. note:: - `shim` files that are required to be signed might might include a ``.efi`` - or ``.EFI`` suffix. + `shim` files that are required to be signed might might include a + ``.efi`` or ``.EFI`` suffix. Some files may be absent in newer packages. @@ -130,16 +137,17 @@ to be protected by secure boot. sbsign --key $KEYPATH/$KEYNAME.key --cert $KEYPATH/$KEYNAME.crt --output $SIGNEDFILE $UNSIGNEDFILE - Keys and certificates: + .. rubric:: Keys and certificates: - .. code-block:: none + * ``boot.crt`` - Certificate to boot (to be programmed in firmware) - boot.crt - Certificate to boot (to be programmed in firmware) - boot.key - Private key with which to sign shim - shim.crt - Certificated embedded within shim used to validate kernel, grub - shim.key - Private key with which to sign kernel/grub + * ``boot.key`` - Private key with which to sign shim - Key generation: + * ``shim.crt`` - Certificated embedded within shim used to validate kernel, grub + + * ``shim.key`` - Private key with which to sign kernel/grub + + .. rubric:: Key generation: .. code-block:: none @@ -164,12 +172,17 @@ to be protected by secure boot. server. The secure boot verification sequence of StarlingX Debian is: - UEFI firmware verify shim image; - shim verify grub image; - grub verify kernel image and initramfs image. - Bootloader shim will enroll the public key to verify grub image. - Bootloader grub-efi will enroll the public key to verify kernel and initramfs image. + #. UEFI firmware verify shim image + + #. shim verify grub image + + #. grub verify kernel image and initramfs image + + The bootloader shim will enroll the public key to verify grub image. + + The bootloader grub-efi will enroll the public key to verify kernel and + initramfs image. The following process should be followed to request a secure boot signing: @@ -184,43 +197,44 @@ to be protected by secure boot. sign-secure-boot_debian build-image - The "key file" is the private key generated by "ssh-keygen -t rsa" + The "key file" is the private key generated by :command:`ssh-keygen -t rsa` and used to setup signing server access without password. The signing script ``sign-secure-boot_debian`` does secure boot signing for - |prod| Debian in this way: + |prod| Debian as follows: - .. code-block:: none - (1) Sign shim / grub images - The shim/grub efi images are obtained from extracted shim/grub - packages, and they are sent to signing server and signed there and - copied back. Then the shim/grub packages are repacked with the - signed efi images. + #. Sign shim / grub images - (2) Sign kernel images and LockDown.efi - The file sign_rootfs-post-scripts is inserted to where the - hook script "rootfs-post-scripts" is defined in the LAT config file - base-bullseye.yaml. This will sign kernel images and LockDown.efi - on signing server in the LAT build process. - The "rootfs-post-scripts" is the hook in LAT tool running after rootfs - is created. + The shim/grub efi images are obtained from extracted shim/grub + packages, and they are sent to signing server and signed there and + copied back. Then the shim/grub packages are repacked with the + signed efi images. - (3) Sign initramfs and mini initrd - The file sign_initramfs-sign-script is inserted to where the hook - script "initramfs-sign-script" is defined in the LAT config file - base-bullseye.yaml. This will sign initramfs and mini initrd on signing server in - the LAT build process. - The "initramfs-sign-script" is the hook in LAT tool running after initramfs - is created. + #. Sign kernel images and ``LockDown.efi`` - Above (2) and (3) prepare the signing codes in LAT config file. - After build-image is triggered, the signing codes inserted in LAT config files will - run on LAT container in the right sequence. + The file sign_rootfs-post-scripts is inserted to where the hook script + "rootfs-post-scripts" is defined in the LAT config file + ``base-bullseye.yaml``. This will sign kernel images and + ``LockDown.efi`` on signing server in the LAT build process. The + "rootfs-post-scripts" is the hook in LAT tool running after rootfs is + created. + + #. Sign initramfs and mini initrd + + The file`` sign_initramfs-sign-script`` is inserted to where the hook + script ``initramfs-sign-script`` is defined in the LAT config file + ``base-bullseye.yaml``. This will sign initramfs and mini initrd on + signing server in the LAT build process. The ``initramfs-sign-script`` + is the hook in LAT tool running after initramfs is created. + + **2** and **3** above prepare the signing codes in the LAT config file. + After build-image is triggered, the signing codes inserted into the LAT + config files will run on the LAT container in the correct sequence. Here is an example for signing an image file in sign-secure-boot_debian: - .. code-block:: none + .. code-block:: bash # Request upload path from signing server. REQUEST=$(ssh ${SSH_OPTION_NOCHECKING} ${SIGNING_SERVER} sudo /opt/signing/sign-debian.sh -r) @@ -233,8 +247,8 @@ to be protected by secure boot. # Copy back signed shimx64.efi which is renamed as bootx64.efi sudo scp ${SSH_OPTION_NOCHECKING} ${SIGNING_SERVER}:${UPLOAD_PATH}/bootx64.efi ./ - The sign-debian.sh in above code is the script running on signing server whose interface - is defined as below: + ``sign-debian.sh``, above, is the script running on signing server whose + interface is defined as below: .. code-block:: none @@ -251,84 +265,106 @@ to be protected by secure boot. -t shimtool - signs a shim tool EFI binary with the shim key -t grub-gpg - signs a kernel/initrd/grub.cfg with the grub gpg key + .. _key-management-use-uefi-secure-boot: - Keys management: + .. rubric:: Keys management: - .. code-block:: none - Upstream stx public keys repo: https://opendev.org/starlingx/public-keys + Upstream stx public keys repo: https://opendev.org/starlingx/public-keys - The keys under cgcs-root/public-keys are the public keys used in - the verification process of secure boot process for StarlingX - Debian. + The keys under cgcs-root/public-keys are the public keys used in + the verification process of secure boot process for StarlingX + Debian. - Keys Introduction: - tis-boot.crt: it is the public key flashed into UEFI to verify - bootx64.efi (signed shim image shimx64.efi); - tis-shim.der: it is the public key used by shim to verify - grubx64.efi (signed grub image) and mmx64.efi - (signed shim tool image); - boot_pub_key: it is the public key used by grub to verify signed - kernel image and initramfs image and efitools image and so on. - TiBoot.crt: it is the same pub key with tis-boot.crt (pem) as a - der format. It is installed as /CERTS/TiBoot.crt in the efi.img - which is in the iso image. + .. rubric:: Keys Introduction: + + ``tis-boot.crt``: The public key flashed into |UEFI| to verify + ``bootx64.efi`` (signed shim image ``shimx64.efi``) - The following ways can be used to create substitute keys: - (1)example to create tis-boot.crt/TiBoot.crt - openssl req -new -x509 -newkey rsa:2048 -keyout BOOT.priv -outform DER -out BOOT.der -days 36500 -subj "/CN=My Boot/" -nodes - openssl x509 -inform der -in BOOT.der -out BOOT.pem - cp BOOT.pem tis-boot.crt - cp BOOT.priv tis-boot.key - cp BOOT.der TiBoot.crt - The tis-boot.crt and tis-boot.key are used to sign images mentioned above (shim image). + ``tis-shim.der``: The public key used by shim to verify + ``grubx64.efi`` (signed grub image) and ``mmx64.efi`` + (signed shim tool image); - The tis-shim.crt/tis-shim.der/tis-shim.key can be created in the same way, and used to sign images mentioned above (grub image and shim tool image). + ``boot_pub_key``: it is the public key used by grub to verify signed + kernel image and initramfs image and efitools image and so on. - (2)example to create boot_pub_key + ``TiBoot.crt``: it is the same pub key with ``tis-boot.crt`` (pem) as a + der format. It is installed as ``/CERTS/TiBoot.crt`` in the ``efi.img`` + which is in the iso image. - #!/bin/bash - key_dir="./" - priv_key="${key_dir}/BOOT-GPG-PRIVKEY-SecureBootCore" - pub_key="${key_dir}/BOOT-GPG-KEY-SecureBootCore" - name_real="SecureBootCore" - pw="PASSWORD" - USE_PW="Passphrase: PASSWORD" - cat >"${key_dir}/gen_keyring" < "${pub_key}" - gpg --homedir "${key_dir}" --export-secret-keys --pinentry-mode=loopback --passphrase "${pw}" --armor "${name_real}" > "${priv_key}" - gpg --homedir "${key_dir}" --export "${name_real}" > ${key_dir}/boot_pub_key + #. Example to create ``tis-boot.crt/TiBoot.crt``. - The BOOT-GPG-PRIVKEY-SecureBootCore is used to sign images mentioned above (kernel image and initramfs image and efitools image and so on). + .. code-block:: bash + + openssl req -new -x509 -newkey rsa:2048 -keyout BOOT.priv -outform DER -out BOOT.der -days 36500 -subj "/CN=My Boot/" -nodes + openssl x509 -inform der -in BOOT.der -out BOOT.pem + cp BOOT.pem tis-boot.crt + cp BOOT.priv tis-boot.key + cp BOOT.der TiBoot.crt - Signing commands to sign image files: - .. code-block:: none + The ``tis-boot.crt`` and ``tis-boot.key`` are used to sign images + mentioned above (shim image). - Signing command to sign type shim/grub/shimtool image files: - sbsign --key $KEYPATH/$KEYNAME.key \ - --cert $KEYPATH/$KEYNAME.crt \ - --output $SIGNEDFILE \ - $UNSIGNEDFILE + The ``tis-shim.crt``/``tis-shim.der``/``tis-shim.key`` can be created in + the same way, and used to sign images mentioned above (grub image and + shim tool image). - for "-t shim", the output file name is bootx64.efi; - for "-t grub", the output file name is grubx64.efi; - for "-t shimtool", the output file name is ${UNSIGNEDFILE}.signed. + #. Example to create ``boot_pub_key``. + + .. code-block:: bash + + #!/bin/bash + key_dir="./" + priv_key="${key_dir}/BOOT-GPG-PRIVKEY-SecureBootCore" + pub_key="${key_dir}/BOOT-GPG-KEY-SecureBootCore" + name_real="SecureBootCore" + pw="PASSWORD" + USE_PW="Passphrase: PASSWORD" + cat >"${key_dir}/gen_keyring" < "${pub_key}" + gpg --homedir "${key_dir}" --export-secret-keys --pinentry-mode=loopback --passphrase "${pw}" --armor "${name_real}" > "${priv_key}" + gpg --homedir "${key_dir}" --export "${name_real}" > ${key_dir}/boot_pub_key + + The ``BOOT-GPG-PRIVKEY-SecureBootCore`` is used to sign images mentioned + above (kernel image, initramfs image and efitools image and so on). + + #. Signing commands to sign image files: + + * Signing command to sign type shim/grub/shimtool image files: + + .. code-block:: none + + sbsign --key $KEYPATH/$KEYNAME.key \ + --cert $KEYPATH/$KEYNAME.crt \ + --output $SIGNEDFILE \ + $UNSIGNEDFILE + + * for ``-t shim``, the output file name is ``bootx64.efi`` + + * for ``-t grub``, the output file name is ``grubx64.efi`` + + * for ``-t shimtool``, the output file name is ${UNSIGNEDFILE}.signed + + * Signing command to sign type grub-gpg files: + + .. code-block:: - Signing command to sign type grub-gpg files: gpg2 --batch \ --homedir ${GPGHOME} \ --passphrase PASSWORD \ @@ -342,4 +378,5 @@ to be protected by secure boot. --passphrase-fd 0 \ ${FILEIN} - Please pay attention to the keys they should use according to [Keys management] section. + Refer to :ref:`Key management ` + to determine the keys they should use.