Introduce sgx.remote_attestation = "[none|epid|dcap]"

This commit deprecates ambiguous `sgx.remote_attestation = true` in favor of an explicit attestation-type string. The first side benefit of this change is that the weird logic "if ra_client_spid is set, then it is EPID otherwise DCAP" is gone. The second side benefit is that this allows us to add more SGX quote formats in the future, if needed. Also, a new pseudo-file `/dev/attestation/attestation_type` is introduced at the LibOS level. It helps the application to determine which attestation scheme should be used. Several CI examples are rewritten to use the new syntax: Python, ra-tls-mbedlts, ra-tls-secret-prov, Busybox (the latter is purely for testing purposes). The `attestation` LibOS regression test also uses the new syntax; the old syntax is tested via the newly added test `attestation_deprecated_syntax`. Signed-off-by: Dmitrii Kuvaiskii <[email protected]>
gramineproject · Jun 21, 2022 · 5faa9eb · 5faa9eb
1 parent 63d8dca
commit 5faa9eb
Show file tree

Hide file tree

Showing 38 changed files with 547 additions and 244 deletions.
diff --git a/.ci/lib/stage-test-sgx.jenkinsfile b/.ci/lib/stage-test-sgx.jenkinsfile
@@ -9,7 +9,7 @@ stage('test-sgx') {
     timeout(time: 5, unit: 'MINUTES') {
         sh '''
             cd CI-Examples/python
-            RA_CLIENT_SPID=${ra_client_spid} make ${MAKEOPTS}
+            make ${MAKEOPTS} RA_TYPE=epid RA_CLIENT_SPID=${ra_client_spid}
             make ${MAKEOPTS} check
         '''
     }
@@ -102,12 +102,10 @@ stage('test-sgx') {
             cd CI-Examples/ra-tls-mbedtls
             if [ "${ra_client_spid}" != "" ] && [ "${ra_client_key}" != "" ]; \
             then \
-                make check_epid RA_CLIENT_SPID=${ra_client_spid} \
-                                        RA_TLS_EPID_API_KEY=${ra_client_key} \
-                                        RA_CLIENT_LINKABLE=0; \
-                make check_epid_fail RA_CLIENT_SPID=${ra_client_spid} \
-                                            RA_TLS_EPID_API_KEY=${ra_client_key} \
-                                            RA_CLIENT_LINKABLE=0; \
+                make check_epid RA_TYPE=epid RA_CLIENT_SPID=${ra_client_spid} \
+                    RA_TLS_EPID_API_KEY=${ra_client_key} RA_CLIENT_LINKABLE=0; \
+                make check_epid_fail RA_TYPE=epid RA_CLIENT_SPID=${ra_client_spid} \
+                    RA_TLS_EPID_API_KEY=${ra_client_key} RA_CLIENT_LINKABLE=0; \
             else \
                 echo "Failure: no ra_client_spid and/or ra_client_key!"; \
                 exit 1; \
@@ -119,9 +117,8 @@ stage('test-sgx') {
             cd CI-Examples/ra-tls-secret-prov
             if [ "${ra_client_spid}" != "" ] && [ "${ra_client_key}" != "" ]; \
             then \
-                make SGX=1 check_epid RA_CLIENT_SPID=${ra_client_spid} \
-                                        RA_TLS_EPID_API_KEY=${ra_client_key} \
-                                        RA_CLIENT_LINKABLE=0; \
+                make check_epid RA_TYPE=epid RA_CLIENT_SPID=${ra_client_spid} \
+                    RA_TLS_EPID_API_KEY=${ra_client_key} RA_CLIENT_LINKABLE=0; \
             else \
                 echo "Failure: no ra_client_spid and/or ra_client_key!"; \
                 exit 1; \

diff --git a/.ci/lib/stage-test.jenkinsfile b/.ci/lib/stage-test.jenkinsfile
@@ -15,7 +15,7 @@ stage('test') {
         try {
             sh '''
                 cd LibOS/test/regression
-                RA_CLIENT_SPID=${ra_client_spid} gramine-test build -v
+                RA_TYPE=epid RA_CLIENT_SPID=${ra_client_spid} gramine-test build -v
                 python3 -m pytest -v --junit-xml libos-regression.xml
             '''
         } finally {
@@ -31,7 +31,8 @@ stage('test') {
                     cd LibOS/test/regression
                     # For some unknown reason it fails without this clean on sgx-18.04 pipeline
                     gramine-test clean
-                    RA_CLIENT_SPID=${ra_client_spid} gramine-test -n tests_musl.toml build -v
+                    RA_TYPE=epid RA_CLIENT_SPID=${ra_client_spid} \
+                        gramine-test -n tests_musl.toml build -v
                     python3 -m pytest -v --junit-xml libos-regression-musl.xml
                 '''
             } finally {

diff --git a/CI-Examples/busybox/Makefile b/CI-Examples/busybox/Makefile
@@ -13,6 +13,9 @@ else
 GRAMINE_LOG_LEVEL = error
 endif
 
+RA_TYPE ?= none
+RA_CLIENT_SPID ?=
+RA_CLIENT_LINKABLE ?= 0
 
 .PHONY: all
 all: busybox busybox.manifest
@@ -44,6 +47,9 @@ busybox.manifest: busybox.manifest.template
 	gramine-manifest \
 		-Dlog_level=$(GRAMINE_LOG_LEVEL) \
 		-Darch_libdir=$(ARCH_LIBDIR) \
+		-Dra_type=$(RA_TYPE) \
+		-Dra_client_spid=$(RA_CLIENT_SPID) \
+		-Dra_client_linkable=$(RA_CLIENT_LINKABLE) \
 		$< > $@
 
 # Make on Ubuntu <= 20.04 doesn't support "Rules with Grouped Targets" (`&:`),

diff --git a/CI-Examples/busybox/README.md b/CI-Examples/busybox/README.md
@@ -3,6 +3,34 @@
 This directory contains the Makefile and the template manifest for the most
 recent version of Busybox (as of this writing, commit ac78f2ac96).
 
+## Building with SGX remote attestation
+
+If you want to try out [`/dev/attestation/` files][attestation], you must build
+the example with SGX remote attestation enabled. By default, the example is
+built *without* remote attestation.
+
+[attestation]: https://gramine.readthedocs.io/en/latest/attestation.html
+
+If you want to build the example for DCAP attestation, first make sure you have
+a working DCAP setup. Then build the example as follows:
+```
+make SGX=1 RA_TYPE=dcap
+```
+
+Otherwise, you will probably want to use EPID attestation. For this, you will
+additionally need to provide an SPID and specify whether it is set up for
+linkable quotes or not:
+```
+make SGX=1 RA_TYPE=epid RA_CLIENT_SPID=12345678901234567890123456789012 \
+    RA_CLIENT_LINKABLE=0
+```
+
+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
+
 # Quick Start
 
 ```sh

diff --git a/CI-Examples/busybox/busybox.manifest.template b/CI-Examples/busybox/busybox.manifest.template
@@ -22,6 +22,10 @@ fs.mounts = [
 
 sgx.debug = true
 
+sgx.remote_attestation = "{{ ra_type }}"
+sgx.ra_client_spid = "{{ ra_client_spid }}"
+sgx.ra_client_linkable = {{ 'true' if ra_client_linkable == '1' else 'false' }}
+
 sgx.trusted_files = [
   "file:{{ gramine.libos }}",
   "file:busybox",

diff --git a/CI-Examples/python/Makefile b/CI-Examples/python/Makefile
@@ -12,11 +12,18 @@ ifeq ($(SGX),1)
 all: python.manifest.sgx python.sig python.token
 endif
 
+RA_TYPE ?= none
+RA_CLIENT_SPID ?=
+RA_CLIENT_LINKABLE ?= 0
+
 python.manifest: python.manifest.template
 	gramine-manifest \
 		-Dlog_level=$(GRAMINE_LOG_LEVEL) \
 		-Darch_libdir=$(ARCH_LIBDIR) \
 		-Dentrypoint=$(realpath $(shell sh -c "command -v python3")) \
+		-Dra_type=$(RA_TYPE) \
+		-Dra_client_spid=$(RA_CLIENT_SPID) \
+		-Dra_client_linkable=$(RA_CLIENT_LINKABLE) \
 		$< >$@
 
 # Make on Ubuntu <= 20.04 doesn't support "Rules with Grouped Targets" (`&:`),

diff --git a/CI-Examples/python/README.md b/CI-Examples/python/README.md
@@ -18,18 +18,25 @@ Run `make` (non-debug) or `make DEBUG=1` (debug) in the directory.
 
 ## Building for SGX
 
-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.
+Run `make SGX=1` (non-debug) or `make SGX=1 DEBUG=1` (debug) in the directory.
 
-If you do have DCAP set up, run `make SGX=1` (non-debug) or
-`make SGX=1 DEBUG=1` (debug) in this directory.
+If you want to run the `scripts/sgx-quote.py` script, you must build the example
+with SGX remote attestation enabled. By default, the example is built *without*
+remote attestation.
+
+If you want to build the example for DCAP attestation, first make sure you have
+a working DCAP setup. Then build the example as follows:
+```
+make SGX=1 RA_TYPE=dcap
+```
 
 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:
+additionally 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
+make SGX=1 RA_TYPE=epid RA_CLIENT_SPID=12345678901234567890123456789012 \
+    RA_CLIENT_LINKABLE=0
 ```
 
 The above dummy values will suffice for simple experiments, but if you wish to

diff --git a/CI-Examples/python/python.manifest.template b/CI-Examples/python/python.manifest.template
@@ -28,9 +28,9 @@ sgx.enclave_size = "512M"
 sys.stack.size = "2M"
 sgx.thread_num = 32
 
-sgx.remote_attestation = true
-sgx.ra_client_spid = "{{ env.get('RA_CLIENT_SPID', '') }}"
-sgx.ra_client_linkable = {{ 'true' if env.get('RA_CLIENT_LINKABLE', '0') == '1' else 'false' }}
+sgx.remote_attestation = "{{ ra_type }}"
+sgx.ra_client_spid = "{{ ra_client_spid }}"
+sgx.ra_client_linkable = {{ 'true' if ra_client_linkable == '1' else 'false' }}
 
 sgx.trusted_files = [
   "file:{{ gramine.libos }}",

diff --git a/CI-Examples/python/scripts/sgx-quote.py b/CI-Examples/python/scripts/sgx-quote.py
@@ -8,9 +8,12 @@ def tohex(b):
 
 if not os.path.exists("/dev/attestation/user_report_data"):
     print("Cannot find `/dev/attestation/user_report_data`; "
-          "are you running under SGX?")
+          "are you running under SGX, with remote attestation enabled?")
     sys.exit(1)
 
+with open('/dev/attestation/attestation_type') as f:
+    print(f"Detected attestation type: {f.read()}")
+
 with open("/dev/attestation/user_report_data", "wb") as f:
     f.write(b'\0'*64)
 

diff --git a/CI-Examples/ra-tls-mbedtls/Makefile b/CI-Examples/ra-tls-mbedtls/Makefile
@@ -3,11 +3,6 @@ GRAMINE_PKGLIBDIR ?= /usr/lib/x86_64-linux-gnu/gramine # this is debian/ubuntu s
 
 ARCH_LIBDIR ?= /lib/$(shell $(CC) -dumpmachine)
 
-# for EPID attestation, specify your SPID and linkable/unlinkable attestation policy;
-# for DCAP/ECDSA attestation, specify SPID as empty string (linkable value is ignored)
-RA_CLIENT_SPID ?=
-RA_CLIENT_LINKABLE ?= 0
-
 ifeq ($(DEBUG),1)
 GRAMINE_LOG_LEVEL = debug
 CFLAGS += -O0 -ggdb3
@@ -19,6 +14,10 @@ endif
 CFLAGS += -fPIE
 LDFLAGS += -pie
 
+RA_TYPE ?= none
+RA_CLIENT_SPID ?=
+RA_CLIENT_LINKABLE ?= 0
+
 .PHONY: all
 all: app epid  # by default, only build EPID because it doesn't rely on additional (DCAP) libs
 
@@ -93,6 +92,7 @@ server.manifest: server.manifest.template
 	gramine-manifest \
 		-Dlog_level=$(GRAMINE_LOG_LEVEL) \
 		-Darch_libdir=$(ARCH_LIBDIR) \
+		-Dra_type=$(RA_TYPE) \
 		-Dra_client_spid=$(RA_CLIENT_SPID) \
 		-Dra_client_linkable=$(RA_CLIENT_LINKABLE) \
 		$< > $@
@@ -155,7 +155,7 @@ client_epid.token: client_epid.sig
 
 .PHONY: check_epid
 check_epid: app epid
-	gramine-sgx server epid & SERVER_ID=$$!; \
+	gramine-sgx server & SERVER_ID=$$!; \
 	sleep 30; \
 	./client epid > OUTPUT; \
 	./client epid 0 0 0 0 >> OUTPUT; \
@@ -168,14 +168,14 @@ check_epid: app epid
 
 .PHONY: check_epid_fail
 check_epid_fail: app epid
-	gramine-sgx server epid dummy-option >/dev/null & SERVER_ID=$$!; \
+	gramine-sgx server dummy-option >/dev/null & SERVER_ID=$$!; \
 	sleep 30; \
 	./client epid && exit 1 || echo "[ Success 1/1 ]"; \
 	kill -9 $$SERVER_ID
 
 .PHONY: check_dcap
 check_dcap: app dcap
-	gramine-sgx server dcap >/dev/null & SERVER_ID=$$!; \
+	gramine-sgx server >/dev/null & SERVER_ID=$$!; \
 	sleep 30; \
 	./client dcap > OUTPUT; \
 	./client dcap 0 0 0 0 >> OUTPUT; \
@@ -188,7 +188,7 @@ check_dcap: app dcap
 
 .PHONY: check_dcap_fail
 check_dcap_fail: app dcap
-	gramine-sgx server dcap dummy-option >/dev/null & SERVER_ID=$$!; \
+	gramine-sgx server dummy-option >/dev/null & SERVER_ID=$$!; \
 	sleep 30; \
 	./client dcap && exit 1 || echo "[ Success 1/1 ]"; \
 	kill -9 $$SERVER_ID

diff --git a/CI-Examples/ra-tls-mbedtls/README.md b/CI-Examples/ra-tls-mbedtls/README.md
@@ -4,11 +4,11 @@ This directory contains the Makefile, the template server manifest, and the
 minimal server and client written against the mbedTLS library.
 
 The server and client are based on `ssl_server.c` and `ssl_client1.c` example
-programs shipped with mbedTLS. We modified them to allow using RA-TLS flows if
-the programs are given the command-line argument `epid`/`dcap`.  In particular,
-the server uses a self-signed RA-TLS cert with the SGX quote embedded in it via
-`ra_tls_create_key_and_crt()`. The client uses an RA-TLS verification callback
-to verify the server RA-TLS certificate via `ra_tls_verify_callback()`.
+programs shipped with mbedTLS. We modified them to allow using RA-TLS flows. In
+particular, the server uses a self-signed RA-TLS cert with the SGX quote
+embedded in it via `ra_tls_create_key_and_crt()`. The client uses an RA-TLS
+verification callback to verify the server RA-TLS certificate via
+`ra_tls_verify_callback()`.
 
 This example uses the RA-TLS libraries `ra_tls_attest.so` for server and
 `ra_tls_verify_epid.so`/ `ra_tls_verify_dcap.so` for client. These libraries are
@@ -24,14 +24,12 @@ https://gramine.readthedocs.io/en/latest/attestation.html.
 ## RA-TLS server
 
 The server is supposed to run in the SGX enclave with Gramine and RA-TLS
-dlopen-loaded. If RA-TLS library `ra_tls_attest.so` is not requested by user via
-`epid`/`dcap` command-line argument, the server falls back to using normal X.509
-PKI flows (specified as `native` command-line argument).
+dlopen-loaded. If the server is started not in the SGX enclave, then it falls
+back to using normal X.509 PKI flows.
 
-If server is run with more command-line arguments (the only important thing is
-to have at least one additional argument), then the server will maliciously
-modify the SGX quote before sending to the client. This is useful for testing
-purposes.
+If server is run with a command-line argument (the only important thing is to
+have at least one argument), then the server will maliciously modify the SGX
+quote before sending to the client. This is useful for testing purposes.
 
 ## RA-TLS client
 
@@ -78,7 +76,7 @@ an [SPID and the corresponding IAS API keys][spid].
 
 ```sh
 make app
-./server native &
+./server &
 ./client native
 # client will successfully connect to the server via normal x.509 PKI flows
 kill %%
@@ -88,9 +86,10 @@ kill %%
 
 ```sh
 make clean
-RA_CLIENT_SPID=<your SPID> RA_CLIENT_LINKABLE=<1 if SPID is linkable, else 0> make app epid
+make app epid RA_TYPE=epid RA_CLIENT_SPID=<your SPID> \
+    RA_CLIENT_LINKABLE=<1 if SPID is linkable, else 0>
 
-gramine-sgx ./server epid &
+gramine-sgx ./server &
 
 RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 \
 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
@@ -109,9 +108,9 @@ kill %%
 
 ```sh
 make clean
-make app dcap
+make app dcap RA_TYPE=dcap
 
-gramine-sgx ./server dcap &
+gramine-sgx ./server &
 
 RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 \
 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
@@ -129,9 +128,9 @@ kill %%
 
 ```sh
 make clean
-make app dcap
+make app dcap RA_TYPE=dcap
 
-gramine-sgx ./server dcap &
+gramine-sgx ./server &
 
 RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 ./client dcap \
     <MRENCLAVE of the server enclave> \
@@ -147,9 +146,9 @@ kill %%
 
 ```sh
 make clean
-make app dcap
+make app dcap RA_TYPE=dcap
 
-gramine-sgx ./server dcap dummy-option &
+gramine-sgx ./server dummy-option &
 ./client dcap
 
 # client will fail to verify the malicious SGX quote and will *not* connect to the server
@@ -165,11 +164,14 @@ as `RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE`, `RA_TLS_ALLOW_OUTDATED_TCB_INSECURE`,
 
 ```sh
 make clean
-RA_CLIENT_SPID=<your SPID> RA_CLIENT_LINKABLE=<1 if SPID is linkable, else 0> make app client_epid.manifest.sgx
+make app epid RA_TYPE=epid RA_CLIENT_SPID=<your SPID> \
+    RA_CLIENT_LINKABLE=<1 if SPID is linkable, else 0>
 
-gramine-sgx ./server epid &
+gramine-sgx ./server &
 
-RA_TLS_EPID_API_KEY=<your EPID API key> gramine-sgx ./client_epid epid
+RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
+    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 %%
@@ -179,12 +181,12 @@ kill %%
 
 ```sh
 make clean
-make app dcap
+make app dcap RA_TYPE=dcap
 
-gramine-sgx ./server dcap &
+gramine-sgx ./server &
 
-RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 gramine-sgx \
-    ./client_dcap dcap \
+RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
+    gramine-sgx ./client_dcap dcap \
     <MRENCLAVE of the server enclave> \
     <MRSIGNER of the server enclave> \
     <ISV_PROD_ID of the server enclave> \