gnh1201/wasm-micro-runtime
1
0
Fork 0
mirror of https://github.com/bytecodealliance/wasm-micro-runtime.git synced 2025-03-12 00:45:28 +00:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

Enhance the readability of WAMR SGX docs (#442)

Browse Source 
The global doc/linux_sgx.md needs to explicitly describe the methods to
build a debug enclave and hardware running mode. Because using debug key
to signing enclave image rather than production key is still not trivial
in reality.

For the adaption of Inclavare Containers part, add a prolog and give
more details in order to enhance the readability.

Signed-off-by: Jia Zhang <zhang.jia@linux.alibaba.com>
This commit is contained in:
Jia Zhang 2020-11-13 13:11:34 +08:00 committed by GitHub
parent 8f4a1963fc
commit a2641e174a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 44 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/linux_sgx.md
View File

@ -17,8 +17,6 @@ cmake ..
make
```
**Note:** By default, the generated SGX application assumes it is signed with production key and running on simulation mode. In order to build a debug enclave on hardware-based SGX platform, execute `make SGX_DEBUG=1 SGX_MODE=HW` instead.
This builds two libraries required by SGX application:
- libvmlib.a for Enclave part
- libvmlib_untrusted.a for App part
@ -32,6 +30,8 @@ cd enclave-sample
make
```
**Note:** By default, the generated SGX application assumes it is signed with production key and running on simulation mode. The user can explicitly specify the relative variables in commandline to overwrite the default settings. For example, to build a debug enclave, please build the enclave with `make SGX_DEBUG=1`. To build the enclave running on a hardware-based SGX platform, execute `make SGX_MODE=HW`.
The binary file iwasm will be generated. To run the sample:
``` Bash

67
product-mini/platforms/linux-sgx/enclave-sample/App/README.md
View File

@ -1,53 +1,48 @@
# WAMR as an Enclave Runtime for Rune
# Running WAMR as an [Enclave Runtime](https://github.com/alibaba/inclavare-containers/blob/master/docs/design/terminology.md#enclave-runtime) for [Inclavare Containers](https://github.com/alibaba/inclavare-containers)
## Build WAMR vmcore (iwasm) for Linux-SGX
In order to establish with `rune`, a novel OCI Runtime for spawning and running enclaves in containers, it is required to implement an [enclave runtime PAL](https://github.com/alibaba/inclavare-containers/blob/master/docs/design/terminology.md#enclave-runtime-pal) to make the communications with WAMR.
Please follow [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/linux_sgx.md#build-wamr-vmcore-iwasm-for-linux-sgx) to build iwasm as the prerequisite.
With the assist of `rune`, WAMR is brought to the cloud-native ecosystem beyond the basis. This is the so-called term "WAMR enclave runtime".
Then build enclave image and sign it:
This guide will provide the information about the build, integration and deployment for WAMR enclave runtime. Eventually, the resulting docker image will be launched by `rune`, and the WARM application as the entrypoint of docker image will run in Intel SGX enclave with the hardware-enforced isolation and cryptographically data protection.
```shell
cd enclave-sample
make
/opt/intel/sgxsdk/bin/x64/sgx_sign sign -key Enclave/Enclave_private.pem -enclave enclave.so -out enclave.signed.so -config Enclave/Enclave.config.xml
```
## Build WAMR vmcore (iwasm) and enclave image
The generated enclave.signed.so is required by PAL.
Please follow [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/linux_sgx.md#build-wamr-vmcore-iwasm-for-linux-sgx) to build iwasm and enclave image as the prerequisite.
The generated enclave image enclave.signed.so will be consumed by WAMR enclave runtime mentioned below.
---
## Build PAL dynamically linked shared object
To build WAMR as an Enclave Runtime for [Inclavare Containers](https://github.com/alibaba/inclavare-containers), we should implement the [PAL API v2](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/spec_v2.md) in WAMR for rune to call the PAL to create the enclave with WAMR and run applications.
## Build and install the PAL of WAMR enclave runtime
```shell
g++ -shared -fPIC -o libwamr-pal.so App/*.o libvmlib_untrusted.a -L/opt/intel/sgxsdk/lib64 -lsgx_urts -lpthread -lssl -lcrypto
cp ./libwamr-pal.so /usr/lib/libwamr-pal.so
```
Note: Assuming `/opt/intel/sgxsdk/` is where you installed the SGX SDK.
---
## Build WAMR application
To Build a WAMR application, please refer to [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/build_wasm_app.md#build-wasm-applications)
To run a WAMR application with Intel SGX enclave by `rune`, please refer to [this guide](https://github.com/bytecodealliance/wasm-micro-runtime#build-wamrc-aot-compiler) to generate wamrc AoT compiler, and then refer to [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/build_wasm_app.md#compile-wasm-to-aot-module) to compile the `.wasm` file to `.aot` file.
Note: the AoT file must be generated using --size-level=1 to set a bigger code size, e.g,
As the prerequisite, please
- refer to [this step](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/build_wasm_app.md#prepare-wasm-building-environments) to install wasi-sdk. Note that the binaries of wasi-sdk must be installed at `/opt/wasi-sdk/bin/`.
- refer to [this guide](https://github.com/bytecodealliance/wasm-micro-runtime#build-wamrc-aot-compiler) to generate wamrc AoT compiler.
The sample WAMR application test.c is provided in [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/build_wasm_app.md#build-wasm-applications). Don't forget to compile the `.wasm` file to `.aot` file:
```shell
wamrc --size-level=1 -o test.aot test.wasm
wamrc -sgx -o test.aot test.wasm
```
The generated test.aot is the WAMR application launched by WAMR enclave runtime.
---
## Build WAMR docker image
Under the `enclave-sample` directory, to create the WAMR docker images to load the `enclave.signed.so` and target application wasm files, please type the following commands to create a `Dockerfile`:
For centos:
For CentOS:
```shell
cat >Dockerfile <<EOF
@ -57,9 +52,9 @@ RUN mkdir -p /run/rune
WORKDIR /run/rune
COPY enclave.signed.so .
COPY ${wasm_app.aot} .
#COPY ${wasm_app2.aot} .
#...
COPY test.aot app
#COPY ${wasm_app.aot} .
ENTRYPOINT ["/run/rune/app"]
EOF
```
@ -73,23 +68,23 @@ RUN mkdir -p /run/rune
WORKDIR /run/rune
COPY enclave.signed.so .
COPY ${wasm_app.aot} .
COPY test.aot app
#COPY ${wasm_app.aot} .
#...
ENTRYPOINT ["/run/rune/app"]
EOF
```
where `${wasm_app.aot}` files are the other applications you want to run in WAMR.
where `${wasm_app.aot}` files are the extra WAMR applications you want to run.
Then build the WAMR docker image with the command:
```shell
docker build . -t wamr-app
docker build . -t wamr-sgx-app
```
---
## Run WAMR SGX with Docker and OCI Runtime rune
## Deploy WAMR SGX Docker image
The following guide provides the steps to run WAMR with Docker and OCI Runtime `rune`.
@ -112,11 +107,11 @@ The following guide provides the steps to run WAMR with Docker and OCI Runtime `
- The simplest way to install `rune` is to download a pre-built binary from [Inclavare Containers release page](https://github.com/alibaba/inclavare-containers/releases).
### Configuring OCI Runtime rune for Docker
### Integrate OCI Runtime rune with Docker
Add the assocated configuration for `rune` in dockerd config file, e.g, `/etc/docker/daemon.json`, on your system.
Add the associated configuration for `rune` in dockerd config file, e.g, `/etc/docker/daemon.json`, on your system.
```
```json
{
"runtimes": {
"rune": {
@ -141,7 +136,7 @@ The expected result would be:
Runtimes: rune runc
```
### Run WAMR docker image
### Run WAMR SGX docker image
You need to specify a set of parameters to `docker run` to run:
@ -150,7 +145,7 @@ docker run -it --rm --runtime=rune \
-e ENCLAVE_TYPE=intelSgx \
-e ENCLAVE_RUNTIME_PATH=/usr/lib/libwamr-pal.so \
-e ENCLAVE_RUNTIME_ARGS=debug \
wamr-app /run/rune/${wasm_app.aot}
wamr-sgx-app
```
where:
@ -161,6 +156,6 @@ where:
---
## (Optional) Run WAMR bundle for rune
## Develop and debug WAMR enclave runtime with rune
Please refer to [this guide](https://github.com/leyao-daily/wasm-micro-runtime/blob/main/product-mini/platforms/linux-sgx/enclave-sample/App/wamr-bundle.md). This is optional, and suits for the developer in most cases.

23
product-mini/platforms/linux-sgx/enclave-sample/App/wamr-bundle.md
View File

@ -1,15 +1,15 @@
# Run WAMR bundle for Rune
# Run WAMR enclave runtime with bundle
## Create WAMR Application bundle
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 WAMR application container image.
`rune` can directly launch an OCI bundle converted from docker image. If you have Docker installed you can use its `export` sub-command to acquire a root filesystem from an existing WAMR application docker image.
```shell
# create the top most bundle directory
mkdir -p "$HOME/rune_workdir"
cd "$HOME/rune_workdir"
mkdir rune-container
cd rune-container
mkdir wamr-sgx-bundle
cd warmr-sgx-bundle
# create the rootfs directory
mkdir rootfs
@ -26,23 +26,23 @@ 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 target applications in WAMR with `rune`, you need to change the entrypoint from `sh` to `/run/rune/${wasm_app1.wasm}`, and in order to run multi-applications in one runtime with enclave, change it to `/run/rune/${wasm_app1.aot}`, `/run/rune/${wasm_app2.aot}` ...
In order to run the target application in WAMR with `rune`, you need to change the entrypoint from `sh` to the target application, and in order to run multi-applications in one runtime with enclave, change it to `/run/rune/${wasm_app1.aot}`, `/run/rune/${wasm_app2.aot}` ...
```yaml
```json
"process": {
"args": [
"/run/rune/demo.aot"
"/run/rune/${wasm_app}"
],
}
```
and then configure enclave runtime as following:
```yaml
```json
"annotations": {
"enclave.type": "intelSgx",
"enclave.runtime.path": "/usr/lib/libwamr-pal.so",
"enclave.runtime.args": "./"
"enclave.runtime.args": "debug"
}
```
@ -59,7 +59,6 @@ where:
Assuming you have an OCI bundle from the previous step you can execute the container in this way.
```shell
cd "$HOME/rune_workdir/rune-container"
sudo rune run ${wamr_application_container_name}
cd "$HOME/rune_workdir/wamr-sgx-bundle"
sudo rune run wamr-sgx-app
```