From 814ea21997dfd982da0aa0d8dd869bfa806bc581 Mon Sep 17 00:00:00 2001 From: "Tate, Hongliang Tian" Date: Sat, 30 Nov 2019 11:54:43 +0000 Subject: [PATCH] Update README for version 0.7.0 --- README.md | 45 ++++++++++++++++++++++++++++++++++++-------- src/libos/Cargo.lock | 2 +- src/libos/Cargo.toml | 2 +- 3 files changed, 39 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 8fce6b74..9597b7d5 100644 --- a/README.md +++ b/README.md @@ -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 in `occlum run + // `. 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. diff --git a/src/libos/Cargo.lock b/src/libos/Cargo.lock index 6729fe0b..6c5f14d6 100644 --- a/src/libos/Cargo.lock +++ b/src/libos/Cargo.lock @@ -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)", diff --git a/src/libos/Cargo.toml b/src/libos/Cargo.toml index e8f7cb9b..20a1538d 100644 --- a/src/libos/Cargo.toml +++ b/src/libos/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "Occlum" -version = "0.6.0" +version = "0.7.0" [lib] name = "occlum_rs"