From 7a511bf7f60034a7ef7dc445457687ff3061ba9c Mon Sep 17 00:00:00 2001 From: Dmitrii Kuvaiskii Date: Wed, 17 Feb 2021 01:36:43 -0800 Subject: [PATCH] fixup! [Docs] Add documentation on Attestation --- Documentation/attestation.rst | 195 ++++++++++++------------ Documentation/glossary.rst | 29 ++++ Documentation/sgx-intro.rst | 75 ++++++++- Pal/src/host/Linux-SGX/tools/README.rst | 190 +++-------------------- 4 files changed, 223 insertions(+), 266 deletions(-) diff --git a/Documentation/attestation.rst b/Documentation/attestation.rst index b0c2f527..d93712b0 100644 --- a/Documentation/attestation.rst +++ b/Documentation/attestation.rst @@ -2,35 +2,38 @@ Attestation =========== Graphene is typically used to create and run Trusted Execution Environments -(TEEs). A very important aspect of a TEE is *attestation*. Broadly speaking, -attestation is a mechanism for a remote user to verify that the application runs -in a correct up-to-date TEE and that the code and data residing inside the TEE -have the expected by the user contents (at least during TEE start-up). +(:term:`TEE`). A very important aspect of a TEE is :term:`Attestation`. Broadly +speaking, attestation is a mechanism for a remote user to verify that the +application runs in a correct, up-to-date TEE and that the code and data +residing inside the TEE have the expected by the user contents (at least during +TEE start-up). -Attestation can be local (when two TEEs run on the same physical machine) and -remote (when a user attests a TEE running on a remote physical machine). In the -following, we discuss only *remote attestation*. Moreover, even though Graphene -attestation flows are designed to be TEE-agnostic, we discuss only *Intel SGX* -remote attestation flows. +There are two types of attestation: :term:`Local Attestation` and +:term:`Remote Attestation`. Local attestation is used when two TEEs run on the +same physical machine and remote attestation is used when a user attests a TEE +running on a remote physical machine. In the following, we discuss only +:term:`Remote Attestation`. Moreover, even though Graphene attestation flows are +designed to be TEE-agnostic, we discuss only :term:`SGX` remote attestation +flows (the SGX flows are currently the only ones implemented). By itself, attestation only provides the assurance to the user that the remotely executing TEE is trusted, that the correct code is executed and that the data is processed securely. In addition to this assurance, the user needs to create a -*secure channel* for trusted communication with the remote TEE. In many cases, -the user also wants *secret provisioning* to transparently provision secret keys -and other sensitive data to the remote TEE. +:term:`Secure Channel` for trusted communication with the remote TEE. In many +cases, the user also wants :term:`Secret Provisioning` to transparently +provision secret keys and other sensitive data to the remote TEE. Graphene provides support for all three levels of attestation flows: -#. *Remote attestation* is exposed to the application via ``/dev/attestation`` - pseudo-filesystem. Remote attestation in Graphene uses the Intel SGX PSW's - AESM service and the Intel DCAP libraries under the hood. +#. :term:`Remote Attestation` is exposed to the application via + ``/dev/attestation`` pseudo-filesystem. Remote attestation in Graphene uses + the Intel SGX PSW's AESM service and the Intel DCAP libraries under the hood. -#. *Secure channels* are constructed using the RA-TLS libraries. *RA-TLS* uses - raw ``/dev/attestation`` pseudo-files under the hood. +#. :term:`Secure Channel` is constructed using the RA-TLS libraries. + :term:`RA-TLS` uses raw ``/dev/attestation`` pseudo-files under the hood. -#. *Secret provisioning* services are built using the Secret Provisioning - libraries. These libraries use RA-TLS under the hood. +#. :term:`Secret Provisioning` is built using the Secret Provisioning libraries. + These libraries use RA-TLS under the hood. Applications running under Graphene can use each of the above three levels to build their attestation flows. Each next level builds on the previous one and @@ -42,8 +45,9 @@ Low-level ``/dev/attestation`` interface ---------------------------------------- The first level of the ``/dev/attestation`` pseudo-filesystem exposes the -low-level abstractions of *attestation report* and *attestation quote* objects, -in the form of two pseudo-files: +low-level abstractions of *attestation report* and *attestation quote* objects +(:term:`SGX Report` and :term:`SGX Quote` in SGX parlance), in the form of two +pseudo-files: - ``/dev/attestation/user_report_data`` pseudo-file can be opened for read or write access. Typically, it is opened and written into before opening and @@ -58,19 +62,23 @@ in the form of two pseudo-files: The resulting quote can be passed to another TEE or service as part of the remote attestation flow. In case of Intel SGX, the obtained quote is the SGX - quote created by the Quoting Enclave. + quote created by the :term:`Quoting Enclave`. Using these two files, the user application may construct arbitrary attestation flows. Typically, the application will write some unique identifier of the TEE into ``/dev/attestation/user_report_data``, such that when the remote user receives the SGX quote (with user report data embedded), the remote user can tie the TEE instance to this identifier. Typically, user report data contains a -secure hash of the unique private key generated by the TEE instance. +secure hash of the unique public key generated by the TEE instance. In case of Intel SGX, the ``/dev/attestation/user_report_data`` pseudo-file uses the ``EREPORT`` hardware instruction and the ``/dev/attestation/quote`` pseudo-file uses the Quoting Enclave accessed via the AESM service. +Please note that these files are process-local, so there is no need to add +locking between processes when setting the user report data or reading the +quote. + An example of this low-level interface can be found under ``LibOS/shim/test/regression/attestation.c``. Here is a C code snippet of how the remote attestation flow may look like in your application:: @@ -80,38 +88,36 @@ the remote attestation flow may look like in your application:: int fd1 = open("/dev/attestation/user_report_data", O_WRONLY); write(fd1, &user_report_data, sizeof(user_report_data)); - close(fd1); uint8_t quote[SGX_QUOTE_MAX_SIZE]; int fd2 = open("/dev/attestation/quote", O_RDONLY); read(fd2, "e, sizeof(quote)); - close(fd2); /* ...send `quote` to the remote user for verification... */ The remote user should receive this attestation quote and verify it. In case of Intel SGX, this verification flow depends on whether the SGX remote attestation -is EPID-based or DCAP/ECDSA-based: +is EPID based or DCAP/ECDSA based: -- *EPID-based quote verification* is done with the help of the Intel Attestation - Service (IAS). In particular, the remote user should forward the received SGX - quote to the well-known IAS endpoint via a secure internet connection and get - the *IAS attestation report* (not to be confused with SGX report!) back. The - user then should examine the contents of the IAS attestation report and decide - whether to trust the remote SGX enclave or not. +- :term:`EPID` based quote verification is done with the help of the Intel + Attestation Service (:term:`IAS`). In particular, the remote user should + forward the received SGX quote to the well-known IAS endpoint via a secure + internet connection and get the IAS attestation report (not to be confused + with SGX report!) back. The user then should examine the contents of the IAS + attestation report and decide whether to trust the remote SGX enclave or not. -- *DCAP/ECDSA-based quote verification* is done with the help of the Intel DCAP +- :term:`DCAP` based quote verification is done with the help of the Intel DCAP libraries. These libraries encapsulate the complicated DCAP flows (extracting - Intel SGX certificates from the Intel Provisioning Certification Service, - caching these certificates in the Provisioning Certificate Caching Service, - etc.). + Intel SGX certificates from the + :term:`Intel Provisioning Certification Service`, caching these certificates + in the Provisioning Certificate Caching Service, etc.). Graphene does *not* provide any pseudo-files under ``/dev/attestation`` for verification of the attestation quote. Instead, the remote user is encouraged to use the :program:`quote_dump`, :program:`ias_request` and :program:`verify_ias_report` tools shipped together with Graphene (for -EPID-based quote verification) or to use the Intel DCAP libraries and tools (for -DCAP-based quote verification). +EPID based quote verification) or to use the Intel DCAP libraries and tools (for +DCAP based quote verification). Mid-level RA-TLS interface @@ -123,19 +129,19 @@ provide any convenient interface for user-side quote verification. Also, that low-level interface provides no means to transfer any data to/from the TEE other than the attestation quote itself. -RA-TLS interface hides the complexity of the low-level ``/dev/attestation`` -flows and provides a simple and powerful abstraction of a TLS connection between -the TEE and the remote user (enhanced with remote-attestation flows). Using -RA-TLS, the application can securely send and receive arbitrary data to/from the -remote user. RA-TLS is currently tied to Intel SGX but can be adapted for other -TEEs. +:term:`RA-TLS` interface hides the complexity of the low-level +``/dev/attestation`` flows and provides a simple and powerful abstraction of a +TLS connection between the TEE and the remote user (enhanced with +remote-attestation flows). Using RA-TLS, the application can securely send and +receive arbitrary data to/from the remote user. RA-TLS is currently tied to +Intel SGX but can be adapted for other TEEs. RA-TLS integrates Intel SGX remote attestation into the TLS connection setup. Conceptually, it extends the standard X.509 certificate with SGX-related information (SGX quote). The additional information allows the remote user (verifier) of the certificate to verify that it is indeed communicating with an SGX enclave (attester). RA-TLS is shipped as three libraries: -``ra_tls_attest.so``, EPID-based ``ra_tls_verify_epid.so`` and DCAP/ECDSA-based +``ra_tls_attest.so``, EPID based ``ra_tls_verify_epid.so`` and DCAP/ECDSA based ``ra_tls_verify_dcap.so``. The examples of using RA-TLS can be found under ``Examples/ra-tls-mbedtls``. @@ -143,23 +149,23 @@ The examples of using RA-TLS can be found under ``Examples/ra-tls-mbedtls``. ``ra_tls_attest.so`` ^^^^^^^^^^^^^^^^^^^^ -This library creates the self-signed RA-TLS certificate. It must be loaded into -the SGX enclave. This library relies on the pseudo-FS ``/dev/attestation`` to -retrieve the SGX quote and embed it into the RA-TLS certificate. The library is -typically linked into server applications; it is *not* thread-safe. +This library creates the self-signed RA-TLS certificate. This library must be +loaded into the SGX enclave. The library relies on the pseudo-FS +``/dev/attestation`` to retrieve the SGX quote and embed it into the RA-TLS +certificate. The library is *not* thread-safe. -The library expects the following information in the manifest for EPID-based +The library expects the following information in the manifest for EPID based attestation: - ``sgx.remote_attestation = 1`` -- remote attestation is enabled. - ``sgx.ra_client_spid`` -- client SPID for EPID remote attestation. -- ``sgx.ra_client_linkable`` -- client linkable/unlinkable attestation policy. +- ``sgx.ra_client_linkable`` -- client linkable/unlinkable attestation mode. -For ECDSA-based (DCAP) attestation, the library expects instead: +For DCAP/ECDSA based attestation, the library expects instead: - ``sgx.remote_attestation = 1`` -- remote attestation is enabled. -- ``sgx.ra_client_spid = ""`` -- hints that this is a DCAP - attestation, *not* EPID attestation. +- ``sgx.ra_client_spid = ""`` -- hints that this is a DCAP attestation, *not* + EPID attestation. The library uses the following environment variables if available: @@ -177,18 +183,18 @@ This library contains the verification callback that should be registered with the TLS library during verification of the TLS certificate. It verifies the RA-TLS certificate and the SGX quote by sending it to the Intel Attestation Service (IAS) and retrieving the attestation report from IAS. This library is -typically linked into client applications; it is *not* thread-safe. +*not* thread-safe. The library uses the following SGX-specific environment variables, representing SGX measurements, if available: -- ``RA_TLS_MRSIGNER`` (optional) -- verify that the server enclave has this +- ``RA_TLS_MRSIGNER`` (optional) -- verify that the attesting enclave has this ``MRSIGNER``. This is a hex string. -- ``RA_TLS_MRENCLAVE`` (optional) -- verify that the server enclave has this +- ``RA_TLS_MRENCLAVE`` (optional) -- verify that the attesting enclave has this ``MRENCLAVE``. This is a hex string. -- ``RA_TLS_ISV_PROD_ID`` (optional) -- verify that the server enclave has this - ``ISV_PROD_ID``. This is a decimal string. -- ``RA_TLS_ISV_SVN`` (optional) -- verify that the server enclave has this +- ``RA_TLS_ISV_PROD_ID`` (optional) -- verify that the attesting enclave has + this ``ISV_PROD_ID``. This is a decimal string. +- ``RA_TLS_ISV_SVN`` (optional) -- verify that the attesting enclave has this ``ISV_SVN``. This is a decimal string. The four SGX measurements above may be also verified via a user-specified @@ -226,8 +232,7 @@ Similarly to ``ra_tls_verify_epid.so``, this library contains the verification callback that should be registered with the TLS library during verification of the TLS certificate. Verifies the RA-TLS certificate and the SGX quote by forwarding it to DCAP verification library (``libsgx_dcap_quoteverify.so``) and -checking the result. This library is typically linked into client applications; -it is *not* thread-safe. +checking the result. This library is *not* thread-safe. The library uses the same SGX-specific environment variables as ``ra_tls_verify_epid.so`` and ignores the EPID-specific environment variables. @@ -250,27 +255,27 @@ same key to encrypt the outputs. Such an application doesn't need a TLS communication with the remote user but simply a way to securely obtain this single key from a well-known location. -This is the scenario where the high-level Secret Provisioning interface comes -into play. Secret Provisioning is shipped together with Graphene in the form of -(helper) shared libraries. These libraries are reference implementations for the -flows to provision secrets from a trusted machine (server, verifier) to an -enclavized application (client, attester). These libraries rely heavily on +This is the scenario where the high-level :term:`Secret Provisioning` interface +comes into play. Secret Provisioning is shipped together with Graphene in the +form of (helper) shared libraries. These libraries are reference implementations +for the flows to provision secrets from a trusted machine (service, verifier) to +an enclavized application (client, attester). These libraries rely heavily on RA-TLS and re-use the same configuration parameters as listed in the previous section. Secret Provisioning libraries hide the complexity of RA-TLS but use it under the hood for communication between the enclavized application and the trusted -server. Conceptually, a client application and a trusted server establish a -secure RA-TLS communication channel via TLS mutual attestation. The server sends -its normal X.509 certificate for verification by client, whereas the client -sends its RA-TLS X.509 certificate with the SGX quote for verification by -server. After this mutual attestation, the trust is established, and the server -provisions the secrets to the client. The established TLS channel may be either -closed after provisioning these initial secrets or may be further used by both -parties for continued secure communication. +service. Conceptually, a client application and a trusted service establish a +secure RA-TLS communication channel via TLS mutual attestation. The service +sends its normal X.509 certificate for verification by client, whereas the +client sends its RA-TLS X.509 certificate with the SGX quote for verification by +the service. After this mutual attestation, the trust is established, and the +service provisions the secrets to the client. The established TLS channel may be +either closed after provisioning these initial secrets or may be further used by +both parties for continued secure communication. Secret Provisioning is shipped as three libraries: ``secret_prov_attest.so``, -EPID-based ``secret_prov_verify_epid.so`` and ECDSA-based (DCAP) +EPID based ``secret_prov_verify_epid.so`` and DCAP/ECDSA based ``secret_prov_verify_dcap.so``. The examples of using RA-TLS can be found under ``Examples/ra-tls-secret-prov``. @@ -280,14 +285,14 @@ well as provisioning of an encryption key and its later use for protected files. ``secret_prov_attest.so`` ^^^^^^^^^^^^^^^^^^^^^^^^^ -This library is typically linked into client (enclavized) applications. The -application calls into this library to initiate the RA-TLS session with the -remote trusted server for secret provisioning. Alternatively, the library runs -before application's entry point, initializes the RA-TLS session, receives the -secret and stashes it in an environment variable -``SECRET_PROVISION_SECRET_STRING``. In both cases, the application may call -into the library to continue secure communication with the trusted server and/or -to retrieve the secret. This library is *not* thread-safe. +This library is typically linked into enclavized applications. The application +calls into this library to initiate the RA-TLS session with the remote trusted +service for secret provisioning. Alternatively, the library runs before +application's entry point, initializes the RA-TLS session, receives the secret +and stashes it in an environment variable ``SECRET_PROVISION_SECRET_STRING``. +In both cases, the application may call into the library to continue secure +communication with the trusted party and/or to retrieve the secret. This +library is *not* thread-safe. The library expects the same configuration information in the manifest and environment variables as RA-TLS. In addition, the library uses the following @@ -326,15 +331,15 @@ The secret may be retrieved by the application in two ways: ``secret_prov_verify_epid.so`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This library is typically linked into a (normal non-enclavized) -secret-provisioning server service. The server calls into this library to -listen for clients in an endless loop. When a new client connects, the server -initiates an RA-TLS session with the client, verifies the RA-TLS X.509 -certificate of the client, and provisions the secret to the client if -verification is successful. The server can register a callback to continue -secure communication with the client (instead of simply closing the session -after the first secret is sent to the client). This library is *not* -thread-safe. This library uses EPID-based RA-TLS flows underneath. +This library is typically linked into a normal, non-enclavized application +(secret provisioning service). The service calls into this library to listen for +clients in an endless loop. When a new client connects, the service initiates an +RA-TLS session with the client, verifies the RA-TLS X.509 certificate of the +client, and provisions the secret to the client if verification is successful. +The service can register a callback to continue secure communication with the +client (instead of simply closing the session after the first secret is sent to +the client). This library is *not* thread-safe. This library uses EPID based +RA-TLS flows underneath. The library expects the same configuration information in the manifest and environment variables as RA-TLS. @@ -343,8 +348,8 @@ environment variables as RA-TLS. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Similarly to ``secret_prov_verify_epid.so``, this library is used in -secret-provisioning servers. The only difference is that this library uses -DCAP-based RA-TLS flows underneath. +secret-provisioning services. The only difference is that this library uses +DCAP based RA-TLS flows underneath. The library uses the same SGX-specific environment variables as ``secret_prov_verify_epid.so`` and ignores the EPID-specific environment diff --git a/Documentation/glossary.rst b/Documentation/glossary.rst index fcb04d71..773a00e5 100644 --- a/Documentation/glossary.rst +++ b/Documentation/glossary.rst @@ -21,6 +21,35 @@ Glossary is host-platform agnostic and is backed by the host-platform specific PAL, for example, the Linux-SGX PAL. + RA-TLS + A library to augment classic SSL/TLS sessions with + :term:`Remote Attestation`. RA-TLS extends the SSL/TLS handshake protocol + to force one endpoint into verifying the :term:`SGX Quote` embedded into + the other endpoint's certificate chain. RA-TLS is designed to be a drop-in + replacement for classic SSL/TLS libraries. + + .. seealso:: + + :doc:`attestation` + + Secret Provisioning + Secret provisioning is a mechanism to deliver secrets (such as encryption + keys, passwords, etc.) from a remote trusted party inside a :term:`TEE`. + It is typically built on top of a :term:`Secure Channel`. + + .. seealso:: + + :doc:`attestation` + + Secure Channel + Secure channels are communication channels for trusted transmission of + arbitrary data between a :term:`TEE` and a remote trusted party or between + two TEEs. They are typically built on top of the classic TLS/SSL channels. + + .. seealso:: + + :doc:`attestation` + SGX Software Guard Extensions is a set of instructions on Intel processors for creating Trusted Execution Environments (:term:`TEE`). See diff --git a/Documentation/sgx-intro.rst b/Documentation/sgx-intro.rst index f6cc027f..88e67987 100644 --- a/Documentation/sgx-intro.rst +++ b/Documentation/sgx-intro.rst @@ -187,7 +187,8 @@ SGX terminology AE A |~| set of "system" enclaves concerned with starting and attesting other - enclaves. + enclaves. Intel provides reference implementations of these enclaves, + though other companies may write their own implementations. .. seealso:: @@ -202,10 +203,25 @@ SGX terminology .. todo:: TBD Attestation - .. todo:: TBD + + Attestation is a mechanism to prove the correctness of the SGX enclave to + a local or remote party. There are two types of the attestation: + :term:`Local Attestation` and :term:`Remote Attestation`. For local + attestation, the attesting SGX enclave collects attestation evidence in + the form of an :term:`SGX Report` using the EREPORT hardware instruction. + For remote attestation, the attesting SGX enclave collects attestation + evidence in the form of an :term:`SGX Quote` using the :term:`Quoting + Enclave` (and the :term:`Provisioning Enclave` if required). The enclave + then may send the collected attestation evidence to the local or remote + party, which will verify the evidence and confirm the correctness of the + attesting enclave. After this, the local or remote party trusts the + enclave and may establish a secure channel with the enclave and send + secrets to it. .. seealso:: + :doc:`attestation` + :term:`Local Attestation` Description of Local Attestation @@ -302,7 +318,15 @@ SGX terminology :term:`Architectural Enclaves` Local Attestation - .. todo:: TBD + + In local attestation, the attesting SGX enclave collects attestation + evidence in the form of an :term:`SGX Report` using the EREPORT hardware + instruction. This form of attestation is used to send the attestation + evidence to a local party (on the same physical machine). + + .. seealso:: + + :doc:`attestation` Intel Attestation Service IAS @@ -362,14 +386,29 @@ SGX terminology Quoting Enclave - .. todo:: TBD + One of the Architectural Enclaves of the Intel SGX software + infrastructure. It is part of the :term:`SGX Platform Software`. The + Quoting Enclave receives an :term:`SGX Report` and produces a + corresponding :term:`SGX Quote`. The identity of the Quoting Enclave is + publicly known (it signer, its measurements and its attributes) and is + vetted by public companies such as Intel (in the form of the certificate + chain ending in a publicly known root certificate of the company). .. seealso:: :term:`Architectural Enclaves` Remote Attestation - .. todo:: TBD + + In remote attestation, the attesting SGX enclave collects attestation + evidence in the form of an :term:`SGX Quote` using the :term:`Quoting + Enclave` (and the :term:`Provisioning Enclave` if required). This form of + attestation is used to send the attestation evidence to a remote party + (not on the same physical machine). + + .. seealso:: + + :doc:`attestation` Intel SGX Software Development Kit Intel SGX SDK @@ -386,6 +425,27 @@ SGX terminology .. todo:: TBD + SGX Quote + + The SGX quote is the proof of correctness of the enclave and is used + during :term:`Remote Attestation`. The attesting enclave generates the + enclave-specific :term:`SGX Report`, sends the request to the + :term:`Quoting Enclave` using :term:`Local Attestation`, and the Quoting + Enclave returns back the SGX quote with the SGX report embedded in it. The + resulting SGX quote contains the enclave's measurements, attributes and + other security-relevant fields, and is signed by a publicly known key of + the :term:`Quoting Enclave` to prove its authenticity. The obtained SGX + quote may be later sent to the verifying remote party, which examines the + SGX quote and gains trust in the remote enclave. + + SGX Report + + The SGX report is a data structure that contains enclave measurements, + signer identity, attributes and a user-defined 64B string. The SGX report + is generated using the ``EREPORT`` hardware instruction. It is used during + :term:`Local Attestation`. The SGX report is embedded into the + :term:`SGX Quote`. + SGX2 This refers to all new SGX instructions and other hardware features that @@ -406,7 +466,10 @@ SGX terminology Trusted Execution Environment TEE - .. todo:: TBD + A Trusted Execution Environment (TEE) is an environment where the code + executed and the data accessed is isolated and protected in terms of + confidentiality (no one have access to the data) and integrity (no one can + change the code and its behavior). Trusted Computing Base TCB diff --git a/Pal/src/host/Linux-SGX/tools/README.rst b/Pal/src/host/Linux-SGX/tools/README.rst index a995300d..c7b0dc99 100644 --- a/Pal/src/host/Linux-SGX/tools/README.rst +++ b/Pal/src/host/Linux-SGX/tools/README.rst @@ -163,177 +163,37 @@ Example report verification with all options enabled:: RA-TLS Libraries ---------------- -RA-TLS integrates Intel SGX remote attestation into the TLS connection setup. Conceptually, it -extends the standard X.509 certificate with SGX-related information. The additional information -allows the receiver (verifier) of the certificate to verify that it is indeed communicating with -an SGX enclave (attester). RA-TLS is shipped as three libraries: ``ra_tls_attest.so``, EPID-based -``ra_tls_verify_epid.so`` and ECDSA-based (DCAP) ``ra_tls_verify_dcap.so``. +RA-TLS integrates Intel SGX remote attestation into the TLS connection setup. +Conceptually, it extends the standard X.509 certificate with SGX-related +information. The additional information allows the receiver (verifier) of the +certificate to verify that it is indeed communicating with an SGX enclave +(attester). RA-TLS is shipped as three libraries: ``ra_tls_attest.so``, +EPID-based ``ra_tls_verify_epid.so`` and ECDSA-based (DCAP) +``ra_tls_verify_dcap.so``. -``ra_tls_attest.so`` -^^^^^^^^^^^^^^^^^^^^ - -This library creates the self-signed RA-TLS certificate. It must be loaded into the SGX enclave. -This library relies on the pseudo-FS ``/dev/attestation`` to retrieve the SGX quote and embed it -into the RA-TLS certificate. Typically linked into server applications. Not thread-safe. - -The library expects the following information in the manifest for EPID-based attestation: - -- ``sgx.remote_attestation = 1`` -- remote attestation is enabled. -- ``sgx.ra_client_spid`` -- client SPID for EPID remote attestation. -- ``sgx.ra_client_linkable`` -- client linkable/unlinkable attestation policy. - -For ECDSA-based (DCAP) attestation, the library expects instead: - -- ``sgx.remote_attestation = 1`` -- remote attestation is enabled. -- ``sgx.ra_client_spid = ""`` -- it is DCAP attestation, *not* EPID attestation. - -The library uses the following environment variables if available: - -- ``RA_TLS_CERT_TIMESTAMP_NOT_BEFORE`` -- the generated RA-TLS certificate uses this - timestamp-not-before value, in the format "20010101000000" (this is also the default value if - environment variable is not available). -- ``RA_TLS_CERT_TIMESTAMP_NOT_AFTER`` -- the generated RA-TLS certificate uses this - timestamp-not-after value, in the format "20301231235959" (this is also the default value if - environment variable is not available). - -``ra_tls_verify_epid.so`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -This library contains the verification callback that should be registered with the TLS library -during verification of the TLS certificate. It verifies the RA-TLS certificate and the SGX quote by -sending it to the Intel Attestation Service (IAS) and retrieving the attestation report from IAS. -Typically linked into client applications. Not thread-safe. - -The library uses the following SGX-specific environment variables, representing SGX measurements, -if available: - -- ``RA_TLS_MRSIGNER`` (optional) -- verify that the server enclave has this ``MRSIGNER``. This is a - hex string. -- ``RA_TLS_MRENCLAVE`` (optional) -- verify that the server enclave has this ``MRENCLAVE``. This is - a hex string. -- ``RA_TLS_ISV_PROD_ID`` (optional) -- verify that the server enclave has this ``ISV_PROD_ID``. - This is a decimal string. -- ``RA_TLS_ISV_SVN`` (optional) -- verify that the server enclave has this ``ISV_SVN``. This is a - decimal string. - -The four SGX measurements above may be also verified via a user-specified callback with the -signature ``int (*callback)(char* mrenclave, char* mrsigner, char* isv_prod_id, char* isv_svn)``. -This callback must be registered via ``ra_tls_set_measurement_callback()``. The measurements from -the received SGX quote are passed as four arguments. It is up to the user to implement the correct -verification of SGX measurements in this callback (e.g., by comparing against expected values stored -in a central database). - -The library also uses the following SGX-specific environment variable: - -- ``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. Values ``1/true/TRUE`` - mean "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. - -The library uses the following EPID-specific environment variables if available: - -- ``RA_TLS_EPID_API_KEY`` (mandatory) -- client API key for EPID remote attestation. -- ``RA_TLS_IAS_REPORT_URL`` (optional) -- URL for IAS "verify attestation evidence" API endpoint. - If not specified, the default hard-coded URL for IAS is used. -- ``RA_TLS_IAS_SIGRL_URL`` (optional) -- URL for IAS "Retrieve SigRL" API endpoint. If not - specified, the default hard-coded URL for IAS is used. -- ``RA_TLS_IAS_PUB_KEY_PEM`` (optional) -- public key of IAS. If not specified, the default - hard-coded public key is used. - -``ra_tls_verify_dcap.so`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Similarly to ``ra_tls_verify_epid.so``, this library contains the verification callback that -should be registered with the TLS library during verification of the TLS certificate. Verifies -the RA-TLS certificate and the SGX quote by forwarding it to DCAP verification library -(``libsgx_dcap_quoteverify.so``) and checking the result. Typically linked into client -applications. Not thread-safe. - -The library uses the same SGX-specific environment variables as ``ra_tls_verify_epid.so`` and -ignores the EPID-specific environment variables. Similarly to the EPID version, instead of using -environment variables, the four SGX measurements may be verified via a user-specified callback -registered via ``ra_tls_set_measurement_callback()``. - -The library expects all the DCAP infrastructure to be installed and working correctly on the host. +For more information on RA-TLS, please read the ``Attestation`` documentation of +Graphene. Secret Provisioning Libraries ----------------------------- -Secret Provisioning libraries are reference implementations for the flows to provision secrets from -a trusted machine (server, verifier) to an enclavized application (client, attester). These -libraries rely heavily on RA-TLS and re-use the same configuration parameters as listed above. +Secret Provisioning libraries are reference implementations for the flows to +provision secrets from a trusted machine (service, verifier) to an enclavized +application (client, attester). These libraries rely heavily on RA-TLS. -Conceptually, a client application and a trusted server establish a secure RA-TLS communication -channel via TLS mutual attestation. The server sends its normal X.509 certificate for verification -by client, whereas the client sends its RA-TLS X.509 certificate with SGX-related information for -verification by server. After this mutual attestation, the trust is established, and the server -provisions the secrets to the client. The established TLS channel may be either closed after -provisioning these initial secrets or may be further used by both parties for continued secure -communication. +Conceptually, a client application and a trusted service establish a secure +RA-TLS communication channel via TLS mutual attestation. The service sends its +normal X.509 certificate for verification by client, whereas the client sends +its RA-TLS X.509 certificate with SGX-related information for verification by +the service. After this mutual attestation, the trust is established, and the +service provisions the secrets to the client. The established TLS channel may be +either closed after provisioning these initial secrets or may be further used by +both parties for continued secure communication. -Secret Provisioning is shipped as three libraries: ``secret_prov_attest.so``, EPID-based -``secret_prov_verify_epid.so`` and ECDSA-based (DCAP) ``secret_prov_verify_dcap.so``. +Secret Provisioning is shipped as three libraries: ``secret_prov_attest.so``, +EPID-based ``secret_prov_verify_epid.so`` and ECDSA-based (DCAP) +``secret_prov_verify_dcap.so``. -``secret_prov_attest.so`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -This library is typically linked into client (enclavized) applications. The application calls into -this library to initiate the RA-TLS session with the remote trusted server for secret provisioning. -Alternatively, the library runs before application's entry point, initializes the RA-TLS session, -receives the secret and stashes it in an environment variable ``SECRET_PROVISION_SECRET_STRING``. -In both cases, the application may call into the library to continue secure communication with the -trusted server and/or to retrieve the secret. This library is not thread-safe. - -The library expects the same configuration information in the manifest and environment variables as -RA-TLS. In addition, the library uses the following environment variables if available: - -- ``SECRET_PROVISION_CONSTRUCTOR`` (optional) -- set it to ``1/true/TRUE`` to initialize the - RA-TLS session and retrieve the secret before the application starts. By default, it is not set, - thus secret provisioning must be explicitly requested by the application. - -- ``SECRET_PROVISION_SET_PF_KEY`` (optional) -- set it to ``1/true/TRUE`` to indicate that the - provisioned secret is a protected-files master key. The key must be a 32-char null-terminated - AES-GCM encryption key in hex format, similar to ``sgx.protected_files_key`` manifest option. - This environment variable is checked only if ``SECRET_PROVISION_CONSTRUCTOR`` is set. - -- ``SECRET_PROVISION_SERVERS`` (optional) -- a comma, semicolon or space separated list of server - names with ports to connect to for secret provisioning. Example: - ``localhost:4433;trusted-server:443``. If not set, defaults to ``localhost:4433``. - Alternatively, the application can specify it as an argument of ``secret_provision_start()``. - -- ``SECRET_PROVISION_CA_CHAIN_PATH`` (required) -- a path to the CA chain of certificates to verify - the server. Alternatively, the application can specify it as an argument of - ``secret_provision_start()``. - -The secret may be retrieved by the application in two ways: - -- Reading ``SECRET_PROVISION_SECRET_STRING`` environment variable. It is updated only if - ``SECRET_PROVISION_CONSTRUCTOR`` is set to true and if the secret is representable as a string of - maximum 4K characters. -- Calling ``secret_provision_get()`` function. It always updates its pointer argument to the secret - (or ``NULL`` if secret provisioning failed). - -``secret_prov_verify_epid.so`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This library is typically linked into a (normal non-enclavized) secret-provisioning server service. -The server calls into this library to listen for clients in an endless loop. When a new client -connects, the server initiates an RA-TLS session with the client, verifies the RA-TLS X.509 -certificate of the client, and provisions the secret to the client if verification is successful. -The server can register a callback to continue secure communication with the client (instead of -simply closing the session after the first secret is sent to the client). This library is not -thread-safe. This library uses EPID-based RA-TLS flows underneath. - -The library expects the same configuration information in the manifest and environment variables as -RA-TLS. - -``secret_prov_verify_dcap.so`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Similarly to ``secret_prov_verify_epid.so``, this library is used in secret-provisioning servers. -The only difference is that this library uses ECDSA/DCAP-based RA-TLS flows underneath. - -The library uses the same SGX-specific environment variables as ``secret_prov_verify_epid.so`` and -ignores the EPID-specific environment variables. The library expects all the DCAP infrastructure -to be installed and working correctly on the host. +For more information on Secret Provisioning, please read the ``Attestation`` +documentation of Graphene.