Setup_for_module_signing.txt

Automatical modules signing during the Kernel-Build using the HSM:

The kernel module signing facility cryptographically signs modules during installation using the unique private kye and then checks the signature upon loading the module. This allows increased kernel security by disallowing the loading of unsigned modules or modules signed with an invalid key.

This setup is adapted so that we can realize the use of HSM in the automatic signing routine of the modules in such a way that the unique private key can never appear openly as a file during kernel building and module signing. 

Step 1: Generate and store the private key securely in the HSM:
pkcs11-tool --module /path/to/hsm/library.so --login --pin <user-PIN> --keypairgen --key-type rsa:2048 --id 01 --label "kernel_signing_key"

Step 2: Confirm that the key pair was generated successfully:
pkcs11-tool --module /path/to/hsm/library.so --login --pin <user-PIN> --list-objects

Step 3: Export the public key and Convert it to the required format, the kernel typically requires the public key in X.509 certificate format:
openssl req -new -x509 -key <(pkcs11-tool --module /path/to/hsm/library.so --login --pin <user-PIN> --read-object --id 01 --type pubkey) -out signing_key.x509 -days 3650

Step 4: Copy signing_key.x509 to "certs" dir

Step 5: Set the parameters: CONFIG_MODULE_SIG=y and CONFIG_MODULE_SIG_FORCE=y in config file.
This specifies how the kernel should deal with a module that has a signature for which the key is not known or a module that is unsigned.
Only modules that have a valid signature that can be verified by a public key in the kernel's possession will be loaded.

Step 6: Set the parameter: CONFIG_MODULE_SIG_ALL=y in config file.
Modules will be automatically signed during the modules_install phase of a build.

Step 7: set the parameter: CONFIG_MODULE_SIG_KEY="certs/signing_key.pem" in config file.
The string provides the path to a directory containing X.509 crtificate (signing_key.x509) and virtually a private key. 
The private key is not physically located in this directory, it is rather extracted by the HSM during the execution of the sign-file script.

Step 8: Modify the sign-file script in the kernel source to use the HSM for signing, 
the script is usually located at /usr/src/linux/scripts/ directory:
-------------sign-file script--------------BEGIN
#!/bin/bash

HASH_ALGO=$1
PRIVATE_KEY=$2
CERT=$3
MODULE=$4

# Use pkcs11-tool to sign the module
pkcs11-tool --module /usr/lib/opensc-pkcs11.so --sign --mechanism RSA-PKCS --input-file $MODULE --output-file $MODULE.sig --login --pin <our-pin> --key-id <key-id>

# Append the signature to the module
cat $MODULE.sig >> $MODULE
-------------sign-file script--------------END

Step 9: We have designed the compilation and build process in such a way that a Debian package is created at the end so that we can install it in our Linux environment without any problems. We achieve this through: 
make -j6 deb-pkg LOCALVERSION=-devimg-waxar KDEB_PKGVERSION=$(make kernelversion)-2

After the compilation, building and signing of the modules is finished, the Debian package file is created:
linux-image-5.15.1-devimg-waxar_5.15.1-2_amd64.deb

After installing this Debian package we can access the kernel and the signed modules. Please note the following: the modules are signed with a kernel-specific certificate that is only valid for the current compilation. The public-key for verification of this certificate is integrated in the kernel. This ensures that after loading the kernel, only modules signed with the corresponding certificate can be loaded. Modules that have no certificate or an invalid certificate are ignored and not loaded.

Signing Kernel and Modules with our CA-Certificate
 
Step 1: Signing the linux kernel with our CA-Certificate using HSM
In order for the linux kernel to be recognized and loaded as trustworthy by Shim, we sign our linux kernel with our CA certificate, whereby the private key is located in the HSM:
openssl dgst -sha256 -engine pkcs11 -keyform engine -sign "pkcs11:token=our_token;object=our_key_label" -out vmlinuz.signed vmlinuz

Step 2: Additionally signing all modules with our CA-Certificate using HSM
To be sure that modules from older kernels or unwanted modules cannot be loaded, we have used the strategy of double signing of all modules. On the one hand with the unique kernel certificate and on the other hand with our CA certificate. Taking into account that our CA certificate is located in the HSM, this gives us a high level of security in terms of preventing the possibility of infiltration of foreign and unknown modules into the boot process.

To sign all modules with our CA certificate, we use "sign_all_modules" script with previously mentioned modified "sign-file" script, which uses HSM, with the correspondingly adjusted <key-id>:
-------------sign_all_modules--------------BEGIN
#!/bin/bash

ModulesDir=/path/to/modules
SignFileDir=/usr/src/linux/scripts

for modfile in $(find $ModulesDir -type f -name *.ko); do
	echo "Signing $modfile"
		# sign each module file
	$SignFileDir/sign-file sha256 nofile nofile $modfile
done
-------------sign_all_modules--------------END