-
Notifications
You must be signed in to change notification settings - Fork 58
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: Lenovo X1 and compartmentalization
Co-authored-by: Nikita Bazulin <[email protected]> Signed-off-by: Ivan Nikolaenko <[email protected]>
- Loading branch information
1 parent
890ce08
commit ea2cc63
Showing
9 changed files
with
160 additions
and
13 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| <!-- | ||
| Copyright 2022-2023 TII (SSRC) and the Ghaf contributors | ||
| SPDX-License-Identifier: CC-BY-SA-4.0 | ||
| --> | ||
|
|
||
| # Creating an Application VM | ||
|
|
||
| ## What is AppVM? | ||
|
|
||
| AppVM is a virtual machine that is used to improve trust in system components by isolating the applications from both host OS and other applications. This way user can use applications of different trust levels within the same system and without compromising system security. This is because virtualization with hardware backed mechanisms provides better resource protection than traditional OS. While the VMs have overhead, it's acceptable via improved security and usability that makes the application seem like it is running inside an ordinary OS. | ||
|
|
||
| As a result - both highly trusted applications and untrusted applications can be hosted in the same secure system when the concerns are separated in their own AppVMs. | ||
|
|
||
| ## How to add a new AppVM | ||
|
|
||
| ### 1. AppVM description | ||
|
|
||
| Add the VM description in the target configuration. | ||
| [lenovo-x1.nix](../../../targets/lenovo-x1.nix) already has AppVMs inside for Chromium, Gala, and Zathura applications. | ||
|
|
||
| #### Example of the current AppVMs | ||
|
|
||
| ``` | ||
| vms = with pkgs; [ | ||
| { | ||
| name = "chromium"; | ||
| packages = [chromium]; | ||
| ipAddress = "192.168.101.5/24"; | ||
| macAddress = "02:00:00:03:03:05"; | ||
| ramMb = 3072; | ||
| cores = 4; | ||
| } | ||
| { | ||
| name = "gala"; | ||
| packages = [(pkgs.callPackage ../user-apps/gala {})]; | ||
| ipAddress = "192.168.101.6/24"; | ||
| macAddress = "02:00:00:03:03:06"; | ||
| ramMb = 1536; | ||
| cores = 2; | ||
| } | ||
| { | ||
| name = "zathura"; | ||
| packages = [zathura]; | ||
| ipAddress = "192.168.101.7/24"; | ||
| macAddress = "02:00:00:03:03:07"; | ||
| ramMb = 512; | ||
| cores = 1; | ||
| } | ||
| ]; | ||
| ``` | ||
|
|
||
| Each VM has the following properties: | ||
|
|
||
|
|
||
| | **Property** | **Type** | **Unique** | **Description** | **Example** | | ||
| | -------------- | --------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- | --------------------- | | ||
| | name | str | yes | This name is prefixed with `vm-` and will be shown in microvm list. The prefixed name - e.g. `vm-chromium` will be also the VM hostname | “chromium” | | ||
| | packages | list of types.package | no | Packages to include in a VM. It’s possible to make it empty or add several packages | [chromium top] | | ||
| | ipAddress | str | yes | This IP will be used to access a VM from the host. Should has the same subnetwork, as other VMs: Net, GUI VMs | "192.168.101.5/24" | | ||
| | macAddress | str | yes | Needed for network configuration | "02:00:00:03:03:05" | | ||
| | ramMb | int, [1, …, host memory] | no | Memory in MB | 3072 | | ||
| | cores | int, [1, …, host cores] | no | Virtual CPU cores | 4 | | ||
|
|
||
|
|
||
| ### 2. Add an app launcher in GUI VM | ||
|
|
||
| To add an app launcher, add an element in the [guivm.nix](../../../modules/virtualization/microvm/guivm.nix) file to the **graphics.weston.launchers** list. | ||
| A launcher element has 2 properties: | ||
|
|
||
| 1. **path** – path to the executable you want to run, like a graphical application. | ||
| 2. **icon** – path to an icon to show. | ||
|
|
||
| You may want to check the example launchers [here](../../../modules/virtualization/microvm/guivm.nix) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| <!-- | ||
| Copyright 2022-2023 TII (SSRC) and the Ghaf contributors | ||
| SPDX-License-Identifier: CC-BY-SA-4.0 | ||
| --> | ||
|
|
||
| # Example Project | ||
|
|
||
| The compartmentalization could be applied to many specific x86_64 computers and laptops with some customization applied to the Ghaf. The best way of the Ghaf customization is using Ghaf templates. | ||
|
|
||
| 1. Create a template project as described in [Ghaf as Library](../ref_impl/ghaf-based-project.md) section | ||
| 2. Adjust your system configuration with accordance to your HW specification. Determine all VIDs and PIDs of the devices that are passed to the VMs | ||
|
|
||
| 3. Add GUIVM configuration, NetworkVM configuration and optionally some AppVMs | ||
| 4. Set up weston panel shortcuts. | ||
| Refer to the existing [project example for Lenovo T14 and Lenovo X1 laptops](https://github.com/unbel13ver/ghaf-lib) | ||
|
|
||
| Creating the structure that includes all necessary data for the device passthrough: | ||
| ``` | ||
| # File 'my-hardware/lenovo-t14.nix': | ||
| # Copyright 2022-2023 TII (SSRC) and the Ghaf contributors | ||
| # SPDX-License-Identifier: Apache-2.0 | ||
| # | ||
| # Generic x86_64 computer -target | ||
| { | ||
| deviceName = "lenovo-t14"; | ||
| networkPciAddr = "0000:00:14.3"; | ||
| networkPciVid = "8086"; | ||
| networkPciPid = "02f0"; | ||
| gpuPciAddr = "0000:00:02.0"; | ||
| gpuPciVid = "8086"; | ||
| gpuPciPid = "9b41"; | ||
| usbInputVid = "046d"; | ||
| usbInputPid = "c52b"; | ||
| } | ||
| ``` | ||
| The fields of that structure are self-explanatory. Use `lspci -nnk` command to get this data from any Linux OS running on the device. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| <!-- | ||
| Copyright 2022-2023 TII (SSRC) and the Ghaf contributors | ||
| SPDX-License-Identifier: CC-BY-SA-4.0 | ||
| --> | ||
|
|
||
| # Compartmentalization | ||
| Compartmentalization is the technique of separating parts of a system to decrease attack surface and prevent malfunctions from cascading in the system. In Ghaf architecture, there is a separate Virtual Machine (VM) for every vital function of the system. | ||
|
|
||
| Current implementation supports Graphic User Interface (GUI) VM, Networking VM and a couple of Application VMs, such as Chromium web-browser and Zathura pdf reader. | ||
|
|
||
| The GUI VM owns computer's GPU and performs desktop environment and application windows rendering. Wayland protocol for applications in this case is proxified by `waypipe` over SSH. This approach is used temporarly before moving to more sophisticated solutions. | ||
|
|
||
| VM compartmentalization requires all necessary devices passthrough in place. More specifically, you need to know PCI VID and PID of a device and also it's number on the PCI bus. In case of USB device passthrough, it is enough to know device's VID and PID. See [Ghaf as Library](../ref_impl/ghaf-based-project.md) and [Creating Application VM](../ref_impl/creating_appvm.md) sections to know more about the actual implementation. |