Add and update wiki documents for ECDSA-based DCAP attestation (#319)

* Add "Set the attestation mode of the sworker" content to the buildNode chaptor. * Update the sWorkerEntryNetwork document to describe information about the ECDSA-based DCAP attestation. * Update related documents to use crust-node-2.0.0 version, and add 'Config sWorker Attestation Mode' step for Node Configuration section. * Add new wiki document: Q&AForEPID-ECDSA.md, which is to describe detail information for EPID attestation and ECDSA DCAP attestation, and how to migrate to ECDSA DCAP attestation. * Detail document for Q&AForEPID-ECDSA.md. Describe details about how to migrate from EPID IAS attestation to ECDSA DCAP attestation. * Update the shell script to fix the swork.IllegalFilesTransition error.
crustio · May 6, 2024 · 1cd68f0 · 1cd68f0
1 parent 646ddd3
commit 1cd68f0
Show file tree

Hide file tree

Showing 24 changed files with 437 additions and 36 deletions.
diff --git a/docs/Q&AForEPID-ECDSA.md b/docs/Q&AForEPID-ECDSA.md
@@ -0,0 +1,155 @@
+---
+id: Q&AForEPID-ECDSA
+title: EPID & ECDSA
+sidebar_label: EPID & ECDSA
+---
+
+## 1. Overview
+
+### EPID
+Intel plans to end of life (EOL) the Intel SGX Attestation Service Utilizing Intel EPID (IAS for short) April 2, 2025. Refer to [here](https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/resources/sgx-ias-using-epid-eol-timeline.html) for more information. 
+
+### ECDSA
+ECDSA-based attestation with Intel SGX DCAP allows providers to build and deliver their own attestation service instead of using the remote attestation service provided by Intel. This is a replacement for the IAS. Refer to [here](https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/attestation-services.html) for more information. 
+
+Crust has developed a ECDSA-based attestation service with Intel SGX DCAP. The github repo is [crust-dcap](https://github.com/crustio/crust-dcap). sWorker version >= 2.0.0 supports ECDSA-based DCAP attestation.
+
+## 2. Migration Q&A
+
+### 2.1 Do I need to migrate all servers to ECDSA-based DCAP attestation before April 2, 2025?
+
+No. If sWorker runs normally after enter the network, it doesn't need to connect with the Intel IAS service. Therefore, as long as there is no need to re-enter the network (such as disk damage, system reinstallation, new server joining, etc.), the current version of sWorker can continue to use without migration.
+
+### 2.2 Can all servers be upgraded to ECDSA-based DCAP attestation? <a id="server_support_ecdsa"></a>
+
+No. Run the following command to check if your server supports ECDSA DCAP attestation:
+```shell
+cpuid | grep -i "SGX launch config"
+```
+
+Check if the command output is:
+
+```shell
+    SGX_LC: SGX launch config supported      = true
+```
+
+If the output is true, your server supports ECDSA DCAP attestation.
+
+Refer to the following links to confirm if your server CPU model supports ECDSA DCAP attestation:
+
+[Which Platforms Support Intel® SGX DataCenter Attestation Primitives (DCAP)](https://www.intel.com/content/www/us/en/support/articles/000057420/software/intel-security-products.html)
+
+[Intel® Processors Supporting Intel® SGX](https://www.intel.cn/content/www/cn/zh/architecture-and-technology/software-guard-extensions-processors.html)
+
+
+In summary, the following common CPU series support ECDSA DCAP attestation:
+
+- Intel Xeon Scalable series processors >=3rd generation
+
+    Note: Scalable series processors do not support EPID IAS, only ECDSA DCAP.
+
+- Intel Xeon E/D series processors supporting SGX with Intel SPS feature
+
+    Check the CPU official Spec to confirm the following feature:
+
+    ![Pic](assets/qa/sgx-with-intel-sps.png)
+
+    Note 1: This series of processors can support both EPID IAS and ECDSA DCAP.
+
+    Note 2: Processors supporting SGX with Intel ME feature only support EPID IAS, not ECDSA DCAP.
+
+- 8th, 9th, and 10th generation Intel Core processors supporting SGX + AES-NI feature
+
+    Check the CPU official Spec to confirm the following feature:
+
+    ![Pic](assets/qa/sgx-with-aes-ni.png)
+
+    Note 1: This series of processors can support both EPID IAS and ECDSA DCAP.
+
+    Note 2: 11th generation (inclusive) and later Core processors no longer support SGX feature, so neither EPID IAS nor ECDSA DCAP is available.
+
+### 2.3 Why does the 'SGX launch config' output still show false even though my server CPU model supports SGX and DCAP?
+
+In addition to meeting the CPU model requirements, SGX and DCAP features also require BIOS support. 
+
+Please check the BIOS settings or upgrade the corresponding BIOS version. For details, please contact the technical support of the server supplier.
+
+### 2.4 My server supports ECDSA DCAP, and is running the old version of sWorker based on EPID attestation. Now re-entry network is needed, how do I migrate to ECDSA-based DCAP attestation?
+
+Please refer to [3. Migration Guide](#migration_guide)
+
+### 2.5 My server supports ECDSA DCAP and is a new server. How do I deploy from scratch?
+
+Please refer to [Member Node](memberNode.md) or [Isolation Node](isolationNode.md) for deployment installation. 
+
+Crust Node version 2.0.0+ supports automatic recognition and use of ECDSA DCAP attestation mode.
+
+### 2.6 My server doesn't support ECDSA DCAP, and is running the old version of sWorker based on EPID attestation. Now re-entry network is needed, how should I do?
+
+If it is before April 2, 2025, you can still use EPID IAS for entry network attestation, and all currently effective sWorker versions can be used.
+
+If it is after April 2, 2025, since the Intel IAS service has stopped, and the server itself does not support ECDSA DCAP, this server can no longer entry the network and needs to purchase a new server that supports ECDSA DCAP. You can then migrate the hard disks to the new server, and then redeploy to entry the network.
+
+Note: For miners who need to purchase new servers to join in 2024, please be sure to purchase servers that support DCAP according to the contents of [section #2.2](#server_support_ecdsa) and the reference link, to ensure that you can still entry the network after the Intel IAS service stops.
+
+## 3. Migration Guide <a id="migration_guide"></a >
+
+### 3.1 Upgrade Crust Node to the latest installation package
+
+a. Download
+
+Make sure the version number of the installation package is >= 2.0.0
+
+```shell
+wget https://github.com/crustio/crust-node/archive/v2.0.0.tar.gz
+```
+
+b. Unzip
+
+```shell
+tar -xvf v2.0.0.tar.gz
+```
+
+c. Enter the installation directory
+
+```shell
+cd crust-node-2.0.0
+```
+
+### 3.2 Migration Upgrade
+
+Execute the following command for upgrade
+
+```shell
+sudo ./install.sh --update-ecdsa
+```
+
+The script first checks whether the current server supports ECDSA DCAP attestation. If not, it will prompt the following information and exit:
+
+![Pic](assets/qa/update-ecdsa-not-applicable.png)
+
+If the current server supports ECDSA DCAP attestation, it will prompt that the sworker would be stopped and existing sworker data would be purged, and it requires confirmation to execute:
+
+[Note] This operation will reset the storage power of the member node to 0, and will need to re-entry the network and SRD. After data is purged, it cannot be recovered, please confirm before operation.
+
+![Pic](assets/qa/update-ecdsa-yes.png)
+
+Seeing the following display means the upgrade was successful:
+
+![Pic](assets/qa/update-ecdsa-success.png)
+
+### 3.3 Restart sWorker
+Restart sWorker and observe the logs to see if it has successfully entry the network based on ECDSA DCAP:
+
+```shell
+sudo crust start sworker
+sudo crust logs sworker
+```
+
+After confirming that the entry network is successful, re-execute SRD:
+
+```shell
+sudo crust tools change-srd {number}
+```
+
+After the SRD task is completed, sWorker will resume normal operation.
diff --git a/docs/Q&AForMember-node-related.md b/docs/Q&AForMember-node-related.md
@@ -189,16 +189,28 @@ The solution is as follows:
 - Keep sowkrer service online
 - Execute the following command
 ```shell
+#!/bin/bash
+
 account=$(curl http://localhost:12222/api/v0/enclave/id_info | jq .account)
-params=$(curl -s -XPOST 'https://crust.webapi.subscan.io/api/scan/extrinsics' --header 'Content-Type: application/json' --data-raw '{"jsonrpc":"2.0", "call": "report_works", "module": "swork", "no_params": false, "page": 0, "row": 1, "signed": "signed", "success": true,"address": '$account'}' | jq -r .data.extrinsics | jq -r .[0].params | sed 's/\\//g' | jq .)
+extrinsic_index=$(curl -s -XPOST 'https://crust.webapi.subscan.io/api/v2/scan/extrinsics' --header 'Content-Type: application/json' --data-raw '{"page": 0, "row": 1, "signed": "all", "call": "report_works", "module": "swork", "success": true, "address": '$account'}' | jq -r '.data|.extrinsics[0]|.extrinsic_index')
+params=$(curl -s -XPOST 'https://crust.webapi.subscan.io/api/scan/extrinsic' --header 'Content-Type: application/json' --data-raw '{"extrinsic_index": "'$extrinsic_index'", "events_limit": 10, "only_extrinsic_event": true, "focus": ""}' | jq -r .data.params | sed 's/\\//g' | jq .)
+
 added_files=($(echo $params | jq .[6].value | jq -r .[].col1))
 deleted_files=($(echo $params | jq .[7].value | jq -r .[].col1))
 input_data='{"added_files": ['
-for file in ${added_files[@]}; do input_data="${input_data}\"$(echo $file | xxd -r -p)\","; done
-if [ ${#added_files[@]} -ne 0 ]; then input_data=${input_data:0:len-1}; fi
+for file in ${added_files[@]}; do
+        input_data="${input_data}\"$(echo $file | xxd -r -p)\",";
+done
+if [ ${#added_files[@]} -ne 0 ]; then
+        input_data=${input_data:0:len-1};
+fi
 input_data="${input_data}], \"deleted_files\": ["
-for file in ${deleted_files[@]}; do input_data="${input_data}\"$(echo $file | xxd -r -p)\","; done
-if [ ${#deleted_files[@]} -ne 0 ]; then input_data=${input_data:0:len-1}; fi
+for file in ${deleted_files[@]}; do
+        input_data="${input_data}\"$(echo $file | xxd -r -p)\",";
+done
+if [ ${#deleted_files[@]} -ne 0 ]; then
+        input_data=${input_data:0:len-1};
+fi
 input_data="${input_data}]}"
 curl -XPOST "http://localhost:12222/api/v0/file/recover_illegal" --header 'Content-Type: application/json' --data-raw "$input_data"
 ```

diff --git a/docs/assets/node/attestation-mode.png b/docs/assets/node/attestation-mode.png
diff --git a/docs/assets/node/config-set-attestation-mode.png b/docs/assets/node/config-set-attestation-mode.png
diff --git a/docs/assets/qa/sgx-with-aes-ni.png b/docs/assets/qa/sgx-with-aes-ni.png
diff --git a/docs/assets/qa/sgx-with-intel-sps.png b/docs/assets/qa/sgx-with-intel-sps.png
diff --git a/docs/assets/qa/update-ecdsa-not-applicable.png b/docs/assets/qa/update-ecdsa-not-applicable.png
diff --git a/docs/assets/qa/update-ecdsa-success.png b/docs/assets/qa/update-ecdsa-success.png
diff --git a/docs/assets/qa/update-ecdsa-yes.png b/docs/assets/qa/update-ecdsa-yes.png
diff --git a/docs/build-node.md b/docs/build-node.md
@@ -104,7 +104,22 @@ sudo crust config chain-port 30889
 ```
 ![start](assets/node/chainport.png)
 
-### 2.5 Show configuration file
+### 2.5 Set the attestation mode of the sworker
+
+- Command
+```shell
+sudo crust config attestation-mode {epid/ecdsa}
+```
+
+- Instance
+Change the attestation-mode to ecdsa
+
+```shell
+sudo crust config attestation-mode ecdsa
+```
+![start](assets/node/attestation-mode.png)
+
+### 2.6 Show configuration file
 
 - Command
 ```shell

diff --git a/docs/isolationNode.md b/docs/isolationNode.md
@@ -51,15 +51,15 @@ wget https://github.com/crustio/crust-node/releases/download/sgxenable-1.0.0/sgx
 a. Download
 
 ```plain
-wget https://github.com/crustio/crust-node/archive/v1.0.0.tar.gz
+wget https://github.com/crustio/crust-node/archive/v2.0.0.tar.gz
 ```
 b. Unzip
 ```plain
-tar -xvf v1.0.0.tar.gz
+tar -xvf v2.0.0.tar.gz
 ```
 c. Go to package directory
 ```plain
-cd crust-node-1.0.0
+cd crust-node-2.0.0
 ```
 ### 2.5 Install Crust Service
 
@@ -110,7 +110,13 @@ Enter the password for the Member backup file as prompted and press Enter to end
 
 ![pic](assets/mining/member_password_config.png)
 
-### 3.5 Config Hard Disks
+### 3.5 Config sWorker Attestation Mode
+
+Follow the prompts to enter the sworker attestation mode, generally use the default value is good to go (Refer to [EPID & ECDSA](Q&AForEPID-ECDSA.md) for more information), simply press Enter to end:
+
+![pic](assets/node/config-set-attestation-mode.png)
+
+### 3.6 Config Hard Disks
 
 > Disk organization solution is not unitary. If there is a better solution, you can optimize it yourself.
 

diff --git a/docs/memberNode.md b/docs/memberNode.md
@@ -41,15 +41,15 @@ wget https://github.com/crustio/crust-node/releases/download/sgxenable-1.0.0/sgx
 a. Download
 
 ```plain
-wget https://github.com/crustio/crust-node/archive/v1.0.0.tar.gz
+wget https://github.com/crustio/crust-node/archive/v2.0.0.tar.gz
 ```
 b. Unzip
 ```plain
-tar -xvf v1.0.0.tar.gz
+tar -xvf v2.0.0.tar.gz
 ```
 c. Go to package directory
 ```plain
-cd crust-node-1.0.0
+cd crust-node-2.0.0
 ```
 
 ### 2.4 Install Crust Service
@@ -102,7 +102,13 @@ Enter the password for the backup file as prompted and press Enter to end:
 
 ![pic](assets/mining/member_password_config.png)
 
-### 3.5 Config Hard Disks
+### 3.5 Config sWorker Attestation Mode
+
+Follow the prompts to enter the sworker attestation mode, generally use the default value is good to go (Refer to [EPID & ECDSA](Q&AForEPID-ECDSA.md) for more information), simply press Enter to end:
+
+![pic](assets/node/config-set-attestation-mode.png)
+
+### 3.6 Config Hard Disks
 
 > Disk organization solution is not unitary. If there is a better solution, you can optimize it yourself.
 
@@ -127,7 +133,7 @@ You can use following command to view the file directory:
 sudo crust tools space-info
 ```
 
-### 3.6 External chain Configuration (Optional&recommend)
+### 3.7 External chain Configuration (Optional&recommend)
 
 Enable local storage services to use external chain nodes for information collection, workload reporting, etc.
 

diff --git a/docs/ownerNode.md b/docs/ownerNode.md
@@ -55,15 +55,15 @@ Enter the number of CRUs that **need to be added**, and sign the transaction, as
 a. Download
 
 ```plain
-wget https://github.com/crustio/crust-node/archive/v1.0.0.tar.gz
+wget https://github.com/crustio/crust-node/archive/v2.0.0.tar.gz
 ```
 b. Unzip
 ```plain
-tar -xvf v1.0.0.tar.gz
+tar -xvf v2.0.0.tar.gz
 ```
 c. Go to package directory
 ```plain
-cd crust-node-1.0.0
+cd crust-node-2.0.0
 ```
 ### 2.4 Install Crust Service
 

diff --git a/docs/sWorkerEntryNetwork.md b/docs/sWorkerEntryNetwork.md
@@ -18,6 +18,13 @@ How to check if an application is running in SGX? To deal with this problem, Int
 
 ![sworker remote_attestation](assets/sworker/remoteAttestation.png)
 
+### ECDSA Attestation
+Intel plans to end of life (EOL) the Intel SGX Attestation Service Utilizing Intel EPID (IAS for short) April 2, 2025. Refer to [here](https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/resources/sgx-ias-using-epid-eol-timeline.html) for more information. 
+
+ECDSA-based attestation with Intel SGX DCAP allows providers to build and deliver their own attestation service instead of using the remote attestation service provided by Intel. This is a replacement for the IAS. Refer to [here](https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/attestation-services.html) for more information. 
+
+Crust has developed a ECDSA-based attestation service with Intel SGX DCAP. The github repo is [crust-dcap](https://github.com/crustio/crust-dcap). sWorker version >= 2.0.0 supports ECDSA-based DCAP attestation. For more information, please refer to [here](Q&AForEPID-ECDSA.md).
+
 ### MREnclave
 MREnclave is another important concept. It can be treated as the hash of enclave code and stack data at runtime. An application can be checked if running in the right way through comparing runtime MREnclave with the indicated one. In this way can application protect its data from malware. By the way MREnclave is contained in Quote.
 
@@ -37,3 +44,5 @@ In crust network every sWorker has a unique identity which is contained in work-
 1. Entry network is successful if the identity passes Crust chain’s validation, failed if not.
 
 Note that the quote generated in step 3 contains enclave’s MREnclave. If enclave’s code changes, the MREnclave changes too. After Crust starting, IAS certificate and an indicated MREnclave code will be set in Crust chain by democratic vote. In step 8, public key A is parsed from report, which is used to verify the signature of report. Secondly, through IAS certificate in Crust chain, report can be checked if it is valid. Verification of Report signature prevents attackers from forging IAS signature. Report also contains the validation result of sWorker platform which could tell whether it runs within a valid SGX hardware, which completes SGX environment identification. Thirdly, comparing MREnclave in report with the one in Crust chain completes MREclave identification. Finally Crust chain will bond sWorker identity to corresponding crust chain account so that the reported workload can be calculated to the indicated chain account.
+
+PS: For sWorker version >= 2.0.0, sWorker will use ECDSA-based DCAP attestation instead of IAS.
diff --git a/website/i18n/en.json b/website/i18n/en.json
@@ -304,6 +304,10 @@
         "title": "Applications",
         "sidebar_label": "Applications"
       },
+      "Q&AForEPID-ECDSA": {
+        "title": "EPID & ECDSA",
+        "sidebar_label": "EPID & ECDSA"
+      },
       "Q&AForFix": {
         "title": "Fix unstable chain",
         "sidebar_label": "Fix unstable chain"

diff --git a/website/i18n/zh-CN.json b/website/i18n/zh-CN.json
@@ -273,6 +273,10 @@
         "title": "应用",
         "sidebar_label": "应用"
       },
+      "Q&AForEPID-ECDSA": {
+        "title": "EPID & ECDSA",
+        "sidebar_label": "EPID & ECDSA"
+      },
       "setOnChainIdentity": {
         "title": "设置链上身份",
         "sidebar_label": "设置链上身份"

diff --git a/website/sidebars.json b/website/sidebars.json
@@ -149,6 +149,7 @@
       "Q&AForrelatedgroups",
       "Q&AForFix",
       "Q&AForCrustApplications",
+      "Q&AForEPID-ECDSA",
       "Q&AForOther"
     ]
   }