097142a6a7
Fixed minor editorial issues. Added sub-section to stx only. closes-bug: 1980666 Signed-off-by: Elisamara Aoki Goncalves <elisamaraaoki.goncalves@windriver.com> Change-Id: Iae3c70db5882ebc57200e9ce4b516848d45b399f
150 lines
5.8 KiB
ReStructuredText
150 lines
5.8 KiB
ReStructuredText
|
|
.. fyl1552681364538
|
|
.. _use-uefi-secure-boot:
|
|
|
|
====================
|
|
Use UEFI Secure Boot
|
|
====================
|
|
|
|
Secure Boot is supported in |UEFI| installations only. It is not used when
|
|
booting |prod| as a legacy boot target.
|
|
|
|
|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.
|
|
|
|
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
|
|
the upgrade is complete.
|
|
|
|
For each node that is going to use secure boot, you must populate the |prod|
|
|
public certificate/key in the |UEFI| Secure Boot authorized database in
|
|
accordance with the board manufacturer's process. This must be done for each
|
|
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
|
|
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
|
|
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
|
|
Microsoft certificate\). While certificates can usually be removed from the
|
|
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.
|
|
|
|
.. only:: starlingx
|
|
|
|
--------------------------------------------------------------
|
|
Build considerations for signing packages for UEFI Secure Boot
|
|
--------------------------------------------------------------
|
|
|
|
The |prod| build environment has provisions for calling out to a signing
|
|
server for purposes of creating a secure boot load. At this time |prod|
|
|
does not include an implementation of the signing server. The following
|
|
describes how the signing process is intended to work in the context of a
|
|
CentOS build. You may find it helpful in implementing your own signing
|
|
server.
|
|
|
|
The following environmental variables should be defined before attempting
|
|
to request a secure boot signing:
|
|
|
|
.. code-block:: none
|
|
|
|
export SIGNING_SERVER=<signing-host>
|
|
export SIGNING_USER=<signing-user>
|
|
export SIGNING_SERVER_SCRIPT=<path-to-signing-script>
|
|
|
|
'build-pkgs' further requires that "$USER" == "jenkins", and
|
|
|
|
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
|
|
|
|
# Set up the server side directory for files transfers.
|
|
UPLOAD_PATH=`ssh $SIGNING_USER@$SIGNING_SERVER sudo $SIGNING_SCRIPT -r`
|
|
|
|
# upload the original package
|
|
scp -q $FILE $SIGNING_USER@$SIGNING_SERVER:$UPLOAD_PATH
|
|
|
|
# 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
|
|
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.
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
Some files may be absent in newer packages.
|
|
|
|
Example:
|
|
|
|
.. code-block:: none
|
|
|
|
sbsign --key $KEYPATH/$KEYNAME.key --cert $KEYPATH/$KEYNAME.crt --output $SIGNEDFILE $UNSIGNEDFILE
|
|
|
|
Keys and certificates:
|
|
|
|
.. code-block:: none
|
|
|
|
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
|
|
|
|
Key generation:
|
|
|
|
.. code-block:: none
|
|
|
|
openssl req -new -x509 -newkey rsa:2048 -keyout $KEY.key -out $KEY.pem -days 3650
|
|
openssl x509 -in $KEY.pem -out $KEY.crt -outform DER
|
|
|
|
.. note::
|
|
|
|
``boot.crt`` should be copied to
|
|
``cgcs-root/build-tools/certificates/TiBoot.crt`` for inclusion during the
|
|
``build-iso`` step.
|