diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 00000000..e35d8850 --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1 @@ +_build diff --git a/Documentation/Doxyfile b/Documentation/Doxyfile new file mode 100644 index 00000000..36d25a40 --- /dev/null +++ b/Documentation/Doxyfile @@ -0,0 +1,26 @@ +PROJECT_NAME = "Graphene" +OUTPUT_DIRECTORY = _build/doxygen + +GENERATE_XML = YES +XML_PROGRAMLISTING = NO +XML_OUTPUT = xml + +GENERATE_HTML = NO +GENERATE_LATEX = NO + +RECURSIVE = YES +INPUT = \ + ../Pal \ + ../LibOS/shim/include \ + ../LibOS/shim/src + +EXCLUDE = \ + ../Pal/lib \ + ../Pal/regression \ + ../Pal/test +#EXCLUDE_PATTERNS = + +WARN_NO_PARAMDOC = YES +WARN_AS_ERROR = NO +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_STATIC = YES diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 00000000..b4201012 --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,22 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +clean: + $(RM) -r "$(BUILDDIR)" + +.PHONY: help Makefile Doxyfile clean + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile Doxyfile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/Documentation/_static/.gitigore b/Documentation/_static/.gitigore new file mode 100644 index 00000000..e69de29b diff --git a/Documentation/_templates/.gitignore b/Documentation/_templates/.gitignore new file mode 100644 index 00000000..e69de29b diff --git a/Documentation/conf.py b/Documentation/conf.py new file mode 100644 index 00000000..6151b753 --- /dev/null +++ b/Documentation/conf.py @@ -0,0 +1,139 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +import collections +import pathlib +import subprocess + +import recommonmark.parser + +# -- Project information ----------------------------------------------------- + +project = 'Graphene' +copyright = '2019, Graphene Contributors' +author = 'Graphene Contributors' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'breathe', + 'recommonmark', + 'sphinx_rtd_theme', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', + '.markdown': 'markdown', +} + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + +rst_prolog = ''' +.. |nbsp| unicode:: 0xa0 + :trim: +''' + +breathe_default_project = 'graphene' +breathe_projects = {breathe_default_project: '_build/doxygen/xml'} + +def generate_doxygen(app): + subprocess.check_call(['doxygen', 'Doxyfile']) +def setup(app): + app.connect('builder-inited', generate_doxygen) + +todo_include_todos = True + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('manpages/pal_loader', 'pal_loader', 'FIXME Loader', [author], 1), +] + +# barf if a page is not included +assert (collections.Counter(str(p.with_suffix('')) + for p in pathlib.Path().glob('manpages/*.rst') + if not p.stem == 'index') + == collections.Counter(source + for source, *_ in man_pages)) diff --git a/Documentation/glossary.rst b/Documentation/glossary.rst new file mode 100644 index 00000000..abd14b6d --- /dev/null +++ b/Documentation/glossary.rst @@ -0,0 +1,15 @@ +Glossary +======== + +.. keep this file sorted lexicographically + +.. glossary:: + + PAL + Platform Adaption Layer + + .. todo:: Is this really correct? + + SGX + Software Guard Extensions is a set of instructions on Intel processors. + See https://en.wikipedia.org/wiki/Software_Guard_Extensions. diff --git a/Documentation/howto-doc.rst b/Documentation/howto-doc.rst new file mode 100644 index 00000000..75bd3d3f --- /dev/null +++ b/Documentation/howto-doc.rst @@ -0,0 +1,47 @@ +.. _doc-howto: + +How to write documentation +========================== + +Documentation is generally written as `reStructuredText`_ files and processed +using `Sphinx`_. See `Sphinx' reST primer`_ for short introduction into syntax. +:ref:`Old Wiki ` is imported as it was, in Markdown, but new +documentation should be written in reST. + +API documentation of C |nbsp| language should be written as Doxygen comments +(prefer Qt-style ``/*!`` and ``\param``) and then included in one of the +``.rst`` files (with appropriate description) using one of the `Breathe +directives`_, like :rst:dir:`doxygenfunction` or :rst:dir:`doxygenstruct`. See +`Breathe`_ documentation for more info. Do not use ``autodoxygen`` directives, +and especially do not use ``.. doxygenfile::``, because documentation should be +written as prose, not a |nbsp| coredump. + +In ``.rst`` files use 3-space tab. This is an uncommon value, but good value +because intended blocks usually follow explicit markup, which begins with +``..``). Wrap the paragraphs at 80th character, but don't wrap verbatim text +like logs and use applicable style when wrapping code examples. Use Python +convention for header hierarchy: ``#`` with overline, ``*`` with overline, +``=``, ``-``, ``^``, ``"``. This means most documents use only ``=`` and ``-`` +underlines. Those underlines are easy to enter in :command:`vim` using the +combination ``yypVr-``. + +Documentation of the code should be organized into files by logical concepts, +as they fit into programmers mind. Ideally, this should match the source files, +if those files were organised correctly in the first place, but the reality may +be different. In case of doubt, place them as they fit the narration of the +document, not as they are placed in the source files. + +Documents should be grouped by general areas and presented using +:rst:dir:`toctree` directive in :file:`index.rst` file. This causes them to be +included in TOC in the main document and also in sidebar on RTD. + +The documentation targets ``html`` output of Sphinx. The :file:`manpages/` +subdirectory also targets ``manpage`` builder. Other formats (like ``latex``) +may be considered in the future, but for now their output is neither published +not cared for. + +.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText +.. _Sphinx: https://www.sphinx-doc.org/ +.. _Sphinx' reST primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. _Breathe: https://breathe.readthedocs.io/en/latest/ +.. _Breathe directives: https://breathe.readthedocs.io/en/latest/directives.html diff --git a/Documentation/index.rst b/Documentation/index.rst new file mode 100644 index 00000000..2123a596 --- /dev/null +++ b/Documentation/index.rst @@ -0,0 +1,36 @@ +.. include:: ../README.rst + +.. toctree:: + :caption: Introduction + :maxdepth: 2 + + glossary + howto-doc + +.. toctree:: + :caption: LibOS + + libos/shim-init + +.. toctree:: + :caption: Manual pages + :maxdepth: 1 + :glob: + + manpages/* + +.. _old-wiki: + +.. toctree:: + :caption: Old Wiki (to be rewritten) + :maxdepth: 1 + :glob: + + oldwiki/* + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/Documentation/libos/shim-init.rst b/Documentation/libos/shim-init.rst new file mode 100644 index 00000000..96a212f8 --- /dev/null +++ b/Documentation/libos/shim-init.rst @@ -0,0 +1,10 @@ +A random file documentation +=========================== + +.. note:: + + This file is more like a |nbsp| stub, not yet a |nbsp| real documentation. + +There is a |nbsp| random function: + +.. doxygenfunction:: parse_int diff --git a/Documentation/manpages/pal_loader.rst b/Documentation/manpages/pal_loader.rst new file mode 100644 index 00000000..c29944c2 --- /dev/null +++ b/Documentation/manpages/pal_loader.rst @@ -0,0 +1,42 @@ +.. program:: pal_loader + +====================================== +:program:`pal_loader` -- Run something +====================================== + +.. note:: + + This page is a stub. + +Synopsis +======== + +:command:`pal_loader` [SGX] [GDB] {<*MANIFEST*> | <*EXECUTABLE*>} [<*ARGS*> ...] + +Description +=========== + +Command line arguments +====================== + +.. option:: SGX + + Enable :term:`SGX`. + + .. seealso:: + + :envvar:`SGX environment variable ` + For an equivalent. + +Environment variables +===================== + +.. envvar:: SGX + + If not empty and not ``0``, enable :term:`SGX`. Could be used instead of + :option:`SGX option `. This has some unexplained interaction with + :envvar:`SGX_RUN`. + +.. envvar:: SGX_RUN + + This is a mystery to me. It cannot be set together with :envvar:`SGX`. diff --git a/Documentation/requirements.txt b/Documentation/requirements.txt new file mode 100644 index 00000000..03a20a33 --- /dev/null +++ b/Documentation/requirements.txt @@ -0,0 +1,2 @@ +breathe +recommonmark diff --git a/LibOS/shim/src/shim_init.c b/LibOS/shim/src/shim_init.c index 955412ec..009f5234 100644 --- a/LibOS/shim/src/shim_init.c +++ b/LibOS/shim/src/shim_init.c @@ -14,8 +14,8 @@ You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . */ -/* - * shim_init.c +/*! + * \file shim_init.c * * This file contains entry and exit functions of library OS. */ @@ -110,6 +110,15 @@ long convert_pal_errno (long err) pal_errno_to_unix_errno[err] : 0; } +/*! + * \brief Parse a number into an unsigned long. + * + * \param str A string containing a non-negative number. + * + * By default the number should be decimal, but if it starts with 0x it is + * parsed as hexadecimal and if it otherwise starts with 0, it is parsed as + * octal. + */ unsigned long parse_int (const char * str) { unsigned long num = 0; diff --git a/README.md b/README.md deleted file mode 100644 index 3dac7ad2..00000000 --- a/README.md +++ /dev/null @@ -1,217 +0,0 @@ - -# Graphene Library OS with Intel:registered: SGX Support - -![Travis Logo](https://travis-ci.org/oscarlab/graphene.svg?branch=master) - - -*A Linux-compatible Library OS for Multi-Process Applications* - -## 1. WHAT IS GRAPHENE? - -Graphene Library OS is a project which provides lightweight guest OSes with -support for Linux multi-process applications. Graphene can run applications -in an isolated environment with virtualization benefits such as guest -customization, platform independence, and migration, which is comparable -to other virtual machines. - -Graphene Library OS supports native, unmodified Linux applications on -any platform. Currently, Graphene Library OS is successfully ported to -Linux, FreeBSD and Intel SGX enclaves upon Linux platforms. - -With the Intel:registered: SGX support, Graphene Library OS can secure a critical -application in a hardware encrypted memory region. Graphene Library OS can -protect applications against a 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") - -Graphene Library OS currently only works on x86_64 architecture. - -Graphene Library OS is tested to be compiling and running on Ubuntu 14.04/16.04 -(both server and desktop version), along with Linux kernel 3.5/3.14/4.4. -We recommend 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. - -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 python-protobuf - - -To run unit tests locally, you also need the python3-pytest package: - - sudo apt-get install -y python3-pytest - - -To build the system, 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 library OS with debug symbols, run "make DEBUG=1" instead of -"make". To specify custom mirrors for downloading the GLIBC source, use -"GLIBC_MIRRORS=..." when running "make". - -To build with "-Werror", run "make WERROR=1". - -### 2.1. BUILD WITH KERNEL-LEVEL SANDBOXING (OPTIONAL) - -This feature is marked as EXPERIMENTAL and no longer exists in the mainstream code. - -### 2.2 BUILD WITH INTEL:registered: SGX SUPPORT - -#### 2.1.1 Prerequisites - -(1) Generating signing keys -A 3072-bit RSA private key (PEM format) is required for signing the enclaves. -If you don't have a private key, create it with the following command: - - openssl genrsa -3 -out enclave-key.pem 3072 - -You could either put the generated enclave key to the default path, -'host/Linux-SGX/signer/enclave-key.pem', or specify the key through environment -variable 'SGX_SIGNER_KEY' when building Graphene with SGX support. - -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 SGX-enabled hosts. - -(2) Installing Intel SGX SDK and driver -The Intel SGX Linux SDK is required for running Graphene Library OS. Download and install -from the official Intel github repositories: - - - - - - -A Linux driver must be installed before running 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 - -#### 2.1.2 Building Graphene-SGX - -To build Graphene Library OS with Intel SGX support, in the root directory of Graphene repo, run following command: - - make SGX=1 - -To build with debug symbols, run the command: - - make SGX=1 DEBUG=1 - -Using "make SGX=1" in the test or regression directory will automatically generate the enclave signatures (.sig files). - -#### 2.1.3 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 Hello World program with Graphene on SGX -- go to LibOS/shim/test/native, build the enclaves via command: - - make SGX=1 - - The command will build enclaves for all the programs in the folder -- Generate the token from aesmd service, via command: - - make SGX_RUN=1 - -- Run Hello World program with Graphene on SGX: - - SGX=1 ./pal_loader helloworld or ./pal_loader SGX helloworld - -(2) Build and run python helloworld script in Graphene on SGX -- go to LibOS/shim/test/apps/python, build the enclave: - - make SGX=1 - -- Generate token: - - make SGX_RUN=1 - -- Run python helloworld with Graphene-SGX via: - - SGX=1 ./python.manifest.sgx scripts/helloworld.py - -#### 2.1.3 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/ - -## 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 -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) - -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 and file systems to -be mounted. - -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: . - - - -## 4. CONTACT - -For any questions or bug reports, please send an email to or post an -issue on our GitHub repository: . - -Our mailing list is publicly archived [here](https://groups.google.com/forum/#!forum/graphene-support). diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..e9d4a995 --- /dev/null +++ b/README.rst @@ -0,0 +1,250 @@ +****************************************** +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 Library OS is a |_| project which provides lightweight guest OSes +with support for Linux multi-process applications. Graphene can run applications +in an isolated environment with virtualization benefits such as guest +customization, platform independence, and migration, which is comparable to +other virtual machines. + +Graphene Library OS supports native, unmodified Linux applications on +any platform. 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 a |_| 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. + + + +How to build Graphene? +====================== + +Graphene Library OS is consist of five parts: + +- Instrumented GNU C Library +- LibOS (a shared library named ``libsysdb.so``) +- PAL, a.k.a Platform Adaption Layer (a shared library named ``libpal.so``) + +Graphene Library OS currently only works on x86_64 architecture. + +Graphene Library OS is tested to be compiling and running on Ubuntu 14.04/16.04 +(both server and desktop version), along with Linux kernel 3.5/3.14/4.4. +We recommend 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. + +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 python-protobuf + +To run unit tests locally, you also need the python3-pytest package:: + + sudo apt-get install -y python3-pytest + +To build the system, 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 library OS 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``. + +Build with kernel-level sandboxing (optional) +--------------------------------------------- + +This feature is marked as EXPERIMENTAL and no longer exists in the mainstream code. + +Build with Intel SGX Support +---------------------------- + +Prerequisites +^^^^^^^^^^^^^ + +1. Generating signing keys + + A 3072-bit RSA private key (PEM format) is required for signing the enclaves. + If you don't have a private key, create it with the following command:: + + openssl genrsa -3 -out enclave-key.pem 3072 + + You could either put the generated enclave key to the default path, + ``host/Linux-SGX/signer/enclave-key.pem``, or specify the key through + environment variable ``SGX_SIGNER_KEY`` when building Graphene with SGX + support. + + 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 SGX-enabled hosts. + +2. Installing Intel SGX SDK and driver + + The Intel SGX Linux SDK is required for running Graphene Library OS. Download + and install from the official Intel github repositories: + + - + - + + A Linux driver must be installed before running Graphene Library OS in + enclaves. Simply run the following command to build the driver: + + .. note:: + + 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 + +Building Graphene-SGX +^^^^^^^^^^^^^^^^^^^^^ + +To build Graphene Library OS with Intel SGX support, in the root directory of +Graphene repo, run following command:: + + make SGX=1 + +To build with debug symbols, run the command:: + + make SGX=1 DEBUG=1 + +Using ``make SGX=1`` in the test or regression directory will automatically +generate the enclave 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 |_| Hello World program with Graphene on SGX + + - go to LibOS/shim/test/native, build the enclaves via command:: + + make SGX=1 + + The command will build enclaves for all the programs in the folder + + - Generate the token from aesmd service, via command:: + + make SGX_RUN=1 + + - Run Hello World program with Graphene on SGX:: + + SGX=1 ./pal_loader helloworld + + or:: + + ./pal_loader SGX helloworld + +2. Build and run python helloworld script in Graphene on SGX + + - go to LibOS/shim/test/apps/python, build the enclave:: + + make SGX=1 + + - Generate token:: + + make SGX_RUN=1 + + - Run python helloworld 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/ + +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 +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) + +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 and file systems to +be mounted. + +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 +documentation `_. + +Contact +======= + +For any questions or bug reports, please send an email to + or post an issue on our GitHub repository: +. + +Our mailing list is publicly archived `here +`_.