Update README for version 0.7.0

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
+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.
-```json
+```
 {
+    // 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.

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)",

src/libos/Cargo.toml

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