`inclavare-containers` is a set of tools for running trusted applications in containers with the hardware-assisted enclave technology. Enclave, referred to as a protected execution environment, prevents the untrusted entity from accessing the sensitive and confidential assets in use.
---
## Components
### rune
`rune` is a CLI tool for spawning and running enclaves in containers according to the OCI specification. The codebase of `rune` is a fork of [runc](https://github.com/opencontainers/runc), so `rune` can be used as `runc` if enclave is not configured or available.
...
...
@@ -29,10 +31,10 @@ sudo make install
`rune` will be installed to `/usr/local/sbin/rune` on your system.
### shim-rune
`shim-rune` resides in between `containerd` and `rune`, conducting enclave signing and management beyond the normal `shim` basis. `shim-rune` and `rune` can compose a basic enclave containerization stack for the cloud-native ecosystem.
`shim-rune` resides in between `containerd` and `rune`, conducting enclave signing and management beyond the normal `shim` basis. `shim-rune` and `rune` can compose a basic enclave containerization stack for the cloud-native ecosystem. Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/shim/README.md) for the details.
### enclave runtime
The backend of `rune` is a component called enclave runtime, which is responsible for loading and running protected applications inside enclaves. The interface between `rune` and enclave runtime is [Enclave Runtime PAL API](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/spec.md), which allows invoking enclave runtime through well-defined functions. The software for confidential computing may benefit from this interface to interact with OCI runtime.
The backend of `rune` is a component called enclave runtime, which is responsible for loading and running protected applications inside enclaves. The interface between `rune` and enclave runtime is [Enclave Runtime PAL API](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/spec_v2.md), which allows invoking enclave runtime through well-defined functions. The software for confidential computing may benefit from this interface to interact with OCI runtime.
One typical class of enclave runtime implementations is based on library OSes. Currently, the default enclave runtime interacting with `rune` is [Occlum](https://github.com/occlum/occlum), a memory-safe, multi-process library OS for Intel SGX.
...
...
@@ -45,14 +47,14 @@ In addition, you can write your own enclave runtime with any programming languag
## Using rune
### Run Occlum
Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum_bundle.md) to run `Occlum` with `rune`.
Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum.md) to run `Occlum` with `rune`.
### Run skeleton
Skeleton is an example of enclave runtime, interfacing with Enclave Runtime PAL API for easy interfacing with `rune`. Skeleton sample code is helpful to write your own enclave runtime.
Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/skeleton/README.md) to run skeleton with `rune`.
For more information about Enclave Runtime PAL API, please refer to [Enclave Runtime PAL API Specification](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/spec_v2.md).
### Run OCI bundle
Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum_bundle.md) to run `occlum bundle` with `rune`.
For more information about Enclave Runtime PAL API, please refer to [Enclave Runtime PAL API Specification](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/spec.md).
[rune](https://github.com/alibaba/inclavare-containers) is a new OCI runtime used to run trusted applications in containers with the hardware-assisted enclave technology.
[rune](https://github.com/alibaba/inclavare-containers) is a set of tools for running trusted applications in containers with the hardware-assisted enclave technology.
## Hardware requirements
## Requirements
- Install [Intel SGX driver for Linux](https://github.com/intel/linux-sgx-driver#build-and-install-the-intelr-sgx-driver), required by Intel SGX SDK && PSW.
- Install [enable_rdfsbase kernel module](https://github.com/occlum/enable_rdfsbase#how-to-build), allowing to use `rdfsbase` -family instructions in Occlum.
- Assume the host system is CentOS 7.5.
- You can also launch a CentOS 7.5 container as your host system with the following command:
```shell
```
If so, you need to run **another docker daemon** inside this CentOS 7.5 container. Please refer to [this guide](https://docs.docker.com/engine/install/centos) to install docker daemon, and type the following command to start dockerd.
```shell
dockerd -b docker0 --storage-driver=vfs &
```
---
## Build Occlum application Docker image
### Download Occlum sdk image
```shell
docker pull occlum/occlum:0.13.0-centos7.5
## Build Occlum application container image
### Download Occlum SDK container image
```shell
mkdir"$HOME/rune_workdir"
docker run -it--privileged--device /dev/isgx \
-v"$HOME/rune_workdir":/root/rune_workdir \
occlum/occlum:0.13.0-centos7.5
```
### Prepare the materials
Before Occlum build, execute the following command to set your Occlum instance dir:
``` shell
Before Occlum build, execute the following command to set your Occlum instance name:
```shell
export OCCLUM_INSTANCE_DIR=occlum-app
```
You can build a "hello world" demo application or your own product with an [Occlum CentOS Docker image](https://hub.docker.com/r/occlum/occlum/tags).
[This guide](https://github.com/occlum/occlum#hello-occlum) can help you to create your first occlum build.
After Occlum build, execute the following commands in Occlum sdk container environment:
Assuming "hello world" demo program is built, execute the following commands in Occlum SDK container:
Now you can build your occlum application image in the same Occlum sdk container environment.
You need to [download docker](https://docs.docker.com/engine/install/centos/) in the Occlum sdk container environment. And type the following command to start your docker service.
``` shell
dockerd -b docker0 --storage-driver=vfs &
```
### Prepare Occlum application image
Now you can build your occlum application image in the $HOME/rune_workdir directory of your host system.
Type the following commands to create a `Dockerfile`:
``` Dockerfile
cd "$HOME/rune_workdir"
cat >Dockerfile <<EOF
FROM centos:7.5.1804
...
...
@@ -53,6 +54,7 @@ RUN mkdir -p /run/rune/${OCCLUM_INSTANCE_DIR}
You can download rune centos binarys from 0.2.0 release, it includes
-`rune` : is a set of tools for running trusted applications in containers with the hardware-assisted enclave technology. You can install `rune` in `/usr/local/sbin` on your centos system.
-`liberpal-occlum.so` : is the path to occlum to launch. you can install it on `/usr/lib` on your centos system.
-`sgx_linux_x64_sdk_2.9.101.2.bin` : is a [SGX SDK](https://github.com/intel/linux-sgx#install-the-intelr-sgx-sdk-1) binary.
-`sgx_linux_x64_psw_2.9.101.2.bin` : is a [SGX PSW](https://github.com/intel/linux-sgx#install-the-intelr-sgx-psw) binary.
## Install Inclavare Containers binary
Download the binary release from [here](https://github.com/alibaba/inclavare-containers/releases/).
### Install `sgx_linux_x64_sdk_2.9.101.2.bin`
Type the following commands to Install `sgx_linux_x64_sdk_2.9.101.2.bin` on your centos system.
```shell
Type the following commands to install `sgx_linux_x64_sdk_2.9.101.2.bin` on your host system.
@@ -133,7 +134,6 @@ docker run -it --rm --runtime=rune \
```
where:
- @runtime: choose the runtime (`rune`, `runc`, or others) to use for this container.
- @ENCLAVE_TYPE: specify the type of enclave hardware to use, such as `intelSgx`.
- @ENCLAVE_PATH: specify the path to enclave runtime to launch. For an Occlum application, you need to specify the path of `liberpal-occlum.so` which is a soft link to `libocclum-pal.so` of your Occlum instance dir (`OCCLUM_INSTANCE_DIR`).
- @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, separated by the comma. For an Occlum application, you need to specify the name of your Occlum instance dir (`OCCLUM_INSTANCE_DIR`) in this parameter.
- @ENCLAVE_PATH: specify the path to enclave runtime to launch.
- @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, separated by the comma.
`rune` is a CLI tool for spawning and running enclaves in containers according to the OCI specification.
...
...
@@ -6,13 +7,13 @@ Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blo
---
## Build Occlum application docker image
Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum_bundle.md) to build the Occlum application Docker image.
## Build Occlum application container image
Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blob/master/docs/running_rune_with_occlum.md) to build the Occlum application container image.
## Create Occlum application bundle
In order to use `rune` you must have your container in the format of an OCI bundle. If you have Docker installed you can use its `export` method to acquire a root filesystem from an existing Occlum application Docker container.
In order to use `rune` you must have your container image in the format of an OCI bundle. If you have Docker installed you can use its `export` method to acquire a root filesystem from an existing Occlum application container image.
After a root filesystem is populated you just generate a spec in the format of a config.json file inside your bundle. `rune` provides a spec command which is similar to `runc` to generate a template file that you are then able to edit.
```shell
```shell
rune spec
```
...
...
@@ -56,12 +57,13 @@ where:
- @enclave.type: specify the type of enclave hardware to use, such as `intelSgx`.
- @enclave.runtime.path: specify the path to enclave runtime to launch. For an Occlum application, you need to specify the path of `liberpal-occlum.so` which is a soft link to `libocclum-pal.so` of your Occlum instance dir (`OCCLUM_INSTANCE_DIR`).
- @enclave.runtime.args: specify the specific arguments to enclave runtime, separated by the comma. For an Occlum application, you need to specify the name of your Occlum instance dir (`OCCLUM_INSTANCE_DIR`) in this parameter.
---
## Run Occlum application
Assuming you have an OCI bundle from the previous step you can execute the container in this way.
```shell
```shell
cd"$HOME/rune_workdir/rune-container"
sudo rune run ${Occlum_application_container_name}
- @runtime: choose the runtime (`rune`, `runc` or others) to use for this container.
- @ENCLAVE_TYPE: specify the type of enclave hardware to use, such as `intelSgx`.
- @ENCLAVE_PATH: specify the path to enclave runtime to launch.
- @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, seperated by the comma.
---
# Run skeleton OCI bundle
Note: The following method to launch skeleton with `rune` is usually provided for developmemt purpose.
## Create skeleton bundle
In order to use `rune` you must have your container in the format of an OCI bundle. If you have Docker installed you can use its `export` method to acquire a root filesystem from an existing skeleton Docker container.
In order to use `rune` you must have your container image in the format of an OCI bundle. If you have Docker installed you can use its `export` method to acquire a root filesystem from an existing skeleton Docker container image.
```shell
```shell
# create the top most bundle directory
cd"$HOME/rune_workdir"
mkdir rune-container
...
...
@@ -86,19 +98,19 @@ cd rune-container
mkdir rootfs
# export skeleton image via Docker into the rootfs directory
After a root filesystem is populated you just generate a spec in the format of a config.json file inside your bundle. `rune` provides a spec command which is similar to `runc` to generate a template file that you are then able to edit.
```shell
```shell
rune spec
```
To find features and documentation for fields in the spec please refer to the [specs](https://github.com/opencontainers/runtime-spec) repository.
In order to run the skeleton bundle with `rune`, you need to configure enclave runtime as following:
| **Parameters** | @args: the enclave runtime specific argument string.<br/>@log_level: the output log level of enclave runtime. |
| **Return value** | 0: Success<br/>-ENOENT: Invalid instance path of enclave runtime<br/>Others: Enclave runtime specific error codes |
| **Availability **| >=v1 |
## pal_exec()
| **Description** | Pass the path of the application to be executed, and synchronously wait for the end of the application to run and return the result. |
...
...
@@ -15,7 +14,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | struct pal_stdio_fds {<br/> int stdin, stdout, stderr;<br/>};<br/>int pal_exec(char \*path, char \*argv[],<br/> struct pal_stdio_fds \*stdio,<br/> int \*exit_code); |
| **Parameters** | @path: The path of the application to be run<br/>@argv: The array of argument strings passed to the application, terminated by a NULL pointer<br/>@stdio: The stdio fds consumed by the application<br/>@exit_code: Return the exit code of an application |
| **Return value** | 0: success<br/>-ENOENT: The path does not exist<br/>-EACCES: Permission denied<br/>-ENOEXEC: The path is not an executable file<br=/>-ENOMEM: <br/>-EINVAL: Invalid argument |
| **Availability **| >=v1 |
## pal_destroy()
| **Description** | Destroy the enclave runtime instance |
...
...
@@ -23,4 +21,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | int pal_destroy(); |
| **Parameters** | N/A |
| **Return value** | 0: Success<br/>-ENOSYS: The function is not supported |
| **Parameters** | @path: The path of the binary file to be run (relative path in the libos file system).<br />@argv: Binary parameters, ending with a null element.<br />@env: Binary environment variables, ending with a null element.<br />@stdio: The fd of stdio.<br />@pid: If the function return value is 0, pid stores the pid of the new process in libos. |
| **Return value** | 0: Success<br/>-EINVAL: Invalid argument<br/>-ENOSYS: The function is not supported |
| **Availability ** | >=v2 |
## 4. pal_exec
| **Description** | Execute the program corresponding to pid. |
...
...
@@ -37,7 +34,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | int pal_kill(int pid, int sig); |
| **Parameters** | @pid: Send to all processes if equal to -1, or send to current process if equal to 0, or send to the process that owns the pid if others. <br/>@sig: Signal number to be sent |
| **Return value** | 0: Success<br/>-EINVAL: Invalid argument<br/>-ENOSYS: The function is not supported |
| **Availability ** | >=v2 |
## 6.pal_destroy()
| **Description** | Destroy libos instance. |
...
...
@@ -45,4 +41,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | int pal_destroy(); |
| **Parameters** | NA. |
| **Return value** | 0: Success<br/>-ENOSYS: The function is not supported |
Jia Zhang <zhang.jia@linux.alibaba.com>