# 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`, you will need to use the provided build file. But for the moment, the provided build file doesn't allow yet for the utility to be build outside of Vystem build process. The build file will require `libcommoncrypto.a` to be provided inside the `initfsgen` folder.

External library provided by `commoncrypto` and used inside `initfsgen`:
- 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 `initfsfp.bin`, saved into the current directory.
6) Computing hash of the content of `initfsfp.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 `sshash.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
- `initfsfp.bin` and `sshash.bin` are files expected to be protected by SBFIE and put inside the ESP partition
