README 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201
  1. Graphene Library OS with Intel SGX Support
  2. A Linux-compatible Library OS for Multi-Process Applications
  3. 1. WHAT IS GRAPHENE?
  4. Graphene Library OS is a project to provided lightweight guest OSes with
  5. support for Linux multi-process applications. Comparable to virtual
  6. machines, Graphene can run applications in an isolated environment, with
  7. virtualization benefits such as guest customization, platform independence
  8. and migration.
  9. Graphene Library OS supports native, unmodified Linux appliations upon
  10. any platform that Graphene Library OS has been ported to. Currently,
  11. Graphene Library OS is successfully ported to Linux, FreeBSD and Intel SGX
  12. enclaves upon Linux platforms.
  13. With the Intel SGX support, Graphene Library OS can secure a critical
  14. application in a hardware encrypted memory region. Graphene Library OS can
  15. protect applications against malicious system stack, with minimal porting
  16. effort.
  17. Graphene Library OS is a work published in Eurosys 2014. For more
  18. information. see the paper: Tsai, et al, "Cooperation and Security Isolation
  19. of Library OSes for Multi-Process Applications", Eurosys 2014.
  20. 2. HOW TO BUILD GRAPHENE?
  21. Graphene Library OS is consist of five parts:
  22. - Instrumented GNU Library C
  23. - LibOS (a shared library named "libsysdb.so")
  24. - PAL, a.k.a Platform Adaption Layer (a shared library named "libpal.so")
  25. - Reference monitor (a shared library named "libpal_sec.so")
  26. - Minor kernel customization and kernel modules
  27. Graphene Library OS currently only works on x86_64 architecture.
  28. Graphene Library OS is tested to be compiling and running on Ubuntu 12.04/14.04
  29. (both server and desktop version), along with Linux kernel 3.5/3.14.
  30. We recommand to build and install Graphene with the same host platform.
  31. Other distributions of 64-bit Linux can potentially, but the result is not
  32. guaranteed. If you find Graphene not working on other distributions, please
  33. contact us with a detailed bug report.
  34. The following packages are required for building Graphene: (can be installed
  35. with 'apt-get install')
  36. - build-essential
  37. - autoconf
  38. - gawk
  39. The following packages are also required for building Graphene for SGX (can
  40. be installed with 'apt-get install'):
  41. - python-protobuf
  42. - python-crypto
  43. To build the system, simply run the following commands in the root of the
  44. source tree:
  45. git submodule update --init
  46. make
  47. Each part of Graphene can be built separately in the subdirectories.
  48. To build Graphene library OS with debug symbols, run "make DEBUG=1" instead of
  49. "make".
  50. To enable sandboxing, a customized Linux kernel is needed. Note that
  51. this feature is optional and completely unnecessary for running on SGX.
  52. To build the Graphene Linux kernel, do the following steps:
  53. cd Pal/linux-3.19
  54. make menuconfig
  55. make
  56. make install
  57. (Add Graphene kernel as a boot option by commands like "update-grub")
  58. (reboot and choose the Graphene kernel)
  59. Please note that the building process may pause before building the Linux
  60. kernel, because it requires you to provide a sensible configuration file
  61. (.config). The Graphene kernel requires the following options to be enabled
  62. in the configuration:
  63. - CONFIG_GRAPHENE=y
  64. - CONFIG_GRAPHENE_BULK_IPC=y
  65. - CONFIG_GRAPHENE_ISOLATE=y
  66. For more details about the building and installation, see the Graphene github
  67. Wiki page: <https://github.com/oscarlab/graphene/wiki>.
  68. 2-1. BUILD WITH INTEL SGX SUPPORT
  69. To build Graphene Library OS with Intel SGX support, run "make SGX=1" instead
  70. of "make". "DEBUG=1" can be used to build with debug symbols. Using "make SGX=1"
  71. in the test or regression directory will automatically generate the enclave
  72. signatures (in .sig files).
  73. A 3072-bit RSA private key (PEM format) is required for signing the enclaves.
  74. The default enclave key is placed in 'host/Linux-SGX/signer/enclave-key.pem',
  75. or the key can be specified through environment variable 'SGX_ENCLAVE_KEY'
  76. when building Graphene with Intel SGX support. If you don't have a private key,
  77. create it with the following command:
  78. openssl genrsa -3 -out enclave-key.pem 3072
  79. After signing the enclaves, users may ship the application files with the
  80. built Graphene Library OS, along with a SGX-specific manifest (.manifest.sgx
  81. files) and the signatures, to the Intel SGX-enabled hosts. The Intel SGX
  82. Linux SDK is required for running Graphene Library OS. Download and install
  83. from the official Intel github repositories:
  84. <https://github.com/01org/linux-sgx>
  85. <https://github.com/01org/linux-sgx-driver>
  86. A Linux driver must be installed before runing Graphene Library OS in enclaves.
  87. Simply run the following command to build the driver:
  88. cd Pal/src/host/Linux-SGX/sgx-driver
  89. make
  90. (The console will be prompted to ask for the path of Intel SGX driver code)
  91. sudo ./load.sh
  92. Finally generating the runtime enclave tokens by running "make SGX_RUN=1".
  93. 3. HOW TO RUN AN APPLICATION IN GRAPHENE?
  94. Graphene library OS uses PAL (libpal.so) as a loader to bootstrap an
  95. application in the library OS. To start Graphene, PAL (libpal.so) will have
  96. to be run as an executable, with the name of the program, and a "manifest
  97. file" given from the command line. Graphene provides three options for
  98. spcifying the programs and manifest files:
  99. option 1: (automatic manifest)
  100. [PATH TO Runtime]/pal_loader [PROGRAM] [ARGUMENTS]...
  101. (Manifest file: "[PROGRAM].manifest" or "manifest")
  102. option 2: (given manifest)
  103. [PATH TO Runtime]/pal_loader [MANIFEST] [ARGUMENTS]...
  104. option 3: (manifest as a script)
  105. [PATH TO MANIFEST]/[MANIFEST] [ARGUMENTS]...
  106. (Manifest must have "#![PATH_TO_PAL]/libpal.so" as the first line)
  107. Using "libpal.so" as loader to start Graphene will not attach the applications
  108. to the Graphene reference monitor. Tha applications will have better
  109. performance, but no strong security isolation. To attach the applications to
  110. the Graphene reference monitor, Graphene must be started with the PAL
  111. reference monitor loader (libpal_sec.so). Graphene provides three options for
  112. spcifying the programs and manifest files to the loader:
  113. option 4: (automatic manifest - with reference monitor)
  114. SEC=1 [PATH TO Runtime]/pal_loader [PROGRAM] [ARGUMENTS]...
  115. (Manifest file: "[PROGRAM].manifest" or "manifest")
  116. option 5: (given manifest - with reference monitor)
  117. SEC=1 [PATH TO Pal/src]/pal_loader [MANIFEST] [ARGUMENTS]...
  118. option 6: (manifest as a script - with reference monitor)
  119. SEC=1 [PATH TO MANIFEST]/[MANIFEST] [ARGUMENTS]...
  120. (Manifest must have "#![PATH TO Pal/src]/pal_sec" as the first line)
  121. Although manifest files are optional for Graphene, running an application
  122. usually requires some minimal configuration in its manifest file. A
  123. sensible manifest file will include paths to the library OS and GNU
  124. library C, environment variables such as LD_LIBRARY_PATH, file systems to
  125. be mounted, and isolation rules to be enforced in the reference monitor.
  126. Here is an example of manifest files:
  127. loader.preload = file:LibOS/shim/src/libsysdb.so
  128. loader.env.LDL_LIBRAY_PATH = /lib
  129. fs.mount.glibc.type = chroot
  130. fs.mount.glibc.path = /lib
  131. fs.mount.glibc.uri = file:LibOS/build
  132. More examples can be found in the test directories (LibOS/shim/test). We have
  133. also tested several commercial applications such as GCC, Bash and Apache,
  134. and the manifest files that bootstrap them in Graphene are provided in the
  135. individual directories.
  136. For more information and the detail of the manifest syntax, see the Graphene
  137. github Wiki page: <https://github.com/oscarlab/graphene/wiki>.
  138. 4. HOW TO CONTACT THE MAINTAINER?
  139. For any questions or bug reports, please contact us:
  140. Chia-Che Tsai <chitsai@cs.stonybrook.edu>
  141. Don Porter <porter@cs.unc.edu>
  142. or post an issue on our github repository:
  143. <https://github.com/oscarlab/graphene/issues>