Skip to content

Installation of SGX driver (deprecated)

Starting with Linux kernel 5.11, you do not need to install an SGX drivers anymore. Hence, we recommend to update your kernel instead of using an SGX driver

To install an SGX driver on Linux distributions, follow the description. On server CPUs, you might need to install the DCAP SGX driver.

Alternatively, on a modern Ubuntu system on which you have sudo access, you could execute the following:

curl -fsSL https://raw.githubusercontent.com/scontain/SH/master/install_sgx_driver.sh \
| bash -s - install --auto --dkms -p metrics -p page0 -p version

The advantage of this installation option is that:

  • auto selects the right SGX driver for your CPU
  • dkms (Dynamic Kernel Module Support) ensures that the SGX driver is automatically updated after each kernel update
  • metrics provides SGX metrics that can be visualized by TEEMon

Driver Extensions

We maintain several extensions of the Intel SGX driver. The public extensions add the following features:

  • metrics: adds variables to monitor SGX performance metrics. This is, for example, being used by our TEEMon performance monitoring framework.

  • page0: permits an enclave to start at address 0 to protect against certain attacks.

  • version: permits to check what driver version and what extensions are installed.

  • fsgsbase: installs the fsgsbase patch which is required to run glibc-based applications.

For production, do not use option fsgsbase! Please use a Linux kernel 5.11 (or, newer).

You can install only one extension, for example, the version extension as follows:

curl -fssl https://raw.githubusercontent.com/scontain/SH/master/install_sgx_driver.sh \
 | bash -s - install --auto --dkms -p version

Alternatively, you can download the script as follows:

curl -fssl https://raw.githubusercontent.com/scontain/SH/master/install_sgx_driver.sh --output install_sgx_driver.sh
chmod u+x install_sgx_driver.sh

The script supports the install commands:

install the current Intel out of branch driver if no SGX driver is installed
  -d, --dcap           installs the DCAP driver instead

  -a, --auto           select the driver according to the machine capabilities (DCAP or OOT)

  -p, --patch=[PATCH]  apply patches to the SGX driver. The valid values for PATCH
                       are: 'version', 'metrics', 'page0'.
      -p version       installs the version patch (recommended)
      -p metrics       installs the metrics patch
      -p page0         installs the page0 patch (not available for DCAP)

  -k, --dkms           installs the driver with DKMS (default for DCAP)

  -l, --latest         installs the latest upstream driver (not recommended)

  -f, --force          replaces existing SGX driver, if installed

and the check command:

check   checks if a certain driver is installed
        -p metrics       check the status of 'metrics' extension
        -p page0         check the status of 'page0' extension

        In case of absence or outdated driver, or absence or outdated extension, check
        will return error.

Here are some common examples on how to use this installer. Our recommended way to install the driver is as follows:

# installs OOT SGX driver with metrics, page0, and version extension if no SGX driver is yet installed
 ./install_sgx_driver.sh install --auto --dkms -p metrics -p page0 -p version

This installs the correct driver for the host, ensures that the driver is automatically updated when the kernel is updated and adds all extensions that are required for monitoring and security.

If you need to replace an existing service, add the option --force:

# install SGX driver with metrics extension; replaces any existing SGX driver
 ./install_sgx_driver.sh install --force -p metrics

# install DCAP SGX driver with metrics extension; replaces any existing SGX driver
 ./install_sgx_driver.sh install --dcap --force -p metrics -p version

Option --help prints all commands and all options.

Check which SGX driver and extensions are installed

The checkcommand tests if an up-to-date SGX driver and some required extension are installed. Typically, you would execute as follows:

./install_sgx_driver.sh check

The output will look as follows:

Getting SGX Driver information:

OOT driver detected.
Version: 2.6.0

Detected patches: version metrics page0 

Use DKMS: Yes

Driver commit: 602374c738ca58f83a1c17574d08e5d5e6341953
Driver status: Up to date

Patch 'metrics' version: 2 (Up to date)
Patch 'page0' version  : 1 (Up to date)

OK

To check if an SGX driver and the metrics extension are installed and if they are up-to-date, just execute:

 ./install_sgx_driver.sh check -p metrics

If no SGX driver is installed the output would look like this

FAIL: No SGX driver detected!
ERROR: installation of SGX driver failed (script=install_sgx_driver.sh, Line: 1, 1166)

When an OOT driver without version patch is installed:

Getting SGX Driver information:
OOT driver detected.
Version: 2.6.0
FAIL: Unable to detect 'version' patch! This patch is required for running this command.
To install the driver with 'version' patch, run: ./install_sgx_driver.sh install -p version --force

When executing

./install_sgx_driver.sh check

the output for an OOT outdated driver without patches would look like this:

Getting SGX Driver information:
OOT driver detected.
Version: 2.6.0
Detected patches: version
Driver commit: 95eaa6f6693cd86c35e10a22b4f8e483373c987c
Driver status: Outdated - 1 new commit(s) available            
WARNING: Update is needed!

One can also check that certain extensions are installed. For example, one might want to verify that the metrics and the page0 extensions are installed:

./install_sgx_driver.sh check -p metrics -p page0

The output might look like this:

Getting SGX Driver information:
OOT driver detected.
Version: 2.6.0
Detected patches: version 
Driver commit: 95eaa6f6693cd86c35e10a22b4f8e483373c987c
Driver status: Outdated - 1 new commit(s) available            
Patch 'metrics' not found!
Patch 'page0' not found!
WARNING: Update is needed!

Note that on some platforms that support SGX but the disables SGX in the BIOS, the driver might be successfully installed and even load but using the SGX driver fails. Check on the host as well as inside your containers that the SGX device is visible.

Determine SGX Device

Depending if you have DCAP or a non-DCAP driver installed, you need to use a different SGX device. We can try to determine this with a little bash function:


function determine_sgx_device {
    export SGXDEVICE="/dev/sgx_enclave"
    export MOUNT_SGXDEVICE="--device=/dev/sgx_enclave"
    if [[ ! -e "$SGXDEVICE" ]] ; then
        export SGXDEVICE="/dev/sgx"
        export MOUNT_SGXDEVICE="--device=/dev/sgx"
        if [[ ! -e "$SGXDEVICE" ]] ; then
            export SGXDEVICE="/dev/isgx"
            export MOUNT_SGXDEVICE="--device=/dev/isgx"
            if [[ ! -c "$SGXDEVICE" ]] ; then
                echo "Warning: No SGX device found! Will run in SIM mode." > /dev/stderr
                export MOUNT_SGXDEVICE=""
                export SGXDEVICE=""
            fi
        fi
    fi
}

Storing determine_sgx_device in a separate file

Note that if define and execute determine_sgx_device in a separate file, say, dsd.sh, the environment variables SGXDEVICE and MOUNT_SGXDEVICE are only visible in the shell that executes this file. Use command source dsd.sh to make these variables visible in your current bash shell.

We can now determine if and which SGX driver is installed:

determine_sgx_device
echo $SGXDEVICE

Checking availability of SGX device inside of containers

The SGX device is not automatically mapped into a container: you can to map the device as follows into the container:

# alternative: use --device option without --privileged flag
docker run $MOUNT_SGXDEVICE --rm registry.scontain.com/sconecuratedimages/checksgx || echo "failed to open  SGX device $SGXDEVICE inside of container"

In case that the device is not mapped in the container, you can try to see if the container must be privileged or if we might need to remap the device ids:

docker run $MOUNT_SGXDEVICE --privileged --rm registry.scontain.com/sconecuratedimages/checksgx || echo "failed to open  SGX device $SGXDEVICE inside of container"