@@ -6,7 +6,7 @@ Every command requires to be performed while logged as root unless explicitely i
This stage is about enrolling Rapid.Space's keys in the UEFI firmware of the machine. It all happens in the `uefi-keys/` directory.
`cd uefi-keys/`
Refer to the `README.md` file in there and follow the instructions.
Refer to the `README.md` file in there and follow the instructions. Note that it is usually required one time. If Rapid Space's keys are already enrolled on the machine and they are the one in `uefi-keys/keys`, then you can proceed to [the next step](#initramfs-image) of the current document.
## Initramfs image
This stage is about creating and signing an initramfs image with the Metadata Collect Agent (MCA) enabled in it.
...
...
@@ -17,5 +17,10 @@ Run `sudo ./installation/dependencies.sh`
### Install the dracut module and signed initramfs image
Run `sudo ./installation/install.sh`
Notes:
* The installation of the dracut module is performed by `dracut.module/Makefile`.
* The initramfs image is created by dracut according to the preferences in dracut.module/dracut.conf and the command-line.
* The (unsigned) initramfs image is then signed by dracut, again according to dracut.module/dracut.conf
### Secure Boot
Make sure Secure Boot is enabled. It should be in Custom Mode.
To perform the following instructions, some packages are needed. They are installed by `dependencies.sh` of this directory. By default, the command listed below require to be logged as root. It will be pointed out otherwise.
This steps are only needed if Rapid Space's keys are not already enrolled on the machine. To display the current keys, run `efi-readvar` (no root access needed). If the Common Name (CN) of the Platform Key (PK) contains the string "Rapid.Space", then Rapid Space's keys are already enrolled and you can probably go back to the root directory of this project. Else, please proceed reading this document.
To see the Common Name, scroll up to the top of the `efi-readvar` output, in the field corresponding to the variable PK, then after "CN=" is the Common Name.
By default, the command listed below require to be logged as root. It will be indicated otherwise.
## Install the dependencies
To perform the following instructions, some packages are needed. They are installed by `dependencies.sh` of this directory.
Run `./dependencies.sh`
## Create the keys
WARNING: A set of keys is already created here. So the following instruction is probably NOT what you want to do. This section is simply for documentation and you should proceed to the next section.
Run the script `mkkeys.sh` (no root access needed):
Run the script `./make_keys.sh` (no root access needed). The script creates the keys in `keys/`.
## Sign a UEFI application
You have nothing special to do in this section. This is performed by dracut right after creating the (unsigned) image. Dracut is called in `installation/install.sh` with parameters according to `dracut.conf` and the command line. Tip: `dracut.conf` if generated by `installation/install.sh` from `dracut.conf.in`.
## Sign an UEFI application
You have nothing special to do in this section. This step is documented in the `README.md` at the root of this project. Once the keys are created, you do not have to follow the rest of this document to sign an image. Although, it is required to actually boot on such an image.
## UEFI keys
Run `efi-readvar` (no root access needed).
To display the current keys, run `efi-readvar` (no root access needed).
* The `PK` variable correponds to the Platform Key. There can be only one per machine and it is the top-level key. It is needed to modify the `KEK` variable.
* The `KEK` variable corresponds to the Key Exchange Keys. At least one of them are needed in order to modify the `db` and `dbx` variables.
* The `db` variable corresponds the databases of authorized keys and certificates. It can be viewed as a whitelist and it contains the signing key of the initramfs images we create and use.
* The `dbx` variable corresponds to the databases of forbidden keys and certificates. It can be viewed as a blacklist and has a greater priority than `db`. That means that if it contains a key or certificate also in `db`, then the key or certificate is still unauthorized and it cannot be used to boot on the system. We do not use `dbx` here, as at the moment we enroll only our own key.
* The `MokList` variable is not used here, nor is it documented.
If the fields `PK`, `KEK`, `db` or `dbx` are not all empty, then follow continue to [the next section](#remove-the-current-keys). Else you can bypass the next section and jump directly to [the section after](#add-the-keys-from-rapid-space).
If the PK's Common Name (CN) contains "Rapid.Space", then you probably don't need to do anything unless you are in an undocumented use case.
Else, if at least one of the `PK`, `KEK`, `db` and `dbx` variables has an entry (i.e. `efi-readvar` displays something that seems meaningful), then proceed to [the next section](#remove-the-current-keys).
Else, the output of `efi-readvar` should be clear about the fact that the variables has no entries, and you can bypass the next section and jump directly to [the section after](#add-the-keys-from-rapid-space).
### Remove the current keys
Reboot. Enter the BIOS, disable Secure Boot (SB) and remove every keys. The following instructions are based on the UEFI interface of a capri and may vary depending on the hardware and the UEFI firmware version.
Boot the machine and enter the BIOS. There, disable Secure Boot (SB) and remove every keys. The following instructions are based on the UEFI interface of the capri in Lille office and may vary depending on the hardware and the UEFI firmware version.
To do so, you have to:
To remove the current keys, you have to:
1. Disable Secure Boot
...
...
@@ -33,8 +45,10 @@ To do so, you have to:
3. Go in `Key Management` and delete the keys: `Platform Key (PK)`, `Key Exchange Keys (KEK)`, `Authorized Signatures (db)`, `Forbidden Signatures (dbx)`.
Save and exit, and this time `efi-readvar` should tell that these variables have no entries.
### Add the keys from Rapid Space
If it is empty or after the previous stage is done, add the keys to UEFI as follow. We assume the keys have the name `mkkeys.sh` gave them:
If all the `PK`, `KEK`, `db` and `dbx` variables have no entries, or after the previous stage is done, add the keys to UEFI as follow. We assume the keys have the name `make_keys.sh` gave them:
* Add the Platform Key (the authority key for the machine):
`efi-updatevar -f PK.auth PK`
...
...
@@ -42,12 +56,9 @@ If it is empty or after the previous stage is done, add the keys to UEFI as foll
`efi-updatevar -a -c KEK.crt -k PK.key KEK`
* Add the whitelist certificate:
`efi-updatevar -a -c DB.crt -k KEK.key db`
* Set the variables as immutable:
TODO:
`efi-updatevar -a -c db.crt -k KEK.key db`
* Run `efi-readvar` again to check that `PK`, `KEK` and `db` have at least one entry.
* Run `efi-readvar` again to check that `PK`, `KEK` and `db` have exactly one entry with the Common Name (CN) containing "Rapid.Space".
