README.rst 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284
  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 Library OS is a |_| project which provides lightweight guest OSes
  15. with support for Linux multi-process applications. Graphene can run applications
  16. in an isolated environment with virtualization benefits such as guest
  17. customization, platform independence, and migration, which is comparable to
  18. other virtual machines.
  19. Graphene Library OS supports native, unmodified Linux applications on
  20. any platform. Currently, Graphene Library OS is successfully ported to
  21. Linux, FreeBSD and Intel SGX enclaves upon Linux platforms.
  22. With the Intel SGX support, Graphene Library OS can secure a |_| critical
  23. application in a |_| hardware encrypted memory region. Graphene Library OS can
  24. protect applications against a |_| malicious system stack with minimal porting
  25. effort.
  26. Graphene Library OS is a |_| work published in Eurosys 2014. For more
  27. information. see the paper: Tsai, et al, "Cooperation and Security Isolation
  28. of Library OSes for Multi-Process Applications", Eurosys 2014.
  29. How to build Graphene?
  30. ======================
  31. Graphene Library OS is consist of five parts:
  32. - Instrumented GNU C Library
  33. - LibOS (a shared library named ``libsysdb.so``)
  34. - PAL, a.k.a Platform Adaption Layer (a shared library named ``libpal.so``)
  35. Graphene Library OS currently only works on x86_64 architecture.
  36. Graphene Library OS is tested to be compiling and running on Ubuntu 14.04/16.04
  37. (both server and desktop version), along with Linux kernel 3.5/3.14/4.4.
  38. We recommend to build and install Graphene with the same host platform.
  39. Other distributions of 64-bit Linux can potentially, but the result is not
  40. guaranteed. If you find Graphene not working on other distributions, please
  41. contact us with a detailed bug report.
  42. Run the following command on Ubuntu to install dependencies for Graphene::
  43. sudo apt-get install -y build-essential autoconf gawk bison
  44. For building Graphene for SGX, run the following command in addition::
  45. sudo apt-get install -y python-protobuf libprotobuf-c-dev protobuf-c-compiler
  46. To run unit tests locally, you also need the python3-pytest package::
  47. sudo apt-get install -y python3-pytest
  48. To build the system, simply run the following commands in the root of the
  49. source tree::
  50. git submodule update --init -- Pal/src/host/Linux-SGX/sgx-driver/
  51. make
  52. Each part of Graphene can be built separately in the subdirectories.
  53. To build Graphene library OS with debug symbols, run ``make DEBUG=1``
  54. instead of ``make``. To specify custom mirrors for downloading the GLIBC
  55. source, use ``make GLIBC_MIRRORS=...``.
  56. To build with ``-Werror``, run ``make WERROR=1``.
  57. Build with kernel-level sandboxing (optional)
  58. ---------------------------------------------
  59. This feature is marked as EXPERIMENTAL and no longer exists in the mainstream code.
  60. Build with Intel SGX Support
  61. ----------------------------
  62. Prerequisites
  63. ^^^^^^^^^^^^^
  64. 1. Generating signing keys
  65. A 3072-bit RSA private key (PEM format) is required for signing the enclaves.
  66. If you don't have a private key, create it with the following command::
  67. openssl genrsa -3 -out enclave-key.pem 3072
  68. You could either put the generated enclave key to the default path,
  69. ``host/Linux-SGX/signer/enclave-key.pem``, or specify the key through
  70. environment variable ``SGX_SIGNER_KEY`` when building Graphene with SGX
  71. support.
  72. After signing the enclaves, users may ship the application files with the
  73. built Graphene Library OS, along with a SGX-specific manifest (.manifest.sgx
  74. files) and the signatures, to the SGX-enabled hosts.
  75. 2. Installing Intel SGX SDK and driver
  76. The Intel SGX Linux SDK is required for running Graphene Library OS. Download
  77. and install from the official Intel github repositories:
  78. - <https://github.com/01org/linux-sgx>
  79. - <https://github.com/01org/linux-sgx-driver>
  80. A Linux driver must be installed before running Graphene Library OS in
  81. enclaves. Simply run the following command to build the driver::
  82. cd Pal/src/host/Linux-SGX/sgx-driver
  83. make
  84. (The console will be prompted to ask for the path of Intel SGX driver code)
  85. sudo ./load.sh
  86. Building Graphene-SGX
  87. ^^^^^^^^^^^^^^^^^^^^^
  88. To build Graphene Library OS with Intel SGX support, in the root directory of
  89. Graphene repo, run following command::
  90. make SGX=1
  91. To build with debug symbols, run the command::
  92. make SGX=1 DEBUG=1
  93. Using ``make SGX=1`` in the test or regression directory will automatically
  94. generate the enclave signatures (.sig files).
  95. Run Built-in Examples in Graphene-SGX
  96. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  97. There are a few built-in examples under ``LibOS/shim/test/``. The "native"
  98. folder includes a |_| rich set of C |_| programs and "apps" folder includes
  99. a |_| few tested applications, such as GCC, Python, and Apache.
  100. 1. Build and run a |_| Hello World program with Graphene on SGX
  101. - go to LibOS/shim/test/native, build the enclaves via command::
  102. make SGX=1
  103. The command will build enclaves for all the programs in the folder
  104. - Generate the token from aesmd service, via command::
  105. make SGX=1 sgx-tokens
  106. - Run Hello World program with Graphene on SGX::
  107. SGX=1 ./pal_loader helloworld
  108. or::
  109. ./pal_loader SGX helloworld
  110. 2. Build and run python helloworld script in Graphene on SGX
  111. - go to LibOS/shim/test/apps/python, build the enclave::
  112. make SGX=1
  113. - Generate token::
  114. make SGX=1 sgx-tokens
  115. - Run python helloworld with Graphene-SGX via::
  116. SGX=1 ./python.manifest.sgx scripts/helloworld.py
  117. Including Application Test Cases
  118. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  119. To add the application test cases, issue the following command from the root
  120. of the source tree::
  121. git submodule update --init -- LibOS/shim/test/apps/
  122. Testing the remote attestation feature
  123. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  124. To enable tests for the built-in remote attestation feature for Graphene-SGX, obtain a SPID
  125. and a subscription key (can be linkable or unlinkable) from the Intel API Portal:
  126. https://api.portal.trustedservices.intel.com/EPID-attestation
  127. Specify the SPID, subscription key, and the type of the SPID/key in the manifest::
  128. sgx.ra_client_spid = <SPID>
  129. sgx.ra_client_key = <KEY>
  130. sgx.ra_client_linkable = 1 # or 0 if the SPID/key is unlinkable (default)
  131. If the remote attestation feature is enabled, Graphene-SGX will terminate if the platform
  132. is not successfully verified by the Intel Attestation Service (IAS). The feature ensures that
  133. Graphene-SGX only executes on a genuine, up-to-date SGX hardware.
  134. To enable remote attestation tests in ``Pal/regression``, specify the following variables::
  135. cd PAL/regression
  136. make SGX=1 RA_CLIENT_SPID=<SPID> RA_CLIENT_KEY=<KEY>
  137. make SGX=1 sgx-tokens
  138. If you receive a "GROUP_OUT_OF_DATE" status from IAS, this status indicates that your CPU
  139. is out of date and can be vulnerable to hardware attacks. If you wish to bypass this error,
  140. you can specify the following option in the manifest::
  141. sgx.ra_accept_group_out_of_date = 1
  142. SECURITY ADVISORIES:
  143. "GROUP_OUT_OF_DATE" may indicate that the firmware (microcode) of you CPU is not updated
  144. according to INTEL-SA-00233 (Load/store data sampling) and INTEL-SA-00161 (L1 terminal fault).
  145. It is recommended that you keep the BIOS of your platform up-to-date.
  146. If you receive status "CONFIGURATION_NEEDED" from the IAS after updating your BIOS, you may
  147. need to disable hyperthreading in your BIOS to mitigate L1 terminal fault.
  148. How to run an application in Graphene?
  149. ======================================
  150. Graphene library OS uses PAL (``libpal.so``) as a loader to bootstrap an
  151. application in the library OS. To start Graphene, PAL (``libpal.so``) will have
  152. to be run as an executable, with the name of the program, and a |_| "manifest
  153. file" given from the command line. Graphene provides three options for
  154. specifying the programs and manifest files:
  155. - option 1 (automatic manifest)::
  156. [PATH TO Runtime]/pal_loader [PROGRAM] [ARGUMENTS]...
  157. (Manifest file: "[PROGRAM].manifest" or "manifest")
  158. - option 2 (given manifest)::
  159. [PATH TO Runtime]/pal_loader [MANIFEST] [ARGUMENTS]...
  160. - option 3 (manifest as a script)::
  161. [PATH TO MANIFEST]/[MANIFEST] [ARGUMENTS]...
  162. (Manifest must have "#![PATH_TO_PAL]/libpal.so" as the first line)
  163. Although manifest files are optional for Graphene, running an application
  164. usually requires some minimal configuration in its manifest file. A |_| sensible
  165. manifest file will include paths to the library OS and GNU library C,
  166. environment variables such as LD_LIBRARY_PATH and file systems to
  167. be mounted.
  168. Here is an example of manifest files::
  169. loader.preload = file:LibOS/shim/src/libsysdb.so
  170. loader.env.LDL_LIBRAY_PATH = /lib
  171. fs.mount.glibc.type = chroot
  172. fs.mount.glibc.path = /lib
  173. fs.mount.glibc.uri = file:LibOS/build
  174. More examples can be found in the test directories (``LibOS/shim/test``). We
  175. have also tested several commercial applications such as GCC, Bash and Apache,
  176. and the manifest files that bootstrap them in Graphene are provided in the
  177. individual directories.
  178. For more information and the detail of the manifest syntax, see the `Graphene
  179. documentation <https://graphene.rtfd.io/>`_.
  180. Contact
  181. =======
  182. For any questions or bug reports, please send an email to
  183. <support@graphene-project.io> or post an issue on our GitHub repository:
  184. <https://github.com/oscarlab/graphene/issues>.
  185. Our mailing list is publicly archived `here
  186. <https://groups.google.com/forum/#!forum/graphene-support>`_.