README.rst 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285
  1. ******************************************
  2. Graphene Library OS with Intel SGX Support
  3. ******************************************
  4. .. image:: https://readthedocs.org/projects/graphene/badge/?version=latest
  5. :target: http://graphene.readthedocs.io/en/latest/?badge=latest
  6. :alt: Documentation Status
  7. *A Linux-compatible Library OS for Multi-Process Applications*
  8. .. This is not |nbsp|, because that is in rst_prolog in conf.py, which GitHub
  9. cannot parse. GitHub doesn't appear to use it correctly anyway...
  10. .. |_| unicode:: 0xa0
  11. :trim:
  12. What is Graphene?
  13. =================
  14. Graphene is a lightweight guest OS, designed to run a single application with minimal host
  15. requirements. Graphene can run applications in an isolated environment with benefits comparable to
  16. running a complete OS in a virtual machine -- including guest customization, ease of porting to
  17. different OSes, and process migration.
  18. Graphene supports native, unmodified Linux applications on any platform. Currently, Graphene runs on
  19. Linux, FreeBSD and Intel SGX enclaves on Linux platforms.
  20. With Intel SGX support, Graphene can secure a |_| critical application in a |_| hardware-encrypted
  21. memory region. Graphene can protect applications from a |_| malicious system stack with minimal
  22. porting effort.
  23. Our papers describe the motivation, design choices, and measured performance of Graphene:
  24. - `EuroSys 2014 <http://www.cs.unc.edu/~porter/pubs/tsai14graphene.pdf>`_
  25. - `ATC 2017 <http://www.cs.unc.edu/~porter/pubs/graphene-sgx.pdf>`_
  26. How to build Graphene?
  27. ======================
  28. Graphene consists of three parts:
  29. - An instrumented GNU C Library
  30. - The Library OS itself (a shared library named ``libsysdb.so``, called the "shim" in our source code)
  31. - The Platform Adaptation Layer, or PAL, (a shared library named ``libpal.so``)
  32. Graphene currently only works on the x86_64 architecture. Graphene is currently tested on Ubuntu
  33. 16.04 and 18.04 (both server and desktop version), along with Linux kernel versions 3.x/4.x. We
  34. recommend building and installing Graphene on the same host platform. If you find problems with
  35. Graphene on other Linux distributions, please contact us with a detailed bug report.
  36. Run the following command on Ubuntu to install dependencies for Graphene::
  37. sudo apt-get install -y build-essential autoconf gawk bison
  38. For building Graphene for SGX, run the following command in addition::
  39. sudo apt-get install -y python3-protobuf libprotobuf-c-dev protobuf-c-compiler
  40. To run tests locally, you also need the python3-pytest package::
  41. sudo apt-get install -y python3-pytest
  42. To build Graphene, simply run the following commands in the root of the
  43. source tree::
  44. git submodule update --init -- Pal/src/host/Linux-SGX/sgx-driver/
  45. make
  46. Each part of Graphene can be built separately in the subdirectories.
  47. To build Graphene with debug symbols, run ``make DEBUG=1``
  48. instead of ``make``. To specify custom mirrors for downloading the GLIBC
  49. source, use ``make GLIBC_MIRRORS=...``.
  50. To build with ``-Werror``, run ``make WERROR=1``.
  51. Building with kernel-level sandboxing (optional)
  52. ------------------------------------------------
  53. This feature is marked as EXPERIMENTAL and no longer exists on the master branch.
  54. Building with Intel SGX Support
  55. -------------------------------
  56. Prerequisites
  57. ^^^^^^^^^^^^^
  58. 1. Generate signing keys
  59. A 3072-bit RSA private key (PEM format) is required for signing the manifest.
  60. If you don't have a private key, create it with the following command::
  61. openssl genrsa -3 -out enclave-key.pem 3072
  62. You can either place the generated enclave key in the default path,
  63. ``host/Linux-SGX/signer/enclave-key.pem``, or specify the key's location through
  64. the environment variable ``SGX_SIGNER_KEY``.
  65. After signing the application's manifest, users may ship the application and Graphene binaries,
  66. along with an SGX-specific manifest (.manifest.sgx extension), the signature (.sig extension),
  67. and the aesmd init token (.token extension) to execute on another SGX-enabled host.
  68. 2. Install the Intel SGX SDK and driver
  69. The Intel SGX Linux SDK is required to compile and run Graphene on SGX. Download
  70. and install it from the official Intel GitHub repositories:
  71. - <https://github.com/01org/linux-sgx>
  72. - <https://github.com/01org/linux-sgx-driver>
  73. 3. Build and install the Graphene SGX driver
  74. A Graphene-specific Linux driver must also be installed before running Graphene in
  75. an SGX environment. Simply run the following commands to build the driver::
  76. cd Pal/src/host/Linux-SGX/sgx-driver
  77. make
  78. # The console will be prompted to ask for the path of Intel SGX driver code
  79. sudo ./load.sh
  80. sudo sysctl vm.mmap_min_addr = 0
  81. We note that this last command is a tempoarary work-around for some issues with the Intel SGX
  82. driver. This is an inadvisable configuration for production systems. We hope to remove this
  83. step in a future version of Graphene, once the SGX driver is upstreamed to Linux.
  84. Building Graphene-SGX
  85. ^^^^^^^^^^^^^^^^^^^^^
  86. To build Graphene with Intel SGX support, in the root directory of Graphene repo, run the following
  87. command::
  88. make SGX=1
  89. To build with debug symbols, instead run the command::
  90. make SGX=1 DEBUG=1
  91. Running ``make SGX=1`` in the test or regression directory will automatically generate the required
  92. manifest signatures (.sig files).
  93. Run Built-in Examples in Graphene-SGX
  94. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  95. There are a few built-in examples under ``LibOS/shim/test/``. The "native"
  96. folder includes a |_| rich set of C |_| programs and "apps" folder includes
  97. a |_| few tested applications, such as GCC, Python, and Apache.
  98. 1. Build and run a |_| ``helloworld`` program with Graphene-SGX
  99. - go to LibOS/shim/test/native, build the enclaves via the command::
  100. make SGX=1
  101. This command will build enclaves for all the programs in the folder
  102. - Generate the token from aesmd service, via the command::
  103. make SGX=1 sgx-tokens
  104. - Run a helloworld program with Graphene-SGX::
  105. SGX=1 ./pal_loader helloworld
  106. or::
  107. ./pal_loader SGX helloworld
  108. 2. Build and run the Python ``helloworld.py`` script in Graphene-SGX
  109. - go to LibOS/shim/test/apps/python, and build the enclave::
  110. make SGX=1
  111. - Generate a launch token from the aesmd service::
  112. make SGX=1 sgx-tokens
  113. - Run ``helloworld.py`` script with Graphene-SGX via::
  114. SGX=1 ./python.manifest.sgx scripts/helloworld.py
  115. Including Application Test Cases
  116. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  117. To add the application test cases, issue the following command from the root
  118. of the source tree::
  119. git submodule update --init -- LibOS/shim/test/apps/
  120. Testing the remote attestation feature
  121. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  122. To enable tests for the built-in remote attestation feature for Graphene-SGX, obtain a SPID
  123. and a subscription key (can be linkable or unlinkable) from the Intel API Portal:
  124. <https://api.portal.trustedservices.intel.com/EPID-attestation>.
  125. Specify the SPID, subscription key, and the type of the SPID/key in the manifest::
  126. sgx.ra_client_spid = <SPID>
  127. sgx.ra_client_key = <KEY>
  128. sgx.ra_client_linkable = 1 # or 0 if the SPID/key is unlinkable (default)
  129. If the remote attestation feature is enabled, Graphene-SGX will terminate if the platform
  130. is not successfully verified by the Intel Attestation Service (IAS). The feature ensures that
  131. Graphene-SGX only executes on genuine, up-to-date SGX hardware.
  132. To enable remote attestation tests in ``Pal/regression``, specify the following variables::
  133. cd PAL/regression
  134. make SGX=1 RA_CLIENT_SPID=<SPID> RA_CLIENT_KEY=<KEY>
  135. make SGX=1 sgx-tokens
  136. If you receive a ``GROUP_OUT_OF_DATE`` status from IAS, this status indicates that your CPU
  137. is out of date and can be vulnerable to hardware attacks. If you wish to bypass this error,
  138. you can specify the following option in the manifest::
  139. sgx.ra_accept_group_out_of_date = 1
  140. Similarly, if you receive a ``CONFIGURATION_NEEDED`` status from IAS, this status indicates that
  141. additional configuration of your SGX platform may be needed. If you wish to bypass this error,
  142. you can specify the following option in the manifest::
  143. sgx.ra_accept_configuration_needed = 1
  144. *Security advisories:*
  145. - ``GROUP_OUT_OF_DATE`` may indicate that the firmware (microcode) of you CPU is not updated
  146. according to INTEL-SA-00233 (Load/store data sampling) and INTEL-SA-00161 (L1 terminal fault).
  147. It is recommended that you keep the BIOS of your platform up-to-date.
  148. - If you receive status ``CONFIGURATION_NEEDED`` from the IAS after updating your BIOS, you may
  149. need to disable hyperthreading in your BIOS to mitigate L1 terminal fault.
  150. How to run an application in Graphene?
  151. ======================================
  152. Graphene library OS uses the PAL (``libpal.so``) as a loader to bootstrap applications in the
  153. library OS. To start Graphene, PAL (``libpal.so``) will have to be run as an executable, with the
  154. name of the program, and a |_| "manifest file" (per-app configuration) given from the command
  155. line. Graphene provides three options for specifying the programs and manifest files:
  156. - option 1 (automatic manifest)::
  157. [PATH TO Runtime]/pal_loader [PROGRAM] [ARGUMENTS]...
  158. (Manifest file: "[PROGRAM].manifest" or "manifest")
  159. - option 2 (given manifest)::
  160. [PATH TO Runtime]/pal_loader [MANIFEST] [ARGUMENTS]...
  161. - option 3 (manifest as a script)::
  162. [PATH TO MANIFEST]/[MANIFEST] [ARGUMENTS]...
  163. (Manifest must have "#![PATH_TO_PAL]/libpal.so" as the first line)
  164. Running an application requires some minimal configuration in the application's manifest file. A
  165. |_| sensible manifest file will include paths to the library OS and other libraries the application
  166. requires; environment variables, such as ``LD_LIBRARY_PATH``; and file systems to be mounted.
  167. Here is an example manifest file::
  168. loader.preload = file:LibOS/shim/src/libsysdb.so
  169. loader.env.LD_LIBRAY_PATH = /lib
  170. fs.mount.libc.type = chroot
  171. fs.mount.libc.path = /lib
  172. fs.mount.libc.uri = file:[relative path to Graphene root]/Runtime
  173. More examples can be found in the test directories (``LibOS/shim/test``). We
  174. have also tested several applications, such as GCC, Bash, and Apache.
  175. The manifest files for these applications are provided in the
  176. individual directories under ``LibOS/shim/test/apps``.
  177. For the full documentation of the Graphene manifest syntax, see the `Graphene
  178. documentation <https://graphene.readthedocs.io/>`_.
  179. Contact
  180. =======
  181. For any questions or bug reports, please send an email to
  182. <support@graphene-project.io> or post an issue on our GitHub repository:
  183. <https://github.com/oscarlab/graphene/issues>.
  184. Our mailing list is publicly archived `here
  185. <https://groups.google.com/forum/#!forum/graphene-support>`_.