general/occlum
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README for version 0.7.0

Browse Source
This commit is contained in:
Tate, Hongliang Tian 2019-11-30 11:54:43 +00:00
parent ba3813bea8
commit 814ea21997
3 changed files with 39 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
README.md
View File

@ -1,6 +1,8 @@
# Occlum
[![All Contributors](https://img.shields.io/badge/all_contributors-7-orange.svg?style=flat-square)](CONTRIBUTORS.md)
**NEWS:** Our paper _Occlum: Secure and Efficient Multitasking Inside a Single Enclave of Intel SGX_ has been accepted by [ASPLOS'20](https://asplos-conference.org/). We will release a preprint version of the paper shortly.
Occlum is a *memory-safe*, *multi-process* library OS (LibOS) for [Intel SGX](https://software.intel.com/en-us/sgx). As a LibOS, it enables *legacy* applications to run on SGX with *little or even no modifications* of source code, thus protecting the confidentiality and integrity of user workloads transparently.
Occlum has the following salient features:
@ -20,11 +22,11 @@ Thanks to Occlum, you can be freed from writing any extra SGX-aware code and onl
**Step 1. Compile the user program with the Occlum toolchain (e.g., `occlum-gcc`)**
```
$ occlum-gcc -fPIC -pie -o hello_world hello_world.c
$ occlum-gcc -o hello_world hello_world.c
$ ./hello_world
Hello World
```
There are two things worth to mention. First, programs must be compiled as position-independent code (`-fPIC`) or executables (`-pie`) to be run on Occlum. Second, the Occlum toolchain is not cross-compiling, i.e., the binaries built by the Occlum toolchain is also runnable on Linux. This property makes it convenient to compile, debug, and test user programs intended for Occlum.
Note that the Occlum toolchain is not cross-compiling in the traditional sense: the binaries built by the Occlum toolchain is also runnable on Linux. This property makes it convenient to compile, debug, and test user programs intended for Occlum.
**Step 2. Initialize a directory as the Occlum context via `occlum init`**
```
@ -40,7 +42,7 @@ $ occlum build
```
The content of the `image` directory is initialized by the `occlum init` command. The structure of the `image` directory mimics that of an ordinary UNIX FS, containing directories like `/bin`, `/lib`, `/root`, `/tmp`, etc. After copying the user program `hello_world` into `image/bin/`, the `image` directory is packaged by the `occlum build` command to generate a secure Occlum FS image as well as the Occlum SGX enclave.
**Step 4. Run the user program inside an SGX enclave**
**Step 4. Run the user program inside an SGX enclave via `occlum run`**
```
$ occlum run /bin/hello_world
Hello World!
@ -49,20 +51,42 @@ The `occlum run` command starts up an Occlum SGX enclave, which, behind the scen
### Config Occlum
Occlum can be configured easily via a config file named `Occlum.json`, which is generated by the `occlum init` command in the Occlum context directory. The user can modify `Occlum.json` to config Occlum. The default content of `Occlum.json` is
```json
Occlum can be configured easily via a config file named `Occlum.json`, which is generated by the `occlum init` command in the Occlum context directory. The user can modify `Occlum.json` to config Occlum. A sample of `Occlum.json` is shown below. Some comments are added to provide a brief explanation.
```
{
// Virtual memory
"vm": {
// The size of memory available for use by LibOS processes
"user_space_size": "128MB"
},
// Process
"process": {
// The stack size of the "main" thread
"default_stack_size": "4MB",
// The max size of memory allocated by brk syscall
"default_heap_size": "16MB",
// The max size of memory by mmap syscall
"default_mmap_size": "32MB"
},
// Environment variables
//
// This gives a list of trusted environment variables for the "root"
// process started by `occlum run` command.
"env": [
"OCCLUM=yes"
],
// Entry points
//
// Entry points specify all valid path prefixes for <path> in `occlum run
// <path> <args>`. This prevents outside attackers from executing arbitrary
// commands inside an Occlum-powered enclave.
"entry_points": [
"/bin"
],
// Mount points and their file systems
//
// Limitation: configuring mount points by modifying this config file is not
// supported at the momement. The default configuration is shown below.
"mount": [
{
"target": "/",
@ -88,7 +112,6 @@ Occlum can be configured easily via a config file named `Occlum.json`, which is
]
}
```
(Limitation: the `mount` key should not be modified at the moment. We will support the configuration of mount points in future version.)
## How to Use
@ -102,7 +125,7 @@ Step 1-3 are to be done on the host OS (Linux):
3. Run the Occlum Docker container, which has Occlum and its demos preinstalled:
```
docker run -it --device /dev/isgx occlum/occlum:0.6.0
docker run -it --device /dev/isgx occlum/occlum:0.7.0
```
Step 4-5 are to be done on the guest OS running inside the Docker container:
@ -111,7 +134,7 @@ Step 4-5 are to be done on the guest OS running inside the Docker container:
```
cd /opt/intel/sgxsdk/SampleCode/SampleEnclave && make && ./app
```
5. Check out Occlum's demos preinstalled at `/root/occlum/demos`, whose README can be found [here](demos/README.md). Or you can try to build and run your own SGX-protected applications using Occlum as shown in the demos.
5. Check out Occlum's demos preinstalled at `/root/demos`, whose README can be found [here](demos/README.md). Or you can try to build and run your own SGX-protected applications using Occlum as shown in the demos.
## How to Build and Install
@ -139,6 +162,12 @@ To build Occlum from the latest source code, do the following steps in an Occlum
The Occlum Dockerfile can be found at [here](tools/docker/Dockerfile). Use it to build the container directly or read it to see the dependencies of Occlum.
## How to Build Occlum-Compatible Executable Binaries?
Occlum supports running any executable binaries that are 1) based on [musl libc](https://www.musl-libc.org/) and 2) position independent. We chose musl libc instead of Glibc since the codebase of musl libc is 10X smaller than Glibc, which means a much smaller Trusted Computing Base (TCB) and attack surface. We argue this is an important consideration for Occlum, which targets security-critical apps running inside SGX enclaves.
The two aforementioned requirements are not only satisfied by the Occlum toolchain, but also the native toolchains from some Linux distributions, e.g., [Alpine Linux](https://www.alpinelinux.org/). We think Alpine Linux, a popular Linux distribution that emphasizes simplicity and security, is a natural fit for Occlum. We will provide demos to run unmodified apps from [Alpine Linux packages](https://pkgs.alpinelinux.org/packages).
## What is the Implementation Status?
Occlum is being actively developed. We now focus on implementing more system calls and additional features required in the production environment.

2
src/libos/Cargo.lock generated
View File

@ -2,7 +2,7 @@
# It is not intended for manual editing.
[[package]]
name = "Occlum"
version = "0.6.0"
version = "0.7.0"
dependencies = [
"bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)",
"derive_builder 0.7.2 (registry+https://github.com/rust-lang/crates.io-index)",

2
src/libos/Cargo.toml
View File

@ -1,6 +1,6 @@
[package]
name = "Occlum"
version = "0.6.0"
version = "0.7.0"
[lib]
name = "occlum_rs"