First commit, Vystem v0.1

docs/boottools/bootanim.md

@@ -0,0 +1,66 @@
+# Bootanim docs
+
+## Introduction
+
+The `bootanim` utility is responsible for generating the boot animation. It is used even if the bootloader configuration specify to not play the boot animation, as it contain the Vystem logo blueprint.
+
+## Detailled informations
+
+Folder: `Blastproof/bootanim`
+Source code file: `bootanim.cpp`
+
+For building `bootanim`, use the following command:
+``` bash
+g++ bootanim.cpp -o bootanim -Ofast -march=native
+```
+The `-Ofast -march=native` is recommended for better performances, as the boot animation generation is a bit heavy on computation.
+
+External library:
+- stb_image, made by `Sean Barrett`, sourced from [nothings/stb](https://github.com/nothings/stb), provided in the public domain
+
+## Usage
+
+Prerequisites: having `ffmpeg` accessible in path for the use of folder mode, for generating the video.
+
+The `bootanim` can be used like this:
+``` bash
+bootanim <png logo file> [file/folder] <width> <height>
+```
+ 
+You can use `bootanim` in two differents mode:
+- file mode: will export the boot animation as `bootanim.bin`, into a format readable by the bootloader
+- folder mode: will export the boot animation as a folder named `frames` that will contain all the generated frames under the name format `frameXXXX.ppm`, as well as a video named `out.mp4`
+
+Command example:
+``` bash
+bootanim logo.png file 1280 720
+bootanim logo.png folder 2160 1440
+```
+
+## Boot animation generation
+
+The first thing to know about Blastproof boot animation is that, due to poor FAT32 read performance, we decided to find a compromise between the amount of data being stored into the generated file and the amount of data computed at each boot. In order to maintain a fluid, 60 fps animation at each boot on most hardware, we landed on this compromise:
+- We only store 16 frames per second, under the form of points coordinates
+- The 48 others frames per second are computed using linear interpolation at each boot
+This result in the `bootanim.bin` file being only 14 megabytes in size, instead of 56 megabytes, for the actual Vystem logo and a resolution of 1920x1080.
+
+The detailled generation procedure is as follow:
+1) Locate and open the logo file in monochrom mode (with only one color channel, conversion is made by stb_image). The utility will reject any non-square logo.
+2) Center the logo on a black canva the size provided by `width` and `height` arguments.
+3) Scan the canva to detect all points that have their value over 127. Save these points with their coordinates. In the Vystem logo, there is over 45k points.
+4) For each of these points, generate a random position in the canva, the seed doesn't have any cryptographic implication and is randomised for every new build.
+5) Apply two quadratic bezier curves: one for the "explosion" (all points starting from the exact center of the screen and being scattered around the screen to their random position) and one for the logo appearence (each point is assigned a random coordinates in the logo points and will be attrected to this position from their random position).
+6) Generate the selected output media and write it into the files.
+
+It is recommanded that the image file provided is already monochrom.
+
+## Output file structure
+
+The outputted file named `bootanim.bin` is the format that is usable by the bootloader. The file header is structured like this (all uint64_t are in little endian):
+- Signature: an array of 8 bytes containing `BootAnim` in ASCII
+- The width of canva used for generating the boot animation, stored as an uint64_t
+- The height of canva used for generating the boot animation, stored as an uint64_t
+- Number of frame inside the boot animation, stored as an uint64_t
+- Number of points inside each frame, stored as an uint64_t
+
+Then, each frame is written inside the file. Each frame is made of <number of points per frame> points. Each points is made of two uint16_t, one for the x position and one for the y position.

docs/boottools/fontgen.md

@@ -0,0 +1,52 @@
+# Fontgen docs
+
+## Introduction
+
+The `fontgen` utility is responsible for generating the font used by Blastproof. It can only generate FBM font.
+
+## Detailled informations
+
+Folder: `Blastproof/fontgen`
+Source code file: `fontgen.cpp`
+
+For building `fontgen`, use the following command:
+``` bash
+g++ fontgen.cpp -o fontgen
+```
+
+External library:
+- stb_image, made by `Sean Barrett`, sourced from [nothings/stb](https://github.com/nothings/stb), provided in the public domain
+
+## Usage
+
+The `fontgen` utility can be used like this:
+``` bash
+fontgen <text color> <background color> [ascii/utf8/utf16] <path to folder containing images files for characters>
+```
+
+The text and background color arguments must be given under a hexadecimal RGB color code, starting with `#`. They serve as boundary for generating the shading scale.
+The encoding argument can be `ascii`, `utf8` or `utf16`, however in Vystem build script, only the `ascii` encoding is used. Others supported encoding modes haven't been tested.
+The final argument is the path to the folder that contain all images files for the font characters.
+Each character is encoded with the following format:
+- they must named with this format `0xXXXXXXXX` where `X` is an hexadecimal character. All `X` aren't mandatory, and the utility interprete them as characters codepoint. For example, file name `0x00` will be interpreted as a codepoint of value `0x00000000`, resulting in the `\0` character for ASCII
+- each file inside the provided folder must be a PNG file
+- each file must only contain pixel with colors inside the generated shading scale. For instance, the `bitra` font only use color from the two extremities of the shading scale. Transparency isn't checked as the shading scale is in RGB and all images files are opened in 3 channels mode.
+- all files must have the same height and width, that will indicate the dimensions of the bitmap grid for each pixel
+
+Any failure to meet the above points will result in font compilation error.
+
+Command example:
+``` bash
+fontgen "#FFFFFF" "#000000" ascii ./chars
+```
+
+## Detailled generation process
+
+1) Generate the shading scale by associating colors from the linear interpolation of the two provided colors to values ranging from 0 to 15. The text color will be occupy the value 15 and the background color the value 0.
+2) For each image file in the provided folders: extract the character codepoint from the file name, endode it to FBM codepoint format, extract the raw pixel data
+3) For each valid character: extract the codepoint bits that will be inserted into pixel bytes, iterate for each pixel of the character: identify which value in the shading scale the pixel color is, encode it into a byte with codepoint bits and on/off value (off if the shading value is 0, on otherwise)
+4) Write the header and all the encoded characters into the final file that will be named `font.fbm`
+
+Any failure to meet the above criteria (except some of the second step that will only trigger a warning) will result in font compilation error.
+
+For a detailled overview of how a `.fbm` file is structured, please see [FBM docs](../blastproof/fbm.md).

docs/boottools/index.md

@@ -0,0 +1,11 @@
+# Bootloader tools Docs
+
+In order to generate all necessary components for the build of a Vystem disk image, we have created several C++ tools designed to help generating these components. All of these tools have been intented to be used only in a normal Linux environnement. Here is the list of bootloader tools:
+1) [bootanim](bootanim.md)
+2) [fontgen](fontgen.md)
+3) [initfsgen](initfsgen.md)
+4) [keygen](keygen.md)
+
+Here a few precisions about the global mecanisms inside each tools:
+- when a tool is iterating on the content of a folder, it rely on the order provided by the filesystem. But tool like `keygen` get there files list through arguments specifying direct files path rather than a folder path, making it a deterministic order if the build script doesn't change
+- when we say 'securely erased', it mean we are using the `explicit_bzero` function to prevent compiler optimization

docs/boottools/initfsgen.md

@@ -0,0 +1,50 @@
+# Initfsgen documentation
+
+## Introduction
+
+The `initfsgen` utility is responsible for generating the InitFS and SignSyst filesystems.
+
+## Detailled informations
+
+Folder: `Blastproof/initfsgen`
+Source code file: `initfsgen.cpp`
+
+For building `initfsgen`, use the provided build script `build.sh` while being in the utility directory.
+
+External library:
+- SPHINCS+, made by the SPHINCS+ team, sourced from [sphincs/sphincsplus](https://github.com/sphincs/sphincsplus), under the MIT-0 license
+- tiny_sha3, made by mjosaarinen, sourced from [mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3), under the MIT license
+
+## Usage
+
+The `initfsgen` utility can be used like this:
+``` bash
+initfsgen <path to folder containing InitFS file>
+```
+
+The folder must contain only regular files. Any links, block device or folders inside the root folder will result in an error.
+
+Command example:
+``` bash
+initfsgen ./initfs_dir
+```
+
+## Detailled generation process
+
+1) Iterate over the content of the provided folder, checking if all elements are regular files, collecting their file sizes.
+2) Collect 48 bytes of entropy for installation ID and 8 bytes of entropy for entropy check, by opening `/dev/urandom`. No others method of entropy generation are or will be supported.
+3) Copying installation ID inside InitFS and SignSyst headers, filling all possible informations about files and signatures quantity and sizes inside the headers.
+4) Generating entropy check, putting it into InitFS header.
+5) Computing installation ID hash and saving it into `initfs-footprint.bin`, saved into the current directory.
+6) Computing hash of the content of `initfs-footprint.bin` and saving it into the InitFS header.
+7) Iterate for each file: loading the entire file, generating InitFS file name, copying file data into files content area, computing file content hash, generating SPHINCS+ keypair unique to this file, generating signature for file by using private key, securely erasing private key (without compiler optimization), saving file hash and public key into file entry, saving file entry into files table and adding generated signature to SignSyst
+8) Generating files table, files content area and signatures area hash, saving them into headers by xoring them with part of the installation ID
+9) Generating and saving padding for InitFS and SignSyst headers. Computing headers hash and finalizing filesystems raw data.
+10) Saving InitFS under `initfs.bin`, hashing SignSyst header and saving it into `signsyst-hash.bin`, saving SignSyst under `signsyst.bin`
+
+For the full and detailled layout of InitFS and SignSyst, please see [customs filesystems docs](../blastproof/fs.md).
+
+All hashing operations use SHA3-512. All entropy generations use secure entropy from `/dev/urandom`.
+This utility generate four files:
+- `initfs.bin` and `signsyst.bin` are the filesystems expected to be flashed into their respectives partitions on disk
+- `initfs-footprint.bin` and `signsyst-hash.bin` are files expected to be protected by SPFIE and put inside the ESP partition

docs/boottools/keygen.md

@@ -0,0 +1,47 @@
+# 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](../blastproof/spfie.md).
+
+## 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](https://github.com/sphincs/sphincsplus), under the MIT-0 license
+- tiny_sha3, made by mjosaarinen, sourced from [mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3), under the MIT license
+- Argon2, made by the Argon2 team, sourced from [P-H-C/phc-winner-argon2](https://github.com/P-H-C/phc-winner-argon2), under the CC0-1.0 license
+
+## Usage
+
+The `keygen` utility can be used like this:
+``` bash
+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.