`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.
`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
## Components
### rune
### 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.
`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
...
@@ -29,10 +31,10 @@ sudo make install
`rune` will be installed to `/usr/local/sbin/rune` on your system.
`rune` will be installed to `/usr/local/sbin/rune` on your system.
### shim-rune
### 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
### 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.
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
...
@@ -45,14 +47,14 @@ In addition, you can write your own enclave runtime with any programming languag
## Using rune
## Using rune
### Run Occlum
### 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
### 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.
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`.
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
### 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`.
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.
## Requirements
## Hardware 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 [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.
- 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
## Build Occlum application container image
### Download Occlum sdk image
### Download Occlum SDK container image
```shell
```shell
docker pull occlum/occlum:0.13.0-centos7.5
mkdir"$HOME/rune_workdir"
docker run -it--privileged--device /dev/isgx \
docker run -it--privileged--device /dev/isgx \
-v"$HOME/rune_workdir":/root/rune_workdir \
occlum/occlum:0.13.0-centos7.5
occlum/occlum:0.13.0-centos7.5
```
```
### Prepare the materials
### Prepare the materials
Before Occlum build, execute the following command to set your Occlum instance dir:
Before Occlum build, execute the following command to set your Occlum instance name:
``` shell
```shell
export OCCLUM_INSTANCE_DIR=occlum-app
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.
[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.
Now you can build your occlum application image in the $HOME/rune_workdir directory of your host system.
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 &
```
Type the following commands to create a `Dockerfile`:
Type the following commands to create a `Dockerfile`:
``` Dockerfile
``` Dockerfile
cd "$HOME/rune_workdir"
cat >Dockerfile <<EOF
cat >Dockerfile <<EOF
FROM centos:7.5.1804
FROM centos:7.5.1804
...
@@ -53,6 +54,7 @@ RUN mkdir -p /run/rune/${OCCLUM_INSTANCE_DIR}
...
@@ -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
Download the binary release from [here](https://github.com/alibaba/inclavare-containers/releases/).
-`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 `sgx_linux_x64_sdk_2.9.101.2.bin`
### 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.
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 \
...
@@ -133,7 +134,6 @@ docker run -it --rm --runtime=rune \
```
```
where:
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_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_PATH: specify the path to enclave runtime to launch.
- @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_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.
`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
...
@@ -6,13 +7,13 @@ Please refer to [this guide](https://github.com/alibaba/inclavare-containers/blo
---
---
## Build 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_bundle.md) to build the Occlum application Docker 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
## 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.
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
rune spec
```
```
...
@@ -56,12 +57,13 @@ where:
...
@@ -56,12 +57,13 @@ where:
- @enclave.type: specify the type of enclave hardware to use, such as `intelSgx`.
- @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.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.
- @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
## Run Occlum application
Assuming you have an OCI bundle from the previous step you can execute the container in this way.
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"
cd"$HOME/rune_workdir/rune-container"
sudo rune run ${Occlum_application_container_name}
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_TYPE: specify the type of enclave hardware to use, such as `intelSgx`.
- @ENCLAVE_PATH: specify the path to enclave runtime to launch.
- @ENCLAVE_PATH: specify the path to enclave runtime to launch.
- @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, seperated by the comma.
- @ENCLAVE_ARGS: specify the specific arguments to enclave runtime, seperated by the comma.
---
# Run skeleton OCI bundle
# Run skeleton OCI bundle
Note: The following method to launch skeleton with `rune` is usually provided for developmemt purpose.
## Create skeleton bundle
## 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
# create the top most bundle directory
cd"$HOME/rune_workdir"
cd"$HOME/rune_workdir"
mkdir rune-container
mkdir rune-container
...
@@ -86,19 +98,19 @@ cd rune-container
...
@@ -86,19 +98,19 @@ cd rune-container
mkdir rootfs
mkdir rootfs
# export skeleton image via Docker into the rootfs directory
# 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.
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
rune spec
```
```
To find features and documentation for fields in the spec please refer to the [specs](https://github.com/opencontainers/runtime-spec) repository.
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:
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. |
| **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 |
| **Return value** | 0: Success<br/>-ENOENT: Invalid instance path of enclave runtime<br/>Others: Enclave runtime specific error codes |
| **Availability **| >=v1 |
## pal_exec()
## 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. |
| **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
...
@@ -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); |
| **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 |
| **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 |
| **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()
## pal_destroy()
| **Description** | Destroy the enclave runtime instance |
| **Description** | Destroy the enclave runtime instance |
...
@@ -23,4 +21,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
...
@@ -23,4 +21,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | int pal_destroy(); |
| **Prototype** | int pal_destroy(); |
| **Parameters** | N/A |
| **Parameters** | N/A |
| **Return value** | 0: Success<br/>-ENOSYS: The function is not supported |
| **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. |
| **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 |
| **Return value** | 0: Success<br/>-EINVAL: Invalid argument<br/>-ENOSYS: The function is not supported |
| **Availability ** | >=v2 |
## 4. pal_exec
## 4. pal_exec
| **Description** | Execute the program corresponding to pid. |
| **Description** | Execute the program corresponding to pid. |
...
@@ -37,7 +34,6 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
...
@@ -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); |
| **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 |
| **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 |
| **Return value** | 0: Success<br/>-EINVAL: Invalid argument<br/>-ENOSYS: The function is not supported |
| **Availability ** | >=v2 |
## 6.pal_destroy()
## 6.pal_destroy()
| **Description** | Destroy libos instance. |
| **Description** | Destroy libos instance. |
...
@@ -45,4 +41,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
...
@@ -45,4 +41,3 @@ Enclave Runtime PAL API defines a common interface to interact between `rune` an
| **Prototype** | int pal_destroy(); |
| **Prototype** | int pal_destroy(); |
| **Parameters** | NA. |
| **Parameters** | NA. |
| **Return value** | 0: Success<br/>-ENOSYS: The function is not supported |
| **Return value** | 0: Success<br/>-ENOSYS: The function is not supported |