vystem/docs/boottools/keygen.md

Keygen docs

Introduction

The keygen utility is responsible for generating SPFIE 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 SPFIE docs.

Detailled informations

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

For building keygen, first make sure that you have the libargon2.a static library file inside the utility directory. This one and the source of Argon2 for the keygen isn't included inside the main Vystem repository but downloaded and compiled by the build script. So you may have to compile Argon2 yourself before compiling keygen. To compile keygen, use the provided build script build.sh while being in the utility directory.

External libraries:

• 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 recommanded the keygen utility be launched as root.

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 should be running as root to ensure his own security.
2. 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.
3. 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.
4. 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
5. 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
6. 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)
7. Offering the user the possibility to translate their password into a QWERTY representation of it, if they doesn't use a QWERTY keyboard. That way, the user can enter his password like he would do on his keyboard but the password that will be hashed will be the password translated in QWERTY.

Warning: This feature is still very experimental, the only translation supported is AZERTY to QWERTY and the user experience is still very unsettling. For testing purposes, it's recommanded using a password with no characters differences between keyboard layout such as test, for example compatibility between the AZERTY and QWERTY keyboard. A better password inputing experience with support for various keyboard layout is planned for future release.

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.