[PAL/Linux-SGX] Add more envvars to verify SGX quote statuses

Intel IAS and ECDSA/DCAP verification procedures may return different
SGX quote statuses, that can be roughly divided into three classes:
1. Outdated TCB (old hardware, needs an update),
2. HW configuration needed (good hardware, but must change some BIOS
   settings like disabling Hyper-Threading),
3. SW configuration needed (hardware is known to be vulnerable to some
   kinds of exploits and this could be fixed only by using good/patched
   software).

Previously, Gramine's RA-TLS had a single environment variable
`RA_TLS_ALLOW_OUTDATED_TCB_INSECURE` to allow/disallow all three
classes. This commit introduces two more envvars.

Signed-off-by: Dmitrii Kuvaiskii <dmitrii.kuvaiskii@intel.com>

Author: Dmitrii Kuvaiskii

.ci/lib/config.jenkinsfile

@@ -8,6 +8,8 @@ env.XDG_CONFIG_HOME = env.WORKSPACE + '/XDG_CONFIG_HOME'
 env.CARGO_HOME = env.WORKSPACE + '/CARGO_HOME'
 
 env.RA_TLS_ALLOW_OUTDATED_TCB_INSECURE = '1'
+env.RA_TLS_ALLOW_HW_CONFIG_NEEDED = '1'
+env.RA_TLS_ALLOW_SW_HARDENING_NEEDED = '1'
 env.RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE = '1'
 
 env.LC_ALL = 'C.UTF-8'

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

@@ -55,11 +55,12 @@ 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.
+Moreover, we set `RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1`,
+`RA_TLS_ALLOW_HW_CONFIG_NEEDED=1` and `RA_TLS_ALLOW_SW_HARDENING_NEEDED=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). Note that in production environments, you must carefully
+analyze whether to use these options!
 
 # Quick Start
 
@@ -72,6 +73,14 @@ an [SPID and the corresponding IAS API keys][spid].
 
 [spid]: https://gramine.readthedocs.io/en/latest/sgx-intro.html#term-spid
 
+For all examples, we set the following environment variables:
+```sh
+export RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1
+export RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1
+export RA_TLS_ALLOW_HW_CONFIG_NEEDED=1
+export RA_TLS_ALLOW_SW_HARDENING_NEEDED=1
+```
+
 - Normal non-RA-TLS flows; without SGX and without Gramine:
 
 ```sh
@@ -91,8 +100,6 @@ make app epid RA_TYPE=epid RA_CLIENT_SPID=<your SPID> \
 
 gramine-sgx ./server &
 
-RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 \
-RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
 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> \
@@ -112,8 +119,6 @@ make app dcap RA_TYPE=dcap
 
 gramine-sgx ./server &
 
-RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 \
-RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
 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> \
@@ -132,7 +137,7 @@ make app dcap RA_TYPE=dcap
 
 gramine-sgx ./server &
 
-RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 ./client dcap \
+./client dcap \
     <MRENCLAVE of the server enclave> \
     <MRSIGNER of the server enclave> \
     <ISV_PROD_ID of the server enclave> \
@@ -157,10 +162,8 @@ kill %%
 
 - RA-TLS flows with SGX and with Gramine, running EPID client in SGX:
 
-Note: you may also add environment variables to `client.manifest.template`, such
-as `RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE`, `RA_TLS_ALLOW_OUTDATED_TCB_INSECURE`,
-`RA_TLS_MRENCLAVE`, `RA_TLS_MRSIGNER`, `RA_TLS_ISV_PROD_ID` and
-`RA_TLS_ISV_SVN`.
+Note: you may need to add environment variables to `client.manifest.template`, such
+as `RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE`, `RA_TLS_MRENCLAVE`, etc.
 
 ```sh
 make clean
@@ -169,8 +172,7 @@ make app epid RA_TYPE=epid RA_CLIENT_SPID=<your SPID> \
 
 gramine-sgx ./server &
 
-RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
-    RA_TLS_EPID_API_KEY=<your EPID API key> \
+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
@@ -185,8 +187,7 @@ make app dcap RA_TYPE=dcap
 
 gramine-sgx ./server &
 
-RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
-    gramine-sgx ./client_dcap dcap \
+gramine-sgx ./client_dcap dcap \
     <MRENCLAVE of the server enclave> \
     <MRSIGNER of the server enclave> \
     <ISV_PROD_ID of the server enclave> \

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

@@ -41,11 +41,12 @@ 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.
+Moreover, we set `RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1`,
+`RA_TLS_ALLOW_HW_CONFIG_NEEDED=1` and `RA_TLS_ALLOW_SW_HARDENING_NEEDED=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). Note that in production environments, you must carefully
+analyze whether to use these options!
 
 ## Secret Provisioning clients
 
@@ -73,6 +74,14 @@ build time.
 
 # Quick Start
 
+For all examples, we set the following environment variables:
+```sh
+export RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1
+export RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1
+export RA_TLS_ALLOW_HW_CONFIG_NEEDED=1
+export RA_TLS_ALLOW_SW_HARDENING_NEEDED=1
+```
+
 - Secret Provisioning flows, EPID-based (IAS) attestation (you will need to
   provide an [SPID and the corresponding IAS API keys][spid]):
 
@@ -84,8 +93,6 @@ make app epid RA_TYPE=epid RA_CLIENT_SPID=<your SPID> \
 
 # test encrypted files client (other examples can be tested similarly)
 cd secret_prov_pf
-RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 \
-RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
 RA_TLS_EPID_API_KEY=<your EPID API key> \
 ./server_epid wrap_key &
 
@@ -101,8 +108,6 @@ make app dcap RA_TYPE=dcap
 
 # test encrypted files client (other examples can be tested similarly)
 cd secret_prov_pf
-RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE=1 \
-RA_TLS_ALLOW_OUTDATED_TCB_INSECURE=1 \
 ./server_dcap wrap_key &
 
 gramine-sgx ./client

Documentation/attestation.rst

@@ -326,17 +326,38 @@ against expected values stored in a central database).
 
 The library also uses the following SGX-specific environment variables:
 
-- ``RA_TLS_ALLOW_OUTDATED_TCB_INSECURE`` (optional) -- whether to allow outdated
-  TCB as returned in the IAS attestation report or returned by the DCAP
-  verification library. Value ``1`` means "allow outdated TCB". Note that
-  allowing outdated TCB is **insecure** and should be used only for debugging
-  and testing. Outdated TCB is not allowed by default.
+- ``RA_TLS_ALLOW_OUTDATED_TCB_INSECURE`` (optional) -- whether to allow
+  "outdated TCB" status as returned in the IAS attestation report or returned by
+  the DCAP verification library. Note that allowing outdated TCB is **insecure**
+  and should be used only for debugging and testing.
+
+- ``RA_TLS_ALLOW_HW_CONFIG_NEEDED`` (optional) -- whether to allow "HW
+  configuration needed" status. Note that this is not marked as insecure, as in
+  some situations a strictly-compliant HW configuration is not required.
+
+- ``RA_TLS_ALLOW_SW_HARDENING_NEEDED`` (optional) -- whether to allow "SW
+  hardening needed" status. Note that this is not marked as insecure, as in some
+  situations a strictly-compliant SW configuration is not required.
 
 - ``RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE`` (optional) -- whether to allow debug
-  enclaves (enclaves with ``SECS.ATTRIBUTES.DEBUG`` bit set to one). Value ``1``
-  means "allow debug enclaves". Note that allowing debug enclaves is
-  **insecure** and should be used only for debugging and testing. Debug enclaves
-  are not allowed by default.
+  enclaves (enclaves with ``SECS.ATTRIBUTES.DEBUG`` bit set to one). Note that
+  allowing debug enclaves is **insecure** and should be used only for debugging
+  and testing.
+
+Note that the IAS attestation report/DCAP verification library can return the
+"HW configuration and SW hardening needed" status. To allow this status, you
+must set both ``RA_TLS_ALLOW_HW_CONFIG_NEEDED`` and
+``RA_TLS_ALLOW_SW_HARDENING_NEEDED`` environment variables.
+
+Each of the above environment variables must be set to ``1`` to allow the
+corresponding status. By default, all of the above environment variables are not
+set, and thus all not-OK statuses are disallowed. For more information, please
+refer to the official Intel documentation:
+
+- `Intel EPID/IAS
+  <https://api.trustedservices.intel.com/documents/sgx-attestation-api-spec.pdf>`__
+- `Intel ECDSA/DCAP
+  <https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/Intel_SGX_ECDSA_QuoteLibReference_DCAP_API.pdf>`__
 
 The library uses the following EPID-specific environment variables if available:
 

Documentation/manpages/gramine-sgx-ias-verify-report.rst

@@ -40,14 +40,6 @@ Command line arguments
 
    Path to the IAS report's signature.
 
-.. option:: -o, --allow-outdated-tcb
-
-   Treat IAS status GROUP_OUT_OF_DATE as OK.
-
-.. option:: -d, --allow-debug-enclave
-
-   Allow debug enclave (SGXREPORT.ATTRIBUTES.DEBUG = 1).
-
 .. option:: -n, --nonce
 
    Nonce that's expected in the report (optional).
@@ -76,21 +68,40 @@ Command line arguments
 
    Path to IAS public RSA key (PEM format, optional).
 
+.. option:: --allow-debug-enclave
+
+   Allow debug enclave (SGXREPORT.ATTRIBUTES.DEBUG = 1).
+
+.. option:: --allow-outdated-tcb
+
+   Treat IAS status code GROUP_OUT_OF_DATE as OK.
+
+.. option:: --allow-hw-config-needed
+
+   Treat IAS status code CONFIGURATION_NEEDED as OK.
+
+.. option:: --allow-sw-hardening-needed
+
+   Treat IAS status code SW_HARDENING_NEEDED as OK.
+
+To treat the IAS status code CONFIGURATION_AND_SW_HARDENING_NEEDED as OK, set
+both :option:`--allow-hw-config-needed` and
+:option:`--allow-sw-hardening-needed` options.
+
 Example
 =======
 
-Report verification with all options enabled:
+Report verification with most options enabled:
 
 .. code-block:: sh
 
-    $ gramine-sgx-ias-verify-report -v -m -r rp -s sp -i ias.pem -o -d -n thisisnonce -S 14b284525c45c4f526bf1535d05bd88aa73b9e184464f2d97be3dabc0d187b57 -E 4d69102c40401f40a54eb156601be73fb7605db0601845580f036fd284b7b303 -R 0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004ba476e321e12c720000000000000001 -P 0 -V 0
+    $ gramine-sgx-ias-verify-report -v -m -r rp -s sp -i ias.pem -n thisisnonce -S 14b284525c45c4f526bf1535d05bd88aa73b9e184464f2d97be3dabc0d187b57 -E 4d69102c40401f40a54eb156601be73fb7605db0601845580f036fd284b7b303 -R 0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004ba476e321e12c720000000000000001 -P 0 -V 0
     Verbose output enabled
     Endianness set to MSB
     Using IAS public key from file 'ias.pem'
     IAS key: RSA, 2048 bits
     Decoded IAS signature size: 256 bytes
     IAS report: signature verified correctly
-    IAS report: allowing quote status GROUP_OUT_OF_DATE
     IAS report: nonce OK
     IAS report: quote decoded, size 432 bytes
     [...quote dump...]

tools/sgx/common/ias.c

@@ -620,9 +620,40 @@ int ias_send_quote_get_report_raw(struct ias_context_t* context, const void* quo
     return ret;
 }
 
+static int print_allowed_and_advisories(char* quote_status_str, cJSON* json) {
+    INFO("IAS report: allowing quote status %s\n", quote_status_str);
+
+    cJSON* url_node = cJSON_GetObjectItem(json, "advisoryURL");
+    if (url_node) {
+        if (url_node->type != cJSON_String) {
+            ERROR("Unexpected type of `advisoryURL` field (expected JSON string)\n");
+            return -1;
+        }
+        INFO("            [ advisory URL: %s ]\n", url_node->valuestring);
+    }
+
+    cJSON* ids_node = cJSON_GetObjectItem(json, "advisoryIDs");
+    if (ids_node) {
+        if (ids_node->type != cJSON_Array) {
+            ERROR("Unexpected type of `advisoryIDs` field (expected JSON array)\n");
+            return -1;
+        }
+        char* ids_str = cJSON_Print(ids_node);
+        if (!ids_str) {
+            ERROR("Failed to print `advisoryIDs` field\n");
+            return -1;
+        }
+        INFO("            [ advisory IDs: %s ]\n", ids_str);
+        free(ids_str);
+    }
+
+    return 0;
+}
+
 int ias_verify_report_extract_quote(const uint8_t* ias_report, size_t ias_report_size,
                                     uint8_t* ias_sig_b64, size_t ias_sig_b64_size,
-                                    bool allow_outdated_tcb, const char* nonce,
+                                    bool allow_outdated_tcb, bool allow_hw_config_needed,
+                                    bool allow_sw_hardening_needed, const char* nonce,
                                     const char* ias_pub_key_pem, char (*enclave_quote_status)[128],
                                     uint8_t** out_quote, size_t* out_quote_size) {
     mbedtls_pk_context ias_pub_key;
@@ -734,30 +765,15 @@ int ias_verify_report_extract_quote(const uint8_t* ias_report, size_t ias_report
     if (strcmp("OK", node->valuestring) == 0) {
         ret = 0;
         INFO("IAS report: quote status OK\n");
-    } else if (allow_outdated_tcb && (
-               strcmp("GROUP_OUT_OF_DATE", node->valuestring) == 0
-            || strcmp("CONFIGURATION_NEEDED", node->valuestring) == 0
-            || strcmp("SW_HARDENING_NEEDED", node->valuestring) == 0
-            || strcmp("CONFIGURATION_AND_SW_HARDENING_NEEDED", node->valuestring) == 0
-            )) {
-        ret = 0;
-        INFO("IAS report: allowing quote status %s\n", node->valuestring);
-
-        cJSON* url_node = cJSON_GetObjectItem(json, "advisoryURL");
-        if (url_node && url_node->type == cJSON_String)
-            INFO("            [ advisory URL: %s ]\n", url_node->valuestring);
-
-        cJSON* ids_node = cJSON_GetObjectItem(json, "advisoryIDs");
-        if (ids_node && ids_node->type == cJSON_Array) {
-            char* ids_str = cJSON_Print(ids_node);
-            if (!ids_str) {
-                ERROR("IAS report: out-of-memory during reading advisoryIDs\n");
-                ret = -1;
-                goto out;
-            }
-            INFO("            [ advisory IDs: %s ]\n", ids_str);
-            free(ids_str);
-        }
+    } else if (allow_outdated_tcb && strcmp("GROUP_OUT_OF_DATE", node->valuestring) == 0) {
+        ret = print_allowed_and_advisories(node->valuestring, json);
+    } else if (allow_hw_config_needed && strcmp("CONFIGURATION_NEEDED", node->valuestring) == 0) {
+        ret = print_allowed_and_advisories(node->valuestring, json);
+    } else if (allow_sw_hardening_needed && strcmp("SW_HARDENING_NEEDED", node->valuestring) == 0) {
+        ret = print_allowed_and_advisories(node->valuestring, json);
+    } else if (allow_hw_config_needed && allow_sw_hardening_needed
+                   && strcmp("CONFIGURATION_AND_SW_HARDENING_NEEDED", node->valuestring) == 0) {
+        ret = print_allowed_and_advisories(node->valuestring, json);
     }
 
     if (ret != 0) {

tools/sgx/common/ias.h

@@ -103,26 +103,31 @@ int ias_send_quote_get_report_raw(struct ias_context_t* context, const void* quo
  * \brief Verify IAS attestation report. Also extract the SGX quote contained in IAS report:
  *        allocate enough memory to hold the quote and pass it to the user.
  *
- * \param ias_report             IAS attestation verification report.
- * \param ias_report_size        Size of \p ias_report in bytes.
- * \param ias_sig_b64            IAS report signature (base64-encoded as returned by IAS).
- * \param ias_sig_b64_size       Size of \p ias_sig_b64 in bytes.
- * \param allow_outdated_tcb     Treat IAS status codes: GROUP_OUT_OF_DATE, CONFIGURATION_NEEDED,
- *                               SW_HARDENING_NEEDED, CONFIGURATION_AND_SW_HARDENING_NEEDED as OK.
- * \param nonce                  (Optional) Nonce that's expected in the report.
- * \param ias_pub_key_pem        (Optional) IAS public RSA key (PEM format, NULL-terminated).
- *                               If not specified, a hardcoded Intel's key is used.
- * \param enclave_quote_status   (Optional) If non-NULL, this contains the returned
- *                               `isvEnclaveQuoteStatus` string on enclave quote status verification
- *                               failure. The string may be truncated to fit into 128 bytes
- *                               (including the terminating NULL char).
- * \param[out] out_quote         Buffer with quote. User is responsible for freeing it.
- * \param[out] out_quote_size    Size of \p out_quote in bytes.
+ * \param ias_report                IAS attestation verification report.
+ * \param ias_report_size           Size of \p ias_report in bytes.
+ * \param ias_sig_b64               IAS report signature (base64-encoded as returned by IAS).
+ * \param ias_sig_b64_size          Size of \p ias_sig_b64 in bytes.
+ * \param allow_outdated_tcb        Treat IAS status code GROUP_OUT_OF_DATE as OK.
+ * \param allow_hw_config_needed    Treat IAS status code CONFIGURATION_NEEDED as OK.
+ * \param allow_sw_hardening_needed Treat IAS status code SW_HARDENING_NEEDED as OK.
+ * \param nonce                     (Optional) Nonce that's expected in the report.
+ * \param ias_pub_key_pem           (Optional) IAS public RSA key (PEM format, NULL-terminated).
+ *                                  If not specified, a hardcoded Intel's key is used.
+ * \param enclave_quote_status      (Optional) If non-NULL, this contains the returned
+ *                                  `isvEnclaveQuoteStatus` string on enclave quote status
+ *                                  verification failure. The string may be truncated to fit into
+ *                                  128 bytes (including the terminating NULL char).
+ * \param[out] out_quote            Buffer with quote. User is responsible for freeing it.
+ * \param[out] out_quote_size       Size of \p out_quote in bytes.
  *
  * \returns 0 on successful verification, negative value on error.
+ *
+ * To treat the IAS status code CONFIGURATION_AND_SW_HARDENING_NEEDED as OK, both
+ * \p allow_hw_config_needed and \p allow_sw_hardening_needed must be set to true.
  */
 int ias_verify_report_extract_quote(const uint8_t* ias_report, size_t ias_report_size,
                                     uint8_t* ias_sig_b64, size_t ias_sig_b64_size,
-                                    bool allow_outdated_tcb, const char* nonce,
+                                    bool allow_outdated_tcb, bool allow_hw_config_needed,
+                                    bool allow_sw_hardening_needed, const char* nonce,
                                     const char* ias_pub_key_pem, char (*enclave_quote_status)[128],
                                     uint8_t** out_quote, size_t* out_quote_size);

tools/sgx/ra-tls/ra_tls.h

@@ -14,6 +14,8 @@
 #define RA_TLS_EPID_API_KEY "RA_TLS_EPID_API_KEY"
 
 #define RA_TLS_ALLOW_OUTDATED_TCB_INSECURE  "RA_TLS_ALLOW_OUTDATED_TCB_INSECURE"
+#define RA_TLS_ALLOW_HW_CONFIG_NEEDED       "RA_TLS_ALLOW_HW_CONFIG_NEEDED"
+#define RA_TLS_ALLOW_SW_HARDENING_NEEDED    "RA_TLS_ALLOW_SW_HARDENING_NEEDED"
 #define RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE "RA_TLS_ALLOW_DEBUG_ENCLAVE_INSECURE"
 
 #define RA_TLS_MRSIGNER    "RA_TLS_MRSIGNER"