|
|
@@ -1,211 +0,0 @@
|
|
|
-
|
|
|
- Graphene Library OS with Intel SGX Support
|
|
|
-
|
|
|
- A Linux-compatible Library OS for Multi-Process Applications
|
|
|
-
|
|
|
-
|
|
|
-1. WHAT IS GRAPHENE?
|
|
|
-
|
|
|
-Graphene Library OS is a project to provided lightweight guest OSes with
|
|
|
-support for Linux multi-process applications. Comparable to virtual
|
|
|
-machines, Graphene can run applications in an isolated environment, with
|
|
|
-virtualization benefits such as guest customization, platform independence
|
|
|
-and migration.
|
|
|
-
|
|
|
-Graphene Library OS supports native, unmodified Linux appliations upon
|
|
|
-any platform that Graphene Library OS has been ported to. Currently,
|
|
|
-Graphene Library OS is successfully ported to Linux, FreeBSD and Intel SGX
|
|
|
-enclaves upon Linux platforms.
|
|
|
-
|
|
|
-With the Intel SGX support, Graphene Library OS can secure a critical
|
|
|
-application in a hardware encrypted memory region. Graphene Library OS can
|
|
|
-protect applications against malicious system stack, with minimal porting
|
|
|
-effort.
|
|
|
-
|
|
|
-Graphene Library OS is a work published in Eurosys 2014. For more
|
|
|
-information. see the paper: Tsai, et al, "Cooperation and Security Isolation
|
|
|
-of Library OSes for Multi-Process Applications", Eurosys 2014.
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-2. HOW TO BUILD GRAPHENE?
|
|
|
-
|
|
|
-Graphene Library OS is consist of five parts:
|
|
|
- - Instrumented GNU Library C
|
|
|
- - LibOS (a shared library named "libsysdb.so")
|
|
|
- - PAL, a.k.a Platform Adaption Layer (a shared library named "libpal.so")
|
|
|
- - Reference monitor (a shared library named "libpal_sec.so")
|
|
|
- - Minor kernel customization and kernel modules
|
|
|
-
|
|
|
-Graphene Library OS currently only works on x86_64 architecture.
|
|
|
-
|
|
|
-Graphene Library OS is tested to be compiling and running on Ubuntu 12.04/14.04
|
|
|
-(both server and desktop version), along with Linux kernel 3.5/3.14.
|
|
|
-We recommand to build and install Graphene with the same host platform.
|
|
|
-Other distributions of 64-bit Linux can potentially, but the result is not
|
|
|
-guaranteed. If you find Graphene not working on other distributions, please
|
|
|
-contact us with a detailed bug report.
|
|
|
-
|
|
|
-The following packages are required for building Graphene: (can be installed
|
|
|
-with 'apt-get install')
|
|
|
- - build-essential
|
|
|
- - autoconf
|
|
|
- - gawk
|
|
|
-
|
|
|
-The following packages are also required for building Graphene for SGX (can
|
|
|
-be installed with 'apt-get install'):
|
|
|
- - python-protobuf
|
|
|
- - python-crypto
|
|
|
-
|
|
|
-To build the system, simply run the following commands in the root of the
|
|
|
-source tree:
|
|
|
-
|
|
|
- git submodule update --init
|
|
|
- make
|
|
|
-
|
|
|
-Each part of Graphene can be built separately in the subdirectories.
|
|
|
-
|
|
|
-To build Graphene library OS with debug symbols, run "make DEBUG=1" instead of
|
|
|
-"make".
|
|
|
-
|
|
|
- 2.1. BUILD WITH KERNEL-LEVEL SANDBOXING (OPTIONAL)
|
|
|
-
|
|
|
-** Note: this step is optional. **
|
|
|
-** Note: for building with Intel SGX support, skip this step. **
|
|
|
-
|
|
|
-** Disclaimer: this feature is experimental and may contain bugs. Please do
|
|
|
- no use in production system before further assessment.
|
|
|
-
|
|
|
-To enable sandboxing, a customized Linux kernel is needed. Note that
|
|
|
-this feature is optional and completely unnecessary for running on SGX.
|
|
|
-To build the Graphene Linux kernel, do the following steps:
|
|
|
-
|
|
|
- cd Pal/linux-3.19
|
|
|
- make menuconfig
|
|
|
- make
|
|
|
- make install
|
|
|
- (Add Graphene kernel as a boot option by commands like "update-grub")
|
|
|
- (reboot and choose the Graphene kernel)
|
|
|
-
|
|
|
-Please note that the building process may pause before building the Linux
|
|
|
-kernel, because it requires you to provide a sensible configuration file
|
|
|
-(.config). The Graphene kernel requires the following options to be enabled
|
|
|
-in the configuration:
|
|
|
-
|
|
|
- - CONFIG_GRAPHENE=y
|
|
|
- - CONFIG_GRAPHENE_BULK_IPC=y
|
|
|
- - CONFIG_GRAPHENE_ISOLATE=y
|
|
|
-
|
|
|
-For more details about the building and installation, see the Graphene github
|
|
|
-Wiki page: <https://github.com/oscarlab/graphene/wiki>.
|
|
|
-
|
|
|
-
|
|
|
- 2-1. BUILD WITH INTEL SGX SUPPORT
|
|
|
-
|
|
|
-To build Graphene Library OS with Intel SGX support, run "make SGX=1" instead
|
|
|
-of "make". "DEBUG=1" can be used to build with debug symbols. Using "make SGX=1"
|
|
|
-in the test or regression directory will automatically generate the enclave
|
|
|
-signatures (in .sig files).
|
|
|
-
|
|
|
-A 3072-bit RSA private key (PEM format) is required for signing the enclaves.
|
|
|
-The default enclave key is placed in 'host/Linux-SGX/signer/enclave-key.pem',
|
|
|
-or the key can be specified through environment variable 'SGX_ENCLAVE_KEY'
|
|
|
-when building Graphene with Intel SGX support. If you don't have a private key,
|
|
|
-create it with the following command:
|
|
|
-
|
|
|
- openssl genrsa -3 -out enclave-key.pem 3072
|
|
|
-
|
|
|
-After signing the enclaves, users may ship the application files with the
|
|
|
-built Graphene Library OS, along with a SGX-specific manifest (.manifest.sgx
|
|
|
-files) and the signatures, to the Intel SGX-enabled hosts. The Intel SGX
|
|
|
-Linux SDK is required for running Graphene Library OS. Download and install
|
|
|
-from the official Intel github repositories:
|
|
|
-
|
|
|
- <https://github.com/01org/linux-sgx>
|
|
|
- <https://github.com/01org/linux-sgx-driver>
|
|
|
- (The SDK and driver version must be 1.9 or LOWER)
|
|
|
-
|
|
|
-A Linux driver must be installed before runing Graphene Library OS in enclaves.
|
|
|
-Simply run the following command to build the driver:
|
|
|
-
|
|
|
- (Please make sure the GCC version is either 4 or 5)
|
|
|
- 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 ./load.sh
|
|
|
-
|
|
|
-Finally generating the runtime enclave tokens by running "make SGX_RUN=1".
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-3. HOW TO RUN AN APPLICATION IN GRAPHENE?
|
|
|
-
|
|
|
-Graphene library OS uses PAL (libpal.so) as a loader to bootstrap an
|
|
|
-application 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" given from the command line. Graphene provides three options for
|
|
|
-spcifying 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)
|
|
|
-
|
|
|
-Using "libpal.so" as loader to start Graphene will not attach the applications
|
|
|
-to the Graphene reference monitor. Tha applications will have better
|
|
|
-performance, but no strong security isolation. To attach the applications to
|
|
|
-the Graphene reference monitor, Graphene must be started with the PAL
|
|
|
-reference monitor loader (libpal_sec.so). Graphene provides three options for
|
|
|
-spcifying the programs and manifest files to the loader:
|
|
|
-
|
|
|
- option 4: (automatic manifest - with reference monitor)
|
|
|
- SEC=1 [PATH TO Runtime]/pal_loader [PROGRAM] [ARGUMENTS]...
|
|
|
- (Manifest file: "[PROGRAM].manifest" or "manifest")
|
|
|
-
|
|
|
- option 5: (given manifest - with reference monitor)
|
|
|
- SEC=1 [PATH TO Pal/src]/pal_loader [MANIFEST] [ARGUMENTS]...
|
|
|
-
|
|
|
- option 6: (manifest as a script - with reference monitor)
|
|
|
- SEC=1 [PATH TO MANIFEST]/[MANIFEST] [ARGUMENTS]...
|
|
|
- (Manifest must have "#![PATH TO Pal/src]/pal_sec" as the first line)
|
|
|
-
|
|
|
-Although manifest files are optional for Graphene, running an application
|
|
|
-usually requires some minimal configuration in its manifest file. A
|
|
|
-sensible manifest file will include paths to the library OS and GNU
|
|
|
-library C, environment variables such as LD_LIBRARY_PATH, file systems to
|
|
|
-be mounted, and isolation rules to be enforced in the reference monitor.
|
|
|
-
|
|
|
-Here is an example of manifest files:
|
|
|
-
|
|
|
- loader.preload = file:LibOS/shim/src/libsysdb.so
|
|
|
- loader.env.LDL_LIBRAY_PATH = /lib
|
|
|
- fs.mount.glibc.type = chroot
|
|
|
- fs.mount.glibc.path = /lib
|
|
|
- fs.mount.glibc.uri = file:LibOS/build
|
|
|
-
|
|
|
-More examples can be found in the test directories (LibOS/shim/test). We have
|
|
|
-also tested several commercial applications such as GCC, Bash and Apache,
|
|
|
-and the manifest files that bootstrap them in Graphene are provided in the
|
|
|
-individual directories.
|
|
|
-
|
|
|
-For more information and the detail of the manifest syntax, see the Graphene
|
|
|
-github Wiki page: <https://github.com/oscarlab/graphene/wiki>.
|
|
|
-
|
|
|
-
|
|
|
-
|
|
|
-4. HOW TO CONTACT THE MAINTAINER?
|
|
|
-
|
|
|
-For any questions or bug reports, please contact us:
|
|
|
-
|
|
|
-Chia-Che Tsai <chitsai@cs.stonybrook.edu>
|
|
|
-Don Porter <porter@cs.unc.edu>
|
|
|
-
|
|
|
-or post an issue on our github repository:
|
|
|
- <https://github.com/oscarlab/graphene/issues>
|
Don Porter