Home

Awesome

Intel(R) Software Guard Extensions for Linux* OS

linux-sgx

Introduction

Intel(R) Software Guard Extensions (Intel(R) SGX) is an Intel technology for application developers seeking to protect select code and data from disclosure or modification.

The Linux* Intel(R) SGX software stack is comprised of the Intel(R) SGX driver, the Intel(R) SGX SDK, and the Intel(R) SGX Platform Software (PSW). The Intel(R) SGX SDK and Intel(R) SGX PSW are hosted in the linux-sgx project.

The SGXDataCenterAttestationPrimitives project maintains an out-of-tree driver for the Linux* Intel(R) SGX software stack, which will be used until the driver upstreaming process is complete. It is used on the platforms with Flexible Launch Control and Intel(R) AES New Instructions support and could support both Elliptic Curve Digital Signature algorithm (ECDSA) based attestation and Enhanced Privacy Identification (EPID) based attestation.

Note: Ice Lake Xeon-SP (and the future Xeon-SP platforms) doesn't support EPID attestation.

The linux-sgx-driver project hosts the other out-of-tree driver for the Linux* Intel(R) SGX software stack, which will be used until the driver upstreaming process is complete. It is used to support Enhanced Privacy Identification (EPID) based attestation on the platforms without Flexible Launch Control.

The intel-device-plugins-for-kubernetes project enables users to run container applications running Intel(R) SGX enclaves in Kubernetes clusters. It also gives instructions how to set up ECDSA based attestation in a cluster.

The intel-sgx-ssl project provides a full-strength general purpose cryptography library for Intel(R) SGX enclave applications. It is based on the underlying OpenSSL* Open Source project. Intel(R) SGX provides a build combination to build out a SGXSSL based SDK as below. Users could also utilize this cryptography library in SGX enclave applications seperately.

This repository provides a reference implementation of a Launch Enclave for 'Flexible Launch Control' under psw/ae/ref_le. The reference LE implementation can be used as a basis for enforcing different launch control policy by the platform developer or owner. To build and try it by yourself, please refer to the ref_le.md for details. 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.

License

See License.txt for details.

Contributing

See CONTRIBUTING.md for details.

Documentation

Quick Start with Docker and Docker Compose

$ cd docker/build && ./build_compose_run.sh

$ cd linux/installer/docker && ./build_compose_run.sh

Build and Install the Intel(R) SGX Driver

Follow the README.md in the SGXDataCenterAttestationPrimitives project to build and install the Intel(R) SGX driver. NOTE: The above Intel(R) SGX driver requires Flexible Launch Control and Intel(R) AES New Instructions support. If your platform doesn't meet the requirement, please follow the instructions in the linux-sgx-driver project to build and install this version of Intel(R) SGX driver.

Build the Intel(R) SGX SDK and Intel(R) SGX PSW Package

Prerequisites:

   $ git clone https://github.com/intel/linux-sgx.git
   $ cd linux-sgx && make preparation

The above make preparation would trigger the script download_prebuilt.sh to download the prebuilt binaries. You may need to set an https proxy for the wget tool used by the script (such as export https_proxy=http://test-proxy:test-port)

Build the Intel(R) SGX SDK and Intel(R) SGX SDK Installer

  $ make sdk

You can find the three flavors of tools and libraries generated in the build directory.

  $ make sdk USE_OPT_LIBS=0

or

  $ make sdk_no_mitigation USE_OPT_LIBS=2

or

  $ make sdk_no_mitigation USE_OPT_LIBS=3

Note: Building the Intel(R) SGX PSW with open sourced SGXSSL/string/math libraries is not supported. Note: Building mitigation SDK with USE_OPT_LIBS=2 or USE_OPT_LIBS=3 is not allowed.

  $ make sdk DEBUG=1

  $ make clean

  $ make sdk_install_pkg

You can find the generated Intel(R) SGX SDK installer sgx_linux_x64_sdk_${version}.bin located under linux/installer/bin/, where ${version} refers to the version number.

Note: The above command builds the Intel(R) SGX SDK with default configuration firstly and then generates the target SDK Installer. To build the Intel(R) SGX SDK Installer with debug information kept in the tools and libraries, enter the following command:

  $ make sdk_install_pkg DEBUG=1

Build the Intel(R) SGX PSW and Intel(R) SGX PSW Installer

  $ make psw

You can find the tools and libraries generated in the build/linux directory. Note: You can also go to the psw folder and use the make command to build the Intel(R) SGX PSW component only.

  $ make psw DEBUG=1

  $ make clean

The build above uses prebuilt Intel(R) Architecture Enclaves(LE/PvE/QE/PCE) - the files psw/ae/data/prebuilt/libsgx_*.signed.so, which have been signed by Intel in advance.

  $ cd psw/ae/le
  $ make

Install the Intel(R) SGX SDK

Prerequisites

Install the Intel(R) SGX SDK

To install the Intel(R) SGX SDK, invoke the installer, as follows:

$ cd linux/installer/bin
$ ./sgx_linux_x64_sdk_${version}.bin

The above command requires you to specify the installation path. You can use the following command to use the non-interactive installation mode:

$ cd linux/installer/bin
$ ./sgx_linux_x64_sdk_${version}.bin --prefix {SDK_INSTALL_PATH_PREFIX}

NOTE: You need to set up the needed environment variables before compiling your code. To do so, run:

  $ source ${sgx-sdk-install-path}/environment

Test the Intel(R) SGX SDK Package with the Code Samples

  $ cd ${sgx-sdk-install-path}/SampleCode/LocalAttestation
  $ make SGX_MODE=SIM
  $ cd bin
  $ ./app

Use similar commands for other sample codes.

Compile and Run the Code Samples in the Hardware Mode

If you use an Intel SGX hardware enabled machine, you can run the code samples in Hardware mode. Ensure that you install Intel(R) SGX driver and Intel(R) SGX PSW installer on the machine. See the earlier topic, Build and Install the Intel(R) SGX Driver, for information on how to install the Intel(R) SGX driver. See the later topic, Install Intel(R) SGX PSW, for information on how to install the PSW package.

  $ cd ${sgx-sdk-install-path}/SampleCode/LocalAttestation
  $ make
  $ cd bin
  $ ./app

Use similar commands for other code samples. Note: On Ubuntu 22.04 or any distro with systemd v248 or later, /dev/sgx_enclave is only accessible by users in the group "sgx". The enclave app should be run with a uid in the sgx group.

# check systemd version:
$ systemctl --version
# add sgx group to user if it's 248 or above:
$ sudo usermod -a -G sgx <user name>

Install the Intel(R) SGX PSW

Prerequisites

Install the Intel(R) SGX PSW

The SGX PSW provides 3 services: launch, EPID-based attestation, and algorithm agnostic attestation. Starting with the 2.8 release, the SGX PSW is split into smaller packages and the user can choose which features and services to install. There are 2 methods to install the required packages: Using individual packages or using the local repo generated by the build system. Using the local repo is recommended since the system will resolve the dependencies automatically. Currently, we support .deb and .rpm based repos.

Using the local repo(recommended)

Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04 and Debian 10Red Hat Enterprise Linux 9.2, CentOS Stream 9, CentOS 8.3 and Anolis OS 8.6SUSE Linux Enterprise Server 15
launch serviceapt-get install libsgx-launch libsgx-urtsyum install libsgx-launch libsgx-urtszypper install libsgx-launch libsgx-urts
EPID-based attestation serviceapt-get install libsgx-epid libsgx-urtsyum install libsgx-epid libsgx-urtszypper install libsgx-epid libsgx-urts
algorithm agnostic attestation serviceapt-get install libsgx-quote-ex libsgx-urtsyum install libsgx-quote-ex libsgx-urtszypper install libsgx-quote-ex libsgx-urts
DCAP ECDSA-based serviceapt-get install libsgx-dcap-qlyum install libsgx-dcap-qlzypper install libsgx-dcap-ql

Optionally, you can install *-dbgsym or *-debuginfo packages to get the debug symbols, and install *-dev or *-devel packages to get the header files for development.

Using the individual packages

Please refer Intel_SGX_Installation_Guide_Linux for detail.

Upgrade from a legacy installation

Sometimes we will split old package into smaller ones or move file between different packages. In such cases, you will encounter error messages like: "dpkg: error processing archive ....(--unpack): trying to overwrite ...". You can use 2 methods to address it.

apt-get dist-upgrade -o Dpkg::Options::="--force-overwrite"

Configure the installation

Some packages are configured with recommended dependency on other packages that are not required for certain usage. For instance, the background daemon is not required for container usage. It will be installed by default, but you can drop it by using the additional option during the installation.

  --no-install-recommends

  --setopt=install_weak_deps=False

  --no-recommends

ECDSA attestation

To enable ECDSA attestation

NOTE: If you had already installed Intel(R) SGX driver without ECDSA attestation, please uninstall the driver firstly and then install the Intel(R) SGX DCAP driver. Otherwise the newly installed Intel(R) SGX DCAP driver will be unworkable.

Start or Stop aesmd Service

The Intel(R) SGX PSW installer installs an aesmd service in your machine, which is running in a special linux account aesmd. To stop the service: $ sudo service aesmd stop To start the service: $ sudo service aesmd start To restart the service: $ sudo service aesmd restart

Configure the Proxy for aesmd Service

The aesmd service uses the HTTP protocol to initialize some services. If a proxy is required for the HTTP protocol, you may need to manually set up the proxy for the aesmd service. You should manually edit the file /etc/aesmd.conf (refer to the comments in the file) to set the proxy for the aesmd service. After you configure the proxy, you need to restart the service to enable the proxy.

Reproducibility

Intel(R) SGX is providing several prebuilt binaries. All the prebuilt binaries are built from a reproducible environment in SGX docker container. To reproduce the prebuilt binaries, please follow the reproducibility README.md to prepare the SGX docker container and build out the binaries you want to verify. Most of the binaries could be verified utilizing Linux system command diff, except Intel(R) AEs. Please refer to the README.md for how to verify the reproducibililty of the built out AEs.