diff --git a/scala/ppml/src/main/scala/com/intel/analytics/bigdl/ppml/attestation/README.md b/scala/ppml/src/main/scala/com/intel/analytics/bigdl/ppml/attestation/README.md index adb376263fb..28b2354bb8a 100644 --- a/scala/ppml/src/main/scala/com/intel/analytics/bigdl/ppml/attestation/README.md +++ b/scala/ppml/src/main/scala/com/intel/analytics/bigdl/ppml/attestation/README.md @@ -4,16 +4,54 @@ Support Grapmine, Occlum and SGX SDK. ## Environment You should have an available attestation service to attest with. You can use `EHSMAttestationService` and configure eHSM-KMS according to [this link](https://github.com/intel-analytics/BigDL/tree/main/ppml/services/pccs-ehsm/kubernetes), or you can just use `DummyAttestationService` for debug. -To enable bi-attestation, you also need SGX SDK to fulfill quote verification. [Here](https://github.com/intel-analytics/BigDL-core/tree/master/ppml#requirements) is the guide to install SGX SDK with verification libs. + +### Bidirectional Attestation +To enable bidirectional attestation, you also need SGX SDK to fulfill quote verification. Here is the guide to install SGX SDK with related libs. + +```bash +wget https://download.01.org/intel-sgx/sgx-linux/2.16/as.ld.objdump.r4.tar.gz +tar -zxf as.ld.objdump.r4.tar.gz +sudo cp external/toolset/ubuntu20.04/* /usr/local/bin + +wget https://download.01.org/intel-sgx/sgx-dcap/1.13/linux/distro/ubuntu20.04-server/sgx_linux_x64_sdk_2.16.100.4.bin +#choose to install the sdk into the /opt/intel +chmod a+x ./sgx_linux_x64_sdk_2.16.100.4.bin && sudo ./sgx_linux_x64_sdk_2.16.100.4.bin + +source /opt/intel/sgxsdk/environment + +cd /opt/intel + +wget https://download.01.org/intel-sgx/sgx-dcap/1.13/linux/distro/ubuntu20.04-server/sgx_debian_local_repo.tgz + +tar xzf sgx_debian_local_repo.tgz + +echo 'deb [trusted=yes arch=amd64] file:///opt/intel/sgx_debian_local_repo 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 - + +sudo apt-get update + +sudo apt-get install -y libsgx-enclave-common-dev libsgx-ae-qe3 libsgx-ae-qve libsgx-urts libsgx-dcap-ql libsgx-dcap-default-qpl libsgx-dcap-quote-verify-dev libsgx-dcap-ql-dev libsgx-dcap-default-qpl-dev libsgx-quote-ex-dev libsgx-uae-service libsgx-ra-network libsgx-ra-uefi +``` + +And you need to configure PCCS in `/etc/sgx_default_qcnl.conf`. + +```bash +# PCCS server address +PCCS_URL=https://your_pccs_url/sgx/certification/v3/ + +# To accept insecure HTTPS certificate, set this option to FALSE +USE_SECURE_CERT=FALSE +``` ## Usage You can attest your environment with AttestationCLI by command like: ```bash -java -cp [dependent-jars] com.intel.analytics.bigdl.ppml.attestation.AttestationCLI -i -k -u -t -c -p +java -cp [dependent-jars] com.intel.analytics.bigdl.ppml.attestation.AttestationCLI -i -k -u -t -c -p ``` ## Parameters -`-i` **appID** , `-k` **appKey** The appID and appKey pair generated by your attestation service. It is a gap that BigDL names the key as `appkey` while EHSM refers it as `apikey`. We will also turn to `apikey` in the future. +`-i` **appID** , `-k` **apiKey** The appID and apipey pair generated by your attestation service. `-u` **asURL** URL of attestation service. Should match the format `:`, default is `127.0.0.1:9000` @@ -22,3 +60,29 @@ java -cp [dependent-jars] com.intel.analytics.bigdl.ppml.attestation.Attestation `-c` **challenge** Challenge to get quote of attestation service which will be verified by local SGX SDK. Used only for bi-attestation. Should be a BASE64 string, default is "" and will skip bi-attestation. `-p` **userReport** User report to generate quote and attested by attestation service. Default is `test`. + +# Attestation Service Verification Interface + +You can verify Attestation Service (eHSM for example) with VerificationCLI. It will first get quote from Attestation Service and then verify the quote with SGX SDK. + +## Environment +You can follow [this guide](#bi-attestation) to install SGX SDK and related DCAP libraries. + +## Usage +You can attest the attestation service with VerificationCLI by command like: +```bash +java -cp [dependent-jars] com.intel.analytics.bigdl.ppml.attestation.VerificationCLI -i -k -u -t -c +``` +Or you can use `verify-attestation-service.sh` to verify the attestation service quote. +```bash +bash verify-attestation-service.sh +``` + +## Parameters +`-i` **appID** , `-k` **apiKey** The appID and apiKey pair generated by your attestation service. + +`-u` **asURL** URL of attestation service. Should match the format `:`, default is `127.0.0.1:9000` + +`-t` **asType** Type of attestation service. Currently support `EHSMAttestationService`. + +`-c` **challenge** Challenge to get quote of attestation service which will be verified by local SGX SDK. Should be a BASE64 string.