From b72786e9ded042b238737f6eb0387becc250ea47 Mon Sep 17 00:00:00 2001 From: Dmitrii Kuvaiskii Date: Fri, 19 Jun 2020 13:43:05 -0700 Subject: [PATCH] [Docs] Add instructions to install Linux 5.7 with FSGSBASE patch --- Documentation/building.rst | 124 +++++++++++++++++++++++++---------- Documentation/quickstart.rst | 30 ++++----- 2 files changed, 106 insertions(+), 48 deletions(-) diff --git a/Documentation/building.rst b/Documentation/building.rst index bb674604..193ebbd7 100644 --- a/Documentation/building.rst +++ b/Documentation/building.rst @@ -69,51 +69,109 @@ Building with Intel SGX Support Prerequisites ^^^^^^^^^^^^^ -#. Generate signing keys +1. Install the Linux kernel patched with FSGSBASE +""""""""""""""""""""""""""""""""""""""""""""""""" - A 3072-bit RSA private key (PEM format) is required for signing the manifest. - If you don't have a private key, create it with the following command:: +FSGSBASE is a feature in recent processors which allows direct access to the FS +and GS segment base addresses. For more information about FSGSBASE and its +benefits, see `this discussion `__. - openssl genrsa -3 -out enclave-key.pem 3072 +Work is being done to include FSGSBASE enabling in the upstream Linux kernel. +Currently, the FSGSBASE enabling code is out-of-tree, requiring some patches to +the kernel. - You can either place the generated enclave key in the default path, - :file:`Pal/src/host/Linux-SGX/signer/enclave-key.pem`, or specify the key's - location through the environment variable ``SGX_SIGNER_KEY``. +Enabling FSGSBASE support requires building and installing a custom kernel with +backported patches. The instructions to patch and compile a Linux kernel with +FSGSBASE support below are written around Ubuntu 18.04 LTS (Bionic Beaver) with +a Linux 5.7 stable kernel but can be adapted for other distros as necessary. +These instructions ensure that the resulting kernel has FSGSBASE support and up +to date security mitigations. - After signing the application's manifest, users may ship the application and - Graphene binaries, along with an SGX-specific manifest (``.manifest.sgx`` - extension), the signature (``.sig`` extension), and the aesmd init token - (``.token`` extension) to execute on another SGX-enabled host. +#. Setup a build environment for kernel development following `the instructions + in the Ubuntu wiki `__. + Choose Linux version 5.7 via:: -#. Install the Intel SGX SDK and driver + cd linux && git checkout v5.7 - The Intel SGX Linux SDK and the Intel SGX driver are required to compile and - run Graphene on SGX. Download and install them from the official Intel - GitHub repositories: +#. Obtain the patch series from the Linux kernel mailing list:: - - https://github.com/01org/linux-sgx - - https://github.com/01org/linux-sgx-driver + wget -O fsgsbase.patch https://lore.kernel.org/patchwork/series/446124/mbox - Alternatively, if you want to use the DCAP versions of the SDK and driver, - download and install it from: + The conversation regarding this patchset can be found in the kernel mailing + list archives `here + `__. - - https://github.com/intel/SGXDataCenterAttestationPrimitives +#. Apply the patch series to the kernel source tree:: -#. Build and install the Graphene SGX driver - A Graphene-specific Linux driver must also be installed before running - Graphene in an SGX environment. Simply run the following commands to build - the driver:: + git am fsgsbase.patch - cd Pal/src/host/Linux-SGX/sgx-driver - make - # The console will be prompted to ask for the path of Intel SGX driver code - sudo insmod gsgx.ko - sudo sysctl vm.mmap_min_addr = 0 +#. Build and install the kernel following `the instructions in the Ubuntu wiki + `__. + +#. After rebooting, verify the patched kernel is the one that has been booted + and is running:: + + uname -r + +#. Also verify that the patched kernel supports FSGSBASE (the below command + must return that bit 2 is set):: + + LD_SHOW_AUXV=1 /bin/true | grep AT_HWCAP2 + +After the patched Linux kernel is installed, you may proceed with installations +of other SGX software infrastructure: the Intel SGX Linux driver, the Intel SGX +SDK/PSW, and Graphene itself (see next steps). Note that older versions of +these software packages may not work with recent Linux kernels like 5.7. We +recommend to use commit ``b7ccf6f`` of the Intel SGX Linux Driver for Intel SGX +DCAP and commit ``0e71c22`` of the Intel SGX SDK/PSW. + + +2. Generate signing keys +"""""""""""""""""""""""" + +A 3072-bit RSA private key (PEM format) is required for signing the manifest. +If you don't have a private key, create it with the following command:: + + openssl genrsa -3 -out enclave-key.pem 3072 + +You can either place the generated enclave key in the default path, +:file:`Pal/src/host/Linux-SGX/signer/enclave-key.pem`, or specify the key's +location through the environment variable ``SGX_SIGNER_KEY``. + +After signing the application's manifest, users may ship the application and +Graphene binaries, along with an SGX-specific manifest (``.manifest.sgx`` +extension), the signature (``.sig`` extension), and the aesmd init token +(``.token`` extension) to execute on another SGX-enabled host. + +3. Install the Intel SGX driver and SDK/PSW +""""""""""""""""""""""""""""""""""""""""""" + +The Intel SGX Linux SDK and the Intel SGX driver are required to compile and +run Graphene on SGX. Download and install them from the official Intel +GitHub repositories: + +- https://github.com/01org/linux-sgx +- https://github.com/01org/linux-sgx-driver + +Alternatively, if you want to use the DCAP versions of the SDK and driver, +download and install it from: + +- https://github.com/intel/SGXDataCenterAttestationPrimitives + +4. Install the Graphene SGX driver (not for production) +""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +If you followed step 1 and installed the patched Linux kernel, skip this step. +Otherwise, you will need a Graphene-specific Linux driver that enables the +FSGSBASE feature available in recent processors. + +To install the Graphene SGX driver, run the following commands:: + + cd Pal/src/host/Linux-SGX/sgx-driver + make + # The console will be prompted to ask for the path of Intel SGX driver code + sudo insmod gsgx.ko - We note that this last command is a |~| temporary work-around for some issues - with the Intel SGX driver. This is an inadvisable configuration for - production systems. We hope to remove this step in a |~| future version of - Graphene, once the SGX driver is upstreamed to Linux. Building Graphene-SGX ^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/quickstart.rst b/Documentation/quickstart.rst index bcd63820..25d36f42 100644 --- a/Documentation/quickstart.rst +++ b/Documentation/quickstart.rst @@ -3,7 +3,7 @@ Quick Start .. highlight:: sh -#. Clone the Graphene Repository:: +#. Clone the Graphene repository:: git clone https://github.com/oscarlab/graphene.git @@ -13,7 +13,7 @@ Quick Start cd graphene make -#. Build and Run :program:`helloworld`:: +#. Build and run :program:`helloworld`:: cd LibOS/shim/test/native make @@ -24,6 +24,10 @@ Quick Start SGX Quick Start --------------- +Graphene-SGX requires that the FSGSBASE feature of recent processors is enabled +in the Linux kernel. For the ways to enable the FSGSBASE feature, please refer +to :doc:`building`. + Before you run any applications in Graphene-SGX, please make sure that Intel SGX SDK and the SGX driver are installed on your system. We recommend using Intel SGX SDK and the SGX driver no older than version 1.9 (or the DCAP SGX SDK and @@ -36,7 +40,7 @@ If you want to use the DCAP SDK and driver, please follow the README in https://github.com/intel/SGXDataCenterAttestationPrimitives. Please note, that the DCAP driver requires Graphene to run as a root user to access it. -#. Ensure That Intel SGX is Enabled on Your Platform:: +#. Ensure that Intel SGX is enabled on your platform:: lsmod | grep sgx ps ax | grep [a]esm_service @@ -44,25 +48,18 @@ the DCAP driver requires Graphene to run as a root user to access it. The first command should list :command:`isgx` (or :command:`sgx`) and the second command should list the process status of :command:`aesm_service`. -#. Clone the Repository and Set the Home Directory of Graphene:: +#. Clone the repository and set the home directory of Graphene:: git clone https://github.com/oscarlab/graphene.git cd graphene git submodule update --init -- Pal/src/host/Linux-SGX/sgx-driver/ export GRAPHENE_DIR=$PWD -#. Prepare a Signing Key:: +#. Prepare a signing key:: cd $GRAPHENE_DIR/Pal/src/host/Linux-SGX/signer openssl genrsa -3 -out enclave-key.pem 3072 -#. Build and Install Graphene SGX Driver:: - - cd $GRAPHENE_DIR/Pal/src/host/Linux-SGX/sgx-driver - make - # the console will prompt you for the path of the Intel SGX driver code - sudo insmod gsgx.ko - #. Build Graphene-SGX:: sudo apt-get install -y \ @@ -70,14 +67,17 @@ second command should list the process status of :command:`aesm_service`. python3-protobuf libprotobuf-c-dev protobuf-c-compiler cd $GRAPHENE_DIR make SGX=1 + # the console will prompt you for the path to the Intel SGX driver code -#. Set ``vm.mmap_min_addr=0`` in the System:: +#. Set ``vm.mmap_min_addr=0`` in the system:: sudo sysctl vm.mmap_min_addr=0 -#. Build and Run :program:`helloworld`:: + Note that this is an inadvisable configuration for production systems. This + temporary workaround will not be required in the future. + +#. Build and run :program:`helloworld`:: cd $GRAPHENE_DIR/LibOS/shim/test/native - make SGX=1 make SGX=1 sgx-tokens SGX=1 ./pal_loader helloworld