csh/docs: add/update eHSM document

Signed-off-by: 1570005763 <[email protected]>

confidential-data-hub/docs/SEALED_SECRET.md

@@ -156,8 +156,9 @@ When this sealed secret is transferred to TEE, Confidential DataHub will help to
 
 ## Supported Providers
 
-| Provider Name      | README                                                              | Maintainer                |
-| ------------------ | ------------------------------------------------------------------- | ------------------------- |
-| aliyun       	     |  [aliyun](kms-providers/alibaba.md)                              	   | Alibaba                   |
+| Provider Name      | README                                                      			| Maintainer                |
+| ------------------ | -------------------------------------------------------------------- | ------------------------- |
+| aliyun       	     |  [aliyun](kms-providers/alibaba.md)                               	| Alibaba                   |
+| ehsm       	     |  [ehsm](kms-providers/ehsm-kms.md)                              		| Intel                   	|
 
 ## Sealing & Unsealing of the Secret (TODO)

confidential-data-hub/docs/kms-providers/ehsm-kms.md

@@ -0,0 +1,109 @@
+# KMS Driver for eHSM-KMS
+
+## Spec
+
+### Consts & Layouts
+
+Here are the consts for eHSM-KMS.
+
+| Name               | Value       |
+| ------------------ | ----------- |
+| `provider`       	 | `ehsm`       |
+
+The `provider_settings` and `annotations` defined in [Sealed Secret](../SEALED_SECRET.md#format) is as following:
+
+#### annotations
+
+##### encryption/decryption
+
+The `annotations` should be set empty.
+
+#### provider_settings
+
+| Name               | Usage                                                                |
+| ------------------ | -------------------------------------------------------------------- |
+| `app_id`           | App ID of the eHSM-KMS instance that user created.                   |
+| `endpoint`         | Address of the eHSM-KMS instance.                                     |
+
+### Credential files
+
+To connect to a KMS instance, a credential file is needed. A credential file is actually
+[an json file with app_id and api_key](../../kms/src/plugins/ehsm/example_credential/credential.4eb1____.json). 
+The name of the credential file is always derived from the app id. Suppose the
+App ID is `xxx`, then the credential file has name `credential.xxx.json`.
+
+For more details please see the [`Enroll` operation of ehsm](https://github.com/intel/ehsm/blob/main/docs/API_Reference.md#Enroll).
+
+## Behavior
+
+The client `EhsmKmsClient` supports `Encrypter` and `Decrypter` api. When at the
+user side, the credential files can be directly given by the user.
+
+When in Tee, the credential files is supposed to be placed under `/run/confidential-containers/cdh/kms-credential/ehsm` directory.
+
+## Sealed Secrets
+
+This section introduces how to use `ehsm` KMS to seal a secret.
+
+Suppose that we login on a machine where we can connect to a eHSM-KMS instance.
+
+Prepare the following files
+- `kms-key-id.txt`: The content is the key id of the symmetric key. Example
+```
+a3c2...
+```
+- `kms-endpoint.txt`: The content is the key id of the symmetric key. Example
+```
+https://1.2.3.4:9000
+```
+- `Credential.json`: The content is the AppID and ApiKey. Example
+```json
+{
+  "AppId": "2eb6****",
+  "ApiKey": "TvMB****"
+}
+```
+- `plaintext`: The file whose content will be sealed.
+
+Then, let's 
+```bash
+# define the parameters
+KEY_ID=$(cat kms-key-id.txt)
+ENDPOINT=$(cat kms-endpoint.txt)
+CREDENTIAL_FILE_PATH=$(pwd)/Credential.json
+
+git clone https://github.com/confidential-containers/guest-components.git && cd guest-components
+
+cargo build --bin secret_cli --release --features "ehsm"
+
+target/release/secret_cli seal --file-path ../plaintext \
+    envelope --key-id $KEY_ID ehsm \
+    --credential-file-path $CREDENTIAL_FILE_PATH \
+    --endpoint $ENDPOINT \
+    > sealed_secret.json
+```
+
+Finally the sealed secret will be output to `sealed_secret.json`.
+
+```bash
+cat sealed_secret.json | python -m json.tool
+```
+
+And the output
+```json
+{
+    "version": "0.1.0",
+    "type": "envelope",
+    "key_id": "a3c2...",
+    "encrypted_key": "STBp...",
+    "encrypted_data": "QzWk...",
+    "wrap_type": "A256GCM",
+    "iv": "T32...",
+    "provider": "ehsm",
+    "provider_settings": {
+        "app_id": "2eb6...",
+        "endpoint": "https://1.2.3.4:9000"
+    },
+    "annotations": {}
+}
+```

confidential-data-hub/kms/src/plugins/ehsm/README.md

@@ -6,36 +6,39 @@ In CDH, we provide the eHSM-KMS client to interact with the eHSM-KMS Server.
 
 ## eHSM-KMS Service
 
-For eHSM-KMS client to run, you need to set up an eHSM-KMS service in advance. The following method is only a quick start, and you can find more deployment methods (e.g. with Kubernetes) at webpage of eHSM-KMS.
+For eHSM-KMS client to run, you need to set up an eHSM-KMS service in advance. The following method is only a quick start (verified on the **Ubuntu-20.04**), and you can find more deployment methods (e.g. with Kubernetes) at webpage of eHSM-KMS.
 
 > Prerequisite: a sgx capable machine
 
 * Install requirement tools
+
     ``` shell
     sudo apt update
 
     sudo apt install vim autoconf automake build-essential cmake curl debhelper git libcurl4-openssl-dev libprotobuf-dev libssl-dev libtool lsb-release ocaml ocamlbuild protobuf-compiler wget libcurl4 libssl1.1 make g++ fakeroot libelf-dev libncurses-dev flex bison libfdt-dev libncursesw5-dev pkg-config libgtk-3-dev libspice-server-dev libssh-dev python3 python3-pip  reprepro unzip libjsoncpp-dev uuid-dev liblog4cplus-1.1-9 liblog4cplus-dev dnsutils
     ```
 
 * Install SGX SDK
+
     ```shell
-    wget https://download.01.org/intel-sgx/sgx-linux/2.18/as.ld.objdump.r4.tar.gz
+    wget https://download.01.org/intel-sgx/sgx-linux/2.23/as.ld.objdump.r4.tar.gz
     tar -zxf as.ld.objdump.r4.tar.gz
     sudo cp external/toolset/{current_distr}/* /usr/local/bin
 
-    wget https://download.01.org/intel-sgx/sgx-dcap/1.15/linux/distro/ubuntu20.04-server/sgx_linux_x64_sdk_2.18.100.3.bin
+    wget https://download.01.org/intel-sgx/sgx-dcap/1.20/linux/distro/ubuntu20.04-server/sgx_linux_x64_sdk_2.23.100.2.bin
 
     #choose to install the sdk into the /opt/intel
-    chmod a+x ./sgx_linux_x64_sdk_2.18.100.3.bin && sudo ./sgx_linux_x64_sdk_2.18.100.3.bin
+    chmod a+x ./sgx_linux_x64_sdk_2.23.100.2.bin && sudo ./sgx_linux_x64_sdk_2.23.100.2.bin
 
     source /opt/intel/sgxsdk/environment
     ```
 
 * Install DCAP required packages
+
     ```shell
     cd /opt/intel
 
-    wget https://download.01.org/intel-sgx/sgx-dcap/1.15/linux/distro/ubuntu20.04-server/sgx_debian_local_repo.tgz
+    wget https://download.01.org/intel-sgx/sgx-dcap/1.20/linux/distro/ubuntu20.04-server/sgx_debian_local_repo.tgz
 
     tar xzf sgx_debian_local_repo.tgz
 
@@ -49,59 +52,73 @@ For eHSM-KMS client to run, you need to set up an eHSM-KMS service in advance. T
     ```
 
 * Change PCCS server IP
+
     ``` shell
     vim /etc/sgx_default_qcnl.conf
     ```
+
     ``` vi
     # PCCS server address
-    PCCS_URL=https://1.2.3.4:8081/sgx/certification/v3/ (your pccs IP)
+    PCCS_URL=https://1.2.3.4:8081/sgx/certification/v4/ (your pccs IP)
 
     # To accept insecure HTTPS certificate, set this option to FALSE
     USE_SECURE_CERT=FALSE
     ```
 
-* Either start eHSM-KMS on a single machine without remote attestation.
-    ```
-    # run eHSM-KMS
-    ./run_with_single.sh
+* Install Docker Compose
+
+    ``` shell
+    sudo apt install docker-compose-plugin
+    docker compose --version
+    # Docker Compose version v2.21.0
     ```
 
-* Or build and run eHSM-KMS with docker-compose:
-    ```shell
-    # Download the current stable release (remove the "-x $http_proxy" if you don't behind the proxy)
-    sudo curl -x $http_proxy -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
-    sudo chmod +x /usr/local/bin/docker-compose
-    sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
-    docker-compose --version
-    # docker-compose version 1.29.2, build 5becea4c
+* Build and Run ehsm-kms with Docker Compose
 
+    ```shell
     # Download the ehsm code from github
     git clone --recursive https://github.com/intel/ehsm.git ehsm && cd ehsm
-    vim docker/.env
 
+    vim docker/.env
     # Modify the docker/.env configurations
-    HOST_IP=1.2.3.4               # MUST modify it to your host IP.
-    PCCS_URL=https://1.2.3.4:8081 # MUST modify it to your pccs server url.
-    DKEYSERVER_PORT=8888          # (Optional) the default port of dkeyserver, modify it if you want.
-    KMS_PORT=9000                 # (Optional) the default KMS port, modify it if you want.
-    TAG_VERSION=main              # (Optional) the default code base is using the main latest branch, modify it to specific tag if you want.
-
-    # start to build and run the docker images (couchdb, dkeyserver, dkeycache, ehsm_kms_service)
-    cd docker && docker-compose up -d
+    # ======== docker/.env BEGIN ========
+    HOST_IP=1.2.3.4                 # MUST modify it to your host IP.
+    PCCS_URL=https://1.2.3.4:8081   # MUST modify it to your pccs server url.
+    DOCKER_FILE=Dockerfile.ubuntu20 # MUST modify it to your docker file.
+    DKEYSERVER_PORT=8888            # (Optional) the default port of dkeyserver, modify it if you want.
+    KMS_PORT=9000                   # (Optional) the default KMS port, modify it if you want.
+    TAG_VERSION=main                # (Optional) the default code base is using the main latest branch, modify it to specific tag if you want.
+    # ======== docker/.env END ========
+
+    # (Optional) Modify the docker/.env.pccs configurations if PCCS service is needed
+    # Subscribe to Intel Provisioning Certificate Service and receive an API key
+    # Checkout https://api.portal.trustedservices.intel.com/provisioning-certification for more information
+    # ======== docker/.env.pccs BEGIN ========
+    API_KEY=                      # MUST modify it to your API key obtained from registry
+    # ======== docker/.env.pccs END ========
+
+    # Start to build and run the docker images (couchdb, dkeyserver, dkeycache, ehsm_kms_service)
+    cd docker && docker compose up -d
+    # (Optional) If you want to start PCCS service as well, use `pccs` profile
+    docker compose --profile=pccs up -d
     ```
 
 * Enrollment of the APPID and APIKey
-    ```shell
-    curl -v -k -G "https://<kms_ip>:<port>/ehsm?Action=Enroll"
 
-    {"code":200,"message":"successful","result":{"apikey":"xbtXGHwBexb1pgnEz8JZWHLgaSVb1xSk","appid":"56c46c76-60e0-4722-a6ad-408cdd0c62c2"}}
+    ``` shell
+    curl [--insecure] https://1.2.3.4:9000/ehsm?Action=Enroll
     ```
 
-* Run the unittest cases
+* Run the unittest cases (you can do it in another remote device)
+    * Test with python SDK
+
     ``` shell
-    cd test
-    # run the unit testcases
-    python3 test_kms_with_cli.py --url https://<ip_addr>:<port>
+    # (Optional) create a virutal environment first
+    python3 -m venv ./ehsm-venv && source ./ehsm-venv/bin/activate
+    # Install python SDK
+    cd sdk/python && pip install .
+    # Run testcases with `ehsm` module
+    python3 -m ehsm --url https://127.0.0.1:9002/ehsm --insecure server-test --enroll
     ```
 
 Congratulations! eHSM-KMS service should be ready by now.
@@ -111,6 +128,6 @@ Congratulations! eHSM-KMS service should be ready by now.
 eHSM-KMS client requires a credential file to run. The file name of the credential file is `credential.{your_app_id}.json`. The credential file need to be placed in `/run/confidential-containers/cdh/kms-credential/ehsm/`. And the structure of the credential file is shown in `ehsm/example_credential/` folder.
 
 To test eHSM-KMS client, run
-```bash
+``` shell
 cargo test --features ehsm
 ```