PastaBoy12345/vystem-b
2
0
Fork 0
forked from lolo859/vystem
Code Pull Requests Activity

Vystem 0.2

Browse Source
This commit is contained in:
lolo859
2026-05-27 19:34:54 +02:00
parent a43c08b893
commit d238606b75
372 changed files with 51320 additions and 83217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/blastproof/bootconfig.md
View File

@@ -2,7 +2,7 @@
## 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`
Blastproof store his configuration inside a text file named `bp.conf` and stored inside `\EFI\BPFILES` 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
@@ -38,7 +38,7 @@ Any non-ascii character will cause the boot to fail. All the keys that are liste
**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`
- Possible value: any value representing a file name stored inside `EFI\BPFILES`
- Default value: `bitra-ascii-medium.fbm`
**disable_boot_animation:**
@@ -109,3 +109,8 @@ Any non-ascii character will cause the boot to fail. All the keys that are liste
- 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`
**kernel_kbd_events_queue_capacity**
- Description: define the amount of keyboards events each keyboard events can hold
- Possible value: any integer ranging from 64 to 65535
- Default value: `256`

9
docs/blastproof/bootprocess.md
View File

@@ -2,10 +2,7 @@
Blastproof boot process follow a very rigid sequences of steps that are detailled below:
- Printing informations:
- Bootloader version
- Firmware informations
- CPU informations
- Verifying VFTM
- Reading boot password from EFI console
- Verifying integrity of integrated keys (see SBFIE)
- Acquiring access to ESP partition
@@ -20,14 +17,14 @@ Blastproof boot process follow a very rigid sequences of steps that are detaille
- 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
- Parsing the GPT table on which the ESP is located
- 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
- Obtaining ACPI pointer
- Generating Shelter boot configuration
- Allocating pages for kernel sections
- Creating page table

21
docs/blastproof/bplib.md
View File

@@ -29,16 +29,17 @@ The Blastproof bootloader is based on the EDK II framework:
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
- `console.h`: provides a simple way to enter a password inside the EFI shell
- `cpu.h`: provides a simple way to print CPU ID informations
- `crypto.h`: provides the cryptographic abstraction layer to use algorithms such as Argon2, SHA3 or Sphincs+
- `debug.h`: provides outputting primitives to the serial port
- `default.h`: provides macros for default configuration values
- `disk.h`: provides functions to read files from ESP partition
- `font.h`: provides functions to load, parse and render FBM fonts
- `graphic.h`: provides 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
- `ui.h`: provides primitives to render text and boot animation in the GOP framebuffer
- `vyx.h`: provides a very basic Vyx-based kernel loader
- `vftm.h`: verify VFTM authenticity and informations
Additional headers can be generated at compilation time and aren't included in this list, such as `key.h`.

2
docs/blastproof/fbm.md
View File

@@ -50,4 +50,4 @@ When rendering the font, the renderer will take two values: background color and
## 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`.
Vystem provides 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 `FONT.FBM`.

8
docs/blastproof/fs.md
View File

@@ -15,7 +15,7 @@ The header of any InitFS filesystem is as follow:
- 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
- Installation ID: an array of 48 completely random bytes. His SHA3-512 hash is stored inside the `INITFSFP.BIN` file, protected by SBFIE
- 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
@@ -26,11 +26,11 @@ The header of any InitFS filesystem is as follow:
- 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.
- Installation ID double hash: an array of 64 bytes containing the SHA3-512 hash of the content of the `INITFSFP.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.
This header is exactly 512 bytes. The mecanism decribed above with the installation ID and the `INITFSFP.BIN` is to ensure that an installation of Blastproof find his associated InitFS.
### Files table and files entries
@@ -67,7 +67,7 @@ The header of any SignSyst is as follow:
- 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.
The header is exactly 512 bytes. The file `SSHASH.BIN`, protected by SBFIE, contain the full hash of the SignSyst header.
### Signatues area

14
docs/blastproof/index.md
View File

@@ -2,20 +2,22 @@
## 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 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 and partition, 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.
The Blastproof bootloader rely mainly on the EDK II framework for printing to the EFI console, interacting with disks 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) [Keyboard layouts](kbdlayout.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)
4) [Vystem FAT Trusted Manifest](vftm.md)
5) [Secure Boot Files Integrity Enforcement (SBFIE)](sbfie.md)
6) [Custom filesystems](fs.md)
7) [Font Bitmap](fbm.md)
8) [Blastproof library](bplib.md)
For detailled informations about kernel loading, please see Vyld docs.

71
docs/blastproof/kbdlayout.md Normal file
View File

@@ -0,0 +1,71 @@
# Keyboard layouts
## Introduction
Blastproof supports the addition of custom keyboards layout. This file describe how they are structured and how to create one.
## Implementation
The `layout.h` header, located in `Blastproof/src/libs/include`, contain the utilities needed to create custom keyboards layout. Two main structures are needed:
``` C
typedef struct {
CHAR16 char_source;
CHAR16 char_dest;
} bp_layout_CHAR_CONV;
```
The `char_source` field must be the character that Blastproof will receive from the UEFI firmware. In the immense majority of case, the firmware interprets each pressed key using the QWERTY layout. The `char_dest` field must be the character that replaced the inputed character.
``` C
typedef struct {
UINTN conv_count;
bp_layout_CHAR_CONV conv_table[];
} bp_layout_CONV_TABLE;
```
This structure is defined at compilation time and should indicate the amount of characters conversions as well as all the characters conversions, stored in an array.
## Usage
In the immense majority of cases, the firmware uses the QWERTY layout. If this is the case, you should use the keyboard layout of your keyboard. Here are the supported keyboard layout for the moment:
- `QWERTY`
- `AZERTY`
In the case where the firmware already use the keyboard layout of your keyboard, please select the `QWERTY` layout : it doesn't contain any key translation.
## Creating your own layout
In order to create your own keyboard layout, you can follow these steps:
### Creating the header file
1) Create a header file named `<keyboard layout name>.h` inside the `Blastproof/src/libs/include/layouts` folder.
2) Paste it the following template:
``` C
// SPDX-License-Identifier: MPL-2.0
#ifndef BP_LIB_LAYOUT_LAYOUTNAME_H
#define BP_LIB_LAYOUT_LAYOUTNAME_H
#include "../layout.h"
bp_layout_CONV_TABLE layoutname_convs={
.conv_count=0,
.conv_table={
}
};
#endif
```
3) Replace every `layoutname` and `LAYOUTNAME` with the name of your layout.
4) Add as many character conversions as you want. A character conversion is set under the form `{L'a',L'q'}`. In this example, we translate the character `a` to `q`.
5) Don't forget to update the `conv_count` field with the amount of characters conversions.
### Registering the layout
Go inside the `layout_registry.h` file, located inside `Blastproof/src/libs/include/layouts` and add the following line where indicated:
- `#include "<keyboard layout name>.h"` : replace `<keyboard layout name>` with the name of your layout
- add the string that will be displayed (generally the layout name) to the user inside
`layout_list`. Don't forger the `L` string modifier before the first quote
- `&<keyboard layout name>_conv` : add this element inside the `layout_conversions_table` variable. Don't forget the `&` operator

19
docs/blastproof/sbfie.md
View File

@@ -12,7 +12,7 @@ SBFIE has been conceived with the following limitations in mind:
- 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
- any missing file that is supposed to be protected by SBFIE will cause the boot process to fail
## How it work
@@ -27,15 +27,16 @@ The `key.h` header contain the following datas:
- `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
- `bp_key_files_sign`: an array of `N` strings indicating the corresponding signature file for each file of `bp_key_files`
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.
We assume that all files are in the `\EFI\BPFILES` folder with their corresponding names as specified in `bp_key_files` and that their Sphincs+ signatures are stored inside `bp_key_files_sign` as `<file name without extension>.sig` inside of the `\EFI\BPSIGN` folder.
### Detailled steps
The steps in which SPFIE check the files is as follow:
The steps in which SBFIE 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.
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.
@@ -46,8 +47,8 @@ The steps in which SPFIE check the files is as follow:
## 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`
To this date, the following files generated by build script are protected by SBFIE:
- `BP.CFG`
- `FONT.FBM`
- `INITFSFP.BIN`
- `SSHASH.BIN`

5
docs/blastproof/security.md
View File

@@ -7,9 +7,10 @@ The Vystem project has been designed for the ground up for security and integrit
## 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
- Vystem FAT Trusted Manifest (VFTM): ensure that the FAT32 filesystem on the ESP partition was produced by an authorized entity, that the ESP partition hasn't been changed from disk, that the FAT32 filesystem hasn't been corrupted or modified, and allow for the bootloader to check his own binary without EFI Secure Boot. It's signed by Keygen and verified by the bootloader himself. See [VFTM docs](vftm.md) for more informations.
- 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 [SBFIE docs](sbfie.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.
- 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 SBFIE 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 SBFIE verification.
## Limitations

92
docs/blastproof/vftm.md Normal file
View File

@@ -0,0 +1,92 @@
# Vystem FAT Trusted Manifest
## Introduction
Vystem FAT Trusted Manifest (VFTM) is a structure that can be found in the reserved sectors of any FAT32 filesystem generated by VyBuild (please see the conditions for VyBuild to generate this manifest in the VyBuild documentation). It's the first layer of defense in the Vystem Secure Boot Chain, being verified independantly at each boot.
## Position and structure
VTFM can be divided into three parts:
- the VFTM manifest itself, containing all importants informations and hashs. It's stored somewhere between the sector 8 and 31 of the FAT32 filesystem
- the manifest public key. It's stored somewhere between the sector 8 and 31 of the FAT32 filesystem, but never on the same sector of the manifest itself
- the manifest signature. It's stored after the FAT32 filesystem, just before the end of the ESP partition
The manifest and manifest public key have their position determined by this function:
``` C
void generate_vftm_sectors(const uint8_t* part_guid,int* sector_manifest,int* sector_public_key) {
uint32_t h=0x811c9dc5;
for (int i=0;i<16;i++) h=(h^part_guid[i])*0x01000193;
*sector_manifest=8+(h%24);
*sector_public_key=8+(((h>>16)%23+(*sector_manifest-7))%24);
}
```
The `part_guid` argument is an array of 16 bytes containing the ESP partition unique GUID. That way, the position of these components of VFTM is linked to the GPT table.
## Generation of the keys
Two Sphincs+ keypairs are generated by the Keygen utility. They are named `root` and `manifest`. We use `sk_root` to sign `pk_manifest`, generating the signature `sig_root`. `sig_root` and `pk_root` are injected into the `key.h` header generated by Keygen, alongside the SBFIE stuff. `sk_root` is immediately destroyed and never leave Keygen memory space. Then, using UNIX socket named `vftm.sock`, that should be created in the current directory by the calling entity of Keygen, Keygen transmit the keypair `manifest` to the calling entity. It should always be the entity that will generate the FAT32 filesystem (in this case, VyBuild).
VyBuild will sign the generated manifest with `sk_manifest`, and erase it immediately after. `pk_manifest` became the public key that will be injected into one of the reserved sector of the filesystem, alongside the manifest. The generated `sig_manifest` is injected at the end of the ESP partition, right after the FAT32 manifest.
## Manifest structure
The manifest structure can be represented like this:
``` C
#pragma pack(1)
struct vystem_fat_trusted_manifest {
uint8_t sig[8];
uint16_t manifest_version;
uint16_t bootloader_version;
uint32_t os_version;
uint8_t fat_hash[64];
uint8_t fat_build_id[32];
uint64_t clusters_count;
uint64_t bytes_per_sector;
uint64_t sectors_per_cluster;
uint64_t fat_size_bytes;
uint64_t fat_offset_bytes;
uint64_t bootloader_cluster_count;
uint64_t bootloader_cluster_offset;
uint64_t bootloader_build_id;
uint8_t fat_header_hash[64];
uint8_t bootloader_binary_hash[64];
uint64_t signature_offset_bytes;
uint64_t signature_size;
uint8_t gpt_disk_guid[16];
uint8_t gpt_efi_part_unique_guid[16];
uint8_t manifest_hash[64];
};
#pragma pack()
```
The expected signature is `VyFatSig` in ASCII.
## VFTM detailled verification procedure
Before doing anything, the bootloader will do all these steps to verify the authenticity, then the content of the manifest:
### VFTM assets gathering
The bootloader will gather the following assets in order, using various EDK2 protocols:
- the disk GUID from the GPT header
- the ESP partition unique GUID, that will serve to determine where to extract the manifest and public key
- the manifest and public key
- the manifest signature
### Keys verification
The booloader will then do the following steps to confirm the manifest authenticity:
1) Using `pk_root` and `sig_root`, it verify the extracted `pk_manifest`. If this fail, the bootprocess is halted.
2) Using `pk_manifest` and `sig_manifest`, it verify the extracted manifest. If this fail, the bootprocess is halted.
### Manifest contents verification
Finally, it can use the manifest content to verify various things in this order:
1) Verify the indicated manifest signature, various versions and GUID provided into the manifest.
2) Verify the FAT32 header by comparing his hash and fields with what is provided into the manifest.
3) Verify the FATs by hashing the FATs found in the filesystem and comparing them with the hash provided into the manifest.
4) Verify the bootloader binary by hashing it (retrieving his content through metadatas contained inside the manifest, without using the SimpleFilesystemProtocol) and comparing it to the hash provided into the manifest
5) Verify the hash of the manifest
All hashs use the SHA3-512 algorithm.