lolo859/vystem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

First commit, Vystem v0.1

Browse Source
This commit is contained in:
lolo859
2026-03-31 22:15:00 +02:00
commit e15daed8c0
462 changed files with 134655 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/blastproof/bootconfig.md Normal file
View File

@@ -0,0 +1,111 @@
# Blastproof boot config
## Introduction
Blastproof store his configuration inside a text file named `bp.conf` and stored inside `\EFI\BlastProofFiles` inside the EFI partition. Due to being protected by SBFIE, the config is immutable after compilation and any change to it will cause the boot to fail, even if provided password was good. A example configuration is provided as `Blastproof/config/bp_template.conf`
## Syntax and behaviour
Blastproof configuration format is pretty simple:
- Any line starting by `#` will be considered a comment and ignored
- Any empty line will be ignored
- All the other lines will be considered as a key-value pair, the first `=` will be considered as a separator.
- All spaces from both sides of the separator will be considered a part of the key or value, including starting and trailing spaces
- All lines are separated by `\n`
Any non-ascii character will cause the boot to fail. All the keys that are listed below are automatically replaced by their default value if non-present. Somes keys are mandatory for the boot to succeed. Any invalid value will cause the boot process to fail.
## List of all keys
### Serial port related keys
**serial_port_enabled:**
- Description: Authorize the output on serial port once the bootloader enable the selected graphic output mode. Override `serial_port_erroring` and `serial_port_debuging`
- Possible value: `true` or `false`
- Default value: `false`
**serial_port_debuging:**
- Description: Authorize the output on serial port for anything else than errors
- Possible value: `true` or `false`
- Default value: `false`
**serial_port_erroring:**
- Description: Authorize the output on serial port for anything related to errors
- Possible value: `true` or `false`
- Default value: `false`
### Graphics related keys
**font:**
- Description: Give the name of the file containing the font the bootloader will atempt to use.
- Possible value: any value representing a file name stored inside `EFI\BlastProofFiles`
- Default value: `bitra-ascii-medium.fbm`
**disable_boot_animation:**
- Description: Disable the loading and playing of the boot animation
- Possible value: `true` or `false`
- Default value: `true`
**default_horizontal_resolution:**
- Description: define the target horizontal resolution for graphic output mode selection. Set this and `default_vertical_resolution` to `0` to select highest resolution available
- Possible value: any null or positive integer
- Default value: `0`
**default_vertical_resolution:**
- Description: define the target vertical resolution for graphic output mode selection. Set this and `default_horizontal_resolution` to `0` to select highest resolution available
- Possible value: any null or positive integer
- Default value: `0`
### InitFS and SignSyst related keys
**initfs_partition_type_guid:**
- Description: define the type GUID of an InitFS partition. Warning: this GUID is common to all installation and shouldn't be modified in any way
- Possible value: any GUID under the form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where `x` is any hexadecimal character
- Default value: `8362b434-d825-11f0-a68f-10ffe08423a6`
**initfs_partition_guid:**
- Description: define the unique GUID of the InitFS partition. Warning: this GUID is changed at every compilation and auto-completed by build script
- Possible value: any GUID under the form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where `x` is any hexadecimal character
- Default value: there is no default value for this pair
**signsyst_partition_type_guid:**
- Description: define the type GUID of an SignSyst partition. Warning: this GUID is common to all installation and shouldn't be modified in any way
- Possible value: any GUID under the form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where `x` is any hexadecimal character
- Default value: `da0048b4-d826-11f0-b877-10ffe08423a6`
**signsyst_partition_guid:**
- Description: define the unique GUID of the SignSyst partition. Warning: this GUID is changed at every compilation and auto-completed by build script
- Possible value: any GUID under the form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where `x` is any hexadecimal character
- Default value: there is no default value for this pair
### Shelter related keys
**kernel_log_level:**
- Description: define the log level of the kernel
- Possible value: any integer ranging from 0 to 6
- Default value: `1`
**kernel_test_benchmark:**
- Description: define if the kernel should test and benchmark his subsystems
- Possible value: `true` or `false`
- Default value: `false`
**kernel_bench_iterations:**
- Description: define the amount of iterations used for tests and benchmarks
- Possible value: any integer ranging from 0 to 10000
- Default value: `10000`
**kernel_log_disable_serial_port:**
- Description: disable the outputting of logs on the serial port
- Possible value: `true` or `false`
- Default value: `true`
**kernel_disable_serial_port:**
- Description: disable any outputting on the serial port
- Possible value: `true` or `false`
- Default value: `false`
**kernel_log_ring_size:**
- Description: define the amount of pages used for logging ring buffer. Setting this pair to 0 will disable the logging ring.
- Possible value: any integer ranging from 0 to 65535
- Default value: `2048`

35
docs/blastproof/bootprocess.md Normal file
View File

@@ -0,0 +1,35 @@
# Blastproof boot process
Blastproof boot process follow a very rigid sequences of steps that are detailled below:
- Printing informations:
- Bootloader version
- Firmware informations
- CPU informations
- Reading boot password from EFI console
- Verifying integrity of integrated keys (see SBFIE)
- Acquiring access to ESP partition
- Acquiring loaded image handle
- Acquiring BlockIO protocol for ESP partition
- Acquiring filesystem protocol (Blastproof doesn't have an integrated FAT32 driver)
- Opening root folder
- Performing cryptographic checks with internal keys on his own files (see SBFIE)
- Readind, parsing and applying boot configuration
- Locating Simple Graphic Protocol (GOP) handle
- Identify a suitable graphic output format, based on configuration, or highest resolution available in case of fallback
- Loading and rendering bitmap font according to selected graphic output format
- Loading, rendering and playing boot animation if configuration allow it
- Loading InitFS and SignSyst
- Listing all availables BlockIO protocol
- Locating handles for InitFS and SignSyst
- Allocating memory for them
- Loading them into RAM
- Parsing their headers
- Performing cryptographic checks to validate their headers and contents
- Loading the kernel
- Loading Shelter and Keycard binary
- Generating Shelter boot configuration
- Allocating pages for kernel sections
- Creating page table
- Parsing EFI Memory Map and transforming it into a understandable format for Vystem
- Jumping to kernel

44
docs/blastproof/bplib.md Normal file
View File

@@ -0,0 +1,44 @@
# Blastproof library
## Introduction
While Blastproof is based on EDK II C library, it uses a wrapper around what EDK II can provide (mainly BlockIO protocol, filesystem protocol, graphic output protocol and custom Vystem formats support) as well custom-integrated cryptographic libraries. This wrapper is called the Blastproof library.
## External libraries
The source code for external libraries are stored in different folders depending on the library. Their source code has been adapted to run in an EDK II environment. Here is a list of all external libraries inside the Blastproof library, that doesn't include libraries used in boot utilities:
Folder | Original source code | Author | License
--- | --- | --- | ---
Blastproof/src/libs/sha3 | [mjosaarinen/tiny_sha3](https://github.com/mjosaarinen/tiny_sha3) | mjosaarinen | MIT
Blastproof/src/libs/sphincsplus | [sphincs/sphincsplus](https://github.com/sphincs/sphincsplus) | SPHINCS+ team | MIT-0
Blastproof/src/libs/argon2 | [P-H-C/phc-winner-argon2](https://github.com/P-H-C/phc-winner-argon2) | Argon2 team | CC0-1.0
Note: some of the projects cited above let the user choose the license at their convenience. The most permissive option has been selected when applicable
## EDK II
The Blastproof bootloader is based on the EDK II framework:
- Source: https://github.com/tianocore/
- License: BSD-2-Clause-Patent
- Copyright:
Copyright (c) Intel Corporation and other contributors.
## Blastproof library components
Blastproof library is divided into several components, some relying on the external libraries cited above, and all relying on the EDK II framework. Here is the list of all components with their headers:
- `conf.h`: manage configuration loading and parsing
- `console.h`: provide a simple way to enter a password inside the EFI shell
- `cpu.h`: provide a simple way to print CPU ID informations
- `crypto.h`: provide the cryptographic abstraction layer to use algorithms such as Argon2, SHA3 or Sphincs+
- `debug.h`: provide outputting primitives to the serial port
- `default.h`: provide macros for default configuration values
- `disk.h`: provide functions to read files from ESP partition
- `font.h`: provide functions to load, parse and render FBM fonts
- `graphic.h`: provide basic primitives to interact with GOP framebuffers
- `initfs.h`: InitFS and SignSyst drivers
- `ui.h`: provide primitives to render text and boot animation in the GOP framebuffer
- `vyx.h`: provide a very basic Vyx-based kernel loader
Additional headers can be generated at compilation time and aren't included in this list, such as `key.h`.

53
docs/blastproof/fbm.md Normal file
View File

@@ -0,0 +1,53 @@
# Font Bitmap
## Introduction
Font Bitmap (FBM) is the custom font format used by the Blastproof bootloader. It has been designed to be simple and support a selected set of features useful and simple to render from a bare metal environnement. This font format is generated by the `fontgen` utility. In this file, we describe how they are structured, not how they are generated, rendered or used. Please take note that this format has been designed for the x86-64 architecture and for little endian usage. More precisely, all multibytes integer are little endian, except codepoint encoding (see below).
## Header
Each FBM font start with the following 10 bytes header:
- Signature: 3 bytes that are set to `FBM` in ASCII
- Encoding: 1 byte. Reserved encoding are 0x01 for ASCII, 0x08 for UTF-8 and 0x10 for UTF-16
- Entries count: 4 bytes, indicate the number of glyph inside the file
- Width: 1 byte, the width in pixel of a glyph
- Height: 1 byte, the heigth in pixel of a glyph
Please note that the provided font in Vystem are only tested for ASCII encoding.
## Glyphs table
Each glyph occupies `4+width*height` bytes.
### Codepoint
The 4 first byte are for the codepoint. The codepoint is encoded as detailled below, **no matter the endianness**:
- ASCII: the first byte of the codepoint is the ASCII code, the next 3 are set to 0
- UTF-8: if `N` is the amount of byte the UTF-8 code take, then the first `N` are to be set to the UTF-8 code bytes, and the next `4-N` bytes are set to 0
- UTF-16: if 2 bytes are used, the two first bytes of the UTF-16 code are set into the first two bytes of the codepoint. If 4 bytes are used, use all codepoint bytes
In all cases, the useful bytes are always left-aligned and the unused bytes are set to 0. The codepoint `0xFFFFFFFF` is reserved for the replacement character in case of missing character in the font.
### Pixel encoding
Each pixel is encoded with two values in mind:
- a boolean indicating if the pixel is on or off
- a 4 bit value indicating the shading of the pixel, ranging from 0 (background color) to 15 (text full color)
Each pixel is encoded on one byte with the following scheme:
- Bit 0 (MSB): shading bit 0 (MSB of the shading value)
- Bit 1: second bit of the first byte of the codepoint
- Bit 2: shading bit 1
- Bit 3: fourth bit of the second byte of the codepoint
- Bit 4: shading bit 2
- Bit 5: sixth bit of the third byte of the codepoint
- Bit 6: shading bit 3 (LSB of the shading value)
- Bit 7: on/off bit
Note: above, when we provide a bit index, it starting from left to rigth. It apply to pixel byte, shading value and bit index for corruption detection.
When rendering the font, the renderer will take two values: background color and text color. It will create a scale ranging from 0 to 15 using linear interpolation and apply the expected color to each pixel using this scale and the shading value. The bit 1, 3 and 5 of each pixel is set to bits found in the codepoint to detect corruption. The pixels are stored in a grid, line by line, from top to bottom.
## Provided font
Vystem provide a basic font named `bitra`, with 12 pixels as width and 20 as height, only supporting ASCII characters. This font is stored in the file `bitra-medium-ascii.fbm`.

91
docs/blastproof/fs.md Normal file
View File

@@ -0,0 +1,91 @@
# Custom filesystems
## Introduction
Vystem define two new filesystems: InitFS and SignSyst. The purpose of these filesystems are to store any sensitive systems files. Both of these filesystems are designed to be integrated together. For each InitFS, there is always a SignSyst and vice versa. These filesystems are generated by the `initfsgen` utility. In this file, we describe how they are structured, not how they are generated, verified or used. Please take note that these filesystems has been designed for the x86-64 architecture and for little endian usage.
## InitFS
InitFS is new, very simple filesystem. It doesn't support folders and is completely immutable after generation. It has been designed to support strong files integrity check and be loader as one big chunk into memory.
### Header
The header of any InitFS filesystem is as follow:
- Signature: 8 bytes that are set to `InitFiSy` in ASCII
- Bootloader version: an uint16_t indicating the bootloader version, currently set to `0x0001`
- InitFS version: an uint16_t indicating the InitFS version, currently set to `0x0001`
- OS version: an uint32_t indicating the OS version, currently set to `0x00000001`
- Installation ID: an array of 48 completely random bytes. His SHA3-512 hash is stored inside the `initfs-footprint.bin` file, protected by SPFIE
- InitFS Size: the amount of bytes in the total filesystem, not forcefully rounded to the disk block size. Stored as an uint64_t
- Files table size: the amount of bytes used for the filesystem files table. Stored as an uint64_t
- Files content size: the amount of bytes for the filesystem files content area. Stored as an uint64_t
- Entry width: the width of a file table entry. In the current version of InitFS, must always be set to 256. Stored as an uint64_t
- Entries count: the count of entries inside files table, stored as an uint64_t
- Files content area offset: the amount to bytes to add to the filesystem base to reach the files content area. Stored as an uint64_t
- Entropy: 8 bytes of random data, stored as an uint64_t
- Entropy check: 8 bytes of a value generated with this formula : `header.entropy_check=(header.entropy*0x9E3779B185EBCA87)^header.entropy`. Stored as an uint64_t
- Files table hash: an array of 64 bytes containing the SHA3-512 hash of the files table
- Files content area hash: an array of 64 bytes containig the SHA3-512 hash of the files content area
- Installation ID double hash: an array of 64 bytes containing the SHA3-512 hash of the content of the `initfs-footprint.bin` file.
- Padding: 128 bytes of padding generated with a specific pattern (see below)
- Header hash: an array of 64 bytes containing the SHA3-512 of the InitFS header, not including the last 64 bytes
This header is exactly 512 bytes. The mecanism decribed above with the installation ID and the `initfs-footprint.bin` is to ensure that an installation of Blastproof find his associated InitFS.
### Files table and files entries
The files table is filled with files entries structured as follow, each being 256 bytes:
- File offset in the files content area, starting at the beginning of the files content area,stored as an uint64_t
- File size, stored in bytes as an uint64_t
- Sphincs+ public key of the file, stored as an array of 64 bytes
- SHA3-512 hash of the file, stored as an array of 64 bytes
- File name, stored as an array of 112 bytes
Files names can only use ASCII and have to be finished by `\0`, unless the file name is exactly 112 characters.
### Files content area
The files content area come just after the files table and contain the files content.
## SignSyst
SignSyst is a special filesystem: it doesn't contain files but signatures. Signatures have all the same fixed size and are stored in the same order as the files entries inside the associated InitFS.
### Header
The header of any SignSyst is as follow:
- Signature: 8 bytes that are set to `SignSyst` in ASCII
- Bootloader version: an uint16_t indicating the bootloader version, need to be set as same as the associated InitFS
- InitFS version: an uint16_t indicating the InitFS version, need to be set as same as the associated InitFS
- OS version: an uint32_t indicating the OS version, need to be set as same as the associated InitFS
- Installation ID: an array of 48 bytes containing the installation ID, need to be set as same as the associated InitFS
- Signature size: the size of a signature, stored as an uint64_t
- Signature count: the count of signatures, stored as an uint64_t
- SignSyst size: the amount of bytes in the total filesystem, not forcefully rounded to the disk block size. Stored as an uint64_t
- Signature area size: the amount of bytes used to actually store the signatures, stored as an uint64_t
- Signature area hash: an array of 64 bytes containing the SHA3-512 hash of the signatures area
- Padding: 288 bytes of padding generated with the same pattern as InitFS
- Header hash: an array of 64 bytes containing the SHA3-512 of the SignSyst header, not including the last 64 bytes
The header is exactly 512 bytes. The file `signsyst-hash.bin`, protected by SPFIE, contain the full hash of the SignSyst header.
### Signatues area
The signatures area come just after the SignSyst header and contain all Sphincs+ signatures.
## Padding generation
InitFS and SignSyst padding use a very specific generation method:
The padding is first initialized with zeroed bytes, after which a marker value `p` is written at positions determined by the sequence defined by (f0,f1)=(0,1) and iteratively updated as (f0←f1,f1←f0+f1). At each step, the byte at index `f0` is set to `p`, resulting in writes at offsets following the Fibonacci sequence until the index exceeds the padding size.
In InitFS, the marquer value `p` is the first byte of the installation ID.
In SignSyst, the marquer value `p` is the last byte of the installation ID.
## Hash generation
The files table hash, files content area hash and signatures area hash are altered in a certain way: their 48 last bytes are xored with the installation ID. The header hash for both filesystems are generated at the final end of the generation process.
## Stored files
To this day, the InitFS contain the following files
- `shelter.vyx`
- `keycard.bin`

21
docs/blastproof/index.md Normal file
View File

@@ -0,0 +1,21 @@
# Blastproof Docs
## Introduction
Blastproof is Vystem's bootloader. It is a UEFI x86-64 only bootloader that rely on EDK II for all hardware interactions. It is able to confirm the integrity of his files, locate the kernel and load it into memory, using the specific boot protocol designed for Shelter.
## Blastproof architectural overview
The Blastproof bootloader rely mainly on the EDK II framework for printing to the EFI console, interacting with disks/partitions and FAT32 filesystem, graphic output protocol, and memory allocation. However, it uses Vystem standard formats for fonts, filesystems, security and integrity checks, graphic renderer, and kernel loading.
## Ressources
1) [Bootprocess](bootprocess.md)
2) [Boot configuration](bootconfig.md)
3) [Security and integrity model at boot level](security.md)
4) [Secure Boot Files Integrity Enforcement (SBFIE)](sbfie.md)
5) [Custom filesystems](fs.md)
6) [Font Bitmap](fbm.md)
7) [Blastproof library](bplib.md)
For detailled informations about kernel loading, please see Vyld docs.

53
docs/blastproof/sbfie.md Normal file
View File

@@ -0,0 +1,53 @@
# SBFIE
## Introduction
Secure Boot Files Integrity Enforcement (SBFIE) is a compoment of Blastproof in charge of verifying the integrity of Blastproof's files. This allow for cryptographic immutability of boot files.
## Limitations
SBFIE has been conceived with the following limitations in mind:
- it doesn't check integrity of the entire bootloader itself
- it doesn't replace UEFI Secure Boot but make it impossible to use without customised certificates generated at each compilation (not supported for the moment)
- due to the will of it being compatible with a large variety of devices, it doesn't integrate TPM utilization (but support in an eventual future is planned)
- any user of a non-QWERTY keyboard will have a hard time typing a password in an UEFI console
- it use the EFI console as input (support of self-made input methods and protocol will be implemented in a near future)
- any missing file that is supposed to be protected by SPFIE will cause the boot process to fail
## How it work
For details on how to setup SBFIE, see the doc on the `keygen` utility.
### Initial parameters and variables
The following explenations assume that the bootloader has been compiled with a specially generated header `key.h`, generated by the `keygen` utility, for protecting `N` number of files.
The `key.h` header contain the following datas:
- `bp_key_mainsig`: an array of bytes containing the main signature generated with Sphincs+
- `bp_key_pkblob`: an array of `64*N` bytes containing `N` Sphincs+ public keys, one for each file
- `bp_key_pwdsalt`: an array of 32 bytes containing the salt to use for hashing the boot password
- `bp_key_files`: an array of `N` strings indicating the order in which boot files should be verified for each public key from `sh_key_pkblob` to correspond with each file
We assume that all files are in the `\EFI\BlastProofFiles` folder with their corresponding names as specified in `bp_key_files` and that their Sphincs+ signatures are stored as `<file name>.sig` inside of the `\EFI\BlastProofSign` folder.
### Detailled steps
The steps in which SPFIE check the files is as follow:
1. The user enter the boot password
2. The boot password is hashed using Argon2 using 262144 of memory cost and 3 of time cost. The salt is stored inside `bp_key_pwdsalt`The output is a 96 digest.
3. The digest is used as seed for generating a Sphincs+ keypair, immediately erasing the private key and keeping only the public key.
4. The generated public key is used to verify the signature inside `bp_key_mainsig` with the message being `bp_key_pkblob`
5. If the verification is successfull, the boot process continue. If not, the boot process is halted.
6. Each file indicated inside `bp_key_files` is opened in order, their signature file is also opened and their public key is extracted from `bp_key_pkblob`. Each file is verified.
7. If any verification fail, the boot process is halted.
**Note:** all the signatures verifications mecanisms use Sphincs+ and Argon2 for password hashing. The boot password hash is never stored on disk. Their sources come directly from their official implementations in C, only adapted to use types and functions provided by EDK II. All non-deterministic/randomness generation happen at compile time.
## Concerned files
To this date, the following files generated by build script are protected by SPFIE:
- `bp.conf`
- `bitra-ascii-medium.fbm`
- `initfs-footprint.bin`
- `signsyst-hash.bin`

22
docs/blastproof/security.md Normal file
View File

@@ -0,0 +1,22 @@
# Security and integrity model at boot level
## Introduction
The Vystem project has been designed for the ground up for security and integrity, and that start directly at the boot level, by focusing on boot file integrity.
## Overview
In order to achieve a strong amount of security without sacrificing compatibility with existing devices, we have chosen to integrate the following elements into the boot sequence:
- Secure Boot Files Integrity Enforcement (SBFIE): protect cores bootloader files assuming bootloader integrity with a user-defined password, without storing it directly but integrating it very deeply in the integrity check chain. See [SPFIE docs](spfie.md) for more informations
- Robust post-quantum cryptography integrated directly into the bootloader: while we rely on EDK II for files and disk IO as well as password input, all the cryptography stack is integrated into the bootloader, not relying on firmware cryptography at any time. We use post-quantum signing algorithm like SPHINCS+ and strong hashing primitives like Argon2 and SHA3, with their sources codes directly taken from their official implementation, only modified to integrate with EDK II types and memory allocation system
- Signing of every system files: every sensitive system file is integrated into the InitFS, signed into a trio of check: each Blastproof binary (and so SPFIE keys), InitFS and SignSyst is uniquely associated (mainly by installation ID), meaning that the whole system can only work if all of them are properly setup on the same machine device. InitFS integrity check are also cryptographically linked to SPFIE verification.
## Limitations
The current Vystem security model assume that we can trust the firmware and that the user boot password is secure. We plan to add support for UEFI secure boot by using custom certificates generation in the future.
## Detailled parameters for cryptographic algorithms
For SPHINCS+, we use the set of parameters named `sphincs-sha2-256f`.
For SHA3, we use the standard implementation with the 512 bits variant.
For Argon2, we disable parallelism (this would be a pain to setup in a UEFI environnement) and use the following parameters: 96 bytes output (to match SPHINCS+ keypair seed size), 32 bytes salt, memory cost set to 262144 and time cost set to 3. We use the Argon2id variant.