starlingx/docs
Code Issues Proposed changes

Reformat file (r8, r7, r6. r5, dsR8, dsR7, dsR6)

Browse Source 
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 <ronald.stone@windriver.com>
Change-Id: I3fdb3982b162fdc4ce50d4b034a649d0589648df
This commit is contained in:
Ron Stone 2023-07-25 11:48:43 +00:00
parent 8fda6e80c1
commit 80fe12fbe5
1 changed files with 177 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

229
doc/source/security/kubernetes/use-uefi-secure-boot.rst
View File

@ -9,10 +9,14 @@ Use UEFI Secure Boot
Secure Boot is supported in |UEFI| installations only. It is not used when Secure Boot is supported in |UEFI| installations only. It is not used when
booting |prod| as a legacy boot target. 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 |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 system has been installed. Doing so requires a reinstallation of the system.
also means that upgrading from a legacy install to a secure boot install This also means that upgrading from a legacy install to a secure boot install
\(UEFI) is not supported. (|UEFI|) is not supported.
When upgrading a |prod| system from a version which does not support secure 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 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 You may need to work with your hardware vendor to have the certificate
installed. 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 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. mode is enabled, and secure boot is enabled.
Many motherboards ship with Microsoft secure boot certificates Many motherboards ship with Microsoft secure boot certificates
pre-programmed in the |UEFI| certificate database. These certificates may be pre-programmed in the |UEFI| certificate database. These certificates may be
required to boot |UEFI| drivers for video cards, RAID controllers, or NICs 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 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 may be required that you keep the Microsoft certificates to allow for
complete system operation. complete system operation.
Mixed combinations of secure boot and non-secure boot nodes are supported. 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. 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 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 .. only:: partner
@ -65,62 +69,65 @@ to be protected by secure boot.
The following environmental variables should be defined before attempting The following environmental variables should be defined before attempting
to request a secure boot signing: to request a secure boot signing:
.. code-block:: none .. code-block:: bash
export SIGNING_SERVER=<signing-host> export SIGNING_SERVER=<signing-host>
export SIGNING_USER=<signing-user> export SIGNING_USER=<signing-user>
export SIGNING_SERVER_SCRIPT=<path-to-signing-script> export SIGNING_SERVER_SCRIPT=<path-to-signing-script>
'build-pkgs' further requires that "$USER" == "jenkins", and ``build-pkgs`` further requires that ``$USER`` be set to "jenkins", and
:command:`export FORMAL_BUILD=1``.
export FORMAL_BUILD=1
If the above criteria is met, it calls into ``sign-secure-boot``. If the above criteria is met, it calls into ``sign-secure-boot``.
This is an example of the call sequence: 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_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 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 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) DOWNLOAD_FILENAME=$(basename $OUTPUT_FILE)
scp -q $SIGNING_USER@$SIGNING_SERVER:$OUTPUT_FILE $(dirname $FILE) scp -q $SIGNING_USER@$SIGNING_SERVER:$OUTPUT_FILE $(dirname $FILE)
Within the signing server there are two keys used for signing, known as Within the signing server there are two keys used for signing, known as the
the `boot` key and the `shim` key. The public half of the `boot` key `boot` key and the `shim` key. The public `boot` key file must be manually
must be manually added to the secure boot keychain in the firmware. The added to the secure boot keychain in the firmware. The `boot` key signs the
`boot` key signs the first executable loaded, contained in the `shim` first executable loaded, contained in the `shim` package. The first
package. The first executable must then install the public half of the executable must then install the public `shim` key file (automatically)
`shim` key (automatically) before passing control to the grub, and before passing control to the grub, and ultimately the kernel, both of
ultimately the kernel, both of which are signed by the private `shim` which are signed by the private `shim` key.
key.
Three packages need to be passed to the signing server. The RPMs need Three packages need to be passed to the signing server. The RPMs need to be
to be unpacked, the relevant binaries signed with the correct keys, and unpacked, the relevant binaries signed with the correct keys, and the RPMs
the RPMs reassembled. reassembled.
.. code-block:: none .. table::
:widths: auto
package key files to sign +---------+------+------------------------------------+
========= ==== =========================== | Package | Key | Files to sign |
shim boot BOOTX64, shim, shimx64 +=========+======+====================================+
shim MokManager, fallback, mmx64, fbx64 | shim | boot | BOOTX64, shim, shimx64 |
grub shim grubx64.efi, gcdx64.efi | | shim | MokManager, fallback, mmx64, fbx64 |
kernel shim +---------+------+------------------------------------+
| grub | shim | grubx64.efi, gcdx64.efi |
+---------+------+------------------------------------+
| kernel | shim | |
+---------+------+------------------------------------+
.. note:: .. note::
`shim` files that are required to be signed might might include a ``.efi`` `shim` files that are required to be signed might might include a
or ``.EFI`` suffix. ``.efi`` or ``.EFI`` suffix.
Some files may be absent in newer packages. 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 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
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
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 .. code-block:: none
@ -164,12 +172,17 @@ to be protected by secure boot.
server. server.
The secure boot verification sequence of StarlingX Debian is: 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. #. UEFI firmware verify shim image
Bootloader grub-efi will enroll the public key to verify kernel and initramfs 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: 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 sign-secure-boot_debian
build-image 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. and used to setup signing server access without password.
The signing script ``sign-secure-boot_debian`` does secure boot signing for 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 #. Sign shim / grub images
The shim/grub efi images are obtained from extracted shim/grub The shim/grub efi images are obtained from extracted shim/grub
packages, and they are sent to signing server and signed there and packages, and they are sent to signing server and signed there and
copied back. Then the shim/grub packages are repacked with the copied back. Then the shim/grub packages are repacked with the
signed efi images. signed efi images.
(2) Sign kernel images and LockDown.efi #. 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.
(3) Sign initramfs and mini initrd The file sign_rootfs-post-scripts is inserted to where the hook script
The file sign_initramfs-sign-script is inserted to where the hook "rootfs-post-scripts" is defined in the LAT config file
script "initramfs-sign-script" is defined in the LAT config file ``base-bullseye.yaml``. This will sign kernel images and
base-bullseye.yaml. This will sign initramfs and mini initrd on signing server in ``LockDown.efi`` on signing server in the LAT build process. The
the LAT build process. "rootfs-post-scripts" is the hook in LAT tool running after rootfs is
The "initramfs-sign-script" is the hook in LAT tool running after initramfs created.
is created.
Above (2) and (3) prepare the signing codes in LAT config file. #. Sign initramfs and mini initrd
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_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: 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 upload path from signing server.
REQUEST=$(ssh ${SSH_OPTION_NOCHECKING} ${SIGNING_SERVER} sudo /opt/signing/sign-debian.sh -r) 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 # Copy back signed shimx64.efi which is renamed as bootx64.efi
sudo scp ${SSH_OPTION_NOCHECKING} ${SIGNING_SERVER}:${UPLOAD_PATH}/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 ``sign-debian.sh``, above, is the script running on signing server whose
is defined as below: interface is defined as below:
.. code-block:: none .. code-block:: none
@ -251,10 +265,10 @@ to be protected by secure boot.
-t shimtool - signs a shim tool EFI binary with the shim key -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 -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
@ -262,30 +276,45 @@ to be protected by secure boot.
the verification process of secure boot process for StarlingX the verification process of secure boot process for StarlingX
Debian. Debian.
Keys Introduction: .. rubric:: Keys Introduction:
tis-boot.crt: it is the public key flashed into UEFI to verify
bootx64.efi (signed shim image shimx64.efi); ``tis-boot.crt``: The public key flashed into |UEFI| to verify
tis-shim.der: it is the public key used by shim to verify ``bootx64.efi`` (signed shim image ``shimx64.efi``)
grubx64.efi (signed grub image) and mmx64.efi
``tis-shim.der``: The public key used by shim to verify
``grubx64.efi`` (signed grub image) and ``mmx64.efi``
(signed shim tool image); (signed shim tool image);
boot_pub_key: it is the public key used by grub to verify signed
``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. 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 ``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. which is in the iso image.
The following ways can be used to create substitute keys: The following methods can be used to create substitute keys:
(1)example to create tis-boot.crt/TiBoot.crt
#. Example to create ``tis-boot.crt/TiBoot.crt``.
.. 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 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 openssl x509 -inform der -in BOOT.der -out BOOT.pem
cp BOOT.pem tis-boot.crt cp BOOT.pem tis-boot.crt
cp BOOT.priv tis-boot.key cp BOOT.priv tis-boot.key
cp BOOT.der TiBoot.crt cp BOOT.der TiBoot.crt
The tis-boot.crt and tis-boot.key are used to sign images mentioned above (shim 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).
(2)example to create boot_pub_key The ``tis-boot.crt`` and ``tis-boot.key`` are used to sign images
mentioned above (shim 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).
#. Example to create ``boot_pub_key``.
.. code-block:: bash
#!/bin/bash #!/bin/bash
key_dir="./" key_dir="./"
@ -312,23 +341,30 @@ to be protected by secure boot.
gpg --homedir "${key_dir}" --export-secret-keys --pinentry-mode=loopback --passphrase "${pw}" --armor "${name_real}" > "${priv_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 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 and initramfs image and efitools image and so on). 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 commands to sign image files:
* Signing command to sign type shim/grub/shimtool image files:
.. code-block:: none .. code-block:: none
Signing command to sign type shim/grub/shimtool image files:
sbsign --key $KEYPATH/$KEYNAME.key \ sbsign --key $KEYPATH/$KEYNAME.key \
--cert $KEYPATH/$KEYNAME.crt \ --cert $KEYPATH/$KEYNAME.crt \
--output $SIGNEDFILE \ --output $SIGNEDFILE \
$UNSIGNEDFILE $UNSIGNEDFILE
for "-t shim", the output file name is bootx64.efi; * 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. * 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 \ gpg2 --batch \
--homedir ${GPGHOME} \ --homedir ${GPGHOME} \
--passphrase PASSWORD \ --passphrase PASSWORD \
@ -342,4 +378,5 @@ to be protected by secure boot.
--passphrase-fd 0 \ --passphrase-fd 0 \
${FILEIN} ${FILEIN}
Please pay attention to the keys they should use according to [Keys management] section. Refer to :ref:`Key management <key-management-use-uefi-secure-boot>`
to determine the keys they should use.