clearlinux/graphene
2
0
Fork 0
mirror of https://github.com/clearlinux/graphene.git synced 2026-08-26 18:17:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

fixup! [Docs] Add documentation on Attestation

Browse Source
This commit is contained in:
Dmitrii Kuvaiskii
2021-02-17 01:36:43 -08:00
parent faff3fbfea
commit 7a511bf7f6
4 changed files with 223 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/attestation.rst
+100 -95
View File
@@ -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, &quote, 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 = "<empty string>"`` -- 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
Documentation/glossary.rst
+29
View File
@@ -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
Documentation/sgx-intro.rst
+69 -6
View File
@@ -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
Pal/src/host/Linux-SGX/tools/README.rst
+25 -165
View File
@@ -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 = "<empty string>"`` -- 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.