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 <ronald.stone@windriver.com>
Change-Id: I3fdb3982b162fdc4ce50d4b034a649d0589648df
(cherry picked from commit 80fe12fbe5
)
This commit is contained in:
parent
36ad22e2e7
commit
6b18a5a8b3
|
@ -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.
|
||||
|
||||
|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.
|
||||
.. 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 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
|
||||
Microsoft certificate\). While certificates can usually be removed from the
|
||||
certificate database \(again, this is UEFI implementation specific\) it
|
||||
(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.
|
||||
to be protected.
|
||||
|
||||
.. only:: starlingx
|
||||
|
||||
|
@ -61,62 +65,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=<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
|
||||
``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.
|
||||
|
||||
|
@ -126,16 +133,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
|
||||
|
||||
|
|
Loading…
Reference in New Issue