vystem-b/docs/boottools/keygen.md

Keygen docs

Introduction

The keygen utility is responsible for generating VFTM keys, SBFIE keys, files and boot password. This file focus on how these ressources are generated and setuped, not how the verification is made at boot time. The explenations in this file are complementary to the informations in SBFIE docs and VFTM docs.

Detailled informations

Folder: Blastproof/keygen Source code file: keygen.cpp

For building keygen, use the provided build file. The provided build file doesn't allow yet for the utility to be build outside of Vystem B build process.

External libraries provided by commoncrypto and used inside keygen:

• SPHINCS+, made by the SPHINCS+ team, sourced from sphincs/sphincsplus, under the MIT-0 license
• tiny_sha3, made by mjosaarinen, sourced from mjosaarinen/tiny_sha3, under the MIT license
• Argon2, made by the Argon2 team, sourced from P-H-C/phc-winner-argon2, under the CC0-1.0 license

Usage

The keygen utility can be used like this:

sudo keygen <path to file 1> <path to file 2> ... <path to file n>

You can provide as much paths as you want, as long as they all lead to regular files. It's necessary the keygen utility be launched as root. If the user launched keygen using sudo, all created files and folder will be changed of owner to be owned by the user that launched the keygen utility. To transmit the manifest keypair to VyBuild, keygen expect the vftm.sock UNIX socket to be created inside the current folder of execution. The generation process will fail if this socket isn't created by calling entity. The VYSTEM_KEYGEN_PASSWORD environnement variable can be used to transmit a password. If this variable isn't defined of empty, the utility will default on standard input method. This method of transmiting the password should only be used if you are in a test/developpement environnement, and not in production.

Detailled generation processus

1. Firstly, the keygen processus disable all possibilty of process memory dumps or memory swapping before doing anything else. Due the very thight security here, keygen must be running as root to ensure his own security.
2. It generate all the necessary keys for VFTM. Please see VFTM docs for more informations.
3. Verifying if the VYSTEM_KEYGEN_PASSWORD environnement variable exists and acting accordingly.
4. Then, it check for the existence of all the provided files and lock private and public keys buffer as well as signature buffer to ensure that all the secrets aren't dumped on disk due to process fault or swapping.
5. Iterating for all the provided files: loading the file into memory, generating SPHINCS+ keypair for it, computing and signing the SHA3-512 hash of the file content if it's above 1 megabyte, or signing directly the file if under 1 megabyte, securely erasing all temporary keys and signature buffer, saving signature and public key into their dedicated buffer.
6. Saving all signatures into a directory named sign, created if non existing, under the name format <original name>.sig, then securely erasing the signatures buffer

The 2 following steps are only executed if the standard password input method is selected: 6) Letting the user enter a boot password. If password is empty, it will ask for a number multiple of 2 to generate this many hexadecimal characters that will serve as password, the default amount of hexadecimal characters being 16. If the user enter a password, the user will have to confirm it 7) Checking that the password fill all criterias: should be (not enforced) at least 12 characters, can (enforced) only include ASCII characters due to EFI shell limitations, shouldn't be longer that 512 characters (enforced), and shoudn't use the numerical pad at all (not well supported in the EFI shell, but the user can still use numbers)

8. Converting the final password to UTF16LE for EFI environnement easier compatibilty. Obtaining 32 bytes of entropy from /dev/urandom. Hashing the password with the Argon2id algorithm using no parralelism, time cost of 3 and memory cost of 262144, with the salt, resulting in a 96 bytes output.
9. Using the password as seed for generating a master SPHINCS+ keypair. Generating a signature of the public keys of each files concatenated into a single block. Securely erasing both keys of the master keypair.
10. Saving the final datas the bootloader will need into a file named key.h, containing the master signature, the block of files public keys, the password salt and the list of all files to verify, in order.

This utility generate the following files:

• key.h: header file containing important datas, made for single use only, should be placed into Blastproof/src/libs/include in order for the bootloader to succesfully compile
• all the .sig files: binary files containg the signature for each file, should be placed inside the ESP partition.