mirror of
https://github.com/clearlinux/graphene.git
synced 2026-08-22 05:56:23 +00:00
[Doc] Add Documentation/ stub
This commit is contained in:
Wojtek Porczyk
@@ -0,0 +1 @@
|
||||
_build
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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))
|
||||
@@ -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.
|
||||
@@ -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 <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
|
||||
@@ -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`
|
||||
@@ -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
|
||||
@@ -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 <SGX>`
|
||||
For an equivalent.
|
||||
|
||||
Environment variables
|
||||
=====================
|
||||
|
||||
.. envvar:: SGX
|
||||
|
||||
If not empty and not ``0``, enable :term:`SGX`. Could be used instead of
|
||||
:option:`SGX option <SGX>`. 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`.
|
||||
@@ -0,0 +1,2 @@
|
||||
breathe
|
||||
recommonmark
|
||||
@@ -14,8 +14,8 @@
|
||||
You should have received a copy of the GNU Lesser General Public License
|
||||
along with this program. If not, see <http://www.gnu.org/licenses/>. */
|
||||
|
||||
/*
|
||||
* 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;
|
||||
|
||||
@@ -1,217 +0,0 @@
|
||||
|
||||
# Graphene Library OS with Intel:registered: SGX Support
|
||||
|
||||
|
||||
|
||||
|
||||
*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:
|
||||
|
||||
- <https://github.com/01org/linux-sgx>
|
||||
- <https://github.com/01org/linux-sgx-driver>
|
||||
|
||||
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: <https://github.com/oscarlab/graphene/wiki>.
|
||||
|
||||
|
||||
|
||||
## 4. CONTACT
|
||||
|
||||
For any questions or bug reports, please send an email to <support@graphene-project.io> or post an
|
||||
issue on our GitHub repository: <https://github.com/oscarlab/graphene/issues>.
|
||||
|
||||
Our mailing list is publicly archived [here](https://groups.google.com/forum/#!forum/graphene-support).
|
||||
+250
@@ -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:
|
||||
|
||||
- <https://github.com/01org/linux-sgx>
|
||||
- <https://github.com/01org/linux-sgx-driver>
|
||||
|
||||
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 <https://graphene.rtfd.io/>`_.
|
||||
|
||||
Contact
|
||||
=======
|
||||
|
||||
For any questions or bug reports, please send an email to
|
||||
<support@graphene-project.io> or post an issue on our GitHub repository:
|
||||
<https://github.com/oscarlab/graphene/issues>.
|
||||
|
||||
Our mailing list is publicly archived `here
|
||||
<https://groups.google.com/forum/#!forum/graphene-support>`_.
|
||||
Reference in New Issue
Block a user