Download Release

View On Github

Deploy

Deploy GyroidOS on x86 Hardware

This section describes how to deploy GyroidOS on a x86 platform.

Current pre-built release image:
trustmeimage-v0.1.1_x86_trustx-corei7-64.img.bz2
trustmeinstaller-v0.1.1_x86_trustx-corei7-64.img.bz2

You can either deploy GyroidOS directly to a disk attached to your host or use the installer medium to boot the target machine and deploy GyroidOS to the target machine’s internal drive, please refer to the corresponding section.

You have two options for deploying GyroidOS to an x86 machine:

  1. create a bootable medium , e.g., usb/mmc disk to directly boot from that disk on the target
  2. create a bootable installer usb/mmc disk (for installing to an internal disk on the target)

Create bootable medium

Requirements

  • A successfully built GyroidOS image file (trustmeimage.img), either downloaded from Github Release or built following the instructions here.
  • The script copy_image_to_disk.sh which can be found on GitHub or in your build folder at trustme/build/yocto/copy_image_to_disk.sh

In first place, ensure the needed packages are installed on your system.

apt-get install util-linux btrfs-progs gdisk parted

Copy GyroidOS image to disk

Now the GyroidOS image can be copied to the target disk. The provided script takes care of expanding the partitions to use all of the available disk space. WARNING: This operation will wipe all data on the target device

sudo <yocto workspace directory>/trustme/build/yocto/copy_image_to_disk.sh \
   <gyroidos-image> </path/to/target/device>

If you have built from source in ws-yocto and your target device is /dev/mmc0 the command would be:

cd ws-yocto # your yocto workspace directory
sudo trustme/build/yocto/copy_image_to_disk.sh \
   out-yocto/tmp/deploy/images/genericx86-64/trustme_image/trustmeimage.img \
   /dev/mmc0

Install GyroidOS using installer image

Requirements

  • A successfully built GyroidOS image file (trustmeinstaller.img), either downloaded from Github Release or built following the instructions here.

Installation steps

Just follow these simple steps to copy the installer to an usb/mmc disk and run the installation script on the target.

  1. WARNING: This operation will wipe all data on the target device 
    dd if=<trustmeinstaller.img> of=<path/to/target/device> conv=notrunc,fsync status=progress
sync

    e.g. you want to create an bootable mmc on /dev/mmc0

    dd if=trustmeinstaller.img of=/dev/mmc0 conv=notrunc,fsync status=progress
sync
  2. Boot target machine using boot medium created in the previous step
  3. After boot, run the following command 
    /data/install_trustme.sh <path/to/internal/disk>
poweroff

Boot GyroidOS

Boot the target device from the created bootable medium or the just installed internal disk using UEFI. If a CSM is enabled in the BIOS settings, it has to be disabled. The shell will become available on tty12. In order to access it, press Ctrl+Alt+F12.

Optional steps

The following steps are optional if you just want to get a running rudimentary test setup with no security concerns.

TPM Configuration

  • Go to your UEFI BIOS Setup and activate Trusted Computing and the real TPM Chip with 2.0 API.
  • Further, activate the PCR banks which hold sha256 bit values, some BIOS versions do not enable those banks by default.

Secure Boot Configuration

If you use release images from Github add the following public key to your efi db:
ssig_subca.esl (sha256sum b52d9451de399ac5ce8d443ff0e118295b2ad9f08d781e53bc8d662c83ac341)

See https://www.rodsbooks.com/efi-bootloaders/controlling-sb.html

Create a bootable keytool image

We assume you have built the keytool image, see build

Copy the keytool image to an USB device WARNING: This will wipe all data on the target device

dd if=<keytoolimage.img> of=</path/to/target/device>

Replace Platform keys with generated ones

Before proceeding, you may choose to backup your current Secure Boot keys. In order to do so, boot your system from the created USB device using UEFI. Again, if a CSM is enabled, you have to disable it first. In the next step backup your keys, using the Save keys option in the keytool menu.

Now, your UEFI Secure Boot configuration has to be reset to Setup mode. The steps to achieve this are UEFI-dependent. Usually the Menu items are named like this:

  • UEFI -> Security -> Secure Boot -> “Erase platform key” / “Reset to setup mode”

For the exact UEFI options, please refer to your UEFI vendor.

After the UEFI Secure Boot has been set to Setup Mode, the Secure Boot keys can be replaced using the keytool. Therefore, boot your machine using the USB drive containing the keytool. After boot, perform the following steps using the keytool menu:

KeyTool -> Edit Keys
Replace db with keys/DB.esl
Replace KEK with keys/KEK.esl
Replace PK with keys/PK.auth

Now you can enable Secure Boot in the UEFI menu and start using GyroidOS. Again, for exact instructions how to enable secure boot, please refer to your UEFI vendor.