Skip to content

Latest commit

 

History

History
295 lines (231 loc) · 15.4 KB

SGX_QuoteEx_Integration.md

File metadata and controls

295 lines (231 loc) · 15.4 KB
Raw

Attestation: OE SDK Integration with Intel® SGX SDK quote-ex Library for Generation of Evidence in New Formats

This design document proposes an extension of the OE SDK V0.9 implementation for integration with the Intel® SGX SDK quote-ex library, for support of generation of evidence in new SGX formats such as Enhanced Privacy ID (EPID).

Motivation

The V0.9 implementation of the OE SDK SGX attestation, based on the Intel® SGX SDK Data Center Attestation Primitives (DCAP) quote generation library (simply called the DCAP library), only supports generation of evidence in a single SGX ECDSA-p256 format.

On some SGX platforms, other evidence formats, including those based on the Enhanced Privacy ID (EPID) algorithm, are supported and preferred by some application solutions. Generation of evidence in these formats is supported by the Intel® SGX SDK with a library package libsgx-quote-ex (or simply called the quote-ex library).

Note: though the acronym DCAP has "data center" in it, the DCAP library can be used on platforms both inside and outside data centers. Similarly, the quote-ex library can also be used on platforms both inside and outside of data centers.

User Experience

The proposed extension only changes the internal implementation of the OE SDK attestation software stack. It does not impact the OE SDK attestation API. With the integration of the quote-ex library, an attester application enclave's call to OE SDK API oe_attester_initialize() triggers enumeration and registration of all supported attester plugins

Integration of the quote-ex library depends on the installation of the Intel® SGX SDK quote-ex library package and its dependencies, as well as proper configuration of the components and their access to dependent backend services. Details for the quote-ex library installation and configuration are outside the scope of this document.

Specification

Existing OE SDK V0.9 Implementation

Evidence Format Enumeration and Plugin Registration

The existing OE SDK V0.9 implementation based on the DCAP library only supports generation of evidence in a single SGX ECDSA-p256 format, so there is no need for enumeration of supported evidence formats. As implemented in code file enclave/sgx/attester.c, a single attester plugin is created for the SGX ECDSA-p256 evidence format.

  • Note: in the OE SDK V0.9 implementation, the UUID for the ECDSA-p256 evidence format is still called OE_SGX_PLUGIN_UUID, which is the same as OE_SGX_ECDSA_P256_PLUGIN_UUID.

Implementation of OE SDK API oe_get_evidence()

The V0.9 implementation of OE SDK API oe_get_evidence(), in code file common/attest_plugin.c, searches for an attester plugin that supports the requested evidence format, and invokes the get_evidence() entry point of the selected plugin.

The SGX ECDSA-p256 attester plugin is implemented in code file enclave/sgx/attester.c and other relevant enclave-side and host-side code files, called enclave-side and host-side plugin libraries in this document. The enclave-side plugin library interacts with the host-side plugin library via OCALLs defined in interface definition file edl/sgx/platform.edl. For SGX ECDSA-p256 evidence generation, there are 2 OCALLs:

  • oe_get_qetarget_info_ocall(sgx_target_info_t* target_info)
    • Return the SGX Quoting Enclave (QE) target information.
  • oe_get_quote_ocall(const sgx_report_t* sgx_report, void* quote, size_t quote_size, size_t* quote_size_out)
    • Generate an ECDSA-p256 quote and return in the caller-supplied buffer, or return the needed buffer size if the supplied buffer is missing or not large enough.

Since only a single evidence format is supported and this format does not require any optional parameter, these OCALLs pass neither the evidence format ID nor optional parameter.

The host-side plugin library implements the OCALLs, as in code file host/sgx/ocalls.c and other relevant code files. As defined in the main cmake configuration file CMakeLists.txt in the OE SDK top directory, the DCAP library is linked to the OE SDK host-side plugin library. The DCAP library provides following 3 API functions in support of the above two OCALLs, as defined in its header file.

  • sgx_qe_get_target_info(sgx_target_info_t *p_qe_target_info)
    • Return the SGX Quoting Enclave (QE) target information, for the application enclave to generate its SGX report.
  • sgx_qe_get_quote_size(uint32_t *p_quote_size)
    • Return the size of the buffer needed to hold the SGX ECDSA quote to be generated.
  • sgx_qe_get_quote(const sgx_report_t *p_app_report, uint32_t quote_size, uint8_t *p_quote)
    • Generate an SGX ECDSA quote for the input application enclave SGX report, and return it in the caller-supplied buffer.

Project Compilation and Linking

As defined in cmake configuration file host/CMakeLists.txt, when the OE SDK V0.9 is built on an SGX platform, the host-side plugin library code is linked with the DCAP library.

Proposed Changes

quote-ex Library API

For generation of SGX evidence in ECDSA and EPID formats, the SGX quote-ex library has the following relevant API functions defined in its header file:

  • sgx_get_supported_att_key_ids(sgx_att_key_id_ext_t *p_att_key_id_list, uint32_t *p_att_key_id_list_size)
    • Return the list of supported attestation key IDs (which can be mapped to OE SDK evidence formats) on the current platform.
  • sgx_init_quote_ex(const sgx_att_key_id_t* p_att_key_id, sgx_target_info_t *p_qe_target_info, size_t* p_pub_key_id_size, uint8_t* p_pub_key_id);
    • Return the SGX Quoting Enclave (QE) target information for the given attestation key ID.
  • sgx_get_quote_size_ex(const sgx_att_key_id_t *p_att_key_id, uint32_t* p_quote_size)
    • Return the size of the buffer needed to hold the quote to be generated for the given attestation key ID.
  • sgx_get_quote_ex(const sgx_report_t *p_app_report, const sgx_att_key_id_t *p_att_key_id,sgx_qe_report_info_t *p_qe_report_info, uint8_t *p_quote, uint32_t quote_size)
    • Generate a quote for the given attestation key ID and application SGX report, and return it in the caller-supplied buffer.

As compared to the DCAP library API, the quote-ex library API allows enumeration of supported evidence formats (called attestation key IDs in the API). Otherwise the quote-ex API is similar to the DCAP API, except that every function takes an input attestation key ID in its parameter list.

Host-side Plugin Library Link with the SGX DCAP and quote-ex Libraries

Background: the SGX DCAP and quote-ex Libraries

  • The DCAP library only supports generation of SGX quotes in ECDSA-p256 format. With DCAP, the quote generation can be done either in-process, or out-of-process by working with a background service (called AESM) running on the same platform.
    • Environment variable SGX_AESM_ADDR controls the selection.
      • If SGX_AESM_ADDR is defined (regardless of its value), out-of-process quote generation is done.
      • Otherwise if it is not defined, in-process quote generation is done.
    • On Linux platforms, access control for quote generation is enforced by the SGX Linux driver.
      • Every process that hosts a Quoting Enclave (QE) is required to run in an account that belongs to a special group sgx_prv, as documented in the DCAP library readme and the DCAP driver readme.
        • This access control mechanism does not require an QE to be signed by Intel.
        • Note: sgx_prv is an SGX provisioning access control mechanism implemented in the DCAP driver since version V1.22, and in the new upstream SGX Linux driver.
      • Impact to DCAP library usage:
        • For in-process quote generation, every process that calls the DCAP library is required to run in an account that belongs to the special sgx_prv group.
        • On the other hand, for out-of-process quote generation, only the AESM service process account needs to be added to the special group sgx_prv.
    • Note: on Windows platforms, quote generation access control takes a different approach. The QE in the DCAP library is permitted by the Intel-provided Launch Control (LC) driver set for quote generation, and can run in any user account.
  • The quote-ex library supports generation of SGX quotes in multiple formats (including ECDSA-p256 and EPID variations). With quote-ex, quote generation is always done out-of-process by working with an AESM service on the local platform.

Priority between the SGX DCAP and quote-ex Libraries

An SGX platform can have either the DCAP library or the quote-ex library, or both of them installed.

  • If SGX_AESM_ADDR is not set, then the DCAP library must be installed. During quote generation, SGX quoting enclaves will be loaded in the application process.
  • If SGX_AESM_ADDR is set, then the quote-ex library as well as the AESM plugins must be installed. During quote generation, SGX quoting enclaves will be loaded in the SGX AESM service. The necessary libraries and plugins are listed as follows:
    • libsgx-quote-ex
    • sgx-aesm-service
    • libsgx-aesm-ecdsa-plugin
    • libsgx-aesm-pce-plugin
    • libsgx-aesm-quote-ex-plugin

On Linux platforms running kernel 5.11 or later, to be able to use the DCAP library for in-process quote generation, the user running the process needs to be added to the sgx_prv group, with the following command:

  • sudo usermod -a -G sgx_prv <username>

Note that this requires a new session to take effect. If this group has not been created, create it before adding the user to the group.

For more information, see SGX DCAP in-proc quote.

Options for Host-side Plugin Library Link with the SGX DCAP and quote-ex Libraries

There are several options for the OE SDK host-side plugin library to link with the SGX DCAP and quote-ex libraries. From the software stack point of view, the options only differ in the implementation of the host-side plugin library. They share the same enclave-side plugin library implementation and the same OCALL interface.

Option 1: Runtime Detection and Loading of the Two Libraries

With this option, the OE SDK host-side plugin library dynamically detects the presence of the two libraries, and choose to use one of them in the priority defined in the previous section.

Option 2: Built-time Link with the quote-ex Library

As described previously, the quote-ex library supports a superset of formats as compared to the DCAP library, though it always depends on a background service for quote generation.

If on SGX platforms the OE SDK always installs with the AESM background service (as a hard dependency), then it is possible for the host-side plugin library to be linked at build-time only with the quote-ex library. With this option, the dependency on the DCAP library will be dropped.

Option 3: Link with Both Libraries

To avoid the complication of dynamic library loading and to keep the flexibility of using either one of the the libraries, the host-side plugin library can be built to be linked to both the DCAP and the quote-ex libraries, and one of the two libraries will be used in the priority defined in the previous section.

Option 4: Link with DCAP and Dynamic Load of quote-ex

With this option, the existing OE SDK build and run-time behavior (that depends on the DCAP library for in-process quote generation) stays the same. But on a platform which has the quote-ex library installed, one of the two libraries will be used in the priority defined in the previous section.

Proposal: Implement Option 1

The proposal is to implement option 1. With runtime detection and loading of both the SGX DCAP and quote-ex libraries, it's possible for the OE SDK to be built on a non-SGX platform.

Support of SGX Evidence Formats Enumeration

The SGX plugin code file enclave/sgx/attester.c implements the OE SDK API oe_attester_initialize(). The implementation enumerates all supported SGX evidence formats, and registers them with the OE SDK framework using its helper function oe_register_attester_plugin().

For SGX evidence formats enumeration, a new OCALL is added to interface definition file edl/sgx/platform.edl and implemented in the host-side SGX plugin library:

  • oe_get_supported_attester_format_ids_ocall(void* format_ids, size_t format_ids_size, size_t* format_ids_size_out)
    • This OCALL returns a list of supported evidence format IDs in caller-supplied buffer, and returns the size of the buffer actually used to hold the list.
    • But if the supplied buffer is missing or not large enough, it only returns the needed buffer size.

In the implementation of this OCALL by the host-side SGX plugin library:

  • If the DCAP library is used, a list with a single evidence format ID for ECDSA-p256 is returned.
  • Otherwise if the quote-ex library is used, its API sgx_get_supported_att_key_ids() is invoked, and the returned list of attestation key IDs is converted to a list of OE SDK evidence format IDs.

Updated Implementation of SGX Plugin Function get_evidence()

The OCALLs for SGX evidence generation are extended to include the requested evidence format ID and its companion optional parameters, as shown below:

  • oe_get_qetarget_info_ocall(const oe_uuid_t* format_id, const void* opt_params, size_t opt_params_size, sgx_target_info_t* target_info)
    • Return the SGX Quoting Enclave (QE) target information for the given evidence format ID and its optional parameters.
  • oe_get_quote_ocall(const oe_uuid_t* format_id, const void* opt_params, size_t opt_params_size, const sgx_report_t* sgx_report, void* quote, size_t quote_size, size_t* quote_size_out)
    • Generate a quote for the given evidence format ID and its optional parameters, and return it in the caller-supplied buffer.
    • But if the supplied buffer is missing or not large enough, only the needed buffer size is returned.

In the host-side SGX plugin library implementation:

  • If the DCAP library is used, only evidence format of ECDSA-p256 is accepted, and the corresponding DCAP API entry point functions are invoked to get the QE target info or to generate the quote.
  • If the quote-ex library is used, the host-side library maps the input evidence format ID to the corresponding SGX attestation key ID and applies the optional parameter to the key ID structure (if any), and invokes the quote-ex API entry point functions to get the QE target info or to generate the quote.

Alternatives

The SGX quote-ex library is the only option available to support SGX evidence formats other than ECDSA-p256.

Authors

  • Shanwei Cen (@shnwc)
  • Yen Lee (@yentsanglee)