From c093b6b088bd566d716486778cdd0d8ca4fb43d5 Mon Sep 17 00:00:00 2001 From: Valentyn Faychuk Date: Thu, 19 Dec 2024 11:19:06 +0200 Subject: [PATCH] documentation improvements --- INSTALL_SGX.md | 71 ++++++++++++++++++++++++++ README.md | 133 ++++++++++++++----------------------------------- 2 files changed, 108 insertions(+), 96 deletions(-) create mode 100644 INSTALL_SGX.md diff --git a/INSTALL_SGX.md b/INSTALL_SGX.md new file mode 100644 index 0000000..5cc5fc5 --- /dev/null +++ b/INSTALL_SGX.md @@ -0,0 +1,71 @@ +# SGX server setup + +Following are useful links to get more information: +* [SGX installation procedures](https://download.01.org/intel-sgx/sgx-linux/2.13/docs/Intel_SGX_Installation_Guide_Linux_2.13_Open_Source.pdf) +* [DCAP extended installation](https://download.01.org/intel-sgx/sgx-dcap/1.8/linux/docs/Intel_SGX_DCAP_Linux_SW_Installation_Guide.pdf) +* [SGX installation for developers](https://download.01.org/intel-sgx/latest/linux-latest/docs/Intel_SGX_SW_Installation_Guide_for_Linux.pdf) +* [SGX Released Packages](https://download.01.org/intel-sgx/Releases/) +* [PCCS installation readme](https://github.com/intel/SGXDataCenterAttestationPrimitives/tree/main/QuoteGeneration/pccs) + +## SGX drivers for operating the DeTEE daemon +Operators should be able to just install the SGX driver and DCAP: +``` +echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu/ jammy main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list +wget -qO - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add - +sudo apt update +# sudo apt install build-essential ocaml automake autoconf libtool wget python-is-python3 libssl-dev cracklib-runtime +wget https://download.01.org/intel-sgx/sgx-linux/2.24/distro/ubuntu22.04-server/sgx_linux_x64_driver_1.41.bin +sudo ./sgx_linux_x64_driver_1.41.bin +sudo apt install libsgx-dcap-ql libsgx-dcap-default-qpl libsgx-dcap-quote-verify +``` + +## SGX drivers, platform software (PSW), DCAP, PCCS, and SDK +Cheat sheet: +``` +# Add debian repository with SGX +echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu/ jammy main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list +wget -qO - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add - +sudo apt update + +# Choose release https://download.01.org/intel-sgx/Releases/ +wget https://download.01.org/intel-sgx/sgx-linux/2.24/distro/ubuntu22.04-server/sgx_linux_x64_driver_1.41.bin +wget https://download.01.org/intel-sgx/sgx-linux/2.24/distro/ubuntu22.04-server/sgx_linux_x64_driver_2.11.b6f5b4a.bin +wget https://download.01.org/intel-sgx/sgx-linux/2.24/distro/ubuntu22.04-server/sgx_linux_x64_sdk_2.24.100.3.bin +chmod 777 sgx_linux_x64* + +# ECDSA attestation support +sudo apt install build-essential ocaml automake autoconf libtool wget python-is-python3 libssl-dev +# SGX DCAP Driver, kernels v5.11 have it built-in +sudo ./sgx_linux_x64_driver_1.41.bin +# SGX DCAP +sudo apt install python3 cracklib-runtime +sudo apt install libsgx-dcap-ql libsgx-dcap-ql-dev +sudo apt install libsgx-dcap-default-qpl libsgx-dcap-default-qpl-dev +sudo apt install libsgx-dcap-quote-verify libsgx-dcap-quote-verify-dev + +# SGX PSW (platform software), get launch, epid, and agnostic attestation +sudo apt install libssl-dev libcurl4-openssl-dev libprotobuf-dev +sudo ./sgx_linux_x64_driver_2.11.b6f5b4a.bin +# *-dbgsym and *-dev versions are for development +sudo apt install libsgx-launch libsgx-epid libsgx-quote-ex libsgx-urts + +# Put SGX SDK under /opt/intel +sudo apt install build-essential python-is-python3 +sudo ./sgx_linux_x64_sdk_2.24.100.3.bin + +# TODO: PCCS is optional and is hard to install, fix it +curl -fsSL https://deb.nodesource.com/setup_20.10 -o nodesource_setup.sh +sudo -E bash nodesource_setup.sh +sudo apt install nodejs +sudo apt install sgx-dcap-pccs +# file with PCCS configurations /etc/sgx_default_qcnl.conf +# USE_SECURE_CERT=TRUE +# PCCS_URL=https://your_pccs_server:8081/sgx/certification/v2/ +``` + +## Gramine and Occlum installation [in progress] +Make sure you have installed SGX, then add following to the `/etc/apt/sources.list`: +``` +deb [arch=amd64 trusted=yes] https://packages.gramineproject.io/ jammy main +deb [arch=amd64 trusted=yes] https://occlum.io/occlum-package-repos/debian jammy main +``` \ No newline at end of file diff --git a/README.md b/README.md index cb0df86..a8d8813 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Occlum SGX Remote Attestation integrated in TLS connection and many more +# DeTEE library for using SGX features, such as remote attestation, raTLS and sealing ## Requirements to run @@ -6,34 +6,9 @@ * The library depends on the extension present in /dev/sgx * The library must run on top of the occlum libos -## The flow +## Prerequisites -The MRSIGNER of the `example/signing_key.pem` is hardcoded in the enclave code: - -``` -83E8A0C3ED045D9747ADE06C3BFC70FCA661A4A65FF79A800223621162A88B76 -``` - -You can generate your own signing key. Just use the following command: - -``` -openssl genrsa -3 -out signing_key.pem 3072 -``` - -To get the MRSIGNER of the key, compile [this project](https://github.com/intel/sgx-ra-sample) -and use the following command: - -``` -./mrsigner signing_key.pem -# For the example/signing_key.pem the output is: -6871A831CED408CD99F0ED31587CC2B5C728C99D4A0A1ADF2F0C5574EBBB00DC -# FIXME: Which is different from the real MRSIGNER by Occlum: -83E8A0C3ED045D9747ADE06C3BFC70FCA661A4A65FF79A800223621162A88B76 -``` - -## Docker installation - -To run the project in Docker, you need to install the docker first. +To run the project in **Docker**, you need to install the docker first. On Ubuntu, you can use the following commands: ```bash @@ -60,7 +35,32 @@ sudo usermod -aG docker $USER newgrp docker ``` -## Occlum docker instance +## The flow + +The MRSIGNER of the `example/signing_key.pem` is hardcoded in the enclave code: + +``` +83E8A0C3ED045D9747ADE06C3BFC70FCA661A4A65FF79A800223621162A88B76 +``` + +You can generate your own signing key. Just use the following command: + +``` +openssl genrsa -3 -out signing_key.pem 3072 +``` + +To get the MRSIGNER of the key, compile [this project](https://github.com/intel/sgx-ra-sample) +and use the following command: + +``` +./mrsigner signing_key.pem +# For the example/signing_key.pem the output is: +6871A831CED408CD99F0ED31587CC2B5C728C99D4A0A1ADF2F0C5574EBBB00DC +# FIXME: Which is different from the real MRSIGNER by Occlum: +83E8A0C3ED045D9747ADE06C3BFC70FCA661A4A65FF79A800223621162A88B76 +``` + +## Run using Occlum docker ### On the build host (without SGX) @@ -99,11 +99,12 @@ cd server && occlum run /bin/mratls_grpcs_server cd client && occlum run /bin/mratls_grpcs_client ``` -## Running Examples on the SGX host (locally) +## Run locally -Before running make sure you have installed the Occlum and the SGX driver. -You should also have the Occlum Rust toolchain installed to get `occlum-cargo`. -To test the project just run client and server scripts in different terminals: +Before running make sure you have installed Occlum and the SGX driver, see +[this cheatsheet](INSTALL_SGX.md) for more details. You should also have the +Occlum Rust toolchain installed to get `occlum-cargo`. To test the project +just run client and server scripts in different terminals: ``` @@ -132,67 +133,7 @@ The client can be running anywhere. The server config allows to whitelist the public ec25519 key of the client. The client config allows to whitelist MRENCLAVE, MRSIGNER, PRODID, SVN of the server. -## Dependencies +## Sealing example -When running, the server process has following connected shared objects - -``` -/usr/lib/x86_64-linux-gnu/libcrypt.so.1.1.0 -/usr/lib/x86_64-linux-gnu/libsqlite3.so.0.8.6 -/usr/lib/x86_64-linux-gnu/libhx509.so.5.0.0 -/usr/lib/x86_64-linux-gnu/libheimbase.so.1.0.0 -/usr/lib/x86_64-linux-gnu/libwind.so.0.0.0 -/usr/lib/x86_64-linux-gnu/libffi.so.7.1.0 -/usr/lib/x86_64-linux-gnu/libroken.so.18.1.0 -/usr/lib/x86_64-linux-gnu/libhcrypto.so.4.1.0 -/usr/lib/x86_64-linux-gnu/libasn1.so.8.0.0 -/usr/lib/x86_64-linux-gnu/libkrb5.so.26.0.0 -/usr/lib/x86_64-linux-gnu/libheimntlm.so.0.1.0 -/usr/lib/x86_64-linux-gnu/libkeyutils.so.1.8 -/usr/lib/x86_64-linux-gnu/libtasn1.so.6.6.0 -/usr/lib/x86_64-linux-gnu/libp11-kit.so.0.3.0 -/usr/lib/x86_64-linux-gnu/libbrotlicommon.so.1.0.7 -/usr/lib/x86_64-linux-gnu/libgssapi.so.3.0.0 -/usr/lib/x86_64-linux-gnu/libsasl2.so.2.0.25 -/usr/lib/x86_64-linux-gnu/libresolv-2.31.so -/usr/lib/x86_64-linux-gnu/libk5crypto.so.3.1 -/usr/lib/x86_64-linux-gnu/libkrb5.so.3.3 -/usr/lib/x86_64-linux-gnu/libgmp.so.10.4.0 -/usr/lib/x86_64-linux-gnu/libnettle.so.7.0 -/usr/lib/x86_64-linux-gnu/libgnutls.so.30.27.0 -/usr/lib/x86_64-linux-gnu/libunistring.so.2.1.0 -/usr/lib/x86_64-linux-gnu/libcrypto.so.1.1 -/usr/lib/x86_64-linux-gnu/libhogweed.so.5.0 -/usr/lib/x86_64-linux-gnu/libz.so.1.2.11 -/usr/lib/x86_64-linux-gnu/libldap_r-2.4.so.2.10.12 -/usr/lib/x86_64-linux-gnu/libgssapi_krb5.so.2.2 -/usr/lib/x86_64-linux-gnu/libssl.so.1.1 -/usr/lib/x86_64-linux-gnu/libssh.so.4.8.4 -/usr/lib/x86_64-linux-gnu/libkrb5support.so.0.1 -/usr/lib/x86_64-linux-gnu/libcom_err.so.2.1 -/usr/lib/x86_64-linux-gnu/libbrotlidec.so.1.0.7 -/usr/lib/x86_64-linux-gnu/liblber-2.4.so.2.10.12 -/usr/lib/x86_64-linux-gnu/librtmp.so.1 -/usr/lib/x86_64-linux-gnu/libdcap_quoteprov.so.1.13.104.4 -/usr/lib/x86_64-linux-gnu/libpsl.so.5.3.2 -/usr/lib/x86_64-linux-gnu/libidn2.so.0.3.6 -/usr/lib/x86_64-linux-gnu/libnghttp2.so.14.19.0 -/usr/lib/x86_64-linux-gnu/libcurl.so.4.6.0 -/usr/lib/x86_64-linux-gnu/libsgx_default_qcnl_wrapper.so.1.13.104.4 -/usr/lib/x86_64-linux-gnu/libnss_files-2.31.so -/usr/lib/x86_64-linux-gnu/libsgx_urts.so.2.0.103.4 -/usr/lib/x86_64-linux-gnu/libm-2.31.so -/usr/lib/x86_64-linux-gnu/libsgx_pce_logic.so.1.14.104.4 -/usr/lib/x86_64-linux-gnu/libsgx_qe3_logic.so -/usr/lib/x86_64-linux-gnu/libgcc_s.so.1 -/usr/lib/x86_64-linux-gnu/libstdc++.so.6.0.28 -/usr/lib/x86_64-linux-gnu/libsgx_dcap_quoteverify.so.1.12.104.4 -/usr/lib/x86_64-linux-gnu/libsgx_dcap_ql.so.1.11.104.4 -/usr/lib/x86_64-linux-gnu/libdl-2.31.so -/usr/lib/x86_64-linux-gnu/libsgx_enclave_common.so.1.2.103.4 -/usr/lib/x86_64-linux-gnu/libsgx_uae_service.so.2.3.219.4 -/usr/lib/x86_64-linux-gnu/libpthread-2.31.so -/usr/lib/x86_64-linux-gnu/libc-2.31.so -/root/run/server/build/lib/libocclum-pal.so.0.30.1 -/usr/lib/x86_64-linux-gnu/ld-2.31.so -``` +Example shows how to seal and unseal data using the enclave. +The data is stored in the hostfs (`/host` folder inside the enclave).