Skip to content

Commit

Permalink
README.md: a better readme
Browse files Browse the repository at this point in the history 
Signed-off-by: Kun Lai <me@imlk.top>
  • Loading branch information
@imlk0
imlk0 committed Mar 26, 2024
1 parent 4bdbd20 commit 683d58b
Showing 1 changed file with 239 additions and 99 deletions.
338 changes: 239 additions & 99 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,137 +1,277 @@
# Building

## Build Requirements

- git
- make
- autoconf
- libtool
- libcurl
- gcc
- g++
- openssl-devel / libssl-dev
- cargo (only needed in host mode)
- python, bzip2 (only needed in wasm mode)
- SGX driver, Intel SGX SDK & PSW: Please refer to this [guide](https://download.01.org/intel-sgx/sgx-linux/2.18/docs/Intel_SGX_SW_Installation_Guide_for_Linux.pdf) to install.
- Requires Intel SGX SDK and PSW version >= 2.18
- [SGX DCAP](https://github.com/intel/SGXDataCenterAttestationPrimitives): please download and install the packages from this [page](https://download.01.org/intel-sgx/sgx-dcap/#version#linux/distro).
- ubuntu 18.04: `libsgx-dcap-quote-verify-dev`, `libsgx-dcap-ql-dev`, `libsgx-uae-service`
- Requires Intel DCAP version >= 1.15
- For TDX, please see the README in TDX MVP Stack. You need to download the packages and following TDX_E2E_attestation_software_stack_Installation_README-dcap-2021XXXX.txt to do step 2 & step 3 to setup build and dependence libraries.
# librats
![](../../actions/workflows/pr_basic_compilation_check.yml/badge.svg)

## Build and Install
<!-- TODO: add a License badge -->

Please follow the command to build librats from the latested source code on your system.
[librats](https://github.com/inclavare-containers/librats) is a C library designed to facilitate remote attestation for secure computing environments. It provides a framework for attesting the integrity of computing environments remotely, enabling trust establishment between different Trusted Execution Environments (TEEs).

1. Download the latest source code of librats

```shell
mkdir -p "$WORKSPACE"
cd "$WORKSPACE"
git clone https://github.com/inclavare-containers/librats
```
## How to start ?

2. Build and install librats
We currently provide a sample app that uses librats named `cert-app`, which you can take a look at [here](samples/cert-app/README.md).

```shell
cd librats
cmake -DBUILD_SAMPLES=on -H. -Bbuild
make -C build install
```
Also, for the functions exposed by librats, see the [include/librats/api.h](include/librats/api.h) file.

`cert-app` will be installed to `/usr/share/librats/samples/cert-app` on your system. All instances are placed in `/usr/local/lib/librats/`.

If you want to build instances related to sgx(sgx\_ecdsa, sgx\_ecdsa\_qve, sgx\_la), please type the following command.
## Build from source

```shell
cmake -DRATS_BUILD_MODE="sgx" -DBUILD_SAMPLES=on -H. -Bbuild
make -C build install
```
We are currently not providing a pre-built version of librats, and you have to manual compilation from the source. And we use cmake to build this project, which makes it easy to integrate.

If you want to run instances on libos occlum, please type the following command.
### Build Requirements Installation

```shell
cmake -DRATS_BUILD_MODE="occlum" -DBUILD_SAMPLES=on -H. -Bbuild
make -C build install
```
#### Use docker image

If you want to run TDX instances, please type the following command.
```shell
cmake -DRATS_BUILD_MODE="tdx" -DBUILD_SAMPLES=on -H. -Bbuild
make -C build install
```
We've provided [docker images](https://hub.docker.com/r/runetest/compilation-testing/tags) of the librats build environment, which includes all the packages that need to be installed for building librats.

Note that [SGX LVI mitigation](https://software.intel.com/security-software-guidance/advisory-guidance/load-value-injection) is enabled by default. You can set macro `SGX_LVI_MITIGATION` to `0` to disable SGX LVI mitigation.
- `runetest/compilation-testing:anolis8.6`
- `runetest/compilation-testing:ubuntu20.04`

3. Wasm support

Librats provides support for [WebAssembly](https://webassembly.org), which enables it to run in the browser and [WAMR](https://github.com/bytecodealliance/wasm-micro-runtime).
#### Install manually

If you want to run it in browser, please read [this document](wasm/emscripten/README.md).
- This project has been tested on the following platforms, it should also work on similar distributions.

If you want to run it in WAMR, please type the following command.
```shell
# install librats in host mode first
cmake -H. -Bbuild
make -C build install
- Anolis OS 8.6 64bits
- Ubuntu 22.04 LTS Server 64bits

- Install some necessary packages

- On Anolis 8.6
```sh
dnf install -y --nogpgcheck epel-release
dnf --enablerepo=PowerTools install -y git wget \
make cmake autoconf libtool gcc gcc-c++ \
openssl-devel libcurl-devel dnf-utils patch \
libcbor-devel
```

- On Ubuntu 22.04
```sh
echo "deb http://cz.archive.ubuntu.com/ubuntu bionic main" >> /etc/apt/sources.list
apt-get update
apt-get install -y libprotobuf10
apt-get install -y make git vim clang-format-9 gcc \
pkg-config protobuf-compiler debhelper cmake \
wget net-tools curl file gnupg tree libcurl4-openssl-dev \
libbinutils libseccomp-dev libssl-dev binutils-dev libprotoc-dev \
libcbor-dev
```
- Install the Rust toolchain, which is needed by some dependencies of this project. You can install it by following the instructions at this [link](https://www.rust-lang.org/tools/install).

- (For SGX enclave) You may need to install the LVI mitigated toolchain to mitigate the Load Value Injection attack vulnerability of Intel SGX. For more infomation, see this [link](https://github.com/intel/linux-sgx).

- On Anolis 8.6
```sh
SGX_SDK_VERSION=2.23
wget https://download.01.org/intel-sgx/sgx-linux/$SGX_SDK_VERSION/as.ld.objdump.r4.tar.gz && \
tar -zxvf as.ld.objdump.r4.tar.gz && cp -rf external/toolset/anolis8.6/* /usr/local/bin/ && \
rm -rf external && rm -rf as.ld.objdump.r4.tar.gz
```

- On Ubuntu 22.04
```sh
SGX_SDK_VERSION=2.23
wget https://download.01.org/intel-sgx/sgx-linux/$SGX_SDK_VERSION/as.ld.objdump.r4.tar.gz && \
tar -zxvf as.ld.objdump.r4.tar.gz && cp -rf external/toolset/ubuntu20.04/* /usr/local/bin/ && \
rm -rf external && rm -rf as.ld.objdump.r4.tar.gz
```

- Install SGX SDK using the following steps, or refer to the "Intel® SGX Application Developer" section of this [guide](https://download.01.org/intel-sgx/sgx-linux/2.23/docs/Intel_SGX_SW_Installation_Guide_for_Linux.pdf) for installation instructions.
> Note: Requires Intel SGX SDK version >= 2.23
# export librats APIs to wamr
cd wasm/wamr
cmake -H. -Bbuild
make -C build
- On Anolis 8.6
```sh
SGX_SDK_VERSION=2.23
SGX_SDK_RELEASE_NUMBER=2.23.100.2
wget https://download.01.org/intel-sgx/sgx-linux/$SGX_SDK_VERSION/distro/Anolis86/sgx_linux_x64_sdk_$SGX_SDK_RELEASE_NUMBER.bin && \
chmod +x sgx_linux_x64_sdk_$SGX_SDK_RELEASE_NUMBER.bin && \
echo -e 'n\n\/opt/intel\n' | ./sgx_linux_x64_sdk_$SGX_SDK_RELEASE_NUMBER.bin
```

- On Ubuntu 22.04
```sh
SGX_SDK_VERSION=2.23
SGX_SDK_RELEASE_NUMBER=2.23.100.2
wget https://download.01.org/intel-sgx/sgx-linux/$SGX_SDK_VERSION/distro/ubuntu20.04-server/sgx_linux_x64_sdk_$SGX_SDK_RELEASE_NUMBER.bin && \
chmod +x sgx_linux_x64_sdk_$SGX_SDK_RELEASE_NUMBER.bin && \
echo -e 'no\n/opt/intel\n' | ./sgx_linux_x64_sdk_$SGX_SDK_RELEASE_NUMBER.bin
```

- Install SGX DCAP using the following steps, or refer to the "Intel® SGX Application User" section of this [guide](https://download.01.org/intel-sgx/sgx-linux/2.23/docs/Intel_SGX_SW_Installation_Guide_for_Linux.pdf) for installation instructions.
> Note: Requires Intel DCAP version >= 1.20
# run the sample
cd build
./iwasm --native-lib=librats_wamr.so sample/test.wasm
```

# RUN
- On Anolis 8.6

Right now, Librats supports the following instance types:
a. Add repository to package manager of your distro.
```sh
SGX_SDK_VERSION=2.23
wget https://download.01.org/intel-sgx/sgx-linux/$SGX_SDK_VERSION/distro/Anolis86/sgx_rpm_local_repo.tgz && \
tar zxvf sgx_rpm_local_repo.tgz && \
dnf config-manager --add-repo sgx_rpm_local_repo
dnf makecache
```

b. Install DCAP related packages.
```sh
SGX_SDK_VERSION=2.23
SGX_DCAP_VERSION=1.20
dnf install --nogpgcheck -y libsgx-headers-"$SGX_SDK_VERSION*" \
libsgx-dcap-quote-verify-devel-"$SGX_DCAP_VERSION*" \
libsgx-dcap-ql-devel-"$SGX_DCAP_VERSION*" \
libsgx-dcap-default-qpl-"$SGX_DCAP_VERSION*"
```

- On Ubuntu 22.04

a. Add repository to package manager of your distro.
```sh
echo "deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu focal main" | tee /etc/apt/sources.list.d/intel-sgx.list && \
wget -qO - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | apt-key add -
apt-get update -y
```

b. Install DCAP related packages.
```sh
SGX_SDK_VERSION=2.23
SGX_DCAP_VERSION=1.20
apt-get install -y libsgx-headers="$SGX_SDK_VERSION*" \
libsgx-dcap-quote-verify-dev="$SGX_DCAP_VERSION*" \
libsgx-dcap-ql-dev="$SGX_DCAP_VERSION*" \
libsgx-dcap-default-qpl="$SGX_DCAP_VERSION*"
```

- (For TDX attester) Install the TDX Attestation library
- On Anolis 8.6
```sh
SGX_DCAP_VERSION=1.20
dnf install --nogpgcheck -y libtdx-attest-devel-"$SGX_DCAP_VERSION*"
```

- On Ubuntu 22.04
```sh
SGX_DCAP_VERSION=1.20
apt-get install -y libtdx-attest-dev="$SGX_DCAP_VERSION*"
```

### Build and Install librats

Please follow the command to build librats from the latested source code on your system.

1. Download the latest source code of librats
```shell
mkdir -p "$WORKSPACE"
cd "$WORKSPACE"
git clone https://github.com/inclavare-containers/librats
```

2. Build and install librats

> Note that [SGX LVI mitigation](https://software.intel.com/security-software-guidance/advisory-guidance/load-value-injection) is enabled by default. You can set macro `SGX_LVI_MITIGATION` to `0` to disable SGX LVI mitigation.
> Note: If you have the SGX SDK installed in a path other than the default path `/opt/intel`, please specify it using `-DSGX_SDK=<path-to-sdk>`.
- If you want to build instances related to sgx(sgx\_ecdsa, sgx\_ecdsa\_qve, sgx\_la), please type the following command.

```shell
cmake -DRATS_BUILD_MODE="sgx" -H. -Bbuild
make -C build install
```

- If you want to run instances on libos occlum, please type the following command.

```shell
cmake -DRATS_BUILD_MODE="occlum" -H. -Bbuild
make -C build install
```

- If you want to run TDX instances, please type the following command.
```shell
cmake -DRATS_BUILD_MODE="tdx" -H. -Bbuild
make -C build install
```

- If you want to run instances on AMD SEV/SEV-ES/SEV-SNP, CSV or non-TEE host, please type the following command.
```shell
cmake -DRATS_BUILD_MODE="host" -H. -Bbuild
make -C build install
```

| Priority | Attester instances | Verifier instances |
| ---------- | -------------------------- | -------------------------- |
| 0 | nullattester | nullverifier |
| 15 | sgx\_la | sgx\_la |
| 20 | csv | csv |
| 35 | sev | sev |
| 42 | sev\_snp | sev\_snp |
| 42 | tdx\_ecdsa | tdx\_ecdsa |
| 52 | sgx\_ecdsa | sgx\_ecdsa |
| 53 | sgx\_ecdsa | sgx\_ecdsa\_qve |
3. Build and install librats sample apps

For instance priority, the higher, the stronger. By default, Librats will select the **highest priority** instance to use.
You can just set `-DBUILD_SAMPLES=on` for also building samples of librats.

The sample app `cert-app` will be installed to `/usr/share/librats/samples/cert-app` on your system. All instances are placed in `/usr/local/lib/librats/`.

**Notice: special prerequisites for TDX remote attestation in bios configuration and hardware capability.**
4. Wasm support

Check msr 0x503, return value must be 0:
```
sudo rdmsr 0x503s
```
librats provides support for [WebAssembly](https://webassembly.org), which enables it to run in the browser and [WAMR](https://github.com/bytecodealliance/wasm-micro-runtime).

Note that if you want to run SEV-SNP remote attestation, please refer to [link](https://github.com/AMDESE/AMDSEV/tree/sev-snp-devel) to set up the host and guest Linux kernel, qemu and ovmf bios used for launching SEV-SNP guest.
- If you want to run it in browser, please read [this document](wasm/emscripten/README.md).

**Notice: special prerequisites for SEV(-ES) remote attestation in software capability.**
- If you want to run it in WAMR, please type the following command.
```shell
# install librats in host mode first
cmake -H. -Bbuild
make -C build install

- Kernel support SEV(-ES) runtime attestation, please manually apply [these patches](https://github.com/haosanzi/attestation-evidence-broker/tree/master/hack/README.md).
- Start the [attestation evidence broker](https://github.com/haosanzi/attestation-evidence-broker/blob/master/README.md) service in host.
# export librats APIs to wamr
cd wasm/wamr
cmake -H. -Bbuild
make -C build

# run the sample
cd build
./iwasm --native-lib=librats_wamr.so sample/test.wasm
```

## Run librats

Right now, librats supports the following instance types:

| Priority | Attester instances | Verifier instances |
| ---------- | -------------------------- | -------------------------- |
| 0 | nullattester | nullverifier |
| 15 | sgx\_la | sgx\_la |
| 20 | csv | csv |
| 35 | sev | sev |
| 42 | sev\_snp | sev\_snp |
| 42 | tdx\_ecdsa | tdx\_ecdsa |
| 52 | sgx\_ecdsa | sgx\_ecdsa |
| 53 | sgx\_ecdsa | sgx\_ecdsa\_qve |

For instance priority, the higher, the stronger. By default, librats will select the **highest priority** instance to use.

### Some special notices

**Notice: special prerequisites for TDX remote attestation in bios configuration and hardware capability.**

Check msr 0x503, return value must be 0:
```
sudo rdmsr 0x503s
```

Note that if you want to run SEV-SNP remote attestation, please refer to [link](https://github.com/AMDESE/AMDSEV/tree/sev-snp-devel) to set up the host and guest Linux kernel, qemu and ovmf bios used for launching SEV-SNP guest.

**Notice: special prerequisites for SEV(-ES) remote attestation in software capability.**

- Kernel support SEV(-ES) runtime attestation, please manually apply [these patches](https://github.com/haosanzi/attestation-evidence-broker/tree/master/hack/README.md).
- Start the [attestation evidence broker](https://github.com/haosanzi/attestation-evidence-broker/blob/master/README.md) service in host.

**Notice: special prerequisites for CSV(2) remote attestation in software capability.**

- Kernel support CSV(2) runtime attestation, please manually apply [theses patches](https://gitee.com/anolis/cloud-kernel/pulls/412).

## Enable bootstrap debugging
### Enable bootstrap debugging

In the early bootstrap of librats, the debug message is mute by default. In order to enable it, please explicitly set the environment variable `RATS_GLOBAL_LOG_LEVEL=<log_level>`, where \<log_level\> is same as the values of the option `-l`.
In the early bootstrap of librats, the debug message is mute by default. In order to enable it, please explicitly set the environment variable `RATS_GLOBAL_LOG_LEVEL=<log_level>`, where \<log_level\> is same as the values of the option `-l`.


# Third Party Dependencies
## Third Party Dependencies

Direct Dependencies
Direct Dependencies

| Name | Repo URL | Licenses |
| :--: | :-------: | :-------: |
| linux-sgx | https://github.com/intel/linux-sgx | BSD-3-clause |
| SGXDataCenterAttestationPrimitives | https://github.com/intel/SGXDataCenterAttestationPrimitives | BSD-3-clause |
| GNU C library | C library | GNU General Public License version 3 |
| Name | Repo URL | Licenses |
| :--: | :-------: | :-------: |
| linux-sgx | https://github.com/intel/linux-sgx | BSD-3-clause |
| SGXDataCenterAttestationPrimitives | https://github.com/intel/SGXDataCenterAttestationPrimitives | BSD-3-clause |
| GNU C library | C library | GNU General Public License version 3 |

0 comments on commit 683d58b

Please sign in to comment.