INSTALL file for Euresys Memento
================================

Typical installation:

  sudo ./install.sh

The installer first uninstalls the Memento software package if it is already
installed on the system.

The typical installation copies the Memento software package to the system,
then builds and inserts the Memento kernel module. This installation should
be suitable in most situations.

However depending on the target machine it is sometimes required to split the
installation process into two steps, not necessarily happening on the same
machine:

  1. building the Memento kernel module (not necessarily on target machine)

       cd drivers/linux
       make MODULE=memento KDIR=path/to/linux/source
       cd ../..

     this builds the Memento kernel module drivers/linux/memento.ko
     (as well as the symbols file drivers/linux/Module.symvers) using the
     given kernel source tree located at path/to/linux/source

  2. installing a prebuilt Memento kernel module as well as the software
     package to the target platform

       sudo ./install.sh -m path/to/memento.ko

     this copies and inserts the supplied Memento kernel module to the current
     running kernel

     Note: the Memento module exposes symbols that are required by other
           Euresys kernel modules relying on Memento. While building such
           modules, it might be necessary to provide the file containing
           the list of those symbols (Module.symvers) to KBUILD_EXTRA_SYMBOLS

Kernel Module Signing
=====================

With Secure Boot enabled or "module.sig_enforce=1" linux kernel argument set,
modules are required to be signed

The installer supports 3 major use cases:

  - Automatic on debian-based systems with shim-signed keys and dkms
  - Automatic with generated keys in /var/lib/euresys/mok
  - Manual

Automatic procedure on debian-based systems with shim-signed keys and dkms:

  1. install dkms:

       sudo apt install dkms

  2. if the public key /var/lib/shim-signed/mok/MOK.der and
     the private key /var/lib/shim-signed/mok/MOK.priv do not exist, run:

       sudo update-secureboot-policy --new-key

  3. install the package:

       sudo ./install.sh

  4. if /var/lib/shim-signed/mok/MOK.der is not yet enrolled, run:

       sudo update-secureboot-policy --enroll-key

     then reboot and finalize the enrollment from the UEFI KeyManager

Automatic procedure with generation of signing keys in /var/lib/euresys/mok:

Creation, if needed, and use of UNENCRYPTED signing keys stored in
/var/lib/euresys/mok and only readable by root:

      sudo ./install -s

Or creation, if needed, and use of ENCRYPTED signing keys stored in
/var/lib/euresys/mok and only readable by root, a pass phrase will be
required to sign modules:

      sudo ./install -se

Manual procedure:

If signing keys are found in /var/lib/shim-signed/mok and kmodsign is
installed, the installer will use these signing keys

Note: /var/lib/shim-signed/mok/MOK.der shall then be enrolled, see below

The installer can automatically sign modules with
/var/lib/shim-signed/mok/MOK.priv or use a different key if extra
arguments are provided

For example:

      sudo ./install.sh -a sha256 -k priv.key -c pubkey.der

If needed a signing key can be created with openssl. For more details see

      https://www.kernel.org/doc/html/latest/admin-guide/module-signing.html

For example:

      openssl req -new -x509 -newkey rsa:2048 -keyout priv.key \
          -outform DER -out pubkey.der -nodes -days 36500 \
          -subj "/CN=Local Module Signing/" \
          -addext "extendedKeyUsage=codeSigning"

      Note: openssl older than 1.1.1 do not support -addext, in this
            case a config file might be needed if modprobe fails with
            the kernel message "The signer key **** is not CodeSigning"

Note: a passphrase will be required during installation if the private key is
      encrypted ('openssl req' without -nodes option)

The public key associated with the signing private key shall then be enrolled
For example with mokutil, on an UEFI enabled machine:

      sudo mokutil --import pubkey.der

On reboot, the UEFI Key Manager will be invoked to complete the key enrollment
