[Docs,CI-Examples] Document the SPID parameter

The way one was supposed to run RA-TLS was confusing before. Explain
what an SPID is, how to obtain one, and link to that documentation in
the READMEs of relevant examples.

Signed-off-by: Jakub Kądziołka <[email protected]>

CI-Examples/python/README.md

@@ -18,7 +18,25 @@ Run `make` (non-debug) or `make DEBUG=1` (debug) in the directory.
 
 ## Building for SGX
 
-Run `make SGX=1` (non-debug) or `make SGX=1 DEBUG=1` (debug) in the directory.
+To facilitate the `scripts/sgx-quote.py` example, the enclave is set up for
+remote attestation. By default it will be built for DCAP attestation, which
+means that you need a working DCAP setup to launch the enclave.
+
+If you do have DCAP set up, run `make SGX=1` (non-debug) or
+`make SGX=1 DEBUG=1` (debug) in this directory.
+
+Otherwise, you will probably want to use EPID attestation. For this, you will
+need to provide an SPID and specify whether it is set up for linkable quotes or not:
+
+```
+RA_CLIENT_SPID=12345678901234567890123456789012 RA_CLIENT_LINKABLE=0 make SGX=1
+```
+
+The above dummy values will suffice for simple experiments, but if you wish to
+run `sgx-quote.py` and verify the output, you will need to provide an
+[SPID recognized by Intel][spid].
+
+[spid]: https://gramine.readthedocs.io/en/latest/sgx-intro.html#term-spid
 
 ## Building with a local Python installation
 

CI-Examples/ra-tls-mbedtls/README.md

@@ -52,14 +52,28 @@ RA-TLS verification callback that compares `MRENCLAVE`, `MRSIGNER`,
 variables. To run the client with its own verification callback, execute it with
 four additional command-line arguments (see the source code for details).
 
-Also, because this example builds and uses debug SGX enclaves
-(`SIGSTRUCT.ATTRIBUTES.DEBUG` bit is set to one), we use environment variable
-`RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1`. Note that in production environments,
-you must *not* use this option!
+Also, because this example builds and uses debug SGX enclaves (`sgx.debug` is
+set to `true`), we use environment variable `RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1`.
+Note that in production environments, you must *not* use this option!
 
+Moreover, we set `RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1`, to allow performing
+the tests when some of Intel's security advisories haven't been addressed (for
+example, when the microcode or architectural enclaves aren't fully up-to-date).
+As the name of this setting suggests, this is not secure and likewise should not
+be used in production.
 
 # Quick Start
 
+In most of the examples below, you need to tell the client what values it should
+expect for `MRENCLAVE`, `MRSIGNER`, `ISV_PROD_ID` and `ISV_SVN`. One way to
+obtain them is to note them down when they get printed by `gramine-sgx-get-token`
+when generating `server.token`.
+
+Moreover, for EPID-based (IAS) attestation, you will need to provide
+an [SPID and the corresponding IAS API keys][spid].
+
+[spid]: https://gramine.readthedocs.io/en/latest/sgx-intro.html#term-spid
+
 - Normal non-RA-TLS flows; without SGX and without Gramine:
 
 ```sh
@@ -73,18 +87,18 @@ kill %%
 - RA-TLS flows with SGX and with Gramine, EPID-based (IAS) attestation:
 
 ```sh
-# replace dummy values with your SPID, linkable setting, API key, MRENCLAVE, etc!
 make clean
-RA_CLIENT_SPID=12345678901234567890123456789012 RA_CLIENT_LINKABLE=0 make app epid
+RA_CLIENT_SPID=<your SPID> RA_CLIENT_LINKABLE=<1 if SPID is linkable, else 0> make app epid
 
 gramine-sgx ./server epid &
 
 RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 \
 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
-RA_TLS_EPID_API_KEY=12345678901234567890123456789012 \
-RA_TLS_MRENCLAVE=1234567890123456789012345678901234567890123456789012345678901234 \
-RA_TLS_MRSIGNER=1234567890123456789012345678901234567890123456789012345678901234 \
-RA_TLS_ISV_PROD_ID=0 RA_TLS_ISV_SVN=0 \
+RA_TLS_EPID_API_KEY=<your EPID API key> \
+RA_TLS_MRENCLAVE=<MRENCLAVE of the server enclave> \
+RA_TLS_MRSIGNER=<MRSIGNER of the server enclave> \
+RA_TLS_ISV_PROD_ID=<ISV_PROD_ID of the server enclave> \
+RA_TLS_ISV_SVN=<ISV_SVN of the server enclave> \
 ./client epid
 
 # client will successfully connect to the server via RA-TLS/EPID flows
@@ -94,17 +108,17 @@ kill %%
 - RA-TLS flows with SGX and with Gramine, ECDSA-based (DCAP) attestation:
 
 ```sh
-# replace dummy values with your MRENCLAVE, MRSIGNER, etc!
 make clean
 make app dcap
 
 gramine-sgx ./server dcap &
 
 RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 \
 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
-RA_TLS_MRENCLAVE=1234567890123456789012345678901234567890123456789012345678901234 \
-RA_TLS_MRSIGNER=1234567890123456789012345678901234567890123456789012345678901234 \
-RA_TLS_ISV_PROD_ID=0 RA_TLS_ISV_SVN=0 \
+RA_TLS_MRENCLAVE=<MRENCLAVE of the server enclave> \
+RA_TLS_MRSIGNER=<MRSIGNER of the server enclave> \
+RA_TLS_ISV_PROD_ID=<ISV_PROD_ID of the server enclave> \
+RA_TLS_ISV_SVN=<ISV_SVN of the server enclave> \
 ./client dcap
 
 # client will successfully connect to the server via RA-TLS/DCAP flows
@@ -114,17 +128,16 @@ kill %%
 - RA-TLS flows with SGX and with Gramine, client with its own verification callback:
 
 ```sh
-# replace dummy values with your MRENCLAVE, MRSIGNER, etc!
 make clean
 make app dcap
 
 gramine-sgx ./server dcap &
 
-# arguments are: MRENCLAVE in hex, MRSIGNER in hex, ISV_PROD_ID as dec, ISV_SVN as dec
 RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 ./client dcap \
-    1234567890123456789012345678901234567890123456789012345678901234 \
-    1234567890123456789012345678901234567890123456789012345678901234 \
-    0 0
+    <MRENCLAVE of the server enclave> \
+    <MRSIGNER of the server enclave> \
+    <ISV_PROD_ID of the server enclave> \
+    <ISV_SVN of the server enclave>
 
 # client will successfully connect to the server via RA-TLS/DCAP flows
 kill %%
@@ -152,11 +165,11 @@ as `RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE`, `RA_TLS_ALLOW_OUTDATED_TCB_INSECURE`,
 
 ```sh
 make clean
-RA_CLIENT_SPID=12345678901234567890123456789012 RA_CLIENT_LINKABLE=0 make app client_epid.manifest.sgx
+RA_CLIENT_SPID=<your SPID> RA_CLIENT_LINKABLE=<1 if SPID is linkable, else 0> make app client_epid.manifest.sgx
 
 gramine-sgx ./server epid &
 
-RA_TLS_EPID_API_KEY=12345678901234567890123456789012 gramine-sgx ./client_epid epid
+RA_TLS_EPID_API_KEY=<your EPID API key> gramine-sgx ./client_epid epid
 
 # client will successfully connect to the server via RA-TLS/EPID flows
 kill %%
@@ -172,9 +185,10 @@ gramine-sgx ./server dcap &
 
 RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 gramine-sgx \
     ./client_dcap dcap \
-    1234567890123456789012345678901234567890123456789012345678901234 \
-    1234567890123456789012345678901234567890123456789012345678901234 \
-    0 0
+    <MRENCLAVE of the server enclave> \
+    <MRSIGNER of the server enclave> \
+    <ISV_PROD_ID of the server enclave> \
+    <ISV_SVN of the server enclave>
 
 # client will successfully connect to the server via RA-TLS/DCAP flows
 kill %%

CI-Examples/ra-tls-secret-prov/README.md

@@ -27,11 +27,16 @@ There are two versions of the server: the EPID one and the DCAP one. Each of
 them links against the corresponding EPID/DCAP secret-provisioning library at
 build time.
 
-Because this example builds and uses debug SGX enclaves
-(`SIGSTRUCT.ATTRIBUTES.DEBUG` bit is set to one), we use environment variable
-`RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1`. Note that in production environments,
+Because this example builds and uses debug SGX enclaves (`sgx.debug` is set
+to `true`), we use environment variable `RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1`.
+Note that in production environments,
 you must *not* use this option!
 
+Moreover, we set `RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1`, to allow performing
+the tests when some of Intel's security advisories haven't been addressed (for
+example, when the microcode or architectural enclaves aren't fully up-to-date).
+As the name of this setting suggests, this is not secure and likewise should not
+be used in production.
 
 ## Secret Provisioning clients
 
@@ -59,14 +64,17 @@ build time.
 
 # Quick Start
 
-- Secret Provisioning flows, EPID-based (IAS) attestation:
+- Secret Provisioning flows, EPID-based (IAS) attestation (you will need to
+  provide an [SPID and the corresponding IAS API keys][spid]):
+
+[spid]: https://gramine.readthedocs.io/en/latest/sgx-intro.html#term-spid
 
 ```sh
-RA_CLIENT_SPID=12345678901234567890123456789012 RA_CLIENT_LINKABLE=0 make app epid files/input.txt
+RA_CLIENT_SPID=<your SPID> RA_CLIENT_LINKABLE=<1 if SPID is linkable, else 0> make app epid files/input.txt
 
 RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 \
 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
-RA_TLS_EPID_API_KEY=12345678901234567890123456789012 \
+RA_TLS_EPID_API_KEY=<your EPID API key> \
 ./secret_prov_server_epid &
 
 # test minimal client

Documentation/sgx-intro.rst

@@ -250,10 +250,11 @@ SGX terminology
       has a |~| reference launch enclave and is backed by the DCAP-enabled SGX
       driver.
 
-      This allows for launching enclaves without Intel's remote infrastructure.
-      But this requires deployment of own infrastructure, so is operationally
-      more complicated. Therefore it is intended for server environments (where
-      you control all the machines).
+      This allows for launching enclaves with Intel's remote infrastructure
+      only involved in the initial setup. Naturally however, this requires
+      deployment of own infrastructure, so is operationally more complicated.
+      Therefore it is intended for server environments (where you control all
+      the machines).
 
       .. seealso::
 
@@ -286,18 +287,40 @@ SGX terminology
    Enhanced Privacy Identifier
    EPID
 
-      .. todo:: short description
+      EPID is the attestation protocol originally shipped with SGX. Unlike
+      :term:`DCAP`, a |~| remote verifier making use of the EPID protocol needs
+      to contact the :term:`Intel Attestation Service` each time it wishes
+      to attest an |~| enclave.
 
       Contrary to DCAP, EPID may be understood as "opinionated", with most
       moving parts fixed and tied to services provided by Intel. This is
       intended for client enclaves and deprecated for server environments.
 
+      EPID attestation can operate in two modes: *fully-anonymous (unlinkable)
+      quotes* and *pseudonymous (linkable) quotes*.  Unlike fully-anonymous
+      quotes, pseudonymous quotes include an |~| identifier dependent on the
+      identity of the CPU and the developer of the enclave being quoted, which
+      allows determining whether two instances of your enclave are running on
+      the same hardware or not.
+
+      If your security model depends on enforcing that the identifiers are
+      different (e.g. because you want to prevent sybil attacks), keep in mind
+      that the enclave host can generate a new identity by performing an
+      epoch reset. The previous identity will then become inaccessible, though.
+
+      The attestation mode being used can be chosen by the application enclave,
+      but it must match what was chosen when generating the :term:`SPID`.
+
       .. seealso::
 
          :term:`DCAP`
             A way to launch enclaves without relying on the Intel's
             infrastructure.
 
+         :term:`SPID`
+            An identifier one can obtain from Intel, required to make use of EPID
+            attestation.
+
    Flexible Launch Control
    FLC
 
@@ -510,6 +533,17 @@ SGX terminology
 
       Encompasses at least :term:`EDMM`, but is still work in progress.
 
+   Service Provider ID
+   SPID
+
+      An identifier provided by Intel, used together with an |~| :term:`EPID`
+      API key to authenticate to the :term:`Intel Attestation Service`. You can
+      obtain an |~| SPID through Intel's `Trusted Services Portal
+      <https://api.portal.trustedservices.intel.com/EPID-attestation>`_.
+
+      See :term:`EPID` for a |~| description of the difference between *linkable*
+      and *unlinkable* quotes.
+
    State Save Area
    SSA