diff --git a/docs/features/encryption.md b/docs/features/encryption.md index 6d3028d8..781cc064 100644 --- a/docs/features/encryption.md +++ b/docs/features/encryption.md @@ -2,28 +2,53 @@ Encryption allows to prevent unauthorized access to a data with a password. -- [Global encryption](#global-encryption) +- [Installation defaults](#installation-defaults) +- [Relayed encryption](#relayed-encryption) +- [Full-storage encryption](#full-storage-encryption) + - [Passwordless encryption](#passwordless-encryption) + - [Master password encryption](#master-password-encryption) - [Per-user encryption](#per-user-encryption) -- [Combining global and per-user encryptions](#combining-global-and-per-user-encryptions) +- [Per-user shared global encryption (USGE)](#per-user-shared-global-encryption-usge) +- [Which method to use?](#which-method-to-use) -## Global encryption +## Installation defaults -By default, the whole storage can be encrypted using the computer's master password, which is prompted on startup. +During installation, a check-up is performed to check if the system supports Secure Boot and if it has a modern TPM. If both are available, it will suggest to enable full-storage -During installation, even if this feature is turned off by the user, a random encryption key is generated in the bootloader, which can be accessed through the `/etc/sys/gbpwd` file. This key will be used to encrypt the storage when global encryption is active. -This process allows administrators to change the master password whenever they want to. +* Both Secure Boot and TPM enabled => [relayed encryption](#relayed-encryption) +* Otherwise => [USGE](#per-user-shared-global-encryption-usge) -When global encryption is turned on, the administrator must choose an encryption password it will communicate to each user. The system will not be able to start without this password. +## Relayed encryption -On startup, the system will run a _bootloader_ which is not encrypted (and thus vulnerable to attacks) which asks for the master password. This master password is then used to decrypt the master key in the bootloader. Then, the `/sys/valid` file is decrypted, and its content is compared to `ValidMasterKey`. If contents are equal, the provided master password is valid and the boot process starts normally. Else, the key is not the good one and the user is prompted a new one. +Related encryption is the combination of [full-storage](#full-storage-encryption) and [per-user](#per-user-encryption) encryption. It works by encrypting the global storage using the master key, but users' data are only encrypted using their own user key. This avoids double encryption and still remain perfectly secure. -The point of global encryption is that external persons cannot read the storage's data by just reading the storage ; they must either know the master key or put a malicious bootloader to spy on the user. +## Full-storage encryption + +Full-storage encryption encrypts the entire system storage. It is incompatible with USGE (only one of these two can be enabled at a time). + +At any time, it can either be enabled or disabled through the the [control center](../applications/Central.md). **NOTE:** The ability to encrypt the storage globally, change the master password or decrypt the storage is by default reserved to the main administrator, but this privilege can be given to normal administrators, though this is highly discouraged. +### Passwordless encryption + +The installer runs a quick check-up and if the computer is considered secure enough (which notably requires the presence of a TPM and support for Secure Boot), it will suggest to use a passwordless method. The random key is then stored in the TPM and the bootloader is checked by the UEFI using Secure Boot to ensure it has not been compromised, avoiding possible data extraction in case of the device being stolen. + +If this method is selected, the whole installation will be encrypted using that key. On startup, the UEFI will check the bootloader's integrity through Secure Boot, and let it start if valid. The (unencrypted) bootloader will then retrieve the key from the TPM and decrypt the final bootloader, which will handle the remaining boot steps. + +A recovery key is generated, which must be backed up somewhere, in case the bootloader asks for it. + +### Master password encryption + +If the computer isn't deemed secure enough or if the user chooses to, a master password will be asked for. This password allows to encrypt the whole installation by using a global password. + +On startup, the system will run the (unencrypted) bootloader which will ask for the master password. It will then retrieve the encrypted master key and try to decrypt it using the provided master password. If it succeeds, the boot process can continue. + +This is more secure than the passwordless method as it does not depend on the UEFI's Secure Boot which reduces the attack surface, and also prevents cold boot TPM attacks, ensuring that (if implemented correctly) the storage will never be decrypted without the master key. + ## Per-user encryption -But any non-guest user can also use a built-in system tool to encrypt its data using its own password. This way, the user's data become unreadable without his password, making even administrators unable to read his data. +Any non-guest user can also use a built-in system tool to encrypt its data using its own password. This way, the user's data become unreadable without his password, making even administrators unable to read his data. The encryption/decryption key is generated automatically when the user account is created and stored in the user's profile data (in `/etc/sys/users`). @@ -32,10 +57,24 @@ When enabled, the encrypted directories are: - The homedir at `/home/[username]` - The tempdir at `/tmp/[username]` -This feature is enabled by default, but can be disabled by the administrator. Also, it is disabled by default on [domains](domains.md). +This feature is enabled by default, but can be disabled by the administrator. Also, [domains](domains.md) communicate by default the secret key to the domain's manager. + +## Per-user shared global encryption (USGE) + +USGE is a method used to perform near full-storage encryption, without a master password and without the need of an UEFI / TPM. It is does not prevent modifications in case of physical access to the device, but prevents data from being extracted if the device is stolen. + +When configured, it will wait for the user's name and password to be input in the login screen to decrypt a shared master key, which will be used to decrypt the global storage. User's data will then be decrypted using the user key, just like [relayed encryption](#relayed-encryption). The main difference between the two being the way the storage itself is encrypted. + +This allows to not have to input a master password, not rely on an UEFI's Secure Boot system and prevent cold boot TPM attacks, while still providing near full-storage encryption + per-user encryption for all users. + +This feature forces encryption for all users and requires every user to set up a strong password. + +## Which method to use? + +Every method is suited better for a specific type of environment. -## Combining global and per-user encryptions +If you want the maximum level for security, be the only one to use your computer and enable only full-disk encryption with a strong master password and a strong user password. -When both a user enabled encryption for its user account and global encryption is active too, instead of having to encrypt and decrypt the data twice the user's data will be encrypted using a key derived from the master key as well as the user's encryption key. +If you want to prevent data from being extracted in case of theft, enable relayed encryption or USGE. -This allows to save a lot of time but still prevent unauthorized access if the user's password is weak. +If you want to have the most seamless experience, use USGE. You will not be prompted for a master password but still have system and user data encryption. diff --git a/docs/specs/boot-process.md b/docs/specs/boot-process.md new file mode 100644 index 00000000..d0c23997 --- /dev/null +++ b/docs/specs/boot-process.md @@ -0,0 +1,41 @@ +# Boot process + +The system's boot process is divided in two parts: the unsecure bootloader (BOOT1) and the system bootloader (BOOT2). + +## Stage 1: unsecure bootloader (BOOT1) + +This is the component loading at the very beginning, called directly by the UEFI. It is unencrypted (hence the name "unsecure"). + +It starts by initializing the minimum required computer's components. + +If the "Escape" key is detected as being pressed during a short time frame, it shows a troubleshooting menu. + +If other bootloaders are found on the storage, it displays a boot menu asking which system to boot. If another system is selected, it launches it. + +Otherwise, it perform decryption steps depending on the configured [encryption method](../features/encryption.md): + +* If storage encryption is disabled or if only [USGE](../features/encryption.md#per-user-shared-global-encryption-usge) is enabled, nothing to do ; +* If [full-storage encryption](../features/encryption.md#full-storage-encryption) is enabled: + * For passwordless authentication, ensure Secure Boot has verified BOOT1 + * If so, retrieve the master key from the TPM and use it to decrypt the storage + * Otherwise, ask for the recovery key to decrypt the storage (only required once) + * Otherwise ask for master password and use it to decrypt the master key + +If BOOT2 is encrypted (full-storage encryption only), the master key is used to decrypt it. Its signature is then checked to ensure it has not been modified. If the signature don't match, the computer will by default refuse to boot to avoid corruption and/or booting malicious programs. By inputting a specific phrase displayed on the screen, the user can force the boot process, at the expense of security. + +If signatures match, BOOT2 is launched directly. + +## Stage 2: system loader (BOOT2) + +This component checks signature for BOOT3. It also provides more advanced troubleshooting thanks to the whole storage being decryptable. + +If signatures are not valid, an error message is shown and the booting process is halt. By inputting a specific phrase displayed on the screen, the user can force the boot process, at the expense of security. + +It then initializes all required drivers, initialize a graphical session, and asks to select a user account. At this point, it also provides more troubleshooting options. + +If the provided username and password are valid, it then does the following: + +* If [USGE](../features/encryption.md#per-user-shared-global-encryption-usge) is enabled, the master key and user key are decrypted +* If [per-user encryption](../features/encryption.md#per-user-encryption) is enabled, the user key is decrypted + +The user session is then opened by calling the relevant system component. diff --git a/docs/specs/filesystem.md b/docs/specs/filesystem.md index 56e2e665..3d5188c7 100644 --- a/docs/specs/filesystem.md +++ b/docs/specs/filesystem.md @@ -155,11 +155,13 @@ _NOTE:_ `` indicates the item is a file. │   | └── upe History of UPE requests (1) │   ├── public Public data, readable and writable by everyone │   └── sys System's mutable data - available to system only -│   ├── registry System's registry -│   ├── awake System's shutdown indicator to detect if there was an error during last shutdown -│   ├── hashes Critical files' hashes for the integrity checker (2) -│   ├── gbpwd Global storage's encryption key (3) -│   └── users User profiles and groups +│   ├── registry System's registry +│   ├── awake System's shutdown indicator to detect if there was an error during last shutdown +│   ├── integrity Integrity data used during the boot process (2) +| | ├── signkey Key used for signing system files +| | └── signs System file signatures +│   ├── enckey Global storage's encryption key (3) +│   └── users User profiles and groups ├── fl Flow files ├── home Users' data │   └── A specific user's data diff --git a/docs/specs/services/system/fs.md b/docs/specs/services/system/fs.md index 76bb81a6..b7e35d2f 100644 --- a/docs/specs/services/system/fs.md +++ b/docs/specs/services/system/fs.md @@ -2,44 +2,41 @@ The `sys::fs` service is in charge of operations related to the [filesystems](../../filesystem.md). -- [`sys::fs` service](#sysfs-service) - - [Behaviour](#behaviour) - - [Operations and latency](#operations-and-latency) - - [List of natively supported filesystems](#list-of-natively-supported-filesystems) - - [Extending supported filesystems](#extending-supported-filesystems) - - [Filesystems detection](#filesystems-detection) - - [Methods](#methods) - - [`0x0001` IS\_FS\_MOUNTED](#0x0001-is_fs_mounted) - - [`0x0002` ENUM\_FS](#0x0002-enum_fs) - - [`0x0003` FS\_METADATA](#0x0003-fs_metadata) - - [`0x0004` FS\_MOUNT](#0x0004-fs_mount) - - [`0x0005` FS\_UNMOUNT](#0x0005-fs_unmount) - - [`0x0006` FS\_WATCH](#0x0006-fs_watch) - - [`0x0007` FS\_UNWATCH](#0x0007-fs_unwatch) - - [`0x1000` ITEM\_EXISTS](#0x1000-item_exists) - - [`0x1001` FEID\_TO\_SPLIT](#0x1001-feid_to_split) - - [`0x1002` ITEM\_METADATA](#0x1002-item_metadata) - - [`0x2000` RENAME\_ITEM](#0x2000-rename_item) - - [`0x2001` MOVE\_ITEM](#0x2001-move_item) - - [`0x2002` DELETE\_ITEM](#0x2002-delete_item) - - [`0x3000` CREATE\_DIRECTORY](#0x3000-create_directory) - - [`0x3001` READ\_DIRECTORY](#0x3001-read_directory) - - [`0x4000` OPEN\_FILE](#0x4000-open_file) - - [`0x4001` CLOSE\_FILE](#0x4001-close_file) - - [`0x4002` READ\_FILE](#0x4002-read_file) - - [`0x4002` WRITE\_FILE](#0x4002-write_file) - - [`0x5000` CREATE\_SYMLINK](#0x5000-create_symlink) - - [`0x5001` UPDATE\_SYMLINK](#0x5001-update_symlink) - - [`0x5002` READ\_SYMLINK](#0x5002-read_symlink) - - [`0xA000` WATCH\_ITEM](#0xa000-watch_item) - - [`0xA001` WATCH\_DIR\_CONTENT](#0xa001-watch_dir_content) - - [`0xA002` UNWATCH](#0xa002-unwatch) - - [`0xAA00` LOCK\_ITEM](#0xaa00-lock_item) - - [`0xAA01` UNLOCK\_ITEM](#0xaa01-unlock_item) - - [`0xF000` FORMAT](#0xf000-format) - - [Notifications](#notifications) - - [`0x0006` FS\_CHANGED](#0x0006-fs_changed) - - [`0xA000` ITEM\_CHANGED](#0xa000-item_changed) +- [Behaviour](#behaviour) + - [Operations and latency](#operations-and-latency) + - [List of natively supported filesystems](#list-of-natively-supported-filesystems) + - [Extending supported filesystems](#extending-supported-filesystems) + - [Filesystems detection](#filesystems-detection) +- [Methods](#methods) + - [`0x0001` IS\_FS\_MOUNTED](#0x0001-is_fs_mounted) + - [`0x0002` ENUM\_FS](#0x0002-enum_fs) + - [`0x0003` FS\_METADATA](#0x0003-fs_metadata) + - [`0x0004` FS\_MOUNT](#0x0004-fs_mount) + - [`0x0005` FS\_UNMOUNT](#0x0005-fs_unmount) + - [`0x0006` FS\_WATCH](#0x0006-fs_watch) + - [`0x0007` FS\_UNWATCH](#0x0007-fs_unwatch) + - [`0x1000` ITEM\_EXISTS](#0x1000-item_exists) + - [`0x1001` FEID\_TO\_SPLIT](#0x1001-feid_to_split) + - [`0x1002` ITEM\_METADATA](#0x1002-item_metadata) + - [`0x2000` RENAME\_ITEM](#0x2000-rename_item) + - [`0x2001` MOVE\_ITEM](#0x2001-move_item) + - [`0x2002` DELETE\_ITEM](#0x2002-delete_item) + - [`0x3000` CREATE\_DIRECTORY](#0x3000-create_directory) + - [`0x3001` READ\_DIRECTORY](#0x3001-read_directory) + - [`0x4000` OPEN\_FILE](#0x4000-open_file) + - [`0x4001` CLOSE\_FILE](#0x4001-close_file) + - [`0x4002` READ\_FILE](#0x4002-read_file) + - [`0x4002` WRITE\_FILE](#0x4002-write_file) + - [`0x5000` CREATE\_SYMLINK](#0x5000-create_symlink) + - [`0x5001` UPDATE\_SYMLINK](#0x5001-update_symlink) + - [`0x5002` READ\_SYMLINK](#0x5002-read_symlink) + - [`0xA000` WATCH\_ITEM](#0xa000-watch_item) + - [`0xA001` WATCH\_DIR\_CONTENT](#0xa001-watch_dir_content) + - [`0xA002` UNWATCH](#0xa002-unwatch) + - [`0xF000` FORMAT](#0xf000-format) +- [Notifications](#notifications) + - [`0x0006` FS\_CHANGED](#0x0006-fs_changed) + - [`0xA000` ITEM\_CHANGED](#0xa000-item_changed) ## Behaviour diff --git a/docs/technical/integrity-checker.md b/docs/technical/integrity-checker.md deleted file mode 100644 index 01e33dad..00000000 --- a/docs/technical/integrity-checker.md +++ /dev/null @@ -1,28 +0,0 @@ -# Integrity checker - -- [System immutability](#system-immutability) -- [Hashes computing](#hashes-computing) -- [Checking hashes at startup](#checking-hashes-at-startup) - -## System immutability - -The `/sys` directory is immutable, which means it cannot be modified, even by the main administrator. The only process where this directory may be affected is during a repair process or during an update, which are both processes that are handled by the system directly. - -## Hashes computing - -When critical files are written, in `/sys` or `/etc/sys`, their hash is computed using the SHA-384 algorithm and stored in the system's _hash registry_ (`/etc/sys/hashes` file). - -## Checking hashes at startup - -When any of these files is read from the disk, their content is computed and compared to the hash registry. If the hashes don't match, the file is considered as corrupted. The consequences depend on the location of the file: - -- _System_ (`/sys`): the system will check its backup integrity and then restore itself from the backup ; -- _System backup_ (`/sys/backup`): the system will check `/sys` integrity and then make a new backup of itself ; -- _System + system backup_: the system won't boot and indicate it must be reinstalled (documents won't be lost if they aren't corrupted) - It's possible to force the boot process, but a large warning will indicate it may cause crashes or even introduce security issues ; -- _Hash registry_ (`/etc/sys/hashes`): same thing ; -- _Registry_ (`/etc/sys/registry`): same thing ; -- _Crash save_: the crash save won't be restored (can be forced but with a large warning) ; -- _Sandbox_: system will refuse to start the sandbox (can be forced but with a large warning) ; - -**IMPORTANT:** If some malicious person edits the system files **and** its backup, it can also edit the hash registry, so the error won't show up. So that's not because there is no error the system is safe and has not been modified!