@@ -10,7 +10,7 @@ When booting a system, different programs are run. As a very rough and simplifie
* To find the user's root file system, a Linux Kernel may use an already prepared temporary file system called initramfs.
* In our case, the Linux Kernel is directly embedded in the efi application and it uses a custom initramfs.
UEFI provides a feature called Secure Boot (SB) which can verify the efi applications' signature with keys stored by UEFI, so that an attacker cannot modify the boot sequence and tamper with what is run on the machine early during the boot process. Such an attack would make the threat undetectable with the classic forensic tools, i.e. from the already booted OS.
UEFI provides a feature called Secure Boot (SB) which can verify the efi applications' signature with keys stored by UEFI, so that an attacker cannot modify the boot sequence and tamper with what is run on the machine early during the boot process. Such an attack would make the threat undetectable from the already booted OS with classic forensic tools.
Nexedi developped for Rapid.Space a system going further, which scans the user's root file system to be mounted by initramfs **during** the initramfs stage, i.e. before the final root file system has taken over, and send the scan to Wendelin for further analysis. To do so, we create a custom initramfs embedding the scanner and sender and we sign it with our own keys. Then, if our keys are enrolled by UEFI, it can verify the integrity of our customed initramfs, loaded by UEFI as an efi application. With this process, we get a complete scan of the actual root file system each time a server boots. We can detect abnormal file signatures and permissions while being sure than an attacker could not modify the tools we used to create and send the scan.
So the main components for a user to install this project on a machine are:
* A set of keys
* A set of keys.
* Key enrollment in UEFI.
* Initramfs image creation and signature.
...
...
@@ -30,7 +30,7 @@ With the hardest part to master being the second one, documented in `uefi-keys/R
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. 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.
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](#create-an-initramfs-image) of the current document.
## Create an initramfs image
This stage is about creating and signing an initramfs image with the Metadata Collect Agent (MCA) enabled in it.
...
...
@@ -51,6 +51,7 @@ Run `30generate-image.sh`
### Upload the image
Run `40upload-image.sh` to upload the image in shacache and create an entry in shadir.
This step assumes you have a directory `../tls-access-to-shacache` with a file `test.cfg` inside, containing a shacache certificate, and the associated keys in the same directory.
## Install an initramfs image
This stage is about installing an image on the machine.
...
...
@@ -59,23 +60,19 @@ This stage is about installing an image on the machine.
Run `./installation/10install-dependencies.sh`
### Generate the network script
This step has to be performed only once unless the network configuration has been changed.
This step has to be performed only once per machine unless the network configuration has been changed.
Run `./installation/20generate-get-network.sh`
### Install the image
Run `30install-image.sh`
Modify the command-line calling `networkcache-download` to download filter images with metadata. This step assumes you have a directory `../tls-access-to-shacache` with a file `test.cfg` inside, containing a shacache certificate, and the associated keys in the same directory.
### 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
* 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` (generated from `./dracut.module/dracut.conf.in` and the command-line arguments passed to `dracut`.
* 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.
## For developpers...
### Installation
At the moment, the package names are in `installation/packages.sh` and should be modified there. This script is sourced by `installation/install.sh` and `dracut.module/configure`. Not that at the moment, the `configure` script is very simple and non-standard.
