123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292 |
- ******************************************
- Graphene Library OS with Intel SGX Support
- ******************************************
- .. image:: https://readthedocs.org/projects/graphene/badge/?version=latest
- :target: http://graphene.readthedocs.io/en/latest/?badge=latest
- :alt: Documentation Status
- *A Linux-compatible Library OS for Multi-Process Applications*
- .. This is not |nbsp|, because that is in rst_prolog in conf.py, which GitHub
- cannot parse. GitHub doesn't appear to use it correctly anyway...
- .. |_| unicode:: 0xa0
- :trim:
- What is Graphene?
- =================
- Graphene is a lightweight guest OS, designed to run a single application with minimal host
- requirements. Graphene can run applications in an isolated environment with benefits comparable to
- running a complete OS in a virtual machine -- including guest customization, ease of porting to
- different OSes, and process migration.
- Graphene supports native, unmodified Linux applications on any platform. Currently, Graphene runs on
- Linux and Intel SGX enclaves on Linux platforms.
- With Intel SGX support, Graphene can secure a |_| critical application in a |_| hardware-encrypted
- memory region. Graphene can protect applications from a |_| malicious system stack with minimal
- porting effort.
- Our papers describe the motivation, design choices, and measured performance of Graphene:
- - `EuroSys 2014 <http://www.cs.unc.edu/~porter/pubs/tsai14graphene.pdf>`_
- - `ATC 2017 <http://www.cs.unc.edu/~porter/pubs/graphene-sgx.pdf>`_
- How to build Graphene?
- ======================
- Graphene consists of three parts:
- - An instrumented GNU C Library
- - The Library OS itself (a shared library named ``libsysdb.so``, called the "shim" in our source code)
- - The Platform Adaptation Layer, or PAL, (a shared library named ``libpal.so``)
- Graphene currently only works on the x86_64 architecture. Graphene is currently tested on Ubuntu
- 16.04 and 18.04 (both server and desktop version), along with Linux kernel versions 3.x/4.x. We
- recommend building and installing Graphene on the same host platform. If you find problems with
- Graphene on other Linux distributions, please contact us with a detailed bug report.
- Run the following command on Ubuntu to install dependencies for Graphene::
- sudo apt-get install -y build-essential autoconf gawk bison
- For building Graphene for SGX, run the following command in addition::
- sudo apt-get install -y python3-protobuf libprotobuf-c-dev protobuf-c-compiler
- To run tests locally, you also need the python3-pytest package::
- sudo apt-get install -y python3-pytest
- To build Graphene, simply run the following commands in the root of the
- source tree::
- git submodule update --init -- Pal/src/host/Linux-SGX/sgx-driver/
- make
- Each part of Graphene can be built separately in the subdirectories.
- To build Graphene with debug symbols, run ``make DEBUG=1``
- instead of ``make``. To specify custom mirrors for downloading the GLIBC
- source, use ``make GLIBC_MIRRORS=...``.
- To build with ``-Werror``, run ``make WERROR=1``.
- Building with kernel-level sandboxing (optional)
- ------------------------------------------------
- This feature is marked as EXPERIMENTAL and no longer exists on the master branch.
- Building with Intel SGX Support
- -------------------------------
- Prerequisites
- ^^^^^^^^^^^^^
- 1. 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,
- ``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.
- 2. Install the Intel SGX SDK and driver
- The Intel SGX Linux SDK is required to compile and run Graphene on SGX. Download
- and install it from the official Intel GitHub repositories:
- - <https://github.com/01org/linux-sgx>
- - <https://github.com/01org/linux-sgx-driver>
- 3. 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::
- 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
- We note that this last command is a tempoarary 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
- ^^^^^^^^^^^^^^^^^^^^^
- To build Graphene with Intel SGX support, in the root directory of Graphene repo, run the following
- command::
- make SGX=1
- To build with debug symbols, instead run the command::
- make SGX=1 DEBUG=1
- Running ``make SGX=1`` in the test or regression directory will automatically generate the required
- manifest signatures (.sig files).
- Run Built-in Examples in Graphene-SGX
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- There are a few built-in examples under ``LibOS/shim/test/``. The "native"
- folder includes a |_| rich set of C |_| programs and "apps" folder includes
- a |_| few tested applications, such as GCC, Python, and Apache.
- 1. Build and run a |_| ``helloworld`` program with Graphene-SGX
- - go to LibOS/shim/test/native, build the enclaves via the command::
- make SGX=1
- This command will build enclaves for all the programs in the folder
- - Generate the token from aesmd service, via the command::
- make SGX=1 sgx-tokens
- - Run a helloworld program with Graphene-SGX::
- SGX=1 ./pal_loader helloworld
- or::
- ./pal_loader SGX helloworld
- 2. Build and run the Python ``helloworld.py`` script in Graphene-SGX
- - go to LibOS/shim/test/apps/python, and build the enclave::
- make SGX=1
- - Generate a launch token from the aesmd service::
- make SGX=1 sgx-tokens
- - Run ``helloworld.py`` script with Graphene-SGX via::
- SGX=1 ./python.manifest.sgx scripts/helloworld.py
- Including Application Test Cases
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- To add the application test cases, issue the following command from the root
- of the source tree::
- git submodule update --init -- LibOS/shim/test/apps/
- Testing the remote attestation feature
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- To enable tests for the built-in remote attestation feature for Graphene-SGX, obtain a SPID
- and a subscription key (can be linkable or unlinkable) from the Intel API Portal:
- <https://api.portal.trustedservices.intel.com/EPID-attestation>.
- Specify the SPID, subscription key, and the type of the SPID/key in the manifest::
- sgx.ra_client_spid = <SPID>
- sgx.ra_client_key = <KEY>
- sgx.ra_client_linkable = 1 # or 0 if the SPID/key is unlinkable (default)
- If the remote attestation feature is enabled, Graphene-SGX will terminate if the platform
- is not successfully verified by the Intel Attestation Service (IAS). The feature ensures that
- Graphene-SGX only executes on genuine, up-to-date SGX hardware.
- To enable remote attestation tests in ``Pal/regression``, specify the following variables::
- cd PAL/regression
- make SGX=1 RA_CLIENT_SPID=<SPID> RA_CLIENT_KEY=<KEY>
- make SGX=1 sgx-tokens
- If you receive a ``GROUP_OUT_OF_DATE`` status from IAS, this status indicates that your CPU
- is out of date and can be vulnerable to hardware attacks. If you wish to bypass this error,
- you can specify the following option in the manifest::
- sgx.ra_accept_group_out_of_date = 1
- Similarly, if you receive a ``CONFIGURATION_NEEDED`` status from IAS, this status indicates that
- additional configuration of your SGX platform may be needed. If you wish to bypass this error,
- you can specify the following option in the manifest::
- sgx.ra_accept_configuration_needed = 1
- *Security advisories:*
- - ``GROUP_OUT_OF_DATE`` may indicate that the firmware (microcode) of you CPU is not updated
- according to INTEL-SA-00233 (Load/store data sampling) and INTEL-SA-00161 (L1 terminal fault).
- It is recommended that you keep the BIOS of your platform up-to-date.
- - If you receive status ``CONFIGURATION_NEEDED`` from the IAS after updating your BIOS, you may
- need to disable hyperthreading in your BIOS to mitigate L1 terminal fault.
- How to run an application in Graphene?
- ======================================
- Graphene library OS uses the PAL (``libpal.so``) as a loader to bootstrap applications in the
- library OS. To start Graphene, PAL (``libpal.so``) will have to be run as an executable, with the
- name of the program, and a |_| "manifest file" (per-app configuration) given from the command
- line. Graphene provides three options for specifying the programs and manifest files:
- - option 1 (automatic manifest)::
- [PATH TO Runtime]/pal_loader [PROGRAM] [ARGUMENTS]...
- (Manifest file: "[PROGRAM].manifest" or "manifest")
- - option 2 (given manifest)::
- [PATH TO Runtime]/pal_loader [MANIFEST] [ARGUMENTS]...
- - option 3 (manifest as a script)::
- [PATH TO MANIFEST]/[MANIFEST] [ARGUMENTS]...
- (Manifest must have "#![PATH_TO_PAL]/libpal.so" as the first line)
- Running an application requires some minimal configuration in the application's manifest file. A
- |_| sensible manifest file will include paths to the library OS and other libraries the application
- requires; environment variables, such as ``LD_LIBRARY_PATH``; and file systems to be mounted.
- Here is an example manifest file::
- loader.preload = file:LibOS/shim/src/libsysdb.so
- loader.env.LD_LIBRAY_PATH = /lib
- fs.mount.libc.type = chroot
- fs.mount.libc.path = /lib
- fs.mount.libc.uri = file:[relative path to Graphene root]/Runtime
- More examples can be found in the test directories (``LibOS/shim/test``). We
- have also tested several applications, such as GCC, Bash, and Apache.
- The manifest files for these applications are provided in the
- individual directories under ``LibOS/shim/test/apps``.
- For the full documentation of the Graphene manifest syntax, see the `Graphene
- documentation <https://graphene.readthedocs.io/>`_.
- Docker support
- ==============
- We are actively working on adding a proper Docker support. You can find the old and deprecated
- implementation on `DEPRECATED/gsc <https://github.com/oscarlab/graphene/tree/DEPRECATED/gsc>`_
- branch (caveat: use at your own risk!).
- Contact
- =======
- For any questions or bug reports, please send an email to
- <support@graphene-project.io> or post an issue on our GitHub repository:
- <https://github.com/oscarlab/graphene/issues>.
- Our mailing list is publicly archived `here
- <https://groups.google.com/forum/#!forum/graphene-support>`_.
|