vystem/docs/boottools/initfsgen.md

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, under the MIT-0 license
• tiny_sha3, made by mjosaarinen, sourced from mjosaarinen/tiny_sha3, under the MIT license

Usage

The initfsgen utility can be used like this:

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:

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.

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