refresh outdated troubleshoot and attestation docs

docs/docs/getting-started/troubleshoot.md

@@ -1,13 +1,17 @@
 # Troubleshooting
 
 ## SGX
+
 If EGo works in simulation mode (with `OE_SIMULATION=1`), but not with SGX, check the following.
 
 ### Operating system
-EGo currently supports Ubuntu 18.04 and 20.04.
+
+EGo currently supports Ubuntu 20.04 and 22.04.
 
 ### Hardware
+
 The hardware must support SGX and it must be enabled in the BIOS:
+
 ```shell-session
 $ sudo apt install cpuid
 $ cpuid | grep SGX
@@ -16,78 +20,70 @@ $ cpuid | grep SGX
    SGX capability (0x12/0):
       SGX1 supported                         = true
 ```
+
 * `SGX: Software Guard Extensions supported` is true if the hardware supports it.
 * `SGX_LC: SGX launch config supported` is true if the hardware also supports FLC. This is required for attestation.
 * `SGX1 supported` is true if it's enabled in the BIOS.
 
 ### Driver
+
 The SGX driver exposes a device:
-```bash
-ls /dev/*sgx*
-```
-If the output is empty, install the driver.
 
-The easiest way to install the driver is using ego install:
 ```bash
-sudo ego install sgx-driver
+ls /dev/*sgx*
 ```
 
+If the output is empty, install the driver.
 
-As an alternative way you can install it manually.
+If your system [supports FLC](#hardware), make sure your Linux kernel is version 5.11 or newer.
+You can check with `uname -r`.
+If you can't upgrade your kernel, you may [install the *DCAP driver*](https://download.01.org/intel-sgx/latest/linux-latest/docs/Intel_SGX_SW_Installation_Guide_for_Linux.pdf) instead.
 
-If your system supports FLC (see above):
-```bash
-wget https://download.01.org/intel-sgx/sgx-linux/2.12/distro/ubuntu`lsb_release -rs`-server/sgx_linux_x64_driver_1.36.2.bin
-chmod +x sgx_linux_x64_driver_1.36.2.bin
-sudo ./sgx_linux_x64_driver_1.36.2.bin
-```
-
-Otherwise:
-```bash
-wget https://download.01.org/intel-sgx/sgx-linux/2.13.3/distro/ubuntu`lsb_release -rs`-server/sgx_linux_x64_driver_2.11.0_2d2b795.bin
-chmod +x sgx_linux_x64_driver_2.11.0_2d2b795.bin
-sudo ./sgx_linux_x64_driver_2.11.0_2d2b795.bin
-```
+On systems without FLC support, you need the SGX *out-of-tree driver*.
+Note that Intel deprecated this kind of SGX implementation and EGo doesn't support remote attestation on such systems.
+To install the driver, follow the [SGX installation guide from Intel](https://download.01.org/intel-sgx/latest/linux-latest/docs/Intel_SGX_SW_Installation_Guide_for_Linux.pdf).
 
 ### Required packages
 
 #### non-FLC system
+
 If your system doesn't support FLC, install the `libsgx-launch` package:
-```bash
-sudo ego install libsgx-launch
-```
 
-Or manually:
 ```bash
-wget -qO- https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add
-sudo add-apt-repository "deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu `lsb_release -cs` main"
+sudo mkdir -p /etc/apt/keyrings
+wget -qO- https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
+echo "deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/intel-sgx.list
+sudo apt update
 sudo apt install libsgx-launch
 ```
 
 #### SGX device issues
+
 If the [SGX device exists](#driver), but you get one of these errors:
+
 * `Failed to open Intel SGX device.`
 * `ERROR: enclave_load_data failed (addr=0x..., prot=0x1, err=0x1001) (oe_result_t=OE_PLATFORM_ERROR)`
 
 Install the `libsgx-enclave-common` package:
-```bash
-sudo ego install libsgx-enclave-common
-```
 
-Or manually:
 ```bash
-wget -qO- https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add
-sudo add-apt-repository "deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu `lsb_release -cs` main"
+sudo mkdir -p /etc/apt/keyrings
+wget -qO- https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
+echo "deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/intel-sgx.list
+sudo apt update
 sudo apt install --no-install-recommends libsgx-enclave-common
 ```
 
 ## Attestation
+
 If EGo works in SGX mode (i.e., without `OE_SIMULATION`), but attestation fails, check the following.
 
 ### FLC
+
 Attestation only works on [SGX-FLC](#hardware) systems.
 
 ### Quote provider
+
 You must install a [quote provider](../reference/attest.md).
 
 ## Out of memory

docs/docs/reference/attest.md

@@ -1,54 +1,90 @@
 # Remote attestation
+
 Use *remote attestation* to verify that an EGo app is indeed running inside an enclave and to identify it by its hash.
 
 Attestation relies on external SGX services:
+
 * The *Provisioning Certificate Caching Service (PCCS)* caches attestation data from Intel. It's either operated by the cloud provider or must be hosted by yourself.
 * The *quote provider* helps EGo to connect to the PCCS. Both the attester and the verifier must install it.
 
-The required setup varies depending on the environment.
+## Set up the quote provider
+
+Install the quote provider on all machines that should host or verify EGo apps:
 
-## Azure
-Azure operates a PCCS. Use it by installing the Azure DCAP client as quote provider:
 ```bash
-sudo ego install az-dcap-client
+sudo mkdir -p /etc/apt/keyrings
+wget -qO- https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
+echo "deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/intel-sgx.list
+sudo apt update
+sudo apt install libsgx-dcap-default-qpl
 ```
-Or manually:
+
+Locate its configuration file at `/etc/sgx_default_qcnl.conf`.
+If the file doesn't exist or is outdated, download it with the following command:
+
 ```bash
-wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add
-sudo add-apt-repository "deb [arch=amd64] https://packages.microsoft.com/ubuntu/`lsb_release -rs`/prod `lsb_release -cs` main"
-sudo apt install az-dcap-client
+wget -qO- https://raw.githubusercontent.com/intel/SGXDataCenterAttestationPrimitives/master/QuoteGeneration/qpl/sgx_default_qcnl.conf | sudo tee /etc/sgx_default_qcnl.conf > /dev/null
 ```
 
-## Alibaba Cloud
-Alibaba operates a PCCS that can be used with the default quote provider.
-1. Install the default quote provider:
-   ```bash
-   sudo ego install libsgx-dcap-default-qpl
-   ```
-   Or manually by following the [guide from Open Enclave](https://github.com/openenclave/openenclave/blob/master/docs/GettingStartedDocs/Contributors/NonAccMachineSGXLinuxGettingStarted.md#3-set-up-intel-dcap-quote-provider-library-qpl).
+You can configure the quote provider to get the collaterals from the Intel PCS, the PCCS of your cloud service provider (CSP), or your own PCCS.
+
+### Intel PCS (verifier only)
+
+:::note
+
+This method only supports verification. For configuring machines that host EGo apps, choose one of the other methods.
+
+:::
+
+Using the Intel PCS is the simplest and most generic way for verifying, but it may be slower and less reliable than a PCCS.
+Configure it by uncommenting the `"collateral_service"` key:
+
+```json
+  ,"collateral_service": "https://api.trustedservices.intel.com/sgx/certification/v4/"
+```
+
+### PCCS of your CSP
 
-1. Set the `PCCS_URL` in `/etc/sgx_default_qcnl.conf` as explained in [Alibaba's documentation](https://www.alibabacloud.com/help/doc-detail/208095.htm#step-fn4-02q-tj4)
+If you're running an EGo app in the cloud, it's recommended to use the PCCS of your CSP.
+Set the `"pccs_url"` value to the respective address:
 
-## On-premises or other cloud
-You must host a PCCS yourself and use the default quote provider to connect to it.
+* Azure: `https://global.acccache.azure.net/sgx/certification/v4/`
+
+  See the [Azure documentation](https://learn.microsoft.com/en-us/azure/security/fundamentals/trusted-hardware-identity-management#how-do-i-use-intel-qpl-with-trusted-hardware-identity-management) for more information on configuring the quote provider.
+
+* Alibaba: `https://sgx-dcap-server.[Region-ID].aliyuncs.com/sgx/certification/v4/`
+
+  See the [Alibaba documentation](https://www.alibabacloud.com/help/en/ecs/user-guide/build-an-sgx-encrypted-computing-environment) for supported Region-ID values and more information on configuring the quote provider.
+
+### Your own PCCS
+
+If you're running an EGo app on premises, you must host a PCCS yourself.
+
+#### Set up the PCCS
+
+To set up a PCCS, you can either follow [the instructions from Intel](https://www.intel.com/content/www/us/en/developer/articles/guide/intel-software-guard-extensions-data-center-attestation-primitives-quick-install-guide.html) or use our provided Docker image.
+
+To do the latter, follow these steps:
 
-### Set up the PCCS
 1. Register with [Intel](https://api.portal.trustedservices.intel.com/provisioning-certification) to get a PCCS API key
-1. Run the PCCS:
+2. Run the PCCS:
+
    ```bash
    docker run -e APIKEY=<your-API-key> -p 8081:8081 --name pccs -d ghcr.io/edgelesssys/pccs
    ```
-1. Verify that the PCCS is running:
+
+3. Verify that the PCCS is running:
+
    ```bash
-   curl -kv https://localhost:8081/sgx/certification/v3/rootcacrl
+   curl -kv https://localhost:8081/sgx/certification/v4/rootcacrl
    ```
+
    You should see a 200 status code.
 
-### Set up the quote provider
-1. Install the default quote provider:
-   ```bash
-   sudo ego install libsgx-dcap-default-qpl
-   ```
-   Or manually by following the [guide from Open Enclave](https://github.com/openenclave/openenclave/blob/master/docs/GettingStartedDocs/Contributors/NonAccMachineSGXLinuxGettingStarted.md#3-set-up-intel-dcap-quote-provider-library-qpl).
+#### Configure the quote provider
+
+In the configuration file, set the `"pccs_url"` value to the address of your PCCS.
 
-1. If the PCCS runs on another machine than the quote provider, change the host of the `PCCS_URL` in `/etc/sgx_default_qcnl.conf` to the PCCS machine.
+If your PCCS runs with a certificate not signed by a trusted CA, you need to set `"use_secure_cert"` to `false`.
+This instructs the quote provider to accept a self-signed certificate of the PCCS.
+It doesn't affect the security of the remote attestation process itself.

docs/styles/Vocab/edgeless/accept.txt

@@ -2,6 +2,7 @@ Alibaba
 attestable
 cgo
 [Cc]loud
+collateral
 debuggable
 dereference
 env
@@ -12,6 +13,7 @@ SignerID
 signerid
 syscall
 tmpfs
+uncomment
 UniqueID
 uniqueid
 untrusted