Skip to content

Latest commit

 

History

History
117 lines (102 loc) · 7.29 KB

ref_le.md

File metadata and controls

117 lines (102 loc) · 7.29 KB
Raw

Intel(R) SGX Reference Launch Enclave

NOTE: The reference LE is only workable with linux-sgx-driver and is planned to be deprecated starting from Intel(R) SGX release 2.20.

Introduction

A Launch Enclave (LE) is a special type of enclave, generates a Launch Token for other enclave to be initialized. The generated Launch Token is used by the Platform Software as part of the data passed to the driver on EINIT flow.
The Launch Enclave role is divided to two parts:

  1. Determining whether the enclave may be launched on the platform
  2. Generation of Launch Token embedding the security data provided

The default Launch Control in the Intel(R) SGX PSW is signed by Intel and generates tokens based on a control policy defined by Intel.

The Reference Launch Enclave (ref-LE) is a reference implementation of a Launch Enclave that can be used as a basis for enforcing different launch control policy by the platform developer or owner.

Flexible Launch Control

In the Intel(R) SGX architecture, LE must be signed by the Launch Control Policy Provider of the platform in order to be loaded as LE and in order to accept Launch Tokens generated by it.
To define a Launch Control Policy Provider, other than the default Intel, the SHA256 value of the enclave signer public key modulus must be written to the IA32_SGXPUBKEYHASH0..3 MSRs.
To write to these MSRs the platform must support the Flexible Launch Control (FLC) feature and the BIOS must enable it in one of the possible modes:

  1. Unlocked mode - Enabling a ring-0 software to configure the IA32_SGXPUBKEYHASH0..3 MSRs values
  2. Locked mode - Only the BIOS may set the IA32_SGXPUBKEYHASH0..3 MSRs values

In order to use any LE other than the Intel signed one, the target platform must support the FLC feature and the hash value of the enclave signer must be configured into the IA32_SGXPUBKEYHASH0..3 MSRs.

White List

The ref-LE launch policy is based on a white list of enclave signer (MR_SIGNER) and may also limit to a specific enclave hash (MR_ENCLAVE).

The white list record includes the following items:

  • MR_SIGNER - approved enclave signer hash
  • MR_ENCLAVE (optional) - a specific approved enclave hash
  • Match MR_ENCLAVE - whether the optional MR_ENCLAVE should be used
  • Provision Key - whether to allow the enclave to be launched with provision key attribute

The white key must be RSA 3072 signed by the signer of the ref-LE.

The ref-LE Directory Structure

The ref-LE is part of the PSW source tree and located in the ref-le directory, including the following content:

|- ref_le [DIR]                          - Top level ref-LE directory
   |- Makefile                           - A make file for the ref-LE enclave and white list generation
   |- config_linux.xml                   - The enclave configuration XML, defines the LaunchKey property in order to be loaded as LE
   |- ref_le.cpp                         - The ref-LE implementation (ref-le.h is located in psw/ae/inc/internal)
   |- ref_le.edl                         - The ref-LE EDL file, defining the enclave interface
   |- ref_wl_gen [DIR]                   - A reference tool for white list generation
      |- ref_wl.cpp                      - The tool main function calling the generator class
      |- ref_wl_gen.h/cpp                - A white list generation class
   |- ref_keys [DIR]                     - Contains a set of testing keys used by default in the build process 
      |- wl_cfg.csv                      - A sample CSV file to define the white list
      |- le_private/public_test_key.pem       - RSA 3072 key pair used for signing the ref-LE and white list
      |- encalve_private/public_test_key.pem  - RSA 3072 key pair included in the white list and enables signing of an arbitrary enclave
   |- sgx_pubkey_hash_gen                - A tool to generate SHA256 value of the enclave signer public key modulus

Note: the ref_keys directory is meant only for testing purposes and must not be used on a production build

Build and Installation

The ref-LE build is part of the Intel(R) SGX PSW build and is conditioned by setting the build flag "BUILD_REF_LE=1" to the make line.

Prerequisites:

Refer to the README.md in the top of the repository for the Prerequisites of building and installing the Intel(R) SGX PSW.

To build and install the Intel(R) SGX PSW of ref-LE build:

  1. Build the Intel(R) SGX PSW installer with ref-LE support with the following commands:
$ make clean
$ make psw_install_pkg BUILD_REF_LE=1
  1. Install the Intel(R) SGX PSW by invoking the installer with root privilege:
$ cd ${top_dir}/linux/installer/bin
$ sudo ./sgx_linux_x64_psw_${version}.bin
  1. Copy the built-out ref-LE binary and the white list file to the PSW installation folders with root privilege:
$ sudo cp ${top_dir}/build/linux/libsgx_ref_le.signed.so /opt/intel/sgxpsw/aesm/
$ sudo cp ${top_dir}/build/linux/ref_white_list.bin /var/opt/aesmd/data

See the later topic, Generating a White List, for information on how to generate a white list file.

  1. Restart aesmd service with root privilege:
$ sudo service aesmd restart

Note: Building with ref-LE is replacing the standard LE in both the build process and also in the aesm_service, the aesm_service will load and configure only the ref-LE if the PSW is built with the flag BUILD_REF_LE=1. And the BUILD_REF_LE=1 is also building the LE shared object (ref_le.so), the ref-LE white list generation tool and a sample white list created with the tool and the test keys.

Usage

Generating a White List

ref_wl_gen <Command> <Options>  
Command:  
   gen-wl:    Generate a white-list file based on the information provided in the config file.   
Options:  
   -out <file-name>:  The output file name for the white-list.   
   -cfg <file-name>:  A CSV configuration file with the list of hash values or keys to sign.   
   -key <file-name>:  The private key to sign the white-list with.   
   -ver <version>:    An integer value of the white-list version.   
   -verbose:          Print extended report while generating the white-list.   
CSV file columns:   
   allow provision key, mr_enclave valid, mr_signer hash, mr_signer file, mr_enclave hash, mr_enclave file, comments (ignored)   
Notes:    
   * Column 1 and 2 should be true or false.   
   * If mr_enclave valid is false the mr_enclave columns will be ignored. 
   * If mr_signer/mr_enclave hash is not empty the mr_signer/mr_enclave file will be ignored. 
   * mr_signer file should be key file (pem), mr_enclave file should be sigstruct (bin). 
   * Key hash representation should be in little endian, i.e. LSB byte first.    
Example:  
   ref_wl_gen gen-wl -out wl.bin -cfg cfg.csv -key private.pem

Using the ref-LE

The ref-LE exposes two functions for the platform software:

  • ref_le_get_launch_token() - receives MR_ENCLAVE, MR_SIGNER and attributes and generates Launch Token if permitted
  • ref_le_init_white_list() - receives a white list file and stores it for future usage if verified

Defining a Launch Control Policy Provider

Generate SHA256 value of the enclave signer public key modulus of ref_LE to be written to the IA32_SGXPUBKEYHASH0..3 MSRs in order from hash0 to hash3.

sgx_pubkey_hash_gen [PUBLIC_KEY_FILE]
Example:
  ./sgx_pubkey_hash_gen ref_keys/le_public_test_key.pem