Intel(R) Software Guard Extensions SDK Developer Reference for Linux* OS

Intel® Software Guard Extensions SDK for Linux*

Developer Reference

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 2 -

Legal Information

No license (express or implied, by estoppel or otherwise) to any intellectual prop-

erty rights is granted by this document.

Intel disclaims all express and implied warranties, including without limitation, the

implied warranties of merchantability, fitness for a particular purpose, and non-

infringement, as well as any warranty arising from course of performance, course of

dealing, or usage in trade.

This document contains information on products, services and/or processes in

development. All information provided here is subject to change without notice.

Contact your Intel representative to obtain the latest forecast, schedule, spe-

cifications and roadmaps.

The products and services described may contain defects or errors known as errata

which may cause deviations from published specifications. Current characterized

errata are available on request.

Intel technologies features and benefits depend on system configuration and may

require enabled hardware, software or service activation. Learn more at Intel.com, or

from the OEM or retailer.

Copies of documents which have an order number and are referenced in this doc-

ument may be obtained by calling 1-800-548-4725 or by visiting www.in-

tel.com/design/literature.htm.

Intel, the Intel logo, VTune, Xeon, and Xeon Phi are trademarks of Intel Corporation

in the U.S. and/or other countries.

Optimization Notice

Intel's compilers may or may not optimize to the same degree for non-Intel micro-

processors for optimizations that are not unique to Intel microprocessors. These

optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optim-

izations. Intel does not guarantee the availability, functionality, or effectiveness of

any optimization on microprocessors not manufactured by Intel. Microprocessor-

dependent optimizations in this product are intended for use with Intel micro-

processors. Certain optimizations not specific to Intel microarchitecture are

reserved for Intel microprocessors. Please refer to the applicable product User and

Reference Guides for more information regarding the specific instruction sets

covered by this notice.

Notice revision #20110804

* Other names and brands may be claimed as the property of others.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 3 -

Revision History

Revision Number Description Revision

Date

1.5 Intel(R) SGXLinux 1.5 release May 2016

1.6 Intel(R) SGXLinux 1.6 release September

2016

1.7 Intel(R) SGXLinux 1.7 release December

2016

1.8 Intel(R) SGXLinux 1.8 release March

2017

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 4 -

Introduction

Intel provides the Intel(R) Software Guard Extensions (Intel(R) SGX) SDK

Developer Reference for software developers who wish to harden their applic-

ation’s security using Intel Software Guard Extensions technology.

This document covers an overview of the technology, tutorials, tools, sample

code as well as APIreference.

Intel(R) Software Guard Extensions SDK from Intel is a collection of APIs,

sample source code, libraries and tools that enables the software developer to

write and debug Intel(R) Software Guard Extensions applications in C/C++.

NOTE

Intel(R) Software Guard Extensions(Intel(R) SGX) technology is only available

on 6th Generation Intel(R) Core(TM) Processor or newer.

Intel(R) Software Guard Extensions Technology Overview

Intel(R) Software Guard Extensions is an Intel technology whose objective is to

enable a high-level protection of secrets. It operates by allocating hardware-

protected memory where code and data reside. The protected memory area

is called an enclave. Data within the enclave memory can only be accessed by

the code that also resides within the enclave memory space. Enclave code can

be invoked via special instructions. An enclave can be built and loaded as a

shared object on Linux* OS.

NOTE:

The enclave file can be disassembled, so the algorithms used by the enclave

developer will not remain secret.

Intel(R) Software Guard Extensions technology has a hard limit on the pro-

tected memory size, typically 64 MB or 128 MB. As a result, the number of act-

ive enclaves (in memory) is limited. Depending on the memory footprint of

each enclave, use cases suggest that 5-20 enclaves can reside in memory sim-

ultaneously.

Intel(R) Software Guard Extensions Security Properties

Intel designs the Intel(R) Software Guard Extensions to protect against

software attacks:

The enclave memory cannot be read or written from outside the

enclave regardless of current privilege level and CPU mode

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 5 -

(ring3/user-mode, ring0/kernel-mode, SMM, VMM, or another

enclave). The abort page is returned in such conditions.

An enclave can be created with a debug attribute that allows a spe-

cial debugger (Intel(R) Software Guard Extensions debugger) to

view its content like a standard debugger. Production enclaves

(non-debug) cannot be debugged by software or hardware debug-

gers.

The enclave environment cannot be entered via classic function

calls, jumps, register manipulation or stack manipulation. The only

way to call an enclave function is via a new instruction that per-

forms several protect checks. Classic function calls initiated by

enclave code to functions inside the enclave are allowed.

CPU mode can only be 32 or 64 bit when executing enclave code.

Other CPU modes are not supported. An exception is raised in such

conditions.

Intel designs the Intel(R) Software Guard Extensions to protect against

known hardware attacks:

The enclave memory is encrypted using industry-standard encryp-

tion algorithms with replay protection.

Tapping the memory or connecting the DRAM modules to another

system will only give access to encrypted data.

The memory encryption key changes every power cycle randomly

(for example, boot/sleep/hibernate). The key is stored within the

CPU and it is not accessible.

Intel(R) Software Guard Extensions is not designed to handle side

channel attacks or reverse engineering. It is up to the Intel(R) SGX

developers to build enclaves that are protected against these

types of attack.

Intel(R) Software Guard Extensions uses strong industry-standard algorithms

for signing enclaves. The signature of an enclave characterizes the content and

the layout of the enclave at build time. If the enclave’s content and layout are

not correct per the signature, then the enclave will fail to be initialized and,

hence, will not be executed. If an enclave is initialized, it should be identical to

the original enclave and will not be modified at runtime.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 6 -

Application Design Considerations

An Intel(R) Software Guard Extensions application design is different from

non- Intel(R) SGX application as it requires dividing the application into two

logical components:

l Trusted component. The code that accesses the secret resides here.

This component is also called an enclave. More than one enclave can

exist in an application.

l Untrusted component. The rest of the application including all its mod-

ules.

The application writer should make the trusted part as small as possible. It is

suggested that enclave functionality should be limited to operate on the

secret data. A large enclave statistically has more bugs and (user created)

security holes than a small enclave.

The enclave code can leave the protected memory region and call functions in

the untrusted zone (by a special instruction). Reducing the enclave depend-

ency on untrusted code will also strengthen its protection against possible

attacks.

Embracing the above design considerations will improve protection as the

attack surface is minimized.

The application designer, as the first step to harnessing Intel(R) Software

Guard Extensions SDK in the application, must redesign or refactor the applic-

ation to fit these guidelines. This is accomplished by isolating the code mod-

ule(s) that access any secrets and then moving these modules to a separate

package/library. The details of how to create such an enclave are detailed in

the tutorials section. You can also see the demonstrations on creating an

enclave in the sample code that are shipped with the Intel(R) Software Guard

Extensions SDK.

Terminology and Acronyms

AE Architectural enclaves. Enclaves that are part of the Intel(R) Soft-

ware Guard Extensions framework. They include the quoting

From an enclave standpoint, the operating system and VMM are not trusted

components, either.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 7 -

enclave (QE), provisioning enclave (PvE), launch enclave (LE)).

Attestation Prove authenticity. In case of platform attestation, prove the

identity of the platform.

CA Certificate Authority.

ECALL Enclave call. A function call that enters the enclave.

ECDH Elliptic curve Diffie–Hellman.

EDL Enclave Definition Language.

Intel(R)

EPID

Intel(R) Enhanced Privacy ID.

FIPS Federal Information Processing Standards developed by

NISTfor use in computer systems government-wide.

FIPS 140-2 Standard that defines security requirements for cryptographic

modules and is required for sales to the Federal Governments.

HSM Hardware Security Module.

Attestation

Service

Attestation Service for Intel(R) Software Guard Extensions.

ISV Independent Software Vendor.

KE Key Exchange.

LE Launch enclave, an architectural enclave from Intel, involved in

the licensing service.

Nonce An arbitrary number used only once to sign a cryptographic com-

munication.

OCALL Outside call. A function call that calls an untrusted function from

an enclave.

Intel(R) SGX

PSW

Platform Software for Intel(R) Software Guard Extensions.

PvE Provisioning enclave, an architectural enclave from Intel, involved

in the Intel(R) Enhanced Privacy ID (Intel(R) EPID) Provision ser-

vice to handle the provisioning protocol.

QE Quoting enclave, an architectural enclave from Intel, involved in

the quoting service.

Intel(R) SGX Intel(R) Software Guard Extensions.

SigRL Signature revocation list

SMK Session MACkey.

SP Service Provider.

SVN Security version number. Used to version security levels of both

hardware and software components of the Intel(R) Software

Guard Extensions framework.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 8 -

TCB Trusted computing base. Portions of hardware and software that

are considered safe and uncompromised. A system protection is

improved if the TCB is as small as possible, making an attack

harder.

TCS Thread Control Structure.

TLS Thread Local Storage.

TLS Transport Layer Security.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 9 -

Setting up an Intel(R) Software Guard Extensions Project

This topic introduces how to use the features of Intel(R) Software Guard Exten-

sions SDK to create and manage Intel(R) SGXapplication projects.

Creating Intel(R) Software Guard Extensions Projects

To create an Intel(R) Software Guard Extensions project on Linux* OS, you are

recommended to start using the directory structure and Makefiles from a

sample application in the Intel(R) SGXSDK.In an Intel SGX project, you should

normally prepare the following files:

1. Enclave Definition Language (EDL) file - describes enclave trusted and

untrusted functions and types used in the function prototype. See

Enclave Definition Language Syntax for details.

2. Enclave configuration file - contains the information of the enclave

metadata. See Enclave Configuration File for details.

3. Signing key files - used to sign an enclave to produce a signature struc-

ture that contains enclave properties such as enclave measurement. See

Signing Key Files for details.

4. Application and enclave source code - the implementation of application

and enclave functions.

makefile - it performs the following steps:

1. Generates edger routines (see Edger8r Tool for details).

2. Builds the application and enclave.

3. Signs the enclave (see Enclave Signing Tool for details).

6. Linker script file - it is recommended to use the linker script to hide all

unnecessary symbols, and only export enclave_entry, g_global_data, and

g_global_data_sim.

Once you understand how an Intel SGXapplication is built, you may customize

the project setup according to your needs.

To develop an Intel SGXapplication, Intel(R) SGXSDK supports a few non-

standard configurations, not present in other SDKs. Enclave

ProjectConfigurations explains the various enclave project configurations as

well as the corresponding Makefile options.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 10 -

Enclave Image Generation

An enclave image is a statically linked shared object under Linux* OS, without

any external dependencies. You are expected to follow the guidelines below

to generate a proper enclave image:

1. Link the tRTS with the --whole-archive option, so that the whole con-

tent of the trusted runtime library is included in the enclave;

2. From other libraries, you just need to pull the required symbols. For

example, if an enclave requires routines in the trusted standard C and seal lib-

raries:

HW mode:

--start-group –lsgx_tstdc –lsgx_tservice -lsgx_tcrypto -

-end-group

Simulation mode:

--start-group –lsgx_tstdc –lsgx_tservice_sim -lsgx_

tcrypto --end-group

In addition, a linker script is also recommended to hide all unnecessary sym-

bols.

// file: enclave.lds

enclave.so

{

global:

enclave_entry;

g_global_data_sim;

g_peak_heap_used;

local:

};

The symbol enclave_entry is the entry point to the enclave. The symbol

g_global_data_sim comes from the tRTS simulation library and is

required to be exposed for running an enclave in the simulation mode since it

distinguishes between enclaves built to run on the simulator and on the hard-

ware. The sgx_emmt tool relies on the symbol g_peak_heap_used to

determine the size of the heap that the enclave uses. The symbol __

ImageBase is used by tRTS to compute the base address of the enclave.

Assuming that you have a few object files to be linked into a target enclave,

use the command line similar to the following:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 11 -

$ ld -o enclave.so file1.o file2.o \

-pie -eenclave_entry -nostdlib -nodefaultlibs –nostart-

files --no-undefined \

--whole-archive –lsgx_trts --no-whole-archive \

--start-group –lsgx_tstdc ––lsgx_tservice -lsgx_crypto -

-end-group \

-Bstatic -Bsymbolic --defsym=__ImageBase=0 --export-

dynamic \

--version-script=enclave.lds

You are also encouraged to hardening your enclaves, by passing one of the fol-

lowing options to the linker, to put read-only non-executable sections in your

own segment:

ld.gold --rosegment

or,

-Wl,-fuse-ld=gold –Wl,--rosegment

Using Intel(R) Software Guard Extensions Eclipse* Plug-in

The Intel(R) Software Guard Extensions Eclipse* Plug-in helps the enclave

developer to maintain enclaves and untrusted related code inside Eclipse*

C/C++ projects.

To get more information on Intel(R) Software Guard Extensions Eclipse* Plug-

in, see Intel(R) Software Guard Extensions Eclipse* Plug-in Developer Guide

from the Eclipse Help content: Help > Help Contents > Intel(R) SGX Eclipse

Plug-in Developer Guide.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 12 -

Using Intel(R) Software Guard Extensions SDK Tools

This topic introduces how to use the following tools that the Intel(R) Software

Guard Extensions SDK provides:

Edger8r Tool

Generates interfaces between the untrusted components and enclaves.

Enclave Signing Tool

Generates the enclave metadata, which includes the enclave signature,

and adds such metadata to the enclave image.

Enclave Debugger

Helps to debug an enclave.

Performance Measurement using Intel(R) VTune(TM) Amplifier

Helps to measure the performance of the enclave code.

Enclave Memory Measurement Tool

Helps to measure the usage of protected memory by the enclave at

runtime.

CPUSVN Configuration Tool

Helps to simulate the CPUSVN upgrade/downgrade scenario without

modifying the hardware.

Edger8r Tool

The Edger8r tool ships as part of the Intel(R) Software Guard Extensions SDK.

It generates edge routines by reading a user-provided EDL file. These edge

routines provide the interface between the untrusted application and the

enclave. Normally, the tool will run automatically as part of the enclave build

process. However, an advanced enclave writer may invoke the Edger8r manu-

ally.

When given an EDL file, for example, demo.edl, the Edger8r will by default

generate four files:

l demo_t.h – It contains prototype declarations for trusted proxies and

bridges.

l demo_t.c – It contains function definitions for trusted proxies and

bridges.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 13 -

l demo_u.h – It contains prototype declarations for untrusted proxies

and bridges.

l demo_u.c – It contains function definitions for untrusted proxies and

bridges.

Here is the usage description for the Edger8r tool:

Syntax:

sgx_edger8r [options] <.edl file> [another .edl file …]

Arguments:

[Options] Descriptions

--use-prefix

Prefix the untrusted proxy with the enclave

name.

--header-only

Generate header files only.

--search-path

<path>

Specify the search path of EDL files.

--untrusted

Generate untrusted proxy and bridge routines

only.

--trusted

Generate trusted proxy and bridge routines

only.

--untrusted-dir

<dir>

Specify the directory for saving the untrusted

code.

--trusted-dir <dir>

Specify the directory for saving the trusted

code.

--help

Print this help message.

If neither --untrusted nor --trusted is specified, the Edger8r will gen-

erate both.

Here, the path parameter has the same format as the PATH environment vari-

able, and the enclave name is the base file name of the EDL file (demo in this

case).

CAUTION:

The ISV must run the Edger8r tool in a protected malware-free environment

to ensure the integrity of the tool so that the generated code is not com-

promised. The ISV is ultimately responsible for the code contained in the

enclave and should review the code that the Edger8r tool generates.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 14 -

Enclave Signing Tool

The Intel(R) Software Guard Extensions SDK provides a tool named sgx_sign

for you to sign enclaves. In general, signing an enclave is a process that

involves producing a signature structure that contains enclave properties such

as the enclave measurement. Once an enclave is signed in such structure, the

modifications to the enclave file (such as code, data, signature, and so on.) can

be detected. The signing tool also evaluates the enclave image for potential

errors and warns users about potential security hazards. sgx_sign is typically

set up by one of the configuration tools included in the Intel(R) SGX SDK and

runs automatically at the end of the build process. During the loading process,

the signature is checked to confirm that the enclave has not been tampered

with and has been loaded correctly.

Command-Line Syntax

To run sgx_sign, use the following command syntax:

sgx_sign <command> [args]

All valid commands are listed in the table below. See Enclave Signing

Examples for more information.

Table 1 Signing Tool Commands

Command Description Arguments

sign

Sign the enclave using the private

key in one step.

Required: -enclave, -key,

-out

Optional: -config

gendata

The first step of the 2-step signing

process. Generate the enclave sign-

ing material to be signed by an

external tool. This step dumps the

signing material, which consists of the

header and body sections of the

enclave signature structure (see the

Table Enclave Signature Structure in

this topic), into a file (256 bytes in

total).

Required: -enclave, -out

Optional: -config

catsig

The second step of the 2-step sign-

ing process. Generate the signed

enclave with the input signature and

Required: -enclave, -key,

-out, -sig, -unisgned

Optional: -config

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 15 -

public key. The input signature is gen-

erated by an external tool based on

the data generated by the gendata

command. At this step, the signature

and buffer sections are generated.

The signature and buffer sections

together with the header and body

sections complete the enclave sig-

nature structure (see the Table

Enclave Signature Structure in this

topic).

All the valid command options are listed below:

Table 2 Signing Tool Arguments

Arguments Descriptions

-enclave

<file>

Specify the enclave file to be signed.

It is a required argument for the three commands.

-config

<file>

Specify the enclave configuration file

It is an optional argument for the three commands.

-out

<file>

Specify the output file.

It is required for the three commands.

Command Description

sign

The signed enclave file.

gendata

The file with the enclave signing

material.

catsig

The signed enclave file.

-key

<file>

Specify the signing key file. See File Formats for detailed descrip-

tion.

Command Description

sign

Private key.

gendata

Not applicable.

catsig

Public key.

-sig

<file>

Specify the file containing the signature corresponding to the

enclave signing material.

Only valid for catsig command.

Specify the file containing the enclave signing material generated

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 16 -

unsigned

<file>

by gendata.

Only valid for catsig command.

-ignore-

rel-

error

By default, sgx_sign provides an error for enclaves with text relo-

cations. You can ignore the error and continue signing by provid-

ing this option. But it is recommended you eliminate the text

relocations instead of bypassing the error with this option.

The arguments, including options and filenames,can be specified in any order.

Options are processed first, then filenames. Use one or more spaces or tabs to

separate arguments. Each option consists of an option identifier, a dash (-), fol-

lowed by the name of the option. The <file> parameter specifies the abso-

lute or relative path of a file.

sgx_sign generates the output file and returns 0 for success. Otherwise, it gen-

erates an error message and returns -1.

Table 3 Enclave Signature Structure

Section

Name

Header

HEADERTYPE

HEADERLEN

HEADERVERSION

TYPE

MODVENDOR

DATE

SIZE

KEYSIZE

MODULUSSIZE

ENPONENTSIZE

SWDEFINED

RESERVED

Signature

MODULUS

EXPONENT

SIGNATURE

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 17 -

Section

Name

Body

MISCSELECT

MISCMASK

RESERVED

ATTRIBUTES

ATTRIBUTEMASK

ENCLAVEHASH

RESERVED

ISVPRODID

ISVSVN

Buffer

RESERVED

EnclaveSigning Key Management

An enclave project supports different signing methods needed by ISVs during

the enclave development life cycle.

Single-step method using the ISV’s test private key:

The signing tool supports a single-step signing process, which requires

the access to the signing key pair on the local build system. However,

there is a requirement that any white-listed enclave signing key must be

managed in a hardware security module. Thus, the ISV’s test private key

stored in the build platform will not be white-listed and enclaves signed

with this key can only be launched in debug or prerelease mode. In this

scenario, the ISV manages the signing key pair, which could be gen-

erated by the ISV using his own means. Single-step method is the

default signing method for non-production enclave applications, which

are created with the Intel SGX project debug and prerelease profiles.

l 2-step method using an external signing tool:

First step: At the end of the enclave build process, the signing tool

generates the enclave signing material.

The ISV takes the enclave signing material file to an external sign-

ing platform/facility where the private key is stored, signs the sign-

ing material file, and takes the resulting signature file back to the

build platform.

Second step: The ISVruns the signing tool with the catsig

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 18 -

command providing the necessary information at the command

line to add the hash of the public key and signature to the enclave’s

metadata section.

The 2-step signing process protects the signing key in a separate facility.

Thus it is the default signing method for the Intel SGX project release

profile. This means it is the only method for signing production enclave

applications.

File Formats

There are several files with various formats followed by the different options.

The file format details are listed below.

Table 4 Signing Tool File Formats

File Format Description

Enclave file Shared

Object

It is a standard Shared Object.

Signed

enclave file

Shared

Object

sgx_sign generates the signed enclave file , which

includes the signature, to the enclave file.

Configuration

file

XML See Enclave Configuration File.

Key file PEM Key file should follow the PEM format which contains an

unencrypted RSA 3072-bit key. The public exponent

must be 3.

Enclave hex

file

RAW It is a dump file of the enclave signing material data to

be signed with the private RSA key.

Signature file RAW It is a dump file of the signature generated at the ISV’s

signing facility. The signature should follow the RSA-

PKCS1.5 padding scheme. The signature should be gen-

erated using the v1.5 version of the RSA scheme with

an SHA-256 message digest.

Signing Key Files

The enclave signing tool only accepts key files in the PEM format and unen-

crypted. When an enclave project is created for the first time, you have to

choose either using an already existing signing key or automatically generating

one key for you. When you choose to import a pre-existing key, ensure that

such key is in PEM format and unencrypted. If that is not the case, convert the

signing key to the format accepted by the Signing Tool first. For instance, the

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 19 -

following command converts an encrypted private key in PKCS#8/DER format

to unencrypted PEM format:

openssl pkcs8 –inform DER –in private_pkcs8.der –outform

PEM –out private_pkcs1.pem

Depending on the platform OS, the openssl* utility might be installed already

or it may be shipped with the Intel(R) SGX SDK.

Enclave Signing Examples

The following are typical examples for signing an enclave using the one-step

or the two-step method. When the private signing key is available at the build

platform, you may follow the one-step signing process to sign your enclave.

However, when the private key is only accessible in an isolated signing facility,

you must follow the two-step signing process described below.

l One-step signing process:

Signing an enclave using a private key available on the build system:

sgx_sign sign -enclave enclave.so -config config.xml

-out enclave_signed.so -key private.pem

l Two-step signing process:

Signing an enclave using a private key stored in an HSM, for instance:

1. Generate the enclave signing material.

sgx_sign gendata -enclave enclave.so -config con-

fig.xml -out enclave_hash.hex

2. At the signing facility, sign the file containing the enclave signing

material (enclave_hash.hex) and take the resulting signature

file (signature.hex) back to the build platform.

3. Sign the enclave using the signature file and public key.

sgx_sign catsig -enclave enclave.so -config con-

fig.xml -out enclave_signed.so -key public.pem

-sig signature.hex -unsigned enclave_hash.hex

The configuration file config.xml is optional.If you do not provide a con-

figuration file, the signing tool uses the default configuration values.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 20 -

Asingle enclave signing tool is provided, which allows signing 32-bit and 64-

bit enclaves. In addition, on Windows* OS sgx_sign supports signing

enclaves in both PE and ELF formats.

OpenSSL* Examples

The following command lines are typical examples using OpenSSL*.

1. Generate a 3072-bit RSA private key. Use 3 as the public exponent

value.

openssl genrsa -out private_key.pem -3 3072

2. Produce the public part of a private RSA key.

openssl rsa -in private_key.pem -pubout -out public_

key.pem

3. Sign the file containing the enclave signing material.

openssl dgst -sha256 -out signature.hex -sign private_

key.pem -keyform PEM enclave_hash.hex

Enclave Debugger

You can leverage the helper script sgx-gdb to debug your enclave applic-

ations. To debug an enclave on a hardware platform, the <DisableDebug>

configuration parameter should be set to 0 in the enclave configuration file

config.xml, and you should set the Debug parameter to 1 in the sgx_cre-

ate_enclave(…) that creates the enclave. Debugging an enclave is similar

to debugging a shared library. However not all the standard features are avail-

able to debug enclaves. The following table lists some unsupported GDB com-

mands for enclave. sgx-gdb also supports measuring the enclave stack/heap

usage by the Enclave Memory Measurement Tool. See Enclave Memory Meas-

urement Tool for additional information.

Table 5 GDBUnsupported Commands

GDBCommand Description

info sharedlibrary Does not show the status of the loaded enclave.

next/step Does not allows to execute the next/step outside the enclave from inside

the enclave. To go outside the enclave use the finish command.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 21 -

call/print Does not support calling outside the enclave from within an enclave func-

tion, or calling inside the enclave from a function in the untrusted

domain.

charset Only supports GDB'sdefault charset.

gcore Does not support debug enclave with the application dump file

Performance Measurement using Intel(R) VTune(TM) Amplifier

You can use Intel® VTune™ Amplifier Application 2016 Update 2 to measure

the performance of Intel SGX applications including the enclave. Intel(R)

VTune(TM) Amplifier application supports a new analysis type called SGX

Hotspots that can be used to profile the Intel SGX Enclave Applications. You

can use the default settings of SGX Hotspots to profile the application and

the enclave code. Precise event based sampling (PEBS) helps to profile the

Intel SGX enclave code. The _PS events represent precise events. You can

add _PS events to the collection to profile enclave code. Non precise events

would not help with profiling Intel SGX enclave code.

You can use Intel(R) VTune(TM) Amplifier to measure the performance of

enclave code only when the enclave has been launched as a debug enclave.

To launch the enclave as a debug enclave, pass a value of 1 as the second para-

meter to the sgx_create_enclave function which loads and initializes the

enclave as shown below. Use the pre-defined macro SGX_DEBUG_FLAG as

the parameter, which equals 1 in the DEBUG and the PRE-RELEASE mode.

sgx_create_enclave(ENCLAVE_FILENAME, SGX_DEBUG_FLAG,

&token, &updated, &global_eid, NULL);

NOTE:

Only use Intel(R) VTune(TM) Amplifier to measure the performance in the

DEBUG and PRE-RELEASE mode because a DEBUG FLAG value of 1 cannot

be passed in to create an enclave in RELEASE configuration.

Intel(R) VTune(TM) Amplifier provides two options to profile applications:

l Run the applications using Intel(R) VTune(TM) Amplifier. If you use this

approach, you do not have to do anything special.

Attach to an already running process or enclave application. If you use

this approach, define the environment variable as follows:

32bit:

INTEL_LIBITTNOTIFY32 = <VTune Installation

Dir>/lib32/runtime/ittnotify_collector.so

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 22 -

64bit:

INTEL_LIBITTNOTIFY64 = <VTune Installation

Dir>/lib64/runtime/ittnotify_collector.so

Once an enclave is loaded, the invoked ITT API of Intel(R) VTune(TM) Amplifier

in the uRTS passes information about the enclave to VTune and profiles Intel

SGX enclave applications. When you attach Intel(R) VTune(TM) Amplifier to

the application after invoking ITT API of Intel(R) VTune(TM) Amplifier, the mod-

ule information about the enclave is cached in the ITT dynamic library and is

used by the Intel(R) VTune(TM) Amplifier application during attach to process.

The following table describes the different scenarios of how Intel(R) VTune

(TM) Amplifier is used to profile the enclave application.

Intel(R) VTune(TM)

Amplifier Invocation

Additional Con-

figuration

ITTAPI Res-

ult

uRTSAction

Launch the application

with Intel(R) VTune(TM)

Amplifier

N/A Intel(R)

VTune(TM)

Amplifier is

profiling

Set Debug OPTIN bit

andinvoke Module

mapping API.

Late attach before invok-

ing ITTAPI for Intel(R)

VTune(TM) Amplifier pro-

filing check in sgx_

cereate_enclave

ITTenvironment

variable is set.

Intel(R)

VTune(TM)

Amplifier is

profiling

Set Debug OPTIN bit

andinvoke Module

mapping API.

ITTenvironment

variable is not

set.

Intel(R)

VTune(TM)

Amplifier is

not profiling

Do not set Debug

OPTIN bit and do not

invoke Module map-

ping API.

Even though Intel(R)

VTune(TM) Amplifier

is running, it cannot

profile enclaves. You

need to set the envir-

onment variable.

Late attach after invok-

ing ITTAPI for Intel(R)

VTune(TM) Amplifier pro-

filing check in sgx_

cereate_enclave

ITTenvironment

variable is set.

Intel(R)

VTune(TM)

Amplifier is

profiling

Set Debug OPTIN bit

and Invoke Module

mapping API.

The ITTdynamic lib-

rary caches the mod-

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 23 -

ule information and

provides it to the Intel

(R) VTune(TM) Ampli-

fier during attach to

process.

ITTenvironment

variable is not

set.

Intel(R)

VTune(TM)

Amplifier is

not profiling

Do not set Debug

OPTIN bit and do not

Invoke Module map-

ping API.

Even though Intel(R)

VTune(TM) Amplifier

is running here it can-

not profile enclaves.

You need to set the

environment variable.

Launch the application

without Intel(R) VTune

(TM) Amplifier

N/A Intel(R)

VTune(TM)

Amplifier is

not profiling

Do not set Debug

OPTIN bit and do not

invoke Module map-

ping API.

Enclave Memory Measurement Tool

An enclave is an isolated environment. The Intel(R) Software Guard Extensions

SDK provides a tool called sgx_emmt to measure the real usage of protected

memory by the enclave at runtime.

Currently the enclave memory measurement tool provides the following two

functions:

1. Get the stack peak usage value for the enclave.

2. Get the heap peak usage value for the enclave.

The tool reports the size of both stack and heap in KB. When you get the accur-

ate stack and heap usage information for your enclaves, you can rework the

enclave configuration file based on this information to make full use of the pro-

tected memory. See Enclave Configuration File for details.

On Linux* OS, the enclave memory measurement capability is provided by the

helper script sgx-gdb. The sgx-gdb is a GDB extension for you to debug

your enclave applications. See Enclave Debugger for details.

To measure how much protected memory an enclave uses, you should lever-

age sgx-gdb to launch GDB with sgx_emmt enabled and load the test

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 24 -

application which is using the enclave. You may also attach the debugger to a

running an Intel SGX application in order to measure the heap and stack sizes

of th enclave.

The sgx-gdb provides three commands pertaining the sgx_emmt tool:

Table 6 Enclave Memory Measurement Tool Commands

Command Description

enable sgx_emmt Enable the enclave memory measurement tool.

disable sgx_emmt Disable the enclave memory measurement tool.

show sgx_emmt Show whether the enclave memory measurement tool is enabled or not.

Here are the typical steps necessary to collect an enclave’s memory usage

information:

1. Leverage sgx-gdb to start a GDB session.

2. Enable the enclave memory measurement function with enable sgx_

emmt.

3. Load and run the test application which is using the enclave.

NOTE:

To collect peak stack/heap usage for an enclave on a hardware platform cor-

rectly, you need to make sure the enclave meets the following requirements:

1. The enclave is debuggable. This means that the <DisableDebug> con-

figuration parameter in the enclave configuration file should be set to 0.

2. The enclave is launched in the debug mode. To launch the enclave in the

debug mode, set the debug flag to 1 when calling sgx_create_enclave to

load the enclave.

3. You need to export g_peak_heap_used in the version script of the

enclave.

4. You need to destroy the enclave by using thesgx_destroy_enclave API.

CPUSVN Configuration Tool

CPUSVN stands for Security Version Number of the CPU, which affects the key

derivation and report generation process. CPUSVN is not a numeric concept

and will be upgraded/downgraded along with the hardware upgrade/-

downgrade. To simulate the CPUSVN upgrade/downgrade without modifying

the hardware, the Intel(R) Software Guard Extensions SDK provides a CPUSVN

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 25 -

configuration tool for you to configure the CPUSVN. The CPUSVN con-

figuration tool is for Intel(R) SGX simulation mode only.

Command-Line Syntax

To run the Intel(R) SGX CPUSVN configuration tool, use the following syntax:

sgx_config_cpusvn [Command]

The valid commands are listed in the table below:

Table 7 CPUSVNConfiguration Tool Commands

Command Description

-upgrade

Simulate a CPUSVN upgrade.

-downgrade

Simulate a CPUSVN downgrade.

-reset

Restore the CPUSVNto its default value.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 26 -

Enclave Development Basics

This topic introduces the following enclave development basics:

l Writing Enclave Functions

l Calling Functions inside the Enclave

l Calling Functions outside the Enclave

l Linking Enclave with Libraries

l Linking Application with Untrusted Libraries

l Enclave Definition Language Syntax

l Loading and Unloading an Enclave

The typical enclave development process includes the following steps:

1. Define the interface between the untrusted application and the enclave

in the EDL file.

2. Implement the application and enclave functions.

3. Build the application and enclave. In the build process, Edger8r Tool gen-

erates trusted and untrusted proxy/bridge functions. Enclave Signing

Tool generates the metadata and signature for the enclave.

4. Run and debug the application in simulation and hardware modes. See

Enclave Debugger for more details.

5. Prepare the application and enclave for release.

Writing Enclave Functions

From an application perspective, making an enclave call (ECALL) appears as

any other function call when using the untrusted proxy function. Enclave func-

tions are plain C/C++ functions with several limitations.

The user can write enclave functions in C and C++ (native only). Other lan-

guages are not supported.

Enclave functions can rely on special versions of the C/C++ runtime libraries,

STL, synchronization and several other trusted libraries that are part of the

Intel(R) Software Guard Extensions SDK. These trusted libraries are spe-

cifically designed to be used inside enclaves.

The user can write or use other trusted libraries, making sure the libraries fol-

low the same rules as the internal enclave functions:

1. Enclave functions can’t use all the available 32-bit or 64-bit instructions.

To check a list of illegal instructions inside an enclave, see Intel(R)

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 27 -

Software Guard Extensions Programming Reference.

2. Enclave functions will only run in user mode (ring 3). Using instructions

requiring other CPU privileges will cause the enclave to fault.

3. Function calls within an enclave are possible if the called function is stat-

ically linked to the enclave (the function needs to be in the enclave

image file).Linux* Shared Objects are not supported.

CAUTION:

The enclave signing process will fail if the enclave image contains any unre-

solved dependencies at build time.

Calling functions outside the enclave is possible using what are called OCALLs.

OCALLs are explained in detail in the Calling Functions outside the Enclave sec-

tion.

Table 8 Summary of Intel(R) SGX Rules and Limitations

Feature Supported Comment

Languages Partially Native C/C++. Enclave interface functions are lim-

ited to C (no C++).

C/C++ calls to

other Shared

Objects

No Can be done by explicit external calls (OCALLs).

C/C++ calls to

System

provided

C/C++/STL

standard lib-

raries

No A trusted version of these libraries is supplied

with the Intel(R) Software Guard Extensions SDK

and they can be used instead.

OS API calls No Can be done by explicit external calls (OCALLs).

C++ frame-

works

No Including MFC*, QT*, Boost* (partially – as long as

Boost runtime is not used).

Call C++ class

methods

Yes Including C++ classes, static and inline functions.

Intrinsic func-

tions

Partially Supported only if they use supported instruc-

tions.

The allowed functions are included in the Intel(R)

Software Guard Extensions SDK.

Inline assembly Partially Same as the intrinsic functions.

Template func- Partially Only supported in enclave internal functions

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 28 -

tions

Ellipse (…) Partially Only supported in enclave internal functions

Varargs (va_

list)

Partially Only supported in enclave internal functions.

Synchronization Partially The Intel(R) Software Guard Extensions SDK

provides a collection of functions/objects for

synchronization:spin-lock, mutex, and condition

variable.

Threading sup-

port

Partially Creating threads inside the enclave is not sup-

ported. Threads that run inside the enclave are

created within the (untrusted) application. Spin-

locks, trusted mutex and condition variables API

can be used for thread synchronization inside the

enclave.

Thread Local

Storage (TLS)

Partially Only implicitly via __thread.

Dynamic

memory alloc-

ation

Yes Enclave memory is a limited resource. Maximum

heap size is set at enclave creation.

C++ Exceptions Yes Although they have an impact on performance.

SEH Exceptions No The Intel(R) Software Guard Extensions SDK

provides an API to allow you to register functions,

or exception handlers, to handle a limited set of

hardware exceptions. See Custom Exception

Handling for more details.

Signals No Signals are not supported inside an enclave.

Calling Functions inside the Enclave

After an enclave is loaded successfully, you get an enclave ID which is

provided as a parameter when the ECALLs are performed. Optionally, OCALLs

can be performed within an ECALL. For example, assume that you need to com-

pute some secret inside an enclave, the EDL file might look like the following:

// demo.edl

enclave {

// Add your definition of "secret_t" here

trusted {

public void get_secret([out] secret_t* secret);

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 29 -

};

untrusted {

// This OCALL is for illustration purposes only.

// It should not be used in a real enclave,

// unless it is during the development phase

// for debugging purposes.

void dump_secret([in] const secret_t* secret);

};

With the above EDL, the sgx_edger8r will generate an untrusted proxy func-

tion for the ECALLand a trusted proxy function for the OCALL:

Untrusted proxy function (called by the application):

sgx_status_t get_secret(sgx_enclave_id_t eid, secret_t*

secret);

Trusted proxy function (called by the enclave):

sgx_status_t dump_secret(const secret_t* secret);

The generated untrusted proxy function will automatically call into the

enclave with the parameters to be passed to the real trusted function get_

secret inside the enclave. To initiate an ECALL in the application:

// An enclave call (ECALL) will happen here

secret_t secret;

sgx_status_t status = get_secret(eid, &secret);

The trusted functions inside the enclave can optionally do an OCALL to dump

the secret with the trusted proxy dump_secret. It will automatically call out

of the enclave with the given parameters to be received by the real untrusted

function dump_secret. The real untrusted function needs to be imple-

mented by the developer and linked with the application.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 30 -

Checking the Return Value

The trusted and untrusted proxy functions return a value of type sgx_

status_t. If the proxy function runs successfully, it will return SGX_

SUCCESS. Otherwise, it indicates a specific error described in Error Codes sec-

tion. You can refer to the sample code shipped with the SDK for examples of

proper error handling.

Calling Functions outside the Enclave

In some cases, the code within the enclave needs to call external functions

which reside in untrusted (unprotected) memory to use operating system cap-

abilities outside the enclave such as system calls, I/O operations, and so on.

This type of function call is named OCALL.

These functions need to be declared in the EDL file in the untrusted section.

See Enclave Definition Language Syntax for more details.

The enclave image is loaded very similarly to how Linux* OS loads shared

objects. The function address space of the application is shared with the

enclave so the enclave code can indirectly call functions linked with the applic-

ation that created the enclave. Calling functions from the application directly

is not permitted and will raise an exception at runtime.

CAUTION:

The wrapper functions copy the parameters from protected (enclave)

memory to unprotected memory as the external function cannot access pro-

tected memory regions. In particular, the OCALLparameters are copied into

the untrusted stack. Depending on the number of parameters, the OCALL may

cause a stack overrun in the untrusted domain. The exception that this event

will trigger will appear to come from the code that the sgx_eder8r generates

based on the enclave EDLfile. However, the exception can be easily detected

using the Intel(R) SGXdebugger.

CAUTION:

The wrapper functions will copy buffers (memory referenced by pointers) only

if these pointers are assigned special attributes in the EDL file.

CAUTION:

Certain trusted libraries distributed with the Intel(R) Software Guard Exten-

sions SDK provide an API that internally makes OCALLs. Currently, the Intel(R)

Software Guard Extensions mutex, condition variable, and CPUID APIs from

libsgx_tstdc.a make OCALLs. Similarly, the trusted support library libsgx_

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 31 -

tservice.a, which provides services from the Platform Services Enclave (PSE-

Op), also makes OCALLs. Developers who use these APIs must first import the

needed OCALL functions from their corresponding EDL files. Otherwise,

developers will get a linker error when the enclave is built. See the Importing

EDLLibraries for details on how to import OCALL functions from a trusted lib-

rary EDL file.

CAUTION:

To help identify problems caused by missing imports, all OCALL functions

used in the Intel(R) Software Guard Extensions SDK have the suffix ocall. For

instance, the linker error below indicates that the enclave needs to import the

OCALLs sgx_thread_wait_untrusted_event_ocall() and sgx_

thread_set_untrusted_event_ocall() that are needed in

sethread_mutex.obj, which is part of libsgx_tstdc.a.

libsgx_tstdc.a(sethread_mutex.o): In function `sgx_

thread_mutex_lock':

sethread_mutex.cpp:109: undefined reference to `sgx_

thread_wait_untrusted_event_ocall'

libsgx_tstdc.a(sethread_mutex.o): In function `sgx_

thread_mutex_unlock':

sethread_mutex.cpp:213: undefined reference to `sgx_

thread_set_untrusted_event_ocall'

CAUTION:

Accessing protected memory from unprotected memory will result in abort

page semantics. This applies to all parts of the protected memory including

heap, stack, code and data.

Abort page semantics:

An attempt to read from a non-existent or disallowed resource returns all ones

for data (abort page). An attempt to write to a non-existent or disallowed phys-

ical resource is dropped. This behavior is unrelated to exception type abort

(the others being Fault and Trap).

OCALL functions have the following limitations/rules:

l OCALLfunctions must be C functions, or C++ functions with C linkage.

l Pointers that reference data within the enclave must be annotated with

pointer direction attributes in the EDL file. The wrapper function will

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 32 -

perform shallow copy on these pointers. See Pointers for more inform-

ation.

l Exceptions will not be caught within the enclave. The user must handle

them in the untrusted wrapper function.

l OCALLs cannot have an ellipse (…) or a va_list in their prototype.

Example 1: The definition of a simple OCALLfunction

Step 1 – Add a declaration for foo in the EDL file

// foo.edl

enclave {

untrusted {

[cdecl] void foo(int param);

};

Step 2 (optional but highly recommended) – write a trusted, user-friendly

wrapper. This function is part of the enclave's trusted code.

The wrapper function ocall_foo function will look like:

// enclave's trusted code

#include "foo_t.h"

void ocall_foo(int param)

{

// it is necessary to check the return value of foo()

if (foo(param) != SGX_SUCCESS)

abort();

}

Step 3 – write an untrusted foo function.

// untrusted code

void foo(int param)

{

// the implementation of foo

}

The sgx_edger8r will generate an untrusted bridge function which will call

the untrusted function foo automatically. This untrusted bridge and the tar-

get untrusted function are part of the application, not the enclave.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 33 -

Library Development for Enclaves

Trusted library is the term used to refer to a static library designed to be

linked with an enclave. The following list describes the features of trusted lib-

raries:

l Trusted libraries are components of an Intel(R) SGX-based solution. They

typically undergo a more rigorous threat evaluation and review process

than a regular static library.

l A trusted library is developed (or ported) with the specific purpose of

being used within an enclave. Therefore, it should not contain instruc-

tions that are not supported by the Intel(R) SGXarchitecture.

l A subset of the trusted library API may also be part of the enclave inter-

face. The trusted library interface that could be exposed to the untrus-

ted domain is defined in an EDLfile. If present, this EDLfile is a key

component of the trusted library.

l A trusted library may have to be shipped with an untrusted library. Func-

tions within the trusted library may make OCALLs outside the enclave. If

an external function that the trusted library uses is not provided by the

libraries available on the platform, the trusted library will require an

untrusted support library.

In summary, a trusted library, in addition to the .a file containing the trusted

code and data, may also include an .edl file as well as an untrusted .a file.

This topic describes the process of developing a trusted library and provides

an overview of the main steps necessary to build an enclave that uses such a

trusted library.

1. The ISV provides a trusted library including the trusted functions

(without any edge-routines) and, when necessary, an EDL file and an

untrusted support library. To develop a trusted library, an ISV should cre-

ate an enclave project and choose the library option in the Eclipse plug-

in. This ensures the library is built with the appropriate settings. The

ISVmight delete the EDLfile from the project if the trusted library only

provides an interface to be invoked within an enclave. The ISV should

create a standard static library project for the untrusted support library,

if required.

Add a “from/import” statement with the library EDL file path and name

to the enclave EDL file. The import statement indicates which trusted

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 34 -

functions (ECALLs) from the library may be called from outside the

enclave and which untrusted functions (OCALLs) are called from within

the trusted library. You may import all ECALLs and OCALLs from the trus-

ted library or select a specific subset of them.

A library EDL file may import additional library EDL files building a hier-

archical structure. For additional details, See Importing EDLLibraries.

3. During the enclave build process, the sgx_edger8r generates

proxy/bridge code for all the trusted and untrusted functions. The gen-

erated code accounts for the functions declared in the enclave EDLfile

as well as any imported trusted library EDLfile.

The trusted library and trusted proxy/bridge functions are linked to the

enclave code.

NOTE:

If you use the wildcard option to import a trusted library, the resulting

enclave contains the trusted bridge functions for all ECALLs and their cor-

responding implementations. The linker will not be able to optimize this

code out.

The Intel(R) SGX application is linked to the untrusted proxy/bridge

code. Similarly, when the wildcard import option is used, the untrusted

bridge functions for all the OCALLs will be linked in.

Avoiding Name Collisions

An application may be designed to work with multiple enclaves. In this scen-

ario, each enclave would still be an independent compilation unit resulting in a

separate SO file.

Enclaves, like regular SO files, should provide a unique interface to avoid name

collisions when an untrusted application is linked with the edge-routines of

several enclaves. The sgx_edger8r prevents name collisions among OCALL

functions because it automatically prepends the enclave name to the names

of the untrusted bridge functions. However, ISVs must ensure the uniqueness

of the ECALL function names across enclaves to prevent collisions among

ECALL functions.

Despite having unique ECALL function names, name collision may also occur as

the result of developing an Intel(R) SGXapplication. This happens because an

enclave cannot import another SO file. When two enclaves import the same

ECALL function from a trusted library, the set of edge-routines for each

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 35 -

enclave will contain identical untrusted proxy functions and marshaling data

structures for the imported ECALL. Thus, the linker will emit an error when the

application is linked with these two sets of edge-routines. To build an applic-

ation with more than one enclave when these enclaves import the same ECALL

from a trusted library, ISVs have to:

1. Provide the --use-prefix option to sgx_edger8r, which will pre-

pend the enclave name to the untrusted proxy function names. For

instance, when an enclave uses the local attestation trusted library

sample code included in the Intel(R) SGXSDK, the enclave EDLfile must

be parsed with the --use-prefix option to sgx_edger8r. See Local

Attestation for additional details.

2. Prefix all ECALLs in their untrusted code with the enclave name, match-

ing the new proxy function names.

Linking Enclave with Libraries

This topic introduces how to link an enclave with the following types of lib-

raries:

l Dynamic libraries

l Static Libraries

l Simulation Libraries

Dynamic Libraries

An enclave shared object must not depend on any dynamically linked library

in any way. The enclave loader has been intentionally designed to prohibit

dynamic linking of libraries within an enclave. The protection of an enclave is

dependent upon obtaining an accurate measurement of all code and data that

is placed into the enclave at load time; thus, dynamic linking would add com-

plexity without providing any benefit over static linking.

CAUTION:

The enclave image signing process will fail if the enclave file has any unre-

solved dependencies.

Static Libraries

You can link with static libraries as long as they do not have any dependencies.

The Intel(R) Software Guard Extensions SDK provides the following collection

of trusted libraries.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 36 -

Table 9 Trusted Libraries included in the Intel(R) SGX SDK

Name Description Comment

libsgx_

trts.a

Intel(R) SGX internals Must link when

running in HW

mode

libsgx_

trts_sim.a

Intel(R) SGX internals (simulation mode) Must link when

running in sim-

ulation mode

libsgx_

tstdc.a

Standard C library (math, string, and so on.) Must link

libsgx_tsetjm-

p.a

Provides setjmp and longjmp functions to

be used to perform non-local jumps.

Optional

libsgx_

tstdcxx.a

Standard C++ libraries, STL Optional

libsgx_

tservice.a

Data seal/unseal (encryption), trusted Archi-

tectural Enclaves support, Elliptic Curve Diffie-

Hellman (EC DH) library, and so on.

Must link when

using HW mode

libsgx_

tservice_

sim.a

The counterpart of libsgx_tservice.a for sim-

ulation mode

Must link when

using simulation

mode

libsgx_

tcrypto.a

Cryptographic library Must link

libsgx_

tkey_

exchange.a

Trusted key exchange library Optional

Simulation Libraries

The Intel(R) SGX SDK provides simulation libraries to run application enclaves

in simulation mode (Intel(R) SGX hardware is not required).There are an

untrusted simulation library and a trusted simulation library.The untrusted

simulation library provides the functionality that the untrusted runtime library

requires to manage an enclave linked with the trusted simulation library,

including the simulation of the Intel(R) SGXinstructions executed outside the

enclave:ECREATE, EADD, EEXTEND, EINIT, EREMOVE, and EENTER. The trus-

ted simulation library is primarily responsible for simulating the Intel(R) SGX

instructions that can execute inside an enclave:EEXIT, EGETKEY, and

EREPORT.

NOTE

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 37 -

Simulation mode does not require the Intel SGX support in the CPU. However,

the processor must support the Intel(R) Streaming SIMD Extensions 4.1

instructions at least.

Linking Application with Untrusted Libraries

The Intel(R) Software Guard Extensions SDK provides the following collection

of untrusted libraries.

Table 10 Untrusted Libraries included in the Intel(R) SGXSDK

Name Description Comment

libsgx_urts.so

Provides functionality for applic-

ations to manage enclaves

Must link when running

in HW mode.

libsgx_urts.so is

included in Intel(R)

SGXPSW

libsgx_urts_

sim.so

uRTSlibrary used in simulation

mode

Dynamically linked

libsgx_uae_ser-

vice.so

Provides both enclaves and

untrusted applications access to

services provided by the AEs

Must link when running

in HW mode.

libsgx_uae_ser-

vice.so is included

in Intel(R) SGXPSW

libsgx_uae_ser-

vice_sim.so

Untrusted AEsupport library used

in simulation mode

Dynamically linked

libsgx_ukey_

exchange.a

Untrusted key exchange library Optional

Enclave Definition Language Syntax

Enclave Definition Language (EDL) files are meant to describe enclave trusted

and untrusted functions and types used in the function prototypes. Edger8r

Tool uses this file to create C wrapper functions for both enclave exports

(used by ECALLs) and imports (used by OCALLs).

EDL Template

enclave {

//Include files

//Import other edl files

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 38 -

//Data structure declarations to be used as parameters of the

//function prototypes in edl

trusted {

//Include header files if any

//Will be includedd in enclave_t.h

//Trusted function prototypes

};

untrusted {

//Include header files if any

//Will be included in enclave_u.hhead

//Untrusted function prototypes

};

The trusted block is optional only if it is used as a library EDL, and this EDL

would be imported by other EDL files. However the untrusted block is always

optional.

Every EDL file follows this generic format:

enclave {

// An EDL file can optionally import functions from

// other EDL files

from “other/file.edl” import foo, bar; // selective importing

from “another/file.edl” import *; // import all functions

// Include C headers, these headers will be included in the

// generated files for both trusted and untrusted routines

include "string.h"

include "mytypes.h"

// Type definitions (struct, union, enum), optional

struct mysecret {

int key;

const char* text;

};

enum boolean { FALSE = 0, TRUE = 1 };

// Export functions (ECALLs), optional for library EDLs

trusted {

//Include header files if any

//Will be included in enclave_t.h

//Trusted function prototypes

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 39 -

public void set_secret([in] struct mysecret* psecret);

void some_private_func(enum boolean b); // private ECALL

(non-root ECALL).

};

// Import functions (OCALLs), optional

untrusted {

//Include header files if any

//Will be included in enclave_u.h

//Will be inserted in untrusted header file

“untrusted.h”

//Untrusted function prototypes

// This OCALL is not allowed to make another ECALL.

void ocall_print();

// This OCALL can make an ECALL to function

// “some_private_func”.

int another_ocall([in] struct mysecret* psecret)

allow(some_private_func);

};

Comments

Both types of C/C++ comments are valid.

Example

enclave {

include “stdio.h” // include stdio header

include “../../util.h” /* this header defines some custom public

types */

};

Include Headers

Include C headers which define types (C structs, unions, typedefs, etc.); oth-

erwise auto generated code cannot be compiled if these types are referenced

in EDL. The included header file can be global or belong to trusted functions

or untrusted functions only.

A global included header file doesn’t mean that the same header file is

included in the enclave and untrusted application code. In this case, the

enclave will use the stdio.h from the Intel(R) Software Guard Extensions

SDK. While the application code will use the stdio.h shipped with the host

compiler.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 40 -

Using the include directive is convenient when developers are migrating

existing code to the Intel SGX technology, since data types are defined

already in this case. Similar to other IDL languages like Microsoft* interface

definition language (MIDL*) and CORBA* interface definition language (OMG-

IDL), a user can define data types inside the EDL file and sgx_edger8r will

generate a C header file with the data type definitions. For a list of supported

data types with in EDL, see Basic Types.

Syntax

include “filename.h”

Example

enclave {

include “stdio.h” // global headers

include “../../util.h”

trusted {

include “foo.h” // for trusted functions only

};

untrusted {

include “bar.h” // for untrusted functions only

};

Keywords

The identifiers listed in the following table are reserved for use as keywords of

the Enclave Definition Language.

Table 11 EDLReserved Keywords

Data Types

char short int float double void

int8_t int16_t int32_t int64_t size_t wchar_t

uint8_t uint16_t uint32_t uint64_t unsigned struct

union enum long

Pointer Parameter Handling

in out user_check count size readonly

isptr sizefunc string wstring

Others

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 41 -

enclave from import trusted untrusted include

public allow isary const propagate_errno

Function Calling Convention

cdecl stdcall fastcall dllimport

Basic Types

EDL supports the following basic types:

char, short, long, int, float, double, void, int8_t,

int16_t, int32_t, int64_t, size_t, wchar_t, uint8_t,

uint16_t, uint32_t, uint64_t, unsigned, struct, enum,

union.

It also supports long long and64-bit long double.

Basic data types can be modified using the C modifiers:

const, *, [].

Additional types can be defined by including a C header file.

Structures, Enums and Unions

Basic types and user defined data types can be used inside the struc-

ture/union except it differs from the standard in the following ways:

Unsupported Syntax:

enclave{

// 1. Each member of the structure has to be

// defined separately

struct data_def_t{

int a, b, c; // Not allowed

// It has to be int a; int b; int c;

};

// 2. Bit fields in structures/unions are not allowed.

struct bitfields_t{

short i : 3;

short j : 6;

short k : 7;

};

//3. Nested structure definition is not allowed

struct my_struct_t{

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 42 -

int out_val;

float out_fval;

struct inner_struct_t{

int in_val;

float in_fval;

};

Valid Syntax:

enclave{

include "user_types.h" //for ufloat: typedef float ufloat

struct struct_foo_t {

uint32_t struct_foo_0;

uint64_t struct_foo_1;

};

enum enum_foo_t {

ENUM_FOO_0 = 0,

ENUM_FOO_1 = 1

};

union union_foo_t {

uint32_t union_foo_0;

uint32_t union_foo_1;

uint64_t union_foo_3;

};

trusted {

public void test_char(char val);

public void test_int(int val);

public void test_long(long long val);

public void test_float(float val);

public void test_ufloat(ufloat val);

public void test_double(double val);

public void test_long_double(long double val);

public void test_size_t(size_t val);

public void test_wchar_t(wchar_t val);

public void test_struct(struct struct_foo_t val);

public void test_struct2(struct_foo_t val);

public void test_enum(enum enum_foo_t val);

public void test_enum2(enum_foo_t val);

public void test_union(union union_foot_t val);

public void test_union2(union_foo_t val);

};

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 43 -

};

Pointers

EDL defines several attributes that can be used with pointers:

in, out, user_check, string, wstring, size, count, size-

func, isptr, readonly.

Each of them is explained in the following topics.

CAUTION:

The pointer attributes explained in this topic apply to ECALL and OCALL func-

tion parameters exclusively, not to the pointers returned by an ECALL or

OCALL function. Thus, pointers returned by an ECALL or OCALL function are

not checked by the edge-routines and must be verified by the enclave and

application code.

Pointer Handling

Pointers should be decorated with either a pointer direction attribute in, out

or a user_check attribute explicitly. The [in] and [out] serve as direction

attributes.

l [in] – when [in] is specified for a pointer argument, the parameter is

passed from the calling procedure to the called procedure. For an ECALL

the in parameter is passed from the application to the enclave, for an

OCALL the parameter is passed from the enclave to the application.

l [out] – when [out] is specified for a pointer argument, the parameter is

returned from the called procedure to the calling procedure. In an ECALL

function an out parameter is passed from the enclave to the application

and an OCALL function passes it from the application to the enclave.

l [in] and [out] attributes may be combined. In this case the parameter is

passed in both directions.

The direction attribute instructs the trusted edge-routines (trusted bridge

and trusted proxy) to copy the buffer pointed by the pointer. In order to copy

the buffer contents, the trusted edge-routines have to know how much data

needs to be copied. For this reason, the direction attribute is usually followed

by a size, count or sizefunc modifier. If neither of these is provided nor

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 44 -

the pointer is NULL, the trusted edge-routine assumes a count of one. When

a buffer is being copied, the trusted bridge must avoid overwriting enclave

memory in an ECALL and the trusted proxy must avoid leaking secrets in an

OCALL. To accomplish this goal, pointers passed as ECALL parameters must

point to untrusted memory and pointers passed as OCALL parameters must

point to trusted memory. If these conditions are not satisfied, the trusted

bridge and the trusted proxy will report an error at runtime, respectively, and

the ECALL and OCALL functions will not be executed.

You may use the direction attribute to trade protection for performance.

Otherwise, you must use the user_check attribute described below and val-

idate the data obtained from untrusted memory via pointers before using it,

since the memory a pointer points to could change unexpectedly because it is

stored in untrusted memory. However, the direction attribute does not help

with structures that contain pointers. In this scenario, you have to validate and

copy the buffer contents, recursively if needed, yourself.

Example

enclave {

trusted {

public void test_ecall_user_check([user_check] int * ptr);

public void test_ecall_in([in] int * ptr);

public void test_ecall_out([out] int * ptr);

public void test_ecall_in_out([in, out] int * ptr);

};

untrusted {

void test_ocall_user_check([user_check] int * ptr);

void test_ocall_in([in] int * ptr);

void test_ocall_out([out] int * ptr);

void test_ocall_in_out([in, out] int * ptr);

};

Unsupported Syntax:

enclave {

trusted {

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 45 -

// Pointers without a direction attribute

// or ‘user_check’ are not allowed

public void test_ecall_not(int * ptr);

// Function pointers are not allowed

public void test_ecall_func([in]int (*func_ptr)());

};

In the example shown above:

For ECALL:

l [user_check]: In the function test_ecall_user_check, the pointer

ptr will not be verified; you should verify the pointer passed to the trus-

ted function. The buffer pointed to by ptr is not copied to inside buffer

either.

l [in]: In the function test_ecall_in, a buffer with the same size as the

data type of ‘ptr’(int) will be allocated inside the enclave. Content poin-

ted to by ptr, one integer value, will be copied into the new allocated

memory inside. Any changes performed inside the enclave will not be vis-

ible to the untrusted application.

l [out]: In the function test_ecall_out, a buffer with the same size as

the data type of ‘ptr’(int) will be allocated inside the enclave, but the

content pointed to by ptr, one integer value will not be copied. Instead,

it will be initialized to zero. After the trusted function returns, the buffer

inside the enclave will be copied to the outside buffer pointed to by

ptr.

l [in, out]: In the function test_ecall_in_out, a buffer with the same

size will be allocated inside the enclave, the content pointed to by ptr,

one integer value, will be copied to this buffer. After returning, the buffer

inside the enclave will be copied to the outside buffer.

For OCALL:

l [user_check]: In the function test_ocall_user_check, the pointer

ptr will not be verified; the buffer pointed to by ptr is not copied to an

outside buffer. Besides, the application cannot read/modify the memory

pointed to by ptr, if ptr points to enclave memory.

l [in]: In the function test_ocall_in, a buffer with the same size as the

data type of ptr(int) will be allocated in the 'application' side (untrusted

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 46 -

side). Content pointed to by ptr, one integer value, will be copied into

the newly allocated memory outside. Any changes performed by the

application will not be visible inside the enclave.

l [out]: In the function test_ocall_out, a buffer with the same size as

the data type of ptr(int) will be allocated on the application side (untrus-

ted side) and its content will be initialized to zero. After the untrusted

function returns, the buffer outside the enclave will be copied to the

enclave buffer pointed to by ptr.

l [in, out]: In the function test_ocall_in_out, a buffer with the same

size will be allocated in the application side, the content pointed to by

ptr,one integer value, will be copied to this buffer. After returning, the

buffer outside the enclave will be copied into the inside enclave buffer.

The following table summarizes behavior of wrapper functions when using the

in/out attributes:

Table 12 Behavior of wrapper functions when using the in/out attributes

ECALL OCALL

user_

check

Pointer is not checked. Users must per-

form the check and/or copy.

Pointer is not checked. Users

must perform the check

and/or copy

in Buffer copied from the application into

the enclave. Afterwards, changes will

only affect the buffer inside enclave.

Safe but slow.

Buffer copied from the

enclave to the application.

Must be used if pointer points

to enclave data.

out Trusted wrapper function will allocate a

buffer to be used by the enclave. Upon

return, this buffer will be copied to the

original buffer.

The untrusted buffer will be

copied into the enclave by

the trusted wrapper function.

Safe but slow.

in,

out

Combines in and out behavior. Data is

copied back and forth.

Same as ECALLs.

EDL cannot analyze C typedefs and macros found in C headers. If a pointer

type is aliased to a type/macro that does not have an asterisk (*), the EDL

parser may report an error or not properly copy the pointer’s data.

In such cases, declare the function prototype to use types that have an aster-

isk.

Example:

// Error, PVOID is not a pointer in EDL

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 47 -

void foo([in, size=4] PVOID buffer);

// OK

void foo([in, size=4] void* buffer);

// OK, “isptr” indicates “PVOID” is pointer type

void foo([in, isptr, size=4] PVOID buffer);

// OK, opaque type, copy by value

// Actual address must be in untrusted memory

void foo(HWND hWnd);

Pointer Handling in ECALLs

In ECALLs, the trusted bridge checks that the marshaling structure does not

overlap with the enclave memory, and automatically allocates space on the

trusted stack to hold a copy of the structure. Then it checks that pointer para-

meters with their full range do not overlap with the enclave memory. When a

pointer to the untrusted memory with the in attribute is passed to the

enclave, the trusted bridge allocates memory inside the enclave and copies

the memory pointed to by the pointer from outside to the enclave memory.

When a pointer to the untrusted memory with the out attribute is passed to

the enclave, the trusted bridge allocates a buffer in the trusted memory, zer-

oes the buffer contents to clear any previous data and passes a pointer to this

buffer to the trusted function. After the trusted function returns, the trusted

bridge copies the contents of the trusted buffer to untrusted memory. When

the in and out attributes are combined, the trusted bridge allocates memory

inside the enclave, makes a copy of the buffer in the trusted memory before

calling the trusted function, and once the trusted function returns, the trusted

bridge copies the contents of the trusted buffer to the untrusted memory.

The amount of data copied out is the same as the amount of data copied in.

NOTE:

When an ECALLwith a pointer parameter with outattribute returns, the trus-

ted bridge always copies data from the buffer in enclave memory to the buffer

outside. You must clear all sensitive data from that buffer on failure.

Before the trusted bridge returns, it frees all the trusted heap memory alloc-

ated at the beginning of the ECALL function for pointer parameters with a dir-

ection attribute. Attempting to use a buffer allocated by the trusted bridge

after it returns results in undefined behavior.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 48 -

Pointer Handling in OCALLs

For OCALLs, the trusted proxy allocates memory on the outside stack to pass

the marshaling structure and checks that the pointer parameters with their full

range are within enclave. When a pointer to trusted memory with the in attrib-

ute is passed from an enclave (an OCALL), the trusted proxy allocates memory

outside the enclave and copies the memory pointed by the pointer from

inside the enclave to the untrusted memory. When a pointer to the trusted

memory with the out attribute is passed from an enclave (an OCALL), the trus-

ted proxy allocates a buffer on the untrusted stack, and passes a pointer to

this buffer to the untrusted function. After the untrusted function returns, the

trusted proxy copies the contents of the untrusted buffer to the trusted

memory. When the in and out attributes are combined, the trusted proxy

allocates memory outside the enclave, makes a copy of the buffer in the

untrusted memory before calling the untrusted function, and after the untrus-

ted function returns the trusted proxy copies the contents of the untrusted

buffer to the trusted memory. The amount of data copied out is the same as

the amount of data copied in.

When the trusted proxy function returns, it frees all the untrusted stack

memory allocated at the beginning of the OCALL function for the pointer para-

meters with a direction attribute. Attempting to use a buffer allocated by the

trusted proxy after it returns results in undefined behavior.

Attribute: user_check

In certain situations, the restrictions imposed by the direction attribute may

not support the application needs for data communication across the enclave

boundary. For instance, a buffer might be too large to fit in enclave memory

and needs to be fragmented into smaller blocks that are then processed in a

series of ECALLs, or an application might require passing a pointer to trusted

memory (enclave context) as an ECALL parameter.

To support these specific scenarios, the EDL language provides the user_

check attribute. Parameters declared with the user_check attribute do not

undergo any of the checks described for [in] and [out] attributes.

However, you must understand the risks associated with passing pointers in

and out the enclave, in general, and the user_check attribute, in particular.

You must ensure that all the pointer checking and data copying are done cor-

rectly or risk compromising enclave secrets.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 49 -

Buffer Size Calculation

The generalized formula for calculating the buffer size using these attributes:

Total number of bytes = count * size

l The above formula holds when both count and size/sizefunc are

specified.

l size can be specified by either size or sizefunc attribute.

l If count is not specified for the pointer parameter, then it is assumed to

be equal to 1, i.e., count=1. Then total number of bytes equals to

size/sizefunc.

l If size is not specified, then the buffer size is calculated using the

above formula where size is sizeof (element pointed by the pointer).

Attribute: size

The size attribute is used to indicate the buffer size in bytes used for copy

depending on the direction attribute ([in]/[out]) (when there is no count

attribute specified). This attribute is needed because the trusted bridge

needs to know the whole range of the buffer passed as a pointer to ensure it

does not overlap with the enclave memory, and to copy the contents of the

buffer from untrusted memory to trusted memory and/or vice versa depend-

ing on the direction attribute. The size may be either an integer constant or

one of the parameters to the function. size attribute is generally used for

void pointers.

Example

enclave{

trusted {

// Copies '100' bytes

public void test_size1([in, size=100] void* ptr, size_t len);

// Copies ‘len’ bytes

public void test_size2([in, size=len] void* ptr, size_t len);

};

Unsupported Syntax:

enclave{

trusted {

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 50 -

// size/count/sizefunc attributes must be used with

// pointer direction ([in, out])

void test_attribute_cant([size=len] void* ptr, size_t len);

};

Attribute: sizefunc

The sizefunc attribute modifier depends on a user defined trusted function

which is called by the edge-routines to get the number of bytes to be copied.

The sizefunc has similar functionality as the sizeof() operator. An

example of where sizefunc can be used is for marshaling variable-length

structures, which are buffers whose total size is specified by a combination of

values stored at well-defined locations inside the buffer (although typically it

is at a single location). To prevent “check first, use later” type of attacks, size-

func is called twice. In the first call, sizefunc operates in untrusted

memory. The second time, sizefunc operates in the data copied into trus-

ted memory. If the sizes returned by the two sizefunc calls do not match,

the trusted bridge will cancel the ECALL and will report an error to the untrus-

ted application. Note that sizefunc must not be combined with the size

attribute. sizefunc cannot be used with out alone, however sizefunc

with both in and out is accepted. Additionally, users cannot define size-

func as strlen or wcslen. In all these scenarios, the sgx_edger8r will

throw an error. Strings should not be passed with the sizefunc modifier, but

with the string or wstring keyword. sizefunc can be used with the

count attribute which gives the total length to be equal to sizefunc *

count. The following is the prototype of the trusted sizefunc that you

need to define inside the enclave:

size_t sizefunc_function_name(const parameter_type * p);

Where parameter_type is the data type of the parameter annotated with

the sizefunc attribute. If you do not provide the definition of the sizefunc

function, the linker will report an error.

NOTE

The function implementing a sizefunc should validate the input pointer

carefully, before using it. Since the function is called before the pointer is

checked by the generated code.

Example

enclave{

trusted {

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 51 -

// Copies get_packet_size bytes

// User must provide a function definition that matches

// size_t get_packet_size(const void* ptr);

void test_sizefunc([in, sizefunc=get_packet_size] void* ptr);

// Copies (get_packet_size * cnt) bytes

void test_sizefunc2(

[in, sizefunc=get_packet_size, count=cnt] void*

ptr,

unsigned cnt);

};

Unsupported Syntax:

enclave{

include "user_types.h"

trusted {

// Cannot use sizefunc and size together

void test_sizefunc_size(

[in, size=100, sizefunc=packet_len] header* h);

// Cannot use strlen or wcslen as sizefunc

void test_sizefunc_strlen([in, sizefunc=strlen] header* h);

void test_sizefunc_wcslen([in, sizefunc=wcslen] header* h);

};

Attribute: count

The count attribute is used to indicate a block ofsizeof element pointed by

the pointer in bytes used for copy depending on the direction attribute. The

count and size attribute modifiers serve the same purpose. The number of

bytes copied by the trusted bridge or trusted proxy is the product of the

count and the size of the data type to which the parameter points. The count

may be either an integer constant or one of the parameters to the function.

The size and count attribute modifiers may also be combined. In this case,

the trusted edge-routine will copy a number of bytes that is the product of

the count and size parameters (size*count) specified in the function declar-

ation in the EDL file.

Example

enclave{

trusted {

// Copies cnt * sizeof(int) bytes

public void test_count([in, count=cnt] int* ptr, unsigned

cnt);

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 52 -

// Copies cnt * len bytes

public void test_count_size([in, count=cnt, size=len] int*

ptr, unsigned cnt, size_t len);

};

Strings

The attributes string and wstring indicate that the parameter is a NULL

terminated C string or a NULL terminated wchar_t string, respectively. To

prevent "check first, use later" type of attacks, the trusted edge-routine first

operates in untrusted memory to determine the length of the string. Once the

string has been copied into the enclave, the trusted bridge explicitly

NULLterminates the string. The size of the buffer allocated in trusted memory

accounts for the length determined in the first step as well as the size of the

string termination character.

NOTE

The string andwstringattributes must not be combined with any other

modifier such as size, countor sizefunc. stringand wstringcannot

be used with outalone. In all these cases, the sgx_edger8r will report an

error. However, stringand wstringwith both inand outare accepted.

Example

enclave {

trusted {

// Cannot use [out] with "string/wstring" alone

// Using [in] , or [in, out] is acceptable

public void test_string([in, out, string] char* str);

public void test_wstring([in, out, wstring] char* wstr);

public void test_const_string([in, string] const char* str);

};

Unsupported Syntax:

enclave {

include "user_types.h" //for typedef void const * pBuf2;

trusted {

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 53 -

// string/wstring attributes must be used

// with pointer direction

void test_string_cant([string] char* ptr);

// string/wstring attributes cannot be used

// with [out] attribute

void test_string_out([out, string] char* str);

// sizefunc can’t be used for strings, use [string/wstring]

void test_string_sizefunc_cant(

[in, string, sizefunc=packet_len] header* h);

};

In the first example, when the string attribute is used for function test_

string, strlen(str)+1 is used as the size for copying the string in and out

of the enclave. The extra byte is for null termination.

In the function test_wstring, wcslen(str)+1 (two-byte units) will be

used as the size for copying the string in and out of the enclave.

User Defined Data Types

The Enclave Definition Language (EDL) supports user defined data types, but

should be defined in a header file. Any basic datatype which is typedef’ed into

another becomes a user defined data type.

Some user data types need to be annotated with special EDLattributes, such

as isptr, isary and readonly. If one of these attributes is missing when a

user-defined type parameter requires it so, the compiler will emit a com-

pilation error in the code that sgx_edger8r generates.

l When there is a user defined data type for a pointer, isptr is used to

indicate that the user defined parameter is a pointer. See Pointers for

more information.

l When there is a user defined data type for arrays, isary is used to indic-

ate that the user defined parameter is an array. See Arrays for more

information.

l When an ECALLor OCALLparameter is a user defined type of a pointer

to a const data type, the parameter should be annotated with the

readonly attribute.

Example

enclave {

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 54 -

include "user_types.h" // for typedef void * pBuf;

// and typedef void const * pBuf2;

// and typedef int uArray[10];

trusted {

public void test_isptr(

[in, isptr, size=len] pBuf pBufptr,

size_t len);

public void test_isptr_readonly(

[in, out, isptr, readonly, size=len] pBuf2

pBuf2ptr,

size_t len);

public void test_isary([in, isary, size=len] uArray arr,

size_t len);

};

Unsupported Syntax:

enclave {

include "user_types.h" //for typedef void const * pBuf2;

// and typedef int uArray[10];

trusted {

// Cannot use [out] when using [readonly] attribute

void test_isptr_readonly_cant(

[in, out, isptr, readonly, size=len] pBuf2

pBuf2ptr,

size_t len);

// User-defined array types need "isary"

public void test_miss_isary([in, size=len] uArray arr,

size_t len);

};

In the function test_isptr_readonly, pBuf2 (typedef void const *

pBuf2) is a user defined pointer type, so isptr is used to indicate that it is a

user defined type. Also, the pBuff2ptr is readonly, so you cannot use the

out attribute. The size attribute indicates the number of bytes to be copied

to the enclave memory.

const Keyword

The EDL language accepts the const keyword with the same meaning as the

const keyword in the C standard. However, the support for this keyword is

limited in the EDL language. It may only be used with pointers and as the out-

ermost qualifier. This satisfies the most important usage in Intel(R) SGX, which

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 55 -

is to detect conflicts between const pointers (pointers to const data) with the

out attribute. Other forms of the const keyword supported in the C stand-

ard are not supported in the EDL language.

Arrays

The Enclave Definition Language (EDL) supports multidimensional, fixed-size

arrays to be used in data structure definition and parameter declaration. Zero-

length array and flexible array member, however, are not supported. The spe-

cial attribute isary is used to designate function parameters that are of a

user defined type array.

Example

enclave {

include "user_types.h" //for uArray - typedef int uArray[10];

trusted {

public void test_array([in] int arr[4]);

public void test_array_multi([in] int arr[4][4]);

public void test_isary([in, isary, size=len] uArray arr,

size_t len);

};

Unsupported Syntax:

enclave {

include "user_types.h" //for uArray - typedef int uArray[10];

trusted {

// Flexible array is not supported

public void test_flexible(int arr[][4]);

// Zero-length array is not supported.

public void test_zero(int arr[0]);

// User-defined array types need "isary"

public void test_miss_isary([in, size=len] uArray arr,

size_t len);

};

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 56 -

Support for arrays also includes attributes [in], [out] and [user_check],

which are similar in usage to the pointers.

Preprocessor Capability

The EDL language supports macro definition and conditional compilation dir-

ectives. To provide this capability, the sgx_edger8r first uses the compiler

preprocessor to parse the EDL file. Once all preprocessor tokens have been

translated, the sgx_edger8r then parses the resulting file as regular EDL lan-

guage. This means that developers may define simple macros and use con-

ditional compilation directives to easily remove debug and test capabilities

from production enclaves, reducing the attack surface of an enclave. See the

following EDL example.

#define SGX_DEBUG

enclave {

trusted {

// ECALL definitions

}

untrusted {

// OCALL definitions

#ifdef SGX_DEBUG

void print([in, string] const char * str);

#endif

}

The current sgx_edger8r does not propagate macro definitions from the

EDLfile into the generated edge-routines. As a result, you need to duplicate

macro definitions in both the EDL file as well as in the compiler arguments or

other source files.

We recommend you only use simple macro definitions and conditional com-

pilation directives in your EDL files.

The sgx_edger8r uses gcc to parse macros and conditional compilation dir-

ectives that might be in the EDL file. You may override the default search beha-

vior or even specify a different preprocessor with the --preprocessor

option.

Propagating errno in OCALLs

OCALLs may use the propagate_errno attribute. When you use this attrib-

ute, the sgx_edger8r produces slightly different edge-routines. The errno

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 57 -

variable inside the enclave, which is provided by the trusted Standard C lib-

rary, is overwritten with the value of errno in the untrusted domain before

the OCALL returns. The trusted errno is updated upon OCALL completion

regardless whether the OCALL was successful or not. This does not change the

fundamental behavior of errno. A function that fails must set errno to indic-

ate what went wrong. A function that succeeds, in this case the OCALL, is

allowed to change the value of errno.

Example

enclave {

include "sgx_stdio_stubs.h" //for FILE and other definitions

trusted {

public void test_file_io(void);

};

untrusted {

FILE * fopen(

[in,string] const char * filename,

[in,string] const char * mode) propagate_errno;

int fclose([user_check] FILE * stream) propagate_errno;

size_t fwrite(

[in, size=size, count=count] const void * buf-

fer,

size_t size,

size_t count,

[user_check]FILE * stream) propagate_errno;

};

Importing EDLLibraries

You can implement export and import functions in external trusted libraries,

akin to static libraries in the untrusted domain. To add these functions to an

enclave, use the enclave definition language (EDL) library import mechanism.

Use the EDL keywords from and import to add a library EDLfile to an

enclave EDL file is done .

The from keyword specifies the location of the library EDL file. Relative and

full paths are accepted. Relative paths are relative to the location of the EDL

file.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 58 -

The import keyword specifies the functions to import. An asterisk (*) can be

used to import all functions from the library. More than one function can be

imported by writing a list of function names separated by commas.

Syntax

from “lib_filename.edl” import func_name, func2_name;

from “lib_filename.edl” import *;

Example

enclave {

from “secure_comms.edl” import send_email, send_sms;

from "../../sys/other_secure_comms.edl" import *;

};

A library EDLfile may import another EDLfile, which in turn, may import

another EDLfile, creating a hierarchical structure as shown below:

// enclave.edl

enclave {

from “other/file_L1.edl” import *; // Import all functions

};

// Trusted library file_L1.edl

enclave {

from "file_L2.edl" import *;

trusted {

public void test_int(int val);

};

// Trusted library file_L2.edl

enclave {

from "file_L3.edl" import *;

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 59 -

trusted {

public void test_ptr(int* ptr);

};

// Trusted library file_L3.edl

enclave {

trusted {

public void test_float(float flt);

};

Granting Access to ECALLs

The default behavior is that ECALL functions cannot be called by any of the

untrusted functions.

To enable an ECALLto be directly called by application code as a root ECALL,

the ECALLshould be explicitly decorated with the public keyword to be a

public ECALL. Without this keyword, the ECALLs will be treated as private

ECALLs, and cannot be directly called as root ECALLs.

Syntax

trusted {

public <function prototype>;

};

An enclave EDL must have one or more public ECALLs, otherwise the Enclave

functions cannot be called at all and sgx_edger8r will report an error in this

case.

To grant an OCALLfunction access to an ECALL function, specify this access

using the allow keyword. Both public and private ECALLs can be put into the

allow list.

Syntax

untrusted {

<function prototype> allow (func_name, func2_name, …);

};

Example

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 60 -

enclave {

trusted {

public void clear_secret();

public void get_secret([out] secret_t* secret);

void set_secret([in] secret_t* secret);

};

untrusted {

void replace_secret(

[in] secret_t* new_secret,

[out] secret_t* old_secret)

allow (set_secret, clear_secret);

};

In the above example, the untrusted code is granted dif-

ferent access permission to the ECALLs.

ECALL called as root ECALL called from replace_secret

clear_secret Y Y

get_secret Y N

set_secret N Y

Enclave Configuration File

The enclave configuration file is an XML file containing the user defined para-

meters of an enclave. This XML file is part of the enclave project. A tool named

sgx_sign uses this file as an input to create the signature and metadata for the

enclave. Here is an example of the configuration file:

<MiscMask>0xFFFFFFFF</MiscMask>

</EnclaveConfiguration>

The table below lists the elements defined in the configuration file. All of them

are optional. Without a configuration file or if an element is not present in the

configuration file, the default value will be used.

Table 13 Enclave Configuration Default Values

Tag Description Default Value

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 61 -

ProdID

ISV assigned Product ID. 0

ISVSVN

ISV assigned SVN. 0

TCSNum

The number of TCS. Must be greater

than 0.

TCSPolicy

TCS management policy.

0 – TCS is bound to the untrusted

thread.

1 – TCS is not bound to the untrusted

thread.

StackMaxSize

The maximum stack size per thread.

Must be 4KB aligned.

0x40000

HeapMaxSize

The maximum heap size for the pro-

cess. Must be 4KB aligned.

0x100000

DisableDebug

Enclave cannot be debugged. 0 - Enclave can be

debugged

MiscSelect

The desired Extended SSA frame feature. 0

MiscMask

The mask bits of MiscSelect to enforce. 0xFFFFFFFF

MiscSelect and MiscMask are for future functional extension. Currently,

MiscSelect must be 0. Otherwise the corresponding enclave may not be

loaded successfully.

To avoid wasting the valuable protected memory resource, you can properly

adjust the StackMaxSize and HeapMaxSize by using the measurement

tool sgx_emmt. See Enclave Memory Measurement Tool for details.

An Eclipse* plug-in named Intel(R) SGX Update Configuration is provided to

help you easily edit your configuration file. See the Intel(R) SGXEclipse* Plug-

in User's Guide from the Eclipse's Help content for details.

If there is no enough stack for the enclave, ECALL returns the error code SGX_

ERROR_STACK_OVERRUN. This error code gives the information to enclave

writer that the StackMaxSize may need further adjustment.

Enclave ProjectConfigurations

Depending on the development stage you are at, choose one of the following

project configurations to build an enclave:

l Simulation: Under the simulation mode the enclave can be either built

with debug or release compiler settings. However, in both cases the

enclave is launched in the enclave debug mode. The Eclipse* plugin

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 62 -

provides the Intel(R) SGX Simulation and Intel(R) SGX Simulation

Debugconfiguration options to enable compiling and launching the

enclave in the simulation mode.From the command line, an enclave can

be built in this mode by passing SGX_DEBUG=1 for debug simulation

and no parameters for release simulation. This is the default build mode.

Single-step signing is the default method to sign a simulation enclave.

l Debug: When the Intel(R) SGXHardware Debugconfiguration option is

selected for an enclave project in Eclipse* plugin, the enclave is com-

piled in the debug mode and the resulting enclave file will contain debug

information and symbols.To use this configuration for an enclave, set

SGX_MODE=HW and SGX_DEBUG=1 as parameters to the Makefile during

the build. Choosing this project configuration also allows the enclave to

be launched in the enclave debug mode. This is facilitated by enabling

the SGX_DEBUG_FLAG that is passed as one of the parameters to the

sgx_create_enclave function. Single-step method is the default

signing method for this project configuration. The signing key used in

this mode does not need to be white-listed.

l Prerelease: When you choose the Intel(R) SGXHardware Prerelease

configuration option for an enclave project, Eclipse* plugin will build the

enclave in release mode with compiler optimizations applied.An enclave

is built in this mode by setting SGX_MODE=HW and SGX_

PRERELEASE=1 in the Makefile during build. Under this configuration,

the enclave is launched in enclave debug mode. The Makefile of the

sample application defines the EDEBUG flag when SGX_PRERELEASE=1

is passed as a command line parameter to the Makefile during build.

When the EDEBUG preprocessor flag is defined, it enables the SGX_

DEBUG_FLAG, which in turn, launches the enclave in the enclave debug

mode. Single-step method is also the default signing method for the

Prerelease project configuration. Like in the Debug configuration, the sign-

ing key does not need to be white-listed either.

l Release: The Intel(R) SGXHardware Release configuration option for an

Eclipse plugin enclave project compiles the enclave in the release mode

and launches the enclave in the enclave release mode. This is done by

disabling the SGX_DEBUG_FLAG.This mode is enabled in enclave by

passing SGX_MODE=HW to the Makefile while building the project. SGX_

DEBUG_FLAG is only enabled when NDEBUG is not defined or EDEBUG is

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 63 -

defined. In the debug configuration NDEBUG is undefined and hence

SGX_DEBUG_FLAG is enabled. In the prerelease configuration NDEBUG

and EDEBUG are both defined, which enables SGX_DEBUG_FLAG. In the

release mode, configuration NDEBUG is defined and hence it disables

SGX_DEBUG_FLAG thereby launching the enclave in enclave release

mode. Two-step method is the default signing method for the Release

configuration. The enclave needs to be signed with a white-listed key.

For additional information on the different enclave signing methods, see

Enclave Signing Tool and Enclave Signing Examples

Loading and Unloading an Enclave

Enclave source code is built as a shared object. To use an enclave, the

enclave.so should be loaded into protected memory by calling the API sgx_

create_enclave(). The enclave.so must be signed by sgx_sign. When load-

ing an enclave for the first time, the loader will get a launch token and save it

back to the in/out parameter token. The user can save the launch token into

a file, so that when loading an enclave for the second time, the application can

get the launch token from the saved file. Providing a valid launch token can

enhance the load performance. To unload an enclave, the user must call sgx_

destroy_enclave() interface with parameter sgx_enclave_id_t.

The sample code to load and unload an Enclave is shown below.

#include <stdio.h>

#include <tchar.h>

#include "sgx_urts.h"

#define ENCLAVE_FILE _T("Enclave.signed.so")

int main(int argc, char* argv[])

{

sgx_enclave_id_t eid;

sgx_status_t ret = SGX_SUCCESS;

sgx_launch_token_t token = {0};

int updated = 0;

// Create the Enclave with above launch token.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 64 -

ret = sgx_create_enclave(ENCLAVE_FILE, SGX_DEBUG_FLAG, &token,

&updated, &eid, NULL);

if (ret != SGX_SUCCESS) {

printf("App: error %#x, failed to create enclave.\n", ret);

return -1;

}

// A bunch of Enclave calls (ECALL) will happen here.

// Destroy the enclave when all Enclave calls finished.

if(SGX_SUCCESS != sgx_destroy_enclave(eid))

return -1;

return 0;

}

Handling Power Events

The protected memory encryption keys that are stored within an Intel SGX-

enabled CPU are destroyed with every power event, including suspend and

hibernation.

Thus, when a power transition occurs, the enclave memory will be removed

and all enclave data will not be accessible after that. As a result, when the sys-

tem resumes, any subsequent ECALL will fail returning the error code SGX_

ERROR_ENCLAVE_LOST. This specific error code indicates the enclave is lost

due to a power transition.

An Intel SGXapplication should have the capability to handle any power trans-

ition that might occur while the enclave is loaded in protected memory. To

handle the power event and resume enclave execution with minimum impact,

the application must be prepared to receive the error code SGX_ERROR_

ENCLAVE_LOST when an ECALL fails. When this happens, one and only one

thread from the application must destroy the enclave, sgx_destroy_

enclave(), and reload it again, sgx_create_enclave(). In addition, to

resume execution from where it was when the enclave was destroyed, the

application should periodically seal and save enclave state information on the

platform and use this information to restore the enclave to its original state

after the enclave is reloaded.

The Power Transition sample code included in the SDKdemonstrates this pro-

cedure.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 65 -

Intel(R) Software Guard Extensions Sample Code

After installing the Intel(R) Software Guard Extensions SDK, the sample code

can be found from $(SGXSDKInstallPath)SampleCode.

l The SampleEnclave project shows how to create an enclave.

l The LocalAttestation project shows how to use the Intel Elliptical Curve

Diffie-Hellman key exchange library to establish a trusted channel

between two enclaves running on the same platform.

l The RemoteAttestation project shows how to use the Intel remote attest-

ation and key exchange library in the remote attestation process.

Sample Enclave

The project SampleEnclave is designed to show you how to write an enclave

from scratch. This topic demonstrates the following basic aspects of enclave

features:

l Initialize and destroy an enclave

l Create ECALLs and/or OCALLs

l Call trusted libraries inside the enclave

The source code is shipped with an installation package of the Intel(R) SGX

SDK in $(SGXSDKInstallPath)SampleCode/SampleEnclave. A Make-

file is provided to build the SampleEnclave on Linux.

NOTE:

If the sample project is located in a system directory, administrator privilege is

required to open it. You can copy the project folder to your directory if admin-

istrator permission cannot be granted.

Initialize an Enclave

Before establishing any trusted transaction between an application and an

enclave, the enclave itself needs to be correctly created and initialized by call-

ing sgx_create_enclave provided by the uRTSlibrary.

Saving and Retrieving the Launch Token

A launch token needs to be passed to sgx_create_enclave for enclave ini-

tialization. If the launch token was saved in a previous transaction, it can be

retrieved and used directly. Otherwise, you can provide an all-0 buffer. sgx_

create_enclave will attempt to create a valid launch token if the input is not

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 66 -

valid. After the enclave is correctly created and initialized, you may need to

save the token if it has been updated. The fourth parameter of sgx_create_

enclave indicates whether or not an update has been performed.

The launch token should be saved in a per-user directory or a registry entry in

case it would be used in a multi-user environment.

ECALL/OCALL Functions

This sample demonstrates basic EDL syntax used by ECALL/OCALL functions,

as well as using trusted libraries inside the enclave. You may see Enclave Defin-

ition Language Syntax for syntax details and Trusted Libraries for C/C++ sup-

port.

Destroy an Enclave

To release the enclave memory, you need to invoke sgx_destroy_enclave

provided by the sgx_urts library. It will recycle the EPC memory and untrus-

ted resources used by that enclave instance.

Power Transition

If a power transition occurs, the enclave memory will be removed and all the

enclave data will be inaccessible. Consequently, when the system is resumed,

each of the in-process ECALLS and the subsequent ECALLs will fail with the

error code SGX_ERROR_ENCLAVE_LOST which indicates the enclave is lost

due to a power transition.

An Intel(R) Software Guard Extensions project should have the capability to

handle the power transition which might impact its behavior. The project

named PowerTransition describes one method of developing Intel(R) Soft-

ware Guard Extensions projects that handle power transitions. See ECALL-

Error-Code Based Retry for more info.

PowerTransition demonstrates the following scenario: an enclave instance is

created and initialized by one main thread and shared with three other child

threads; The three child threads repeatedly ECALL into the enclave, manip-

ulate secret data within the enclave and backup the corresponding encrypted

data outside the enclave; After all the child threads finish, the main thread des-

troys the enclave and frees the associated system resources. If a power trans-

ition happens, one and only one thread will reload the enclave and restore the

secret data inside the enclave with the encrypted data that was saved outside

and then continues the execution.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 67 -

The PowerTransition sample code is released with Intel(R) SGX SDK in

$(SGXSDKInstallPath)SampleCode/PowerTransition. A Makefile is

provided to build the sample code on Linux* OS.

NOTE:

If the sample project locates in a system directory, administrator privilege is

required to open it. You can copy the project folder to your directory if admin-

istrator permission cannot be granted.

ECALL-Error-Code Based Retry

After a power transition, an Intel(R) SGX error code SGX_ERROR_ENCLAVE_

LOST will be returned for the current ECALL. To handle the power transition

and continue the project without impact, you need to destroy the invalid

enclave to free resources first and then retry with a newly created and ini-

tialized enclave instance, as depicted in the following figure.

Figure 1 Power Transition Handling Flow Chart

ECALLs in Demonstration

PowerTransition demonstrates handling the power transition in two types of

ECALLs:

1. Initialization ECALL after enclave creation.

2. Normal ECALL to manipulate secrets within the enclave.

Initialization ECALL after Enclave Creation

PowerTransition illustrates one initialization ECALL after enclave creation

which is shown in the following figure:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 68 -

Figure 2 Enclave Initialization ECall after Enclave Creation Flow Chart

sgx_create_enclave is a key API provided by the uRTS library for enclave cre-

ation. For sgx_create_enclave, a mechanism of power transition handling is

already implemented in the uRTS library. Therefore, it is unnecessary to manu-

ally handle power transition for this API.

NOTE:

To concentrate on handling a power transition, PowerTransition assumes the

enclave file and the launch token are located in the same directory as the

application. See Sample Enclave for how to store the launch token properly.

Normal ECALL to Process Secrets within the Enclave

This is the most common ECALL type into an enclave. PowerTransition demon-

strates the power transition handling for this type of ECALL in a child thread

after the enclave creation and initialization by the main thread, as depicted in

the figure below. Since the enclave instance is shared by the child threads, it is

required to make sure one and only one child thread to re-creates and re-ini-

tializes the enclave instance after the power transition and the others utilize

the re-created enclave instance directly. PowerTransition confirms this point

by checking whether the Enclave ID is updated.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 69 -

Figure 3 Regular ECALL Flow Chart

NOTE:

During the ECALL process, it is recommended to back up the confidential data

as cipher text outside the enclave frequently. Then we can use the backup

data to restore the enclave to reduce the power transition impacts.

Attestation

In the Intel(R) Software Guard Extensions architecture, attestation refers to

the process of demonstrating that a specific enclave was established on the

platform. The Intel(R) SGX Architecture provides two attestation mechanisms:

l One creates an authenticated assertion between two enclaves running

on the same platform referred to as local attestation.

l The second mechanism extends local attestation to provide assertions

to 3rd parties outside the platform referred to as remote attestation.

The remote attestation process leverages a quoting service.

The Intel(R) Software Guard Extensions SDK provides APIs used by applic-

ations to implement the attestation process.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 70 -

Local Attestation

Local attestation refers to two enclaves on the same platform authenticating

to each other using the Intel SGX REPORT mechanism before exchanging

information. In an Intel(R) SGX application, multiple enclaves might collaborate

to perform certain functions. After the two enclaves verify the counterpart is

trustworthy, they can exchange information on a protected channel, which typ-

ically provides confidentiality, integrity and replay protection. The local attest-

ation and protected channel establishment uses the REPORT based Diffie-

Hellman Key Exchange* protocol.

You can find a sample solution shipped with the Intel(R) Software Guard Exten-

sions SDK at $(SGXSDKInstallPath)SampleCode/Local_Attest-

ation directory. A Makefile is provided to compile the project.

NOTE:

If the sample project locates in a system directory, administrator privilege is

required to open it. You can copy the project folder to your directory if admin-

istrator permission cannot be granted.

The sample code shows an example implementation of local attestation,

including protected channel establishment and secret message exchange

using enclave to enclave function call as an example.

Diffie-Hellman Key Exchange Library and Local Attestation Flow

The local attestation sample in the SDK uses the Diffie-Hellman (DH) key

exchange library to establish a protected channel between two enclaves. The

DH key exchange APIs are described in sgx_dh.h. The key exchange library

is part of the Intel(R) SGX application SDK trusted libraries. It is statically

linked with the enclave code and exposes APIs for the enclave code to gen-

erate and process local key exchange protocol messages. The library is com-

bined with other libraries and is built into the final library called libsgx_

tservice.a that is part of the SDK release.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 71 -

Figure 4 Local Attestation Flow with the DHKey Exchange Library

The figure above represents the usage of DH key exchange library. Alocal

attestation flow consists of the following steps:

1. ISV Enclave 1 calls the Intel ECDH key exchange library to initiate the ses-

sion with the initiator role.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 72 -

2. The Enclave 1 does an OCALL into the untrusted code requesting the Dif-

fie-Hellman Message 1 and session id.

3. The untrusted code does an ECALL into Enclave 2.

4. Enclave 2 in turn calls the ECDH key exchange library to initiate the ses-

sion with the responder role.

5. Enclave 2 calls the key exchange library to generate DH Message 1 ga

|| TARGETINFO Enclave 2.

6. DH Message 1 is sent back from Enclave 2 to Enclave 1 through an ECALL

return to the untrusted code followed by an OCALL return into Enclave

7. Enclave 1 processes the Message 1 using the key exchange library API

and generates DH Message 2 gb||[Report Enclave 1(h(ga ||

gb))]SMK.

8. DH Message 2 is sent to the untrusted side through an OCALL.

9. The untrusted code does an ECALL into Enclave 2 giving it the DH Mes-

sage 2 and requesting DH Message 3.

10. Enclave 2 calls the key exchange library API to process DH Message 2

and generates DH Message 3 [ReportEnclave2(h(gb || ga)) ||

Optional Payload]SMK.

11. DH Message 3 is sent back from Enclave2 to Enclave1 through an ECALL

return to the untrusted code followed by an OCALL return into Enclave

12. Enclave 2 uses the key exchange library to process DH Message 3 and

establish the session.

13. Messages exchanged between the enclaves are protected by the AEK.

Protected Channel Establishment

The following figure illustrates the interaction between two enclaves, namely

the source enclave and the destination enclave, to establish a session. The

application initiates a session between the source enclave and the destination

enclave by doing an ECALL into the source enclave, passing in the enclave id of

the destination enclave. Upon receiving the enclave id of the destination

enclave, the source enclave does an OCALL into the core untrusted code

which then does an ECALL into the destination enclave to exchange the mes-

sages required to establish a session using ECDH Key Exchange* protocol.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 73 -

Figure 5 SecureChannel Establishment Flow with the DHKey Exchange

Library

Secret Message Exchange and Enclave to Enclave Call

The following figure illustrates the message exchange between two enclaves.

After the establishment of the protected channel, session keys are used to

encrypt the payload in the message(s) being exchanged between the source

and destination enclaves. The sample code implements interfaces to encrypt

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 74 -

the payload of the message. The sample code also shows the implementation

of an enclave calling a function from another enclave. Call type, target function

ID, total input parameter length and input parameters are encapsulated in the

payload of the secret message sent from the caller (source) Enclave and the

callee (destination) enclave. As one enclave cannot access memory of another

enclave, all input and output parameters, including data indirectly referenced

by a parameter needs to be marshaled across the two enclaves. The sample

code uses Intel(R) SGX SDKtrusted cryptographic library to encrypt the pay-

load of the message. Through such encryption, message exchange is just the

secret and in case of the enclave to enclave call is the marshaled destination

enclave’s function id, total parameter length and all the parameters. The des-

tination enclave decrypts the payload and calls the appropriate function. The

results of the function call are encrypted using the session keys and sent back

to the source enclave.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 75 -

Figure 6 Secret Message Exchange Flow with the DHKey Exchange Library

Remote Attestation

Generally speaking, Remote Attestation is the concept of a HW entity or of a

combination of HW and SW gaining the trust of a remote provider or producer

of some sort. With Intel(R) SGX, Remote Attestation software includes the

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 76 -

app’s enclave and the Intel-provided Quoting Enclave (QE) and Provisioning

Enclave (PvE). The attestation HW is the Intel(R) SGX enabled CPU.

Remote Attestation alone is not enough for the remote party to be able to

securely deliver their service (secrets or assets). Securely delivering services

also requires a secure communication session. Remote Attestation is used dur-

ing the establishment of such a session. This is analogous to how the familiar

SSL handshake includes both authentication and session establishment.

The Intel(R) Software Guard Extensions SDK includes sample code showing:

l How an application enclave can attest to a remote party.

l How an application enclave and the remote party can establish a secure

session.

The SDK includes a remote session establishment or key exchange (KE) lib-

raries that can be used to greatly simplify these processes.

You can find the sample code for remote attestation in the directory

$(SGXSDKInstallPath)SampleCode/RemoteAttestation.

NOTE:

To run the sample code in the hardware mode, you need to access to Internet.

NOTE:

If the sample project is located in a system directory, administrator privilege is

required to open it. You can copy the project folder to your directory if admin-

istrator permission cannot be granted.

Intel(R) SGX uses an anonymous signature scheme, Intel(R) Enhanced Privacy

ID (Intel(R) EPID), for authentication (for example, attestation). The supplied

key exchange libraries implement a Sigma-like protocol for session estab-

lishment. Sigma is a protocol that includes a Diffie-Hellman key exchange, but

also addresses the weaknesses of DH. The protocol Intel(R) SGX uses differs

from the Sigma protocol that’s used in IKE v1 and v2 in that the Intel(R) SGX

platform uses Intel(R) EPID to authenticate while the service provider uses PKI.

(In Sigma, both parties use PKI.) Finally, the KE libraries require the service pro-

vider to use an ECDSA, not an RSA, key pair in the authentication portion of

the protocol and the libraries use ECDH for the actual key exchange.

Remote Key Exchange (KE) Libraries

The RemoteAttestation sample in the SDK uses the remote KE libraries as

described above to create a remote attestation of an enclave, and uses that

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 77 -

attestation during establishment of a secure session (a key exchange).

There are both untrusted and trusted KE libraries. The untrusted KE library is

provided as a static library, libsgx_ukey_exchange.a. The Intel(R)

SGXapplication needs to link with this library and include the header file

sgx_ukey_exchange.h, containing the prototypes for the APIs that the KE

trusted library exposes.

NOTE:

If you are unable to use either of the two pre-built untrusted key exchange

static libraries, the source code for a sample untrusted key exchange library is

included in the isv_app subfolder of the Remote Attestation sample applic-

ation that is shipped with this SDK.

The trusted KE library is also provided as a static library. As a trusted library,

the process for using it is slightly different than that for the untrusted KE lib-

rary. The main difference relates to the fact that the trusted KE library

exposes ECALLs called by the untrusted KE library. This means that the library

has a corresponding EDL file, sgx_tkey_exchange.edl, which has to be

imported in the EDL file for the application enclave that uses the library. We

can see this in code snippet below, showing the complete contents of app_

enclave.edl, the EDL file for the app enclave in the sample code.

enclave {

from "sgx_tkey_exchange.edl" import *;

include "sgx_key_exchange.h"

include "sgx_trts.h"

trusted {

public sgx_status_t enclave_init_ra(

int b_pse,

[out] sgx_ra_context_t *p_context);

public sgx_status_t enclave_ra_close(

sgx_ra_context_t context);

};

It’s worth noting that sgx_key_exchange.h contains types specific to

remote key exchange and must be included as shown above as well as in the

untrusted code of the application that uses the enclave. Finally, sgx_tkey_

exchange.h is a header file that includes prototypes for the APIs that the

trusted library exposes, but that are not ECALLs, i.e., APIs called by ISV code in

the application enclave.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 78 -

Remote Attestation and Protected Session Establishment

This topic describes the functionality of the remote attestation sample in

detail.

NOTE:

In the sample code, the service provider is modeled as a Shared Object, ser-

vice_provider.so. The sample service provider does not depend on

Intel®SGXheaders, type definitions, libraries, and so on. This was done to

demonstrate that the Intel SGXis not required in any way when building a

remote attestation service provider.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 79 -

Figure 7 Remote Attestation and Trust Channel Establishment Flow

An Intel(R) Software Guard Extensions (Intel(R) SGX) application would typ-

ically begin by requesting service (for example, media streaming) from a ser-

vice provider (SP) and the SP would respond with a challenge. This is not

shown in the figure. The figure begins with the app’s reaction to the challenge.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 80 -

1. The flow starts with the app entering the enclave that will be the end-

point of the KE, passing in b_pse, a flag indicating whether the app/en-

clave uses Platform Services.

2. If b_pse is true, then the isv enclave shall call trusted AE support library

with sgx_create_pse_session() to establish a session with PSE.

3. Code in the enclave calls sgx_ra_init(), passing in the SP’s ECDSA

public key, g_sp_pub_key, and b_pse. The integrity of g_sp_pub_

key is a public key is important so this value should just be built into isv_

enclave.

4. Close PSE session by sgx_close_pse_session() if a session is estab-

lished before. The requirement is that, if the app enclave uses Platform

Services, the session with the PSE must already be established before

the app enclave calls sgx_ra_init().

5. sgx_ra_init() returns the KE context to the app enclave and the

app enclave returns the context to the app.

The application calls sgx_get_extended_epid_group_id() and

sends the value returned in p_extended_epid_group_id to the

server in msg0.

The server checks whether the extended Intel(R) EPID group ID is sup-

ported. If the ID is not supported, the server aborts remote attestation.

NOTE:

Currently, the only valid extended Intel(R) EPID group ID is zero. The

server should verify this value is zero. If the Intel(R) EPID group ID is not

zero, the server aborts remote attestation.

8. The application calls sgx_ra_get_msg1(), passing in this KE's context.

Figure 3 shows the app also passing in a pointer to the untrusted proxy

corresponding to sgx_ra_get_ga, exposed by the TKE. This reflects

the fact that the names of untrusted proxies are enclave-specific.

9. sgx_ra_get_msg1() builds an S1 message = (ga || GID) and returns it

to the app.

10. The app sends S1 to the service provider (SP) by ra_network_send_

receive(), it will call sp_ra_proc_msg1_req() to process S1 and

generate S2.

11. Application eventually receives S2 = gb || SPID || 2-byte

TYPE || 2-byte KDF-ID || SigSP(gb, ga) || CMAC

SMK

(gb

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 81 -

|| SPID || 2-byte TYPE || 2-byte KDF-ID || SigSP(gb,

ga)) || SigRL.

12. The application calls sgx_ra_proc_msg2(), passing in S2 and the con-

text.

13. The code in sgx_ra_proc_msg2() builds S3 = CMAC

SMK

(M)||M

where M = ga ||PS_SECURITY_PROPERTY|| QUOTE and returns it.

Platform Services Security Information is included only if the app/en-

clave uses Platform Services.

14. Application sends the msg3 to the SP by ra_network_send_

receive(), and the SP verifies the msg3.

15. SP returns the verification result to the application.

At this point, a session has been established and keys exchanged. Whether the

service provider thinks the session is secure and uses it depends on the secur-

ity properties of the platform as indicated by the S3 message. If the platform’s

security properties meet the service provider’s criteria, then the service pro-

vider can use the session keys to securely deliver a secret and the app enclave

can consume the secret any time after it retrieves the session keys by calling

sgx_ra_get_keys() on the trusted KE library. This is not shown in the fig-

ure, nor is the closing of the session. Closing the session requires entering the

app enclave and calling sgx_ra_close() on the trusted KE library, among

other app enclave-specific cleanup.

Remote Attestation with a Custom Key Derivation Function (KDF)

By default, the platform software uses the KDF described in the definition of

the sgx_ra_get_keys API when the sgx_ra_init API is used to generate

the remote attestation context. If the ISV needs to use a different KDF than

the default KDF used by Intel(R) SGX PSW, the ISV can use the sgx_ra_

init_ex API to provide a callback function to generate the remote attest-

ation keys used in the SIGMA protocol (SMK) and returned by the API sgx_

ra_get_keys (SK, MK, and VK). The decision to use a different KDF is a

policy of the ISV, but it should be approved by the ISV’s security process.

Debugging a Remote Attestation Service Provider

As an ISVwriting the remote attestation service provider, you may want to

debug the message flow. One way to do this would be to provide pre-gen-

erated messages that can be replayed and verified. However, not that S1 mes-

sage = (GID || ga) includes the random component ga generated

inside an enclave.Also, the remote attestation service provider generates a

random public+private key pair as part of its msg2 generation, but without

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 82 -

any interaction with Intel(R) SGX. Finally, each of these has state or context

that is associated with cryptographic operations and is used to ensure that cer-

tain calls being made are in the correct order and that the state is consistent.

These characteristics help protect the remote attestation flow against attacks,

but also make it more difficult to replay pre-generated messages.

To overcome these, the cryptographic library is modified and used (only) by

the sample service provider. Any time that key generation, signing, or other

operation requests a random number, the number 9 is returned.This means

that the crypto functions from libsample_libcrypto.so are predictable

and cryptographically weak. If we can replay msg1 send from the isv_app,

the sample service_provider. will always generate the exact same msg2.

We now have a sufficient system to replay messages sent by the isv_app

and have it verify that the responses sent by the remote service are the expec-

ted ones.

To replay messages and exercise this verification flow, pass in 1 or 2 as a com-

mand-line argument when running the sample application isv_app. The

isv_app will ignore errors generated by the built-in checks in the Intel SGX.

Developers wishing to debug their remote attestation service provider should

be able to temporarily modify their cryptographic subsystem to behave in a

similar manner as the libsample_libcrypto.so and replay the pre-com-

puted messages stored in sample_messages.h. The responses from their

own remote attestation service provider should match the ones generated by

ours, which are also stored in sample_messages.h.

NOTE

Do not use the sample cryptographic library provided in this sample in pro-

duction code.

Using a Different Extended Intel(R) EPID Group for Remote Attestation

The Intel(R) SGX platform software can generate Quotes signed by keys

belonging to a more than one extended Intel(R) EPID Group. Before remote

attestation starts, the ISV Service provider (SP) needs to know which exten-

ded Intel(R) EPID Group the PSW supports. The ISV SP will use this inform-

ation to request Quote generation and verification in the correct extended

Intel(R) EPID Group. The API sgx_get_extended_epid_group_id returns

the extended Intel(R) EPID Group ID. The ISV application should query the cur-

rently configured extended Intel(R) EPID Group ID from the platform software

using this API and sending it to the ISV SP. The ISV SP then knows which

extended Intel(R) EPID Group to use for remote attestation. If the ISV SP does

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 83 -

not support the provided extended Intel(R) EPID Group, it will terminate the

remote attestation attempt.

Sealed Data

The Intel(R) SGX SDK provides APIs to encrypt and integrity-protect enclave

secrets to store them outside the enclave, such as on disk. The Intel(R) SGX

Platform SW provides Monotonic Counter and Trusted Time service to ISV

enclaves. The Monotonic Counter can be used to implement replay-protected

policy, and the Trusted Time can be used to enforce time based policy. Both

of them are in a form of Sealed Data. The requirement of replay-protected

data blob and time based policy data blob is quite subtle. The Intel(R) SGX

SDK will provide reference code to help ISV to implement them correctly.

The sample code SealedData is shipped with the Intel(R) Software Guard

Extensions SDK in $(SGXSDKInstallPath)SealedData folder. A Makefile

is provided to compile the project.

NOTE:

If the sample project is located in a system directory, administrator privilege is

required to modify it. You can copy the project folder to your directory if

administrator permission cannot be granted.

Replay Protected Policy

In EnterpriseRights Management (ERM) type usages, an offline activity log

might need to be maintained and periodically audited by the enterprise, for

example, depending on whether and/or how many times a secret document is

viewed or printed offline. If the offline activity log is tampered with or deleted,

the ERM application will disable the offline use capability. A functional secure

document viewing ERM application is quite complex, involving credential veri-

fication, document key provisioning, secure document rendering, secure dis-

play and many other security processes.

The Replay Protected policy sample code will not implement a full secure doc-

ument viewing functionality, instead, it will demonstrate:

l Initializing a replay protected policy, to create an offline activity log

together with a secret, protected by a Monotonic Counter.

l Verifying and updating the replay protected policy, to verify and update

the activity log before the secret can be used to perform a function.

l Deleting the replay protected policy, to delete the activity log and the

associated Monotonic Counter after the secret is invalidated.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 84 -

Initializing a Policy

1. The Enclave creates a new Monotonic Counter using sgx_create_

monotonic_counter.

2. The Enclave fills the activity log with the sample usage secret and usage

data, the Monotonic Counter_UUID and the Monotonic Counter_

Value returned by sgx_create_monotonic_counter.

3. The Enclave seals the activity log into sealed data using sgx_seal_

data.

Verifying a Policy

1. The Enclave verifies and decrypts the sealed data using sgx_unseal_

data

2. The Enclave retrieves the current Monotonic Counter value of the asso-

ciated Monotonic Counter using sgx_read_monotonic_counter. If it

fails, abort the operation.

3. The Enclave verifies the Monotonic Counter_Value returned by sgx_

read_monotonic_counter is the same as the Monotonic Counter_

Value in the activity log.

4. The Enclave releases the secret to perform functions.

Updating a Policy

1. The Enclave verifies activity log.

2. The Enclave checks that the secret and usage data inside the activity log

has not been invalidated or expired, for example, by comparing the use

count in the activity log against a predetermined threshold. If the secret

is invalidated or expired, the function that requires the secret will not be

rendered.

3. The Enclave Increases the Monotonic Counter value of the associated MC

using sgx_increment_monotonic_counter. If it fails, abort the

operation.

4. The Enclave verifies the Monotonic Counter value returned in sgx_

increment_monotonic_counter is equal to the old value, pre-

viously returned by sgx_read_monotonic_counter, plus one.

5. The Enclave updates the activity log and the Monotonic Counter_

Value.

6. The Enclave seals the activity log into Sealed Data using sgx_seal_

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 85 -

data.

7. The Enclave releases the secret to perform functions.

Deleting a Policy

1. The Enclave follows the process of updating the Replay-Protected Activ-

ity Log to set the use counter to the maximum number of uses allowed,

before releasing the secret for the last time.

2. User connects to the network to upload the activity log and receives a

new secret.

3. The Enclave deletes the activity log and the associated Monotonic

Counter using sgx_destroy_monotonic_counter. If it is blocked by

the attacker, the associated activity log does not allow releasing of the

secret as the secret inside the activity log is invalidated or expired.

Time Based Policy

The sample code demonstrates a proper implementation of a Time-Based

Policy in the form of an offline Digital Rights Management (DRM) Key that

expires after a certain period of time. The sample code will not implement full

DRM functionality. Instead, it demonstrates:

l Creating offline sealed data with the DRM key, a time stamp and the

expiration policy.

l Verifying the DRM key has not expired before releasing the key to per-

form function.

Initializing a Policy

1. The Enclave retrieves the time reference and the time source nonce

using sgx_get_trusted_time.

2. The Enclave fills the policy structure with the sample usage secret, the

time policy, the time reference and the time source nonce returned by

sgx_get_trusted_time.

3. The Enclave seals the policy structure into Sealed Data using sgx_

seal_data.

Verifying a Policy

1. The Enclave verifies and decrypts the sealed data using sgx_unseal_

data.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 86 -

2. The Enclave retrieves the current time using sgx_get_trusted_

time.

3. The Enclave verifies the time source nonce returned by sgx_get_trus-

ted_time is the same as the time source nonce in the policy structure.

If not, abort the operation.

4. Calculate time elapsed.

5. Verify the policy. If the time limit has expired, abort the operation.

6. The Enclave releases the secret to perform functions.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 87 -

Library Functions and Type Reference

This topic includes the following sub-topics to describe library functions and

type reference for Intel(R) Software Guard Extensions SDK:

l Untrusted Library Functions

l Trusted Libraries

l Function Descriptions

l Types and Enumerations

l Error Codes

Untrusted Library Functions

The untrusted library functions can only be called from application code - out-

side the enclave.

The untrusted libraries built for the hardware mode contain a string with the

release number. The string version, which uses the library name as the prefix,

is defined when the library is built. The string version consists of various para-

meters such as the product number, SVN revision number, build number, and

so on. This mechanism ensures all untrusted libraries shipped in a given

Intel®SGX PSW/SDK release have the same version number and allows quick

identification of the untrusted libraries linked into an untrusted component.

For instance, libsgx_urts.so contains a string version SGX_URTS_

VERSION_1.0.0.0. The last digit varies depending on the specific Intel SGX

PSW/SDK release number.

Enclave Creation and Destruction

These functions are used to either create or destroy enclaves:

l sgx_create_enclave

l sgx_destroy_enclave

Quoting Functions

These functions allow application enclaves to ensure that they are running on

an Intel(R) Software Guard Extensions environment.

NOTE:

To run these functions in the hardware mode, you need to access to Internet.

Configure the system network proxy settings if needed.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 88 -

l sgx_init_quote

l sgx_get_quote_size

l sgx_get_quote

l sgx_report_attestation_status

Untrusted Key Exchange Functions

These functions allow exchanging of secrets between ISV’s server and

enclaves. They are used in concert with the trusted Key Exchange functions.

NOTE:

To run these functions in the hardware mode, you need to access to Internet.

Configure the system network proxy settings if needed.

l sgx_ra_get_msg1

l sgx_ra_proc_msg2

l sgx_get_extended_epid_group_id

Untrusted Platform Service Function

This function helps ISVs determine what Intel(R) SGX Platform Services are

supported by the platform.

NOTE:

To run this function in the hardware mode, you need to access to Internet. Con-

figure the system network proxy settings if needed.

l sgx_get_ps_cap

Intel(R) SGX Launch Control Functions

Use sgx_get_whitelist_size to get the size of current Enclave Signing

Key White List Certificate Chain. Use sgx_get_whitelist to get the chain.

l sgx_get_whitelist_size

l sgx_get_whitelist

Trusted Libraries

The trusted libraries are static libraries that linked with the enclave binary.

The Intel(R) Software Guard Extensions SDK ships with several trusted lib-

raries that cover domains such as standard C/C++ libraries, synchronization,

encryption and more.

These functions/objects can only be used from within the enclave.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 89 -

Trusted libraries built for HW mode (for example, not for simulation) contain a

string with the release number. The string version, which uses the library name

as prefix, is defined when the SDK is built and consists of various parameters

such as the product number, SVN revision number, build number, and so on.

This mechanism ensures all trusted libraries shipped in a given SDK release

will have the same version number and allows quick identification of the trus-

ted libraries linked into an enclave.

For instance, libsgx_tstdc.a contains a string version like SGX_TSTDC_

VERSION_1.0.0.0. Of course, the last digits vary depending on the SDK

release.

CAUTION:

Do not link the enclave with any untrusted library including C/C++ standard lib-

raries. This action will either fail the enclave signing process or cause a runtime

failure due to the use of restricted instructions.

Trusted Runtime System

The Intel(R) SGX trusted runtime system (tRTS) is a key component of the

Intel(R) Software Guard Extensions SDK. It provides the enclave entry point

logic as well as other functions to be used by enclave developers.

l Intel(R) Software Guard Extensions Helper Functions

l Custom Exception Handling

Intel(R) Software Guard Extensions Helper Functions

The tRTS provides the following helper functions for you to determine

whether a given address is within or outside enclave memory.

l sgx_is_within_enclave

l sgx_is_outside_enclave

The tRTS provides a wrapper to the RDRAND instruction to generate a true

random number from hardware. The C/C++standard library functions rand

and srand functions are not supported within an enclave because they only

provide pseudo random numbers. Instead, enclave developers should use the

sgx_read_rand function to get true random numbers.

l sgx_read_rand

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 90 -

Custom Exception Handling

The Intel(R) Software Guard Extensions SDK provides an API to allow you to

exceptions. When one of the enclave supported hardware exceptions occurs

within the enclave, the registered exception handlers will be called in a spe-

cific order until an exception handler reports that it has handled the excep-

tion. For example, issuing a CPUID instruction inside an Enclave will result in a

#UD fault (Invalid Opcode Exception). ISV enclave code can call sgx_

register_exception_handler to register a function of type sgx_excep-

tion_handler_t to respond to this exception. To check a list of enclave sup-

ported exceptions, see Intel(R) Software Guard Extensions Programming

Reference.

NOTE:

Custom exception handling is only supported in HWmode. Although the

exception handlers can be registered in simulation mode, the exceptions can-

not be caught and handled within the enclave.

NOTE:

OCALLs are not allowed in the exception handler.

NOTE:

Custom exception handing only saves general purpose registers in sgx_

exception_info_t. You should be careful when touching other registers in

the exception handlers.

Note:

If the exception handlers can not handle the exceptions, abort() is called.

abort() makes the enclave unusable and generates another exception.

The Custom Exception Handling APIs are listed below:

l sgx_register_exception_handler

l sgx_unregister_exception_handler

Custom Exception Handler for CPUID Instruction

If an ISV requiresusing the CPUID information within an enclave, then the

enclave code must make an OCALL to perform the CPUID instruction in the

untrusted application. The Intel(R) SGX SDK provides two functions in the lib-

rary sgx_tstdc to obtain CPUID information through an OCALL:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 91 -

sgx_cpuid

sgx_cpuid_ex

In addition, the Intel SGX SDK also provides the following intrinsics which call

the above functions to obtain CPUID data:

__cpuid

__cpuidex

Both the functions and intrinsics result in an OCALL to the uRTS library to

obtain CPUID data. The results are returned from an untrusted component in

the system. It is recommended that threat evaluation be performed to ensure

that CPUID return values are not problematic. Ideally, sanity checking of the

return values should be performed.

If an ISV's enclave uses a third party library which executes the CPUID instruc-

tion, then the ISV would need to provide a custom exception handler to

handle the exception generated from issuing the CPUID instruction (unless the

third party library registers its own exception handler for CPUID support). The

ISV is responsible for analyzing the usage of the specific CPUID result

provided by the untrusted domain to ensure it does not compromise the

enclave security properties. Recommended implementation of the CPUID

exception handler involves:

1. ISV analyzes the third party library CPUID usages, identifying required

CPUID results.

2. ISV enclave code initialization routine populates a cache of the required

CPUID results inside the enclave. This cache might be maintained by the

RTS or by ISV code.

3. ISV enclave code initialization routine registers a custom exception hand-

ler.

4. The custom exception handler, when invoked, examines the exception

information and faulting instruction. If the exception is caused by a

CPUID instruction:

1. Retrieve the cached CPUID result and populate the CPUID instruc-

tion output registers.

2. Advance the RIP to bypass the CPUID instruction and complete the

exception handling.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 92 -

Trusted Service Library

The Intel(R) Software Guard Extensions SDK provides a trusted library named

sgx_tservice for secure data manipulation and protection. The sgx_tser-

vice library provides the following trusted functionality and services:

l Intel(R) Software Guard Extensions Instruction Wrapper Functions

l Intel(R) Software Guard Extensions Sealing and Unsealing Functions

l Untrusted Platform Service Function

l Diffie–Hellman (DH) Session Establishment Functions

Intel(R) Software Guard Extensions Instruction Wrapper Functions

The sgx_tservice library provides functions for getting specific keys and

for creating and verifying an enclave report. The API functions are listed

below:

l sgx_get_key

l sgx_create_report

l sgx_verify_report

Intel(R) Software Guard Extensions Sealing and Unsealing Functions

The sgx_tservice library provides the following functions:

l Exposes APIs to create sealed data which is both confidentiality and

integrity protected.

l Exposes an API to unseal sealed data inside the enclave.

l Provides APIs to authenticate and verify the input data with AES-GMAC.

See the following related topics for more information.

l sgx_seal_data

l sgx_seal_data_ex

l sgx_unseal_data

l sgx_mac_aadata

l sgx_mac_aadata_ex

l sgx_unmac_aadata

The library also provides APIs to help calculate the sealed data size, encrypt

text length, and Message Authentication Code (MAC) text length.

l sgx_calc_sealed_data_size

l sgx_get_add_mac_txt_len

l sgx_get_encrypt_txt_len

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 93 -

SealLibrary Introduction

When an enclave is instantiated, it provides protections (confidentiality and

integrity) to the data by keeping it within the boundary of the enclave. Enclave

developers should identify enclave data and/or state that is considered secret

and potentially needs preservation across the following enclave destruction

events:

l Application is done with the enclave and closes it.

l Application itself is closed.

l The platform is hibernated or shutdown.

In general, the secrets provisioned within an enclave are lost when the enclave

is closed. However if the secret data needs to be preserved during one of

these events for future use within an enclave, it must be stored outside the

enclave boundary before closing the enclave. In order to protect and preserve

the data, a mechanism is in place which allows enclave software to retrieve a

key unique to that enclave. This key can only be generated by that enclave on

that particular platform. Enclave software uses that key to encrypt data to the

platform or to decrypt data already on the platform. Refer to these encrypt

and decrypt operations as sealing and unsealing respectively as the data is

cryptographically sealed to the enclave and platform.

To provide strong protection against potential key-wear-out attacks, a unique

seal key is generated for each data blob encrypted with the sgx_seal_data

APIcall. A key ID for each encrypted data blob is stored in clear alongside the

encrypted data blob. The key ID is used to re-generate the seal key to decrypt

the data blob.

AES-GCM (AES – Advanced Encryption Standard) is utilized to encrypt and

MAC-protect the payload. To protect against software-based side channel

attacks, the crypto implementation of AES-GCM utilizes Intel® Advanced

Encryption Standard New Instructions (Intel® AES-NI), which is immune to soft-

ware-based side channel attacks. The Galois/Counter Mode (GCM) is a mode of

operation of the AES algorithm. GCM assures authenticity of the confidential

data (of up to about 64 GB per invocation) using a universal hash function.

GCM can also provide authentication assurance for additional data (of prac-

tically unlimited length per invocation) that is not encrypted. GCM can also

provide authentication assurance for additional data (of practically unlimited

length per invocation) that is not encrypted. If the GCM input contains only

data that is not to be encrypted, the resulting specialization of GCM, called

GMAC (Galois Message Authentication Code), is simply an authentication mode

for the input data. The sgx_mac_aadata APIcall restricts the input to non-

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 94 -

confidential data to provide data origin authentication only. The single output

of this function is the authentication tag.

Example Use Cases

One example is that an application may start collecting secret state while

executing that needs to be preserved and utilized on future invocations of

that application. Another example is during application installation, a secret

key may need to be preserved and verified upon starting the application.

For these cases the seal APIs can be utilized to seal the secret data (key or

state) in the examples above, and then unseal the secret data when needed.

Sealing

1. Use sgx_calc_sealed_data_size to calculate the number of bytes

to allocate for the sgx_sealed_data_t structure.

2. Allocate memory for the sgx_sealed_data_t structure.

3. Call sgx_seal_data to perform sealing operation

4. Save the sealed data structure for future use.

Unsealing

1. Use sgx_get_encrypt_txt_len and sgx_get_add_mac_txt_

len to determine the size of the buffers to allocate in terms of bytes.

2. Allocate memory for the decrypted text and additional text buffers.

3. Call sgx_unseal_data to perform the unsealing operation.

Trusted Platform Service Functions

The sgx_tservice library provides the following functions that allow an ISV

to use platform services and get platform services security property.

NOTE:

To run these functions in the hardware mode, you need to access to Internet.

Configure the system network proxy settings if needed.

l sgx_create_pse_session

l sgx_close_pse_session

l sgx_get_ps_sec_prop

l sgx_get_ps_sec_prop_ex

l sgx_get_trusted_time

l sgx_create_monotonic_counter_ex

l sgx_create_monotonic_counter

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 95 -

l sgx_destroy_monotonic_counter

l sgx_increment_monotonic_counter

l sgx_read_monotonic_counter

NOTE

One application is not able to access the monotonic counter created by

another application in the simulation mode. This also affects two different

applications using the same enclave.

Diffie–Hellman (DH) Session Establishment Functions

These functions allow an ISV to establish secure session between two enclaves

using the EC DH Key exchange protocol.

l sgx_dh_init_session

l sgx_dh_responder_gen_msg1

l sgx_dh_initiator_proc_msg1

l sgx_dh_responder_proc_msg2

l sgx_dh_initiator_proc_msg3

C Standard Library

The Intel(R) Software Guard Extensions SDK includes a trusted version of the

C standard library. The library is named sgx_tstdc (trusted standard C), and

can only be used inside an enclave. Standard C headers are located under

$(SGXSDKInstallPath)include/tlibc.

sgx_tstdc provides a subset of C99 functions that are ported from the

OpenBSD* project. Unsupported functions are not allowed inside an enclave

for the following reasons:

l The definition implies usage of a restricted CPU instruction.

l The definition is known to be unsafe or insecure.

l The definition implementation is too large to fit inside an enclave or

relies heavily on information from the untrusted domain.

l The definition is compiler specific, and not part of the standard.

l The definition is a part of the standard, but it is not supported by a spe-

cific compiler.

See Unsupported C Standard Functions for a list of unsupported C99 defin-

itions within an enclave.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 96 -

Locale Functions

A trusted version of locale functions is not provided primarily due to the size

restriction. Those functions rely heavily on the localization data (normally 1MB

to 2MB), which should be preloaded into the enclave in advance to ensure

that it will not be modified from the untrusted domain. This practice would

increase the footprint of an enclave, especially for those enclaves not depend-

ing on the locale functionality. Moreover, since localization data is not avail-

able, wide character functions inquiring enclave locale settings are not

supported either.

Random Number Generation Functions

The random functions srand and rand are not supported in the Intel(R) SGX

SDK Clibrary. A true random function sgx_read_rand is provided in the

tRTS library by using the RDRAND instruction. However, in the Intel(R) SGX

simulation environment, this function still generates pseudo random numbers

because RDRAND may not be available on the hardware platform.

String Functions

The functions strcpy and strcat are not supported in the Intel(R) SGX SDK

C library. You are recommended to use strncpy and strncat instead.

Abort Function

The abort() function is supported within an enclave but has a different beha-

vior. When a thread calls the abort function, it makes the enclave unusable by

setting the enclave state to a specific value that allows the tRTS and applic-

ation to detect and report this event. The aborting thread generates an excep-

tion and exits the enclave, while other enclave threads continue running

normally until they exit the enclave. Once the enclave is in the unusable state,

subsequent enclave calls and OCALL returns generate the same error indic-

ating that the enclave is no longer usable. After all thread calls abort, the

enclave is locked and cannot be recovered. You have to destroy, reload and

reinitialize the enclave to use it again.

Thread Synchronization Primitives

Multiple untrusted threads may enter an enclave simultaneously as long as

more than one thread context is defined by the application and created by

the untrusted loader. Once multiple threads execute concurrently within an

enclave, they will need some forms of synchronization mechanism if they

intend to operate on any global data structure. In some cases, threads may use

the atomic operations provided by the processor’s ISA. In the general case,

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 97 -

however, they would use synchronization objects and mechanisms similar to

those available outside the enclave.

The Intel(R) Software Guard Extensions SDK already supports mutex and con-

ditional variable synchronization mechanisms by means of the following API

and data types defined in the Types and Enumerations section. Some func-

tions included in the trusted Thread Synchronization library may make calls

outside the enclave (OCALLs). If you use any of the APIs below, you must first

import the needed OCALL functions from sgx_tstdc.edl. Otherwise, you

will get a linker error when the enclave is being built; see Calling Functions out-

side the Enclave for additional details. The table below illustrates the prim-

itives that the Intel(R) SGX Thread Synchronization library supports, as well as

the OCALLs that each API function needs.

Function API OCall Function

Mutex Synchronization

sgx_thread_

mutex_init

sgx_thread_

mutex_destroy

sgx_thread_

mutex_lock

sgx_thread_wait_untrusted_

event_ocall

sgx_thread_

mutex_trylock

sgx_thread_

mutex_unlock

sgx_thread_set_untrusted_

event_ocall

Condition Variable Syn-

chronization

sgx_thread_cond_

init

sgx_thread_cond_

destroy

sgx_thread_cond_

wait

sgx_thread_wait_untrusted_

event_ocall

sgx_thread_setwait_untrusted_

events_ocall

sgx_thread_cond_

signal

sgx_thread_set_untrusted_

event_ocall

sgx_thread_cond_

broadcast

sgx_thread_set_multiple_untrus-

ted_events_ocall

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 98 -

Thread Management sgx_thread_self

sgx_thread_equal

Query CPUID inside Enclave

The Intel(R) Software Guard Extensions SDK provides two functions for

enclave developers to query a subset of CPUID information inside the enclave:

l sgx_cpuid

l sgx_cpuidex

GCC*Built-in Functions

GCC* provides built-in functions with optimization purposes. When GCC recog-

nizes a built-in function, it will generate the code more efficiently by lever-

aging its optimization algorithms. GCC always treats functions with __

builtin_ prefix as built-in functions, such as __bultin_malloc, __

builtin_strncpy, and so on. In many cases, GCC tries to use the built-in

variant for standard C functions, such as memcpy, strncpy, and abort. A call

to the C library function is generated unless the -fno-builtin compiler

option is specified.

GCC optimizes built-in functions in certain cases. If GCC does not expand the

built-in function directly, it will call the corresponding library function (without

the __builtin_ prefix). The trusted C library must supply a version of the

functions to ensure the enclave is always built correctly.

The trusted C library does not contain any function considered insecure (for

example, strcpy) or that may contain illegal instructions in Intel SGX (for

example, fprintf). However, the ISV should be aware that GCC may intro-

duce security risks into an enclave if the compiler inlines the code cor-

responding to an insecure built-in function. In this case, the ISV may use the -

fno-builtin or -fno-builtin-function options to suppress any

unwanted built-in code generation.

See Unsupported GCC* Built-in Functions within an enclave for a list of unsup-

ported GCC built-ins.

Non-Local Jumps

The C standard library provides a pair of functions, setjmp and longjmp,

that can be used to perform non-local jumps. setjmp saves the current pro-

gram state into a data structure. longjmp can later use this data structure to

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 99 -

restore the execution context. This means that after longjmp, execution con-

tinues at the setjmp call site.

Since setjmp/longjmp may transfer execution from one function to a pre-

determined location in another function, normal stack unwinding does not

occur. As a result, you must use this functionality carefully, ensuring that an

enclave only calls setjmp in a valid context. You should also perform extens-

ive security validation to ascertain that the enclave never uses these functions

in such a way it could result in undefined behavior. Typical use of

setjmp/longjmp is the implementation of an exception mechanism (error

handling). However, you must never use these functions in C++ programs. You

should use the standard CEH instead. You are recommended to review the

information provided at cert.org on how to use setjmp/longjmp securely.

As a precaution, the Intel® SGXSDK includes the setjmp/longjmp func-

tionality in its own library, rather than within the trusted C library. In this way,

enclaves will not incorporate this functionality by mistake. To access this func-

tionality, you must explicitly give the linker the specific library.

Requirements

Header

setjmp.h

Library

libsgx_tsetjmp.a

C++ Language Support

The Intel® Software Guard Extensions SDK provides a trusted library for C++

support inside the enclave. C++ developers would utilize advanced C++ fea-

tures that require C++ runtime libraries.

The ISO/IEC 14882:2003 C++ standard is chosen as the baseline for the Intel®

Software Guard Extensions SDK trusted library. Most of standard C++ features

are fully supported inside the enclave, and including:

1. Dynamic memory management with new/delete;

2. Global initializers are supported (usually used in the construction of

global objects);

3. Run-time Type Identification (RTTI);

4. C++ exception handling inside the enclave.

Currently, global destructors are not supported due to the reason that EPC

memory will be recycled when destroying an enclave.

NOTE

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 100 -

C++ objects are not supported in enclave interface definitions. If an applic-

ation needs to pass a C++ object across the enclave boundary, you are recom-

mended to store the C++ object’s data in a C struct and marshal the data

across the enclave interface. Then you need to instantiate the C++ object

inside the enclave with the marshaled C struct passed in to the constructor (or

you may update existing instantiated objects with appropriate operators).

C++ Standard Library

The Intel(R) Software Guard Extensions SDK includes a trusted version of the

C++ standard library (including STL) that conforms to the C++03 standard.

The library is ported from STLport.

As for the C++ standard library, most functions will work just as its untrusted

counterpart, but here is a high level summary of features that are not sup-

ported inside the enclave:

1. I/O related functions and classes, like <iostream>;

2. Functions depending on a locale library;

3. Any other functions that require system calls.

However, only C functions can be used as the language for trusted and untrus-

ted interfaces. While you can use C++ to develop your enclaves, you should

not pass C++ objects across the enclave boundary.

Cryptography Library

The Intel(R) Software Guard Extensions SDK includes a trusted cryptography

library named sgx_tcrypto. It includes the cryptographic functions used by

other trusted libraries included in the SDK, such as the sgx_tservice lib-

rary. Thus, the functionality provided by this library is somewhat limited.

l sgx_sha256_msg

l sgx_sha256_init

l sgx_sha256_update

l sgx_sha256_get_hash

l sgx_sha256_close

l sgx_rijndael128GCM_encrypt

l sgx_rijndael128GCM_decrypt

l sgx_rijndael128_cmac_msg

l sgx_cmac128_init

l sgx_cmac128_update

l sgx_cmac128_final

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 101 -

l sgx_cmac128_close

l sgx_aes_ctr_encrypt

l sgx_aes_ctr_decrypt

l sgx_ecc256_open_context

l sgx_ecc256_close_context

l sgx_ecc256_create_key_pair

l sgx_ecc256_compute_shared_dhkey

l sgx_ecc256_check_point

l sgx_ecdsa_sign

l sgx_ecdsa_verify

Trusted Key Exchange Functions

These functions allow an ISV to exchange secrets between its server and its

enclaves. They are used in concert with untrusted Key Exchange functions.

l sgx_ra_init

l sgx_ra_init_ex

l sgx_ra_get_keys

l sgx_ra_close

TCMalloc Library

The Intel(R) Software Guard Extensions SDK includes a trusted version of the

TCMalloc library. The library is named sgx_tcmalloc, and can only be used

inside an enclave. sgx_tcmalloc provides high performance memory alloc-

ation and deallocation functions that are ported from gperftools-2.5:

l malloc

l free

l realloc

l calloc

l memalign

Do the following to enable TCMalloc in Intel(R) SGX:

1.Set the enclave HeapMaxSize equal or larger than 0x900000 in Enclave.-

config.xml.

For example:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 102 -

2.Add "-Wl,--whole-archive -lsgx_tcmalloc -Wl,--no-whole-

archive" into enclave linking options in the Makefile.

For example:

Enclave_Link_Flags := $(SGX_COMMON_CFLAGS) -Wl,--no-

undefined -nostdlib -nodefaultlibs -nostartfiles -

L$(SGX_LIBRARY_PATH) \

-Wl,--whole-archive -l$(Trts_Library_Name) -Wl,--no-

whole-archive \

-Wl,--whole-archive -lsgx_tcmalloc -Wl,--no-whole-

archive \

-Wl,--start-group -lsgx_tstdc -lsgx_tstdcxx -l$(Crypto_

Library_Name) -l$(Service_Library_Name) -Wl,--end-group

-Wl,-Bstatic -Wl,-Bsymbolic -Wl,--no-undefined \

-Wl,-pie,-eenclave_entry -Wl,--export-dynamic \

-Wl,--defsym,__ImageBase=0 \

-Wl,--version-script=Enclave/Enclave.lds

NOTE:

The flags "-Wl,--whole-archive -lsgx_tcmalloc -Wl,--no-

whole-archive" must be inserted before "-Wl,--start-group -

lsgx_tstdc -lsgx_tstdcxx -Wl,--end-group".

Otherwise, the enclave build will fail.

Function Descriptions

This topic describes various functions including their syntax, parameters,

return values, and requirements.

NOTE

When an APIfunction lists an EDLin its requirements, users need to explicitly

import such library EDL file in their enclave's EDL.

sgx_create_enclave

Loads the enclave using its file name and initializes it using a launch token.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 103 -

sgx_status_t sgx_create_enclave(

const char *file_name,

const int debug,

sgx_launch_token_t *launch_token,

int *launch_token_updated,

sgx_enclave_id_t *enclave_id,

sgx_misc_attribute_t *misc_attr

);

Parameters

file_name [in]

Name or full path to the enclave image.

debug [in]

The valid value is 0 or 1.

0 indicates to create the enclave in non-debug mode. An enclave created in

non-debug mode cannot be debugged.

1 indicates to create the enclave in debug mode. The code/data memory

inside an enclave created in debug mode is accessible by the debugger or

other software outside of the enclave and thus is not under the same memory

access protections as an enclave created in non-debug mode.

Enclaves should only be created in debug mode for debug purposes. A helper

macro SGX_DEBUG_FLAG is provided to create an enclave in debug mode. In

release builds, the value of SGX_DEBUG_FLAG is 0. In debug and pre-release

builds, the value of SGX_DEBUG_FLAG is 1 by default.

launch_token [in/out]

A pointer to an sgx_launch_token_t object used to initialize the enclave to be

created. Must not be NULL. The caller can provide an all-0 buffer as the sgx_

launch_token_t object, in which case, the function will attempt to create a

valid sgx_launch_token_t object and store it in the buffer. The caller should

store the sgx_launch_token_t object and re-use it in future calls to create the

same enclave. Certain platform configuration changes can invalidate a pre-

viously stored sgx_launch_token_t object. If the token provided is not valid,

the function will attempt to update it to a valid one.

launch_token_updated [out]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 104 -

The output is 0 or 1. 0 indicates the launch token has not been updated. 1

indicates the launch token has been updated.

enclave_id [out]

A pointer to an sgx_enclave_id_t that receives the enclave ID or handle. Must

not be NULL.

misc_attr [out, optional]

A pointer to an sgx_misc_attribute_t structure that receives the misc select

and attributes of the enclave. This pointer may be NULL if the information is

not needed.

Return value

SGX_SUCCESS

The enclave was loaded and initialized successfully.

SGX_ERROR_INVALID_ENCLAVE

The enclave file is corrupted.

SGX_ERROR_INVALID_PARAMETER

The ‘enclave_id’, ‘updated’ or ‘token’ parameter is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory available to complete sgx_create_enclave().

SGX_ERROR_ENCLAVE_FILE_ACCESS

The enclave file can’t be opened. It may be caused by enclave file not being

found or no privilege to access the enclave file.

SGX_ERROR_INVALID_METADATA

The metadata embedded within the enclave image is corrupt or missing.

SGX_ERROR_INVALID_VERSION

The enclave metadata version (created by the signing tool) and the untrusted

library version (uRTS) do not match.

SGX_ERROR_INVALID_SIGNATURE

The signature for the enclave is not valid.

SGX_ERROR_OUT_OF_EPC

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 105 -

The protected memory has run out. For example, a user is creating too many

enclaves, the enclave requires too much memory, or we cannot load one of the

Architecture Enclaves needed to complete this operation.

SGX_ERROR_NO_DEVICE

The Intel SGX device is not valid. This may be caused by the Intel SGX driver

not being installed or the Intel SGX driver being disabled.

SGX_ERROR_MEMORY_MAP_CONFLICT

During enclave creation, there is a race condition for mapping memory

between the loader and another thread. The loader may fail to map virtual

address. If this error code is encountered, create the enclave again.

SGX_ERROR_DEVICE_BUSY

The Intel SGX driver or low level system is busy when creating the enclave. If

this error code is encountered, we suggest creating the enclave again.

SGX_ERROR_MODE_INCOMPATIBLE

The target enclave mode is incompatible with the mode of the current RTS.

For example, a 64-bit application tries to load a 32-bit enclave or a simulation

uRTS tries to load a hardware enclave.

SGX_ERROR_SERVICE_UNAVAILABLE

sgx_create_enclave() needs the AE service to get a launch token. If the

service is not available, the enclave may not be launched.

SGX_ERROR_SERVICE_TIMEOUT

The request to the AE service timed out.

SGX_ERROR_SERVICE_INVALID_PRIVILEGE

The request requires some special attributes for the enclave, but is not priv-

ileged.

SGX_ERROR_NDEBUG_ENCLAVE

The enclave is signed as a product enclave and cannot be created as a debug-

gable enclave.

SGX_ERROR_UNDEFINED_SYMBOL

The enclave contains an undefined symbol.

The signing tool should typically report this type of error when the enclave is

built.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 106 -

SGX_ERROR_INVALID_MISC

The MiscSelct/MiscMask settings are not correct.

SGX_ERROR_UNEXPECTED

An unexpected error is detected.

Description

The sgx_create_enclave function will load and initialize the enclave using

the enclave file name and a launch token. If the launch token is incorrect, it will

get a new one and save it back to the input parameter “token”, and the para-

meter “updated” will indicate that the launch token was updated.

If both enclave and launch token are valid, the function will return a value of

SGX_SUCCESS. The enclave ID (handle) is returned via the enclave_id para-

meter.

The library libsgx_urts.a provides this function to load an enclave with

Intel(R) SGX hardware, and it cannot be used to load an enclave linked with

the simulation library. On the other hand, the simulation library libsgx_

urts_sim.a exposes an identical interface which can only load a simulation

enclave. Running in simulation mode does not require Intel(R) SGX hard-

ware/driver. However, it does not provide hardware protection.

The randomization of the load address of the enclave is dependent on the

operating system. The address of the heap and stack is not randomized and is

at a constant offset from the enclave base address. A compromised loader or

operating system (both of which are outside the TCB) can remove the ran-

domization entirely. The enclave writer should not rely on the randomization

of the base address of the enclave.

Requirements

Header

sgx_urts.h

Library libsgx_urts.a or libsgx_urts_sim.a (simulation)

sgx_destroy_enclave

The sgx_destroy_enclave function destroys an enclave and frees its asso-

ciated resources.

Syntax

sgx_status_t sgx_destroy_enclave(

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 107 -

const sgx_enclave_id_t enclave_id

);

Parameters

enclave_id [in]

An enclave ID or handle that was generated by sgx_create_enclave.

Return value

SGX_SUCCESS

The enclave was unloaded successfully.

SGX_ERROR_INVALID_ENCLAVE_ID

The enclave ID (handle) is not valid. The enclave has not been loaded or the

enclave has already been destroyed.

Description

The sgx_destroy_enclave function destroys an enclave and releases its

associated resources and invalidates the enclave ID or handle.

The function will block until no other threads are executing inside the enclave.

It is highly recommended that the sgx_destroy_enclave function be

called after the application has finished using the enclave to avoid possible

deadlocks.

The library libsgx_urts.aexposes this function to destroy a previously cre-

ated enclave in hardware mode, while libsgx_urts_sim.a provides a sim-

ulative counterpart.

See more details in Loading and Unloading an Enclave.

Requirements

Header

sgx_urts.h

Library libsgx_urts.a or libsgx_urts_sim.a (simulation)

sgx_init_quote

sgx_init_quote returns information needed by an Intel(R) SGX application

to get a quote of one of its enclaves.

Syntax

sgx_status_t sgx_init_quote(

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 108 -

sgx_target_info_t *p_target_info,

sgx_epid_group_id_t *p_gid

);

Parameters

p_target_info [out]

Allows an enclave for which the quote is being created, to create report that

only QE can verify.

p_gid [out]

ID of platform’s current Intel(R) EPID group.

Return value

SGX_SUCCESS

All of the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers are invalid.

SGX_ERROR_AE_INVALID_EPIDBLOB

The Intel(R) EPID blob is corrupted.

SGX_ERROR_BUSY

The requested service is temporarily not available

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_EPC

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 109 -

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UPDATE_NEEDED

Intel(R) SGX needs to be updated.

SGX_ERROR_UNRECOGNIZED_PLATFORM

Intel(R) EPID Provisioning failed because the platform was not recognized by

the back-end server.

SGX_ERROR_UNEXPECTED

An unexpected error was detected.

Description

Calling sgx_init_quote is the first thing an Intel(R) Software Guard Exten-

sions application does in the process of getting a quote of an enclave. The con-

tent of p_target_info changes when the QE changes. The content of p_gid

changes when the platform SVN changes.

It's suggested that the caller should wait (typically several seconds to tens of

seconds) and retry this API if SGX_ERROR_BUSY is returned.

Requirements

Header

sgx_uae_service.h

Library

libsgx_uae_service.a

libsgx_uae_service_sim.a

(simulation)

sgx_get_quote_size

sgx_get_quote_size returns the required buffer size for the quote.

Syntax

sgx_status_t sgx_get_quote_size(

const uint8_t *p_sig_rl,

uint32_t *p_quote_size

);

Parameters

p_sig_rl [in]

Optional revoke list of signatures, can be NULL.

p_quote_size [out]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 110 -

Indicate the size of quote buffer.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

The p_quote_size pointer is invalid or the other input parameters are cor-

rupted.

Description

You cannot allocate a chunk of memory at compile time because the size of

the quote is not a fixed value. Instead, before trying to call sgx_get_quote,

call sgx_get_quote_size first to get the buffer size and then allocate

enough memory for the quote.

Requirements

Header

sgx_uae_service.h

Library

libsgx_uae_service.a

libsgx_uae_service_sim.a

(simulation)

sgx_get_quote

sgx_get_quote generates a linkable or un-linkable QUOTE.

Syntax

sgx_status_t sgx_get_quote(

const sgx_report_t *p_report,

sgx_quote_sign_type_t quote_type,

const sgx_spid_t *p_spid,

const sgx_quote_nonce_t *p_nonce,

const uint8_t *p_sig_rl,

uint32_t sig_rl_size,

sgx_report_t *p_qe_report,

sgx_quote_t *p_quote,

uint32_t quote_size

);

Parameters

p_report [in]

Report of enclave for which quote is being calculated.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 111 -

quote_type [in]

SGX_UNLINKABLE_SIGNATURE for unlinkable quote or SGX_LINKABLE_

SIGNATURE for linkable quote.

p_spid [in]

ID of service provider.

p_nonce [in]

Optional nonce, if p_qe_report is not NULL, then nonce should not be NULL

as well.

p_sig_rl [in]

Optional revoke list of signatures, can be NULL.

sig_rl_size [in]

Size of p_sig_rl, in bytes. If the p_sig_rl is NULL, then sig_rl_size

shall be 0.

p_qe_report [out]

Optional output. If not NULL, report of QE target to the calling enclave will be

copied to this buffer, and in this case, nonce should not be NULL as well.

p_quote [out]

The major output of get_quote, the quote itself, linkable or unlinkable

depending on quote_type input. quote cannot be NULL.

quote_size [in]

Indicates the size of the quote buffer. To get the size, user shall call sgx_

get_quote_size first.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers are invalid.

SGX_ERROR_AE_INVALID_EPIDBLOB

The Intel(R) EPID blob is corrupted.

SGX_ERROR_EPID_MEMBER_REVOKED

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 112 -

The Intel(R) EPID group membership has been revoked. The platform is not

trusted. Updating the platform and retrying will not remedy the revocation.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond.

SGX_ERROR_SERVICE_TIMEOUT

A request to AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UPDATE_NEEDED

Intel(R) SGX needs to be updated.

SGX_ERROR_UNRECOGNIZED_PLATFORM

Intel(R) EPID Provisioning failed because the platform was not recognized by

the back-end server.

SGX_ERROR_UNEXPECTED

An unexpected error was detected.

Description

Both Intel(R) EPID Member and Verifier need to know the Group Public Key

and the Intel(R) EPID Parameters used. These values not being returned by

either sgx_init_quote() or sgx_get_quote() reflects the reliance on

the Attestation Service for Intel(R) Software Guard Extensions. With the Attest-

ation Service in place, simply sending the GID to the Attestation Service

(through the Intel(R) SGX application and PS) is sufficient for the Attestation

Service to know which public key and parameters to use.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 113 -

The purpose of p_qe_report is for the ISV enclave to confirm the QUOTE it

received is not modified by the untrusted SW stack, and not a replay. The

implementation in QE is to generate a REPORT targeting the ISV enclave (tar-

get info from p_report) , with the lower 32Bytes in report.data =

SHA256(p_nonce||p_quote). The ISV enclave can verify the p_qe_

report and report.data to confirm the QUOTE has not be modified and

is not a replay. It is optional.

It's suggested that the caller should wait (typically several seconds to tens of

seconds) and retry this API if SGX_ERROR_BUSY is returned.

Requirements

Header

sgx_uae_service.h

Library

libsgx_uae_service.a

libsgx_uae_service_sim.a

(simulation)

sgx_ra_get_msg1

sgx_ra_get_msg1 is used to get the remote attestation and key exchange

protocol message 1 to send to a service provider. The application enclave

should use sgx_ra_initor sgx_ra_init_ex function to create the

remote attestation and key exchange process context, and return to the

untrusted code, before the untrusted code can invoke this function.

Syntax

sgx_status_t sgx_ra_get_msg1(

sgx_ra_context_t context,

sgx_enclave_id_t eid,

sgx_ecall_get_ga_trusted_t p_get_ga,

sgx_ra_msg1_t *p_msg1

);

Parameters

context [in]

Context returned by the sgx_ra_init or sgx_ra_init_ex function inside

the application enclave.

eid [in]

ID of the application enclave which is going to be attested.

p_get_ga [in]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 114 -

Function pointer of the ECALL proxy sgx_ra_get_ga generated by sgx_

edger8r. The application enclave should link with sgx_tkey_exchange lib-

rary and import sgx_tkey_exchange.edl in the enclave EDLfile to expose

the ECALL proxy for sgx_ra_get_ga.

p_msg1 [out]

Message 1 used by the remote attestation and key exchange protocol.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers are invalid.

SGX_ERROR_AE_INVALID_EPIDBLOB

The Intel(R) EPID blob is corrupted.

SGX_ERROR_EPID_MEMBER_REVOKED

The Intel(R) EPID group membership has been revoked. The platform is not

trusted. Updating the platform and retrying will not remedy the revocation.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_UPDATE_NEEDED

Intel(R) SGX needs to be updated.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond.

SGX_ERROR_SERVICE_TIMEOUT

A request to AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 115 -

Network connecting or proxy setting issue was encountered.

SGX_ERROR_INVALID_STATE

The API is invoked in incorrect order or state.

SGX_ERROR_UNRECOGNIZED_PLATFORM

Intel(R) EPID Provisioning failed because the platform was not recognized by

the back-end server.

SGX_ERROR_UNEXPECTED

An unexpected error was detected.

Description

The application also passes in a pointer to the untrusted proxy corresponding

to sgx_ra_get_ga, which is exposed by the trusted key exchange library.

This reflects the fact that the names of untrusted proxies are enclave-specific.

It's suggested that the caller should wait (typically several seconds to tens of

seconds) and retry this API if SGX_ERROR_BUSY is returned.

Requirements

Header

sgx_ukey_exchange.h

Library

libsgx_ukey_exchange.a

sgx_ra_proc_msg2

sgx_ra_proc_msg2 is used to process the remote attestation and key

exchange protocol message 2 from the service provider and generate mes-

sage 3 to send to the service provider. If the service provider accepts mes-

sage 3, negotiated session keys between the application enclave and the

service provider are ready for use. The application enclave can use sgx_ra_

get_keys function to retrieve the negotiated keys and can use sgx_ra_

close function to release the context of the remote attestation and key

exchange process. If processing message 2 results in an error, the application

should notify the service provider of the error or the service provider needs a

time-out mechanism to terminate the remote attestation transaction when it

does not receive message 3.

Syntax

sgx_status_t sgx_ra_proc_msg2(

sgx_ra_context_t context,

sgx_enclave_id_t eid,

sgx_ecall_proc_msg2_trusted_t p_proc_msg2,

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 116 -

sgx_ecall_get_msg3_trusted_t p_get_msg3,

const sgx_ra_msg2_t *p_msg2,

uint32_t msg2_size,

sgx_ra_msg3_t **pp_msg3,

uint32_t *p_msg3_size

);

Parameters

context [in]

Context returned by sgx_ra_init.

eid [in]

ID of the application enclave which is going to be attested.

p_proc_msg2 [in]

Function pointer of the ECALL proxy sgx_ra_proc_msg2_trusted_t gen-

erated by sgx_edger8r. The application enclave should link with sgx_

tkey_exchange library and import the sgx_tkey_exchange.edl in the

EDL file of the application enclave to expose the ECALL proxy for sgx_ra_

proc_msg2.

p_get_msg3 [in]

Function pointer of the ECALL proxy sgx_ra_get_msg3_trusted_t gen-

erated by sgx_edger8r. The application enclave should link with sgx_

tkey_exchange library and import the sgx_tkey_exchange.edl in the

EDL file of the application enclave to expose the ECALL proxy for sgx_ra_

get_msg3.

p_msg2 [in]

sgx_ra_msg2_t message 2 from the service provider received by applic-

ation.

msg2_size [in]

The length of p_msg2 (in bytes).

pp_msg3 [out]

sgx_ra_msg3_t message 3 to be sent to the service provider. The message

buffer is allocated by the sgx_ukey_exchange library. The caller should

free the buffer after use.

p_msg3_size [out]

The length of pp_msg3 (in bytes).

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 117 -

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers are invalid.

SGX_ERROR_AE_INVALID_EPIDBLOB

The Intel(R) EPID blob is corrupted.

SGX_ERROR_EPID_MEMBER_REVOKED

The Intel(R) EPID group membership has been revoked. The platform is not

trusted. Updating the platform and retrying will not remedy the revocation.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_UPDATE_NEEDED

Intel(R) SGX needs to be updated.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond.

SGX_ERROR_SERVICE_TIMEOUT

A request to AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_INVALID_STATE

The API is invoked in incorrect order or state.

SGX_ERROR_INVALID_SIGNATURE

The signature is invalid.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 118 -

SGX_ERROR_MAC_MISMATCH

Indicates verification error for reports, sealed data, etc.

SGX_ERROR_KDF_MISMATCH

Indicates key derivation function does not match.

SGX_ERROR_UNRECOGNIZED_PLATFORM

Intel(R) EPID Provisioning failed because the platform was not recognized by

the back-end server.

SGX_ERROR_UNEXPECTED

An unexpected error was detected.

Description

The sgx_ra_proc_msg2 processes the incoming message 2 and returns

message 3. Message 3 is allocated by the library, so the caller should free it

after use.

It's suggested that the caller should wait (typically several seconds to tens of

seconds) and retry this API if SGX_ERROR_BUSY is returned.

Requirements

Header

sgx_ukey_exchange.h

Library

libsgx_ukey_exchange.a

sgx_report_attestation_status

sgx_report_attestation_status reports information from the Intel

Attestation Server during a remote attestation to help to decide whether a

TCB update is required. It is recommended to always call sgx_report_

attestation_status after a remote attestation transaction when it results

in a Platform Info Blob (PIB).

The attestation_status indicates whether the ISV server decided to

trust the enclave or not.

l The value pass:0 indicates that the ISV server trusts the enclave. If the

ISV server trusts the enclave and platform services, sgx_report_

attestation_status will not take actions to correct the TCB that will

cause negative user experience such as long latencies or requesting a

TCB update.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 119 -

l The value fail:!=0 indicates that the ISV server does not trust the

enclave. If the ISV server does not trust the enclave or platform services,

sgx_report_attestation_statuswill take all actions to correct

the TCB which may incur long latencies and/or request the application to

update one of the Intel SGX’s TCB components. It is the ISV’s respons-

ibility to provide the TCB component updates to the client platform.

Syntax

sgx_status_t sgx_report_attestation_status (

const sgx_platform_info_t* p_platform_info

int attestation_status,

sgx_update_info_bit_t* p_update_info

);

Parameters

p_platform_info [in]

Pointer to opaque structure received from Intel Attestation Server.

attestation_status [in]

The value indicates whether remote attestation succeeds or fails. If attestation

succeeds, the value is 0. If it fails, the value will be others.

p_update_info [out]

Pointer to the buffer that receives the update information only when the

return value of sgx_report_attestation_status is SGX_ERROR_

UPDATE_NEEDED.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers are invalid.

SGX_ERROR_AE_INVALID_EPIDBLOB

The Intel(R) EPID blob is corrupted.

SGX_ERROR_UPDATE_NEEDED

Intel(R) SGX needs to be updated.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 120 -

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond.

SGX_ERROR_SERVICE_TIMEOUT

A request to AE service timed out.

SGX_ERROR_BUSY

This service is temporarily unavailable.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UNRECOGNIZED_PLATFORM

Intel(R) EPID Provisioning failed because the platform was not recognized by

the back-end server.

SGX_ERROR_UNEXPECTED

An unexpected error was detected.

Description

The application calls sgx_report_attestation_status after remote

attestation to help to recover the TCB.

Requirements

Header

sgx_uae_service.h

Library

libsgx_uae_service.a

libsgx_uae_service_sim.a

(simulation)

sgx_get_extended_epid_group_id

The function sgx_get_extended_epid_group_id reports which exten-

ded Intel(R) EPIDGroup the client uses by default. The key used to sign a

Quote will be a member of the extended Intel(R) EPIDGroup reported in this

API.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 121 -

sgx_status_t sgx_get_extended_epid_group_id(

uint32_t *p_extended_epid_group_id

);

Parameters

p_extended_epid_group_id [out]

The extended Intel(R) EPIDGroup ID.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

The p_extended_epid_group_id pointer is invalid.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond.

SGX_ERROR_SERVICE_TIMEOUT

A request to AE service timed out.

SGX_ERROR_UNEXPECTED

An unexpected error was detected.

Description

The application uses this value to tell the ISV Service Provider which exten-

ded Intel(R) EPIDGroup to use during remote attestation.

Requirements

Header

sgx_uae_service.h

Library

libsgx_uae_service.a

libsgx_uae_service_sim.a

(simulation)

sgx_get_ps_cap

sgx_get_ps_cap returns the platform service capability of the platform.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 122 -

sgx_status_t sgx_get_ps_cap(

sgx_ps_cap_t* p_sgx_ps_cap

);

Parameters

p_sgx_ps_cap [out]

A pointer to sgx_ps_cap_t structure indicates the platform service capability

of the platform.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

The ps_cap pointer is invalid.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_UNEXPECTED

An unexpected error is detected.

Description

Before using Platform Services provided by the trusted Architecture Enclave

support library, you need to call sgx_get_ps_cap first to get the capability

of the platform.

Requirements

Header

sgx_uae_service.h

Library

libsgx_uae_service.a

libsgx_uae_service_sim.a

(simulation)

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 123 -

sgx_get_whitelist_size

sgx_get_whitelist_size returns the required buffer size for the white-

list.

Syntax

sgx_status_t sgx_get_whitelist_size(

uint32_t *p_whitelist_size

);

Parameters

p_whitelist_size [out]

Indicate the size of white-list buffer.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

The p_whitelist_size pointer is invalid.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond.

SGX_ERROR_SERVICE_TIMEOUT

A request to AE service timed out.

SGX_ERROR_UNEXPECTED

The white-list is invalid.

Description

You cannot allocate a chunk of memory at compile time because the size of

the quote is not a fixed value. Instead, before trying to call sgx_get_whitel-

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 124 -

ist, call sgx_get_whitelist_size first to get the buffer size and then

allocate enough memory for the quote.

Requirements

Header

sgx_uae_service.h

Library

libsgx_uae_service.a

libsgx_uae_service_sim.a

(simulation)

sgx_get_whitelist

sgx_get_whitelist returns the white-list used by aesm_service.

Syntax

sgx_status_t sgx_get_whitelist(

uint8_t *p_whitelist,

uint32_t whitelist_size

);

Parameters

p_whitelist [out]

The white-list.

whitelist_size [in]

Indicate the size of white-list buffer. To get the size, call sgx_get_whitel-

ist_size first.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

The p_whitelist pointer is invalid or p_whitelist_size is not correct.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_SERVICE_UNAVAILABLE

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 125 -

The AE service did not respond.

SGX_ERROR_SERVICE_TIMEOUT

A request to AE service timed out.

SGX_ERROR_UNEXPECTED

The white-list is invalid.

Description

You can get current white-list used by aesm_service.

Requirements

Header

sgx_uae_service.h

Library

libsgx_uae_service.a

libsgx_uae_service_sim.a

(simulation)

sgx_is_within_enclave

The sgx_is_within_enclave function checks that the buffer located at

the pointer addr with its length of size is an address that is strictly within

the calling enclave address space.

Syntax

int sgx_is_within_enclave (

const void *addr,

size_t size

);

Parameters

addr [in]

The start address of the buffer.

size [in]

The size of the buffer.

Return value

The buffer is strictly within the enclave address space.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 126 -

The whole buffer or part of the buffer is not within the enclave, or the buffer is

wrapped around.

Description

sgx_is_within_enclave simply compares the start and end address of

the buffer with the calling enclave address space. It does not check the prop-

erty of the address. Given a function pointer, you sometimes need to confirm

whether such a function is within the enclave. In this case, it is recommended

to use sgx_is_within_enclave with a size of 1.

Requirements

Header

sgx_trts.h

Library

libsgx_trts.a

libsgx_trts_sim.a

(simulation)

sgx_is_outside_enclave

The sgx_is_outside_enclave function checks that the buffer located at

the pointer addr with its length of size is an address that is strictly outside

the calling enclave address space.

Syntax

int sgx_is_outside_enclave (

const void *addr,

size_t size

);

Parameters

addr [in]

The start address of the buffer.

size [in]

The size of the buffer.

Return value

The buffer is strictly outside the enclave address space.

The whole buffer or part of the buffer is not outside the enclave, or the buffer

is wrapped around.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 127 -

Description

sgx_is_outside_enclave simply compares the start and end address of

the buffer with the calling enclave address space. It does not check the prop-

erty of the address.

Requirements

Header

sgx_trts.h

Library

libsgx_trts.a

libsgx_trts_sim.a

(simulation)

sgx_read_rand

The sgx_read_rand function is used to generate a random number inside

the enclave.

Syntax

sgx_status_t sgx_read_rand(

unsigned char *rand,

size_t length_in_bytes

);

Parameters

rand [out]

A pointer to the buffer that receives the random number. The pointer cannot

be NULL. The rand buffer can be either within or outside the enclave, but it is

not allowed to be across the enclave boundary or wrapped around.

length_in_bytes [in]

The length of the buffer (in bytes).

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Invalid input parameters detected.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs during the valid random number gen-

eration process.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 128 -

Description

The sgx_read_rand function is provided to replace the C standard pseudo-

random sequence generation functions inside the enclave, since these stand-

ard functions are not supported in the enclave, such as rand, srand, etc. For

HW mode, the function generates a real-random sequence; while for sim-

ulation mode, the function generates a pseudo-random sequence.

Requirements

Header

sgx_trts.h

Library

libsgx_trts.a

libsgx_trts_sim.a

(simulation)

sgx_register_exception_handler

sgx_register_exception_handler allows developers to register an

exception handler, and specify whether to prepend (when is_first_hand-

ler is equal to 1) or append the handler to the handler chain.

Syntax

void* sgx_register_exception_handler(

int is_first_handler,

sgx_exception_handler_t exception_handler

);

Parameters

is_first_handler [in]

Specify the order in which the handler should be called. If the parameter is

nonzero, the handler is the first handler to be called. If the parameter is zero,

the handler is the last handler to be called.

exception_handler [in]

The exception handler to be called

Return value

Non-zero

Indicates the exception handler is registered successfully. The return value is

an open handle to the custom exception handler.

NULL

The exception handler was not registered.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 129 -

Description

The Intel(R) SGX SDK supports the registration of custom exception handler

functions. You can write your own code to handle a limited set of hardware

exceptions. For example, a CPUID instruction inside an enclave will effectively

result in a #UD fault (Invalid Opcode Exception). ISV enclave code can have an

exception handler to prevent the enclave from being trapped into an excep-

tion condition. See Custom Exception Handling for more details.

Calling sgx_register_exception_handler allows you to register an

exception handler, and specify whether to prepend (when is_first_hand-

ler is nonzero) or append the handler to the handler chain.

After calling sgx_register_exception_handler to prepend an excep-

tion handler, a subsequent call to this function may add another exception

handler at the beginning of the handler chain. Therefore the order in which

exception handlers are called does not only depend on the value of the is_

first_handler parameter, but more importantly depends on the order in

which exception handlers are registered.

NOTE:

Custom exception handling is only supported in hardwaremode. Although the

exception handlers can be registered in simulation mode, the exceptions can-

not be caught and handled within the enclave.

Requirements

Header

sgx_trts_exception.h

Library

libsgx_trts.a

libsgx_trts_sim.a

(simulation)

sgx_unregister_exception_handler

sgx_unregister_exception_handler is used to unregister a custom

exception handler.

Syntax

int sgx_unregister_exception_handler(

void* handler

);

Parameters

handler [in]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 130 -

A handle to the custom exception handler previously registered using the

sgx_register_exception_handler function.

Return value

Non-zero

The custom exception handler is unregistered successfully.

The exception handler was not unregistered (not a valid pointer, handler not

found).

Description

The Intel(R) SGX SDK supports the registration of custom exception handler

functions. An enclave developer can write their own code to handle a limited

set of hardware exceptions. See Custom Exception Handling for more details.

Calling sgx_unregister_exception_handler allows developers to unre-

gister an exception handler that was registered earlier.

Requirements

Header

sgx_trts_exception.h

Library

libsgx_trts.a

libsgx_trts_sim.a

(simulation)

sgx_spin_lock

The sgx_spin_lock function acquires a spin lock within the enclave.

Syntax

uint32_t sgx_spin_lock(

sgx_spinlock_t * lock

);

Parameters

lock [in]

The trusted spin lock object to be acquired.

Return value

This function always returns zero after the lock is acquired.

Description

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 131 -

sgx_spin_lock modifies the value of the spin lock by using compiler atomic

operations. If the lock is not available to be acquired, the thread will always

wait on the lock until it can be acquired successfully.

Requirements

Header

sgx_spinlock.h

Library

libsgx_tstdc.a

sgx_spin_unlock

The sgx_spin_unlock function releases a spin lock within the enclave.

Syntax

uint32_t sgx_spin_unlock(

sgx_spinlock_t * lock

);

Parameters

lock [in]

The trusted spin lock object to be released.

Return value

This function always returns zero after the lock is released.

Description

sgx_spin_unlock resets the value of the spin lock, regardless of its current

state. This function simply assigns a value of zero to the lock, which indicates

the lock is released.

Requirements

Header

sgx_spinlock.h

Library

libsgx_tstdc.a

sgx_thread_mutex_init

The sgx_thread_mutex_init function initializes a trusted mutex object

within the enclave.

Syntax

int sgx_thread_mutex_init(

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 132 -

sgx_thread_mutex_t * mutex,

const sgx_thread_mutexattr_t * unused

);

Parameters

mutex [in]

The trusted mutex object to be initialized.

unused [in]

Unused parameter reserved for future user defined mutex attributes. [NOT

USED]

Return value

The mutex is initialized successfully.

EINVAL

The trusted mutex object is invalid. It is either NULL or located outside of

enclave memory.

Description

When a thread creates a mutex within an enclave, sgx_thread_mutex_

init simply initializes the various fields of the mutex object to indicate that

the mutex is available. sgx_thread_mutex_init creates a non-recursive

mutex. The results of using a mutex in a lock or unlock operation before it has

been fully initialized (for example, the function call to sgx_thread_mutex_

init returns) are undefined. To avoid race conditions in the initialization of a

trusted mutex, it is recommended statically initializing the mutex with the

macro SGX_THREAD_MUTEX_INITIALIZER, SGX_THREAD_NON_

RECURSIVE_MUTEX_INITIALIZER ,of, or SGX_THREAD_RECURSIVE_

MUTEX_INITIALIZER instead.

Requirements

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_thread_mutex_destroy

The sgx_thread_mutex_destroy function destroys a trusted mutex

object within an enclave.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 133 -

Syntax

int sgx_thread_mutex_destroy(

sgx_thread_mutex_t * mutex

);

Parameters

mutex [in]

The trusted mutex object to be destroyed.

Return value

The mutex is destroyed successfully.

EINVAL

The trusted mutex object is invalid. It is either NULL or located outside of

enclave memory.

EBUSY

The mutex is locked by another thread or has pending threads to acquire the

mutex.

Description

sgx_thread_mutex_destroy resets the mutex, which brings it to its initial

status. In this process, certain fields are checked to prevent releasing a mutex

that is still owned by a thread or on which threads are still waiting.

NOTE:

Locking or unlocking a mutex after it has been destroyed results in undefined

behavior. After a mutex is destroyed, it must be re-created before it can be

used again.

Requirements

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_thread_mutex_lock

The sgx_thread_mutex_lock function locks a trusted mutex object within

an enclave.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 134 -

Syntax

int sgx_thread_mutex_lock(

sgx_thread_mutex_t * mutex

);

Parameters

mutex [in]

The trusted mutex object to be locked.

Return value

The mutex is locked successfully.

EINVAL

The trusted mutex object is invalid.

Description

To acquire a mutex, a thread first needs to acquire the corresponding spin

lock. After the spin lock is acquired, the thread checks whether the mutex is

available. If the queue is empty or the thread is at the head of the queue the

thread will now become the owner of the mutex. To confirm its ownership, the

thread updates the refcount and owner fields. If the mutex is not available, the

thread searches the queue. If the thread is already in the queue, but not at the

head, it means that the thread has previously tried to lock the mutex, but it

did not succeed and had to wait outside the enclave and it has been

awakened unexpectedly. When this happens, the thread makes an OCALL and

simply goes back to sleep. If the thread is trying to lock the mutex for the first

time, it will update the waiting queue and make an OCALL to get suspended.

Note that threads release the spin lock after acquiring the mutex or before

leaving the enclave.

NOTE

A thread should not exit an enclave returning from a root ECALL after acquir-

ing the ownership of a mutex. Do not split the critical section protected by a

mutex across root ECALLs.

Requirements

Header

sgx_thread.h sgx_tsrdc.edl

Library

libsgx_tstdc.a

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 135 -

sgx_thread_mutex_trylock

The sgx_thread_mutex_trylock function tries to lock a trusted mutex

object within an enclave.

Syntax

int sgx_thread_mutex_trylock(

sgx_thread_mutex_t * mutex

);

Parameters

mutex [in]

The trusted mutex object to be try-locked.

Return value

The mutex is locked successfully.

EINVAL

The trusted mutex object is invalid.

EBUSY

The mutex is locked by another thread or has pending threads to acquire the

mutex.

Description

A thread may check the status of the mutex, which implies acquiring the spin

lock and verifying that the mutex is available and that the queue is empty or

the thread is at the head of the queue. When this happens, the thread

acquires the mutex, releases the spin lock and returns 0. Otherwise, the

thread releases the spin lock and returns EINVAL/EBUSY. The thread is not sus-

pended in this case.

NOTE

A thread should not exit an enclave returning from a root ECALL after acquir-

ing the ownership of a mutex. Do not split the critical section protected by a

mutex across root ECALLs.

Requirements

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 136 -

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_thread_mutex_unlock

The sgx_thread_mutex_unlock function unlocks a trusted mutex object

within an enclave.

Syntax

int sgx_thread_mutex_unlock(

sgx_thread_mutex_t * mutex

);

Parameters

mutex [in]

The trusted mutex object to be unlocked.

Return value

The mutex is unlocked successfully.

EINVAL

The trusted mutex object is invalid or it is not locked by any thread.

EPERM

The mutex is locked by another thread.

Description

Before a thread releases a mutex, it has to verify it is the owner of the mutex. If

that is the case, the thread decreases the refcount by 1 and then may either

continue normal execution or wakeup the first thread in the queue. Note that

to ensure the state of the mutex remains consistent, the thread that is

awakened by the thread releasing the mutex will then try to acquire the

mutex almost as in the initial call to the sgx_thread_mutex_lock routine.

Requirements

Header

sgx_thread.h sgxtstdc.edl

Library

libsgx_tstdc.a

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 137 -

sgx_thread_cond_init

The sgx_thread_cond_init function initializes a trusted condition vari-

able within the enclave.

Syntax

int sgx_thread_cond_init(

sgx_thread_cond_t * cond,

const sgx_thread_condattr_t * unused

);

Parameters

cond [in]

The trusted condition variable.

attr [in]

Unused parameter reserved for future user defined condition variable attrib-

utes. [NOT USED]

Return value

The condition variable is initialized successfully.

EINVAL

The trusted condition variable is invalid. It is either NULL or located outside

enclave memory.

Description:

When a thread creates a condition variable within an enclave, it simply ini-

tializes the various fields of the object to indicate that the condition variable is

available. The results of using a condition variable in a wait, signal or broadcast

operation before it has been fully initialized (for example, the function call to

sgx_thread_cond_init returns) are undefined. To avoid race conditions

in the initialization of a condition variable, it is recommended statically ini-

tializing the condition variable with the macro SGX_THREAD_COND_

INITIALIZER.

Requirements

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 138 -

sgx_thread_cond_destroy

The sgx_thread_cond_destroy function destroys a trusted condition vari-

able within an enclave.

Syntax

int sgx_thread_cond_destroy(

sgx_thread_cond_t * cond

);

Parameters

cond [in]

The trusted condition variable to be destroyed.

Return value

The condition variable is destroyed successfully.

EINVAL

The trusted condition variable is invalid. It is either NULL or located outside

enclave memory.

EBUSY

The condition variable has pending threads waiting on it.

Description

The procedure first confirms that there are no threads waiting on the con-

dition variable before it is destroyed. The destroy operation acquires the spin

lock at the beginning of the operation to prevent other threads from signaling

to or waiting on the condition variable.

NOTE

Acquiring or releasing a condition variable after it has been destroyed results

in undefined behavior. After a condition variable is destroyed, it must be re-

created before it can be used again.

Requirements

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 139 -

sgx_thread_cond_wait

The sgx_thread_cond_wait function waits on a condition variable within

an enclave.

Syntax

int sgx_thread_cond_wait(

sgx_thread_cond_t * cond,

sgx_thread_mutex_t * mutex

);

Parameters

cond [in]

The trusted condition variable to be waited on.

mutex [in]

The trusted mutex object that will be unlocked when the thread is blocked in

the condition variable.

Return value

The thread waiting on the condition variable is signaled by other thread

(without errors).

EINVAL

The trusted condition variable or mutex object is invalid or the mutex is not

locked.

EPERM

The trusted mutex is locked by another thread.

Description:

A condition variable is always used in conjunction with a mutex. To wait on a

condition variable, a thread first needs to acquire the condition variable spin

lock. After the spin lock is acquired, the thread updates the condition variable

waiting queue. To avoid the lost wake-up signal problem, the condition vari-

able spin lock is released after the mutex. This order ensures the function

atomically releases the mutex and causes the calling thread to block on the

condition variable, with respect to other threads accessing the mutex and the

condition variable. After releasing the condition variable spin lock, the thread

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 140 -

makes an OCALL to get suspended. When the thread is awakened, it acquires

the condition variable spin lock. The thread then searches the condition vari-

able queue. If the thread is in the queue, it means that the thread was already

waiting on the condition variable outside the enclave, and it has been

awakened unexpectedly. When this happens, the thread releases the con-

dition variable spin lock, makes an OCALL and simply goes back to sleep.

Otherwise, another thread has signaled or broadcasted the condition variable

and this thread may proceed. Before returning, the thread releases the con-

dition variable spin lock and acquires the mutex, ensuring that upon returning

from the function call the thread still owns the mutex.

NOTE

Threads check whether they are in the queue to make the Intel SGX condition

variable robust against attacks to the untrusted event.

A thread may have to do up to two OCALLs throughout the sgx_thread_

cond_wait function call.

Requirements

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_thread_cond_signal

The sgx_thread_cond_signal function wakes a pending thread waiting

on the condition variable.

Syntax

int sgx_thread_cond_signal(

sgx_thread_cond_t * cond

);

Parameters

cond [in]

The trusted condition variable to be signaled.

Return value

One pending thread is signaled.

EINVAL

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 141 -

The trusted condition variable is invalid.

Description

To signal a condition variable, a thread starts acquiring the condition variable

spin-lock. Then it inspects the status of the condition variable queue. If the

queue is empty it means that there are not any threads waiting on the con-

dition variable. When that happens, the thread releases the condition variable

and returns. However, if the queue is not empty, the thread removes the first

thread waiting in the queue. The thread then makes an OCALL to wake up the

thread that is suspended outside the enclave, but first the thread releases the

condition variable spin-lock. Upon returning from the OCALL, the thread con-

tinues normal execution.

Requirements

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_thread_cond_broadcast

The sgx_thread_cond_broadcast function wakes all pending threads

waiting on the condition variable.

Syntax

int sgx_thread_cond_broadcast(

sgx_thread_cond_t * cond

);

Parameters

cond [in]

The trusted condition variable to be broadcasted.

Return value

All pending threads have been broadcasted.

EINVAL

The trusted condition variable is invalid.

ENOMEM

Internal memory allocation failed.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 142 -

Description

Broadcast and signal operations on a condition variable are analogous. The

only difference is that during a broadcast operation, the thread removes all

the threads waiting on the condition variable queue and wakes up all the

threads suspended outside the enclave in a single OCALL.

Requirements

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_thread_self

The sgx_thread_self function returns the unique thread identification.

Syntax

sgx_thread_t sgx_thread_self(

void

);

Return value

The return value cannot be NULL and is always valid as long as it is invoked by

a thread inside the enclave.

Description

The function is a simple wrap of get_thread_data() provided in the tRTS,

which provides a trusted thread unique identifier.

NOTE:

This identifier does not change throughout the life of an enclave.

Requirements

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_thread_equal

The sgx_thread_equal function compares two thread identifiers.

Syntax

int sgx_thread_equal(sgx_thread_t

sgx_thread_t t1,

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 143 -

sgx_thread_t t2

);

Return value

A nonzero value if the two thread IDs are equal, 0 otherwise.

Description

The function compares two thread identifiers provided by sgx_thread_

self to determine if the IDs refer to the same trusted thread.

Requirements

Header

sgx_thread.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_cpuid

The sgx_cpuid function performs the equivalent of a cpuid() function call or

intrinisic which executes the CPUID instruction to query the host processor for

the information about supported features.

NOTE:

This function performs an OCALL to execute the CPUID instruction.

Syntax

sgx_status_t sgx_cpuid(

int cpuinfo[4],

int leaf

);

Parameters

cpuinfo [in, out]

The information returned in an array of four integers. This array must be loc-

ated within the enclave.

leaf [in]

The leaf specified for retrieved CPU info.

Return value

SGX_SUCCESS

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 144 -

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates the parameter cpuinfo is invalid, which would be NULL or outside the

enclave.

Description

This function provides the equivalent of the cpuid() function or intrinsic. The

function executes the CPUID instruction for the given leaf (input). The CPUID

instruction provides processor feature and type information that is returned in

cpuinfo, an array of 4 integers to specify the values of EAX, EBX, ECX and EDX

registers. sgx_cpuid performs an OCALL by invoking oc_cpuidex to get the

info from untrusted side because the CPUID instruction is an illegal instruction

in the enclave domain.

For additional details, see Intel(R) 64 and IA-32 Architectures Software

Developer's Manual for the description on the CPUID instruction and its indi-

vidual leafs. (Leaf corresponds to EAX in the PRM description).

NOTE

1. As the CPUID instruction is executed by an OCALL, the results should not

be trusted. Code should verify the results and perform a threat eval-

uation to determine the impact on trusted code if the results were

spoofed.

2. The implementation of this function performs an OCALL and therefore,

this function will not have the same serializing or fencing behavior of

executing a CPUID instruction in an untrusted domain code flow.

Requirements

Header

sgx_cpuid.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_cpuidex

The sgx_cpuidex function performs the equivalent of a cpuid_ex() func-

tion call or intrinisic which executes the CPUID instruction to query the host

processor for the information about supported features.

NOTE:

This function performs an OCALL to execute the CPUID instruction.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 145 -

sgx_status_t sgx_cpuidex(

int cpuinfo[4],

int leaf,

int subleaf

);

Parameters

cpuinfo [in, out]

The information returned in an array of four integers. The array must be loc-

ated within the enclave.

leaf[in]

The leaf specified for retrieved CPU info.

subleaf[in]

The sub-leaf specified for retrieved CPU info.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates the parameter cpuinfo is invalid, which would be NULL or outside the

enclave.

Description

This function provides the equivalent of the cpuid() function or intrinsic.

The function executes the CPUID instruction for the given leaf (input). The

CPUID instruction provides processor feature and type information returned

in cpuinfo, an array of 4 integers to specify the values of EAX, EBX, ECX and

EDX registers. sgx_cpuid performs an OCALL by invoking oc_cpuidex to get

the info from untrusted side because the CPUID instruction is an illegal instruc-

tion in the enclave domain.

For additional details, see Intel(R) 64 and IA-32 Architectures Software

Developer's Manual for the description on the CPUID instruction and its indi-

vidual leafs. (Leaf corresponds to EAX in the PRM description).

NOTE

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 146 -

1. As the CPUID instruction is executed by an OCALL, the results should not

be trusted. Code should verify the results and perform a threat eval-

uation to determine the impact on trusted code if the results were

spoofed.

2. The implementation of this function performs an OCALL and therefore,

this function will not have the same serializing or fencing behavior of

executing a CPUID instruction in an untrusted domain code flow.

Requirements

Header

sgx_cpuid.h sgx_tstdc.edl

Library

libsgx_tstdc.a

sgx_get_key

The sgx_get_key function generates a 128-bit secret key using the input

information. This function is a wrapper for the Intel SGX EGETKEY instruction.

Syntax

sgx_status_t sgx_get_key(

const sgx_key_request_t *key_request,

sgx_key_128bit_t *key

);

Parameters

key_request [in]

A pointer to a sgx_key_request_t object used for selecting the appropriate

key and any additional parameters required in the derivation of that key. The

pointer cannot be NULL and must be located within the enclave. See details

on the sgx_key_request_t to understand initializing this structure before call-

ing this function.

key [out]

A pointer to the buffer that receives the cryptographic key output. The

pointer cannot be NULL and must be located within enclave memory.

Return value

SGX_SUCCESS

Indicates success.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 147 -

SGX_ERROR_INVALID_PARAMETER

Indicates an error if the parameters do not meet any of the following con-

ditions:

key_request buffer must be non-NULL and located within the enclave.

key buffer must be non-NULL and located within the enclave.

key_request and key_request->key_policy should not have any

reserved bits set.

SGX_ERROR_OUT_OF_MEMORY

Indicates an error that the enclave is out of memory.

SGX_ERROR_INVALID_ATTRIBUTE

Indicates the key_request requests a key for a KEYNAME which the enclave

is not authorized.

SGX_ERROR_INVALID_CPUSVN

Indicates key_request->cpu_svn is beyond platform CPUSVN value

SGX_ERROR_INVALID_ISVSVN

Indicates key_request->isv_svn is greater than the enclave’s ISVSVN

SGX_ERROR_INVALID_KEYNAME

Indicates key_request->key_name is an unsupported value

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs during the key generation process.

Description

The sgx_get_key function generates a 128-bit secret key from the pro-

cessor specific key hierarchy with the key_request information. If the func-

tion fails with an error code, the key buffer will be filled with random numbers.

The key_request structure needs to be initialized properly to obtain the

requested key type. See sgx_key_request_t for structure details.

Requirements

Header

sgx_utils.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 148 -

sgx_create_report

The sgx_create_report function tries to use the information of the target

enclave and other information to create a cryptographic report of the enclave.

This function is a wrapper for the Intel SGX EREPORT instruction.

Syntax

sgx_status_t sgx_create_report(

const sgx_target_info_t *target_info,

const sgx_report_data_t *report_data,

sgx_report_t *report

);

Parameters

target_info [in]

A pointer to the sgx_target_info_t object that contains the information of the

target enclave, which will be able to cryptographically verify the report calling

sgx_verify_report.

l If the pointer value is NULL, sgx_create_report retrieves inform-

ation about the calling enclave, but the generated report cannot be veri-

fied by any enclave.

l If the pointer value is not NULL the target_info buffer must be within

the enclave.

See sgx_target_info_t for structure details.

report_data [in]

A pointer to the sgx_report_data_t object which contains a set of data used

for communication between the enclaves. This pointer is allowed to be NULL.

If it is not NULL, the report_data buffer must be within the enclave. See

sgx_report_data_t for structure details.

report [out]

A pointer to the buffer that receives the cryptographic report of the enclave.

The pointer cannot be NULL and the report buffer must be within the enclave.

See sgx_report_t for structure details.

Return value

SGX_SUCCESS

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 149 -

Indicates success.

SGX_ERROR_INVALID_PARAMETER

An error is reported if any of the parameters are non-NULL pointers but the

memory is not within the enclave or the reserved fields of the data structure

are not set to zero.

SGX_ERROR_OUT_OF_MEMORY

Indicates that the enclave is out of memory.

Description

Use the function sgx_create_report to create a cryptographic report that

describes the contents of the calling enclave. The report can be used by other

enclaves to verify that the enclave is running on the same platform. When an

enclave calls sgx_verify_report to verify a report, it will succeed only if

the report was generated using the target_info for said enclave. This func-

tion is a wrapper for the Intel SGX EREPORT instruction.

Before the source enclave calls sgx_create_report to generate a report, it

needs to populate target_info with information about the target enclave

that will verify the report. The target enclave may obtain this information call-

ing sgx_create_report with a NULL pointer for target_info and pass it

to the source enclave at the beginning of the inter-enclave attestation pro-

cess.

Requirements

Header

sgx_utils.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_verify_report

The sgx_verify_report function provides software verification for the

report which is expected to be generated by the sgx_create_report function.

Syntax

sgx_status_t sgx_verify_report(

const sgx_report_t * report

);

Parameters

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 150 -

report[in]

A pointer to an sgx_report_t object that contains the cryptographic report to

be verified. The pointer cannot be NULL and the report buffer must be within

the enclave.

Return value

SGX_SUCCESS

Verification success: The input report was generated using a target_info

that matches the one for the enclave making this call.

SGX_ERROR_INVALID_PARAMETER

The report object is invalid.

SGX_ERROR_MAC_MISMATCH

Indicates report verification error.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs during the report verification process.

Description

The sgx_verify_report performs a cryptographic CMAC function of the

input sgx_report_data_t object in the report using the report key. Then the

function compares the input report MAC value with the calculated MAC value

to determine whether the report is valid or not.

Requirements

Header

sgx_utils.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_calc_sealed_data_size

The sgx_calc_sealed_data_size function is a helper function for the

seal library which should be used to determine how much memory to allocate

for the sgx_sealed_data_t structure.

Syntax

uint32_t sgx_calc_sealed_data_size(

const uint32_t add_mac_txt_size,

const uint32_t txt_encrypt_size

);

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 151 -

Parameters

add_mac_txt_size [in]

Length of the optional additional data stream in bytes. The additional data will

not be encrypted, but will be part of the MAC calculation.

txt_encrypt_size [in]

Length of the data stream to be encrypted in bytes. This data will also be part

of the MAC calculation.

Return value

If the function succeeds, the return value is the minimum number of bytes that

need to be allocated for the sgx_sealed_data_t structure. If the function fails,

the return value is 0xFFFFFFFF. It is recommended that you check the return

value before use it to allocate memory.

Description

The function calculates the number of bytes to allocate for the sgx_sealed_

data_t structure. The calculation includes the fixed portions of the structure as

well as the two input data streams: encrypted text and optional additional

MAC text.

Requirements

Header

sgx_tseal.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_get_add_mac_txt_len

The sgx_get_add_mac_txt_len function is a helper function for the seal

library which should be used to determine how much memory to allocate for

the additional_MAC_text buffer output from the sgx_unseal_data func-

tion.

Syntax

uint32_t sgx_get_add_mac_txt_len(

const sgx_sealed_data_t *p_sealed_data

);

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 152 -

Parameters

p_sealed_data [in]

Pointer to the sealed data structure which was populated by the sgx_seal_

data function.

Return value

If the function succeeds, the number of bytes in the optional additional MAC

data buffer is returned. If this function fails, the return value is 0xFFFFFFFF. It

is recommended that you check the return value before use it to allocate

memory.

Description

The function calculates the minimum number of bytes to allocate for the out-

put MAC data buffer returned by the sgx_unseal_data function.

Requirements

Header

sgx_tseal.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_get_encrypt_txt_len

The sgx_get_encrypt_txt_len function is a helper function for the seal

library which should be used to calculate the minimum number of bytes to

allocate for decrypted data returned by the sgx_unseal_data function.

Syntax

uint32_t sgx_get_encrypt_txt_len(

const sgx_sealed_data_t *p_sealed_data

);

Parameters

p_sealed_data [in]

Pointer to the sealed data structure which was populated during by the sgx_

seal_data function.

Return value

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 153 -

If the function succeeds, the number of bytes in the encrypted data buffer is

returned. Othewise, the return value is 0xFFFFFFFF. It is recommended that

you check the return value before use it to allocate memory.

Description

The function calculates the minimum number of bytes to allocate for decryp-

ted data returned by the sgx_unseal_data function.

Requirements

Header

sgx_tseal.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_seal_data

This function is used to AES-GCM encrypt the input data. Two input data sets

are provided: one is the data to be encrypted; the second is optional addi-

tional data that will not be encrypted but will be part of the GCM MAC cal-

culation which also covers the data to be encrypted.

Syntax

sgx_status_t sgx_seal_data(

const uint32_t additional_MACtext_length,

const uint8_t * p_additional_MACtext,

const uint32_t text2encrypt_length,

const uint8_t * p_text2encrypt,

const uint32_t sealed_data_size,

sgx_sealed_data_t * p_sealed_data

);

Parameters

additional_MACtext_length [in]

Length of the additional Message Authentication Code (MAC) data in bytes.

The additional data is optional and thus the length can be zero if no data is

provided.

p_addtional_MACtext [in]

Pointer to the additional Message Authentication Code (MAC) data. This addi-

tional data is optional and no data is necessary (NULL pointer can be passed,

but additional_MACtext_length must be zero in this case).

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 154 -

NOTE:

This data will not be encrypted. This data can be within or outside the enclave,

but cannot cross the enclave boundary.

text2encrypt_length [in]

Length of the data stream to be encrypted in bytes. Must be non-zero.

p_text2encrypt [in]

Pointer to the data stream to be encrypted. Must not be NULL. Must be within

the enclave.

sealed_data_size [in]

Number of bytes allocated for the sgx_sealed_data_t structure. The calling

code should utilize helper function sgx_calc_sealed_data_size to

determine the required buffer size.

p_sealed_data [out]

Pointer to the buffer to store the sealed data.

NOTE:

The calling code must allocate the memory for this buffer and should utilize

helper function sgx_calc_sealed_data_size to determine the required

buffer size. The sealed data must be within the enclave.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates an error if the parameters do not meet any of the following con-

ditions:

l If additional_MACtext_length is non-zero, p_additional_MAC-

text cannot be NULL.

l p_additional_MACtext buffer can be within or outside the enclave,

but cannot cross the enclave boundary.

l p_text2encrypt must be non-zero.

l p_text2encrypt buffer must be within the enclave.

l sealed_data_size must be equal to the required buffer size, which

is calculated by the function sgx_calc_sealed_data_size.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 155 -

l p_sealed_data buffer must be within the enclave.

l Input buffers cannot cross an enclave boundary.

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

SGX_ERROR_UNEXPECTED

Indicates a crypto library failure or the RDRAND instruction fails to generate a

random number.

Description

The sgx_seal_data function retrieves a key unique to the enclave and uses

that key to encrypt the input data buffer. This function can be utilized to pre-

serve secret data after the enclave is destroyed. The sealed data blob can be

unsealed on future instantiations of the enclave.

The additional data buffer will not be encrypted but will be part of the MAC

calculation that covers the encrypted data as well. This data may include

information about the application, version, data, etc which can be utilized to

identify the sealed data blob since it will remain plain text

Use sgx_calc_sealed_data_size to calculate the number of bytes to

allocate for the sgx_sealed_data_t structure. The input sealed data buffer and

text2encrypt buffers must be allocated within the enclave.

Requirements

Header

sgx_tseal.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_seal_data_ex

This function is used to AES-GCM encrypt the input data. Two input data sets

are provided: one is the data to be encrypted; the second is optional addi-

tional data that will not be encrypted but will be part of the GCM MAC cal-

culation which also covers the data to be encrypted. This is the expert mode

version of function sgx_seal_data.

Syntax

sgx_status_t sgx_seal_data_ex(

const uint16_t key_policy,

const sgx_attributes_t attribute_mask,

const sgx_misc_select_t misc_mask,

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 156 -

const uint32_t additional_MACtext_length,

const uint8_t * p_additional_MACtext,

const uint32_t text2encrypt_length,

const uint8_t * p_text2encrypt,

const uint32_t sealed_data_size,

sgx_sealed_data_t * p_sealed_data

);

Parameters

key_policy [in]

Specifies the policy to use in the key derivation. Function sgx_seal_data

uses the MRSIGNER policy.

Key policy name Value Description

KEYPOLICY_

MRENCLAVE

0x00-

Derive key using the enclave’s ENCLAVE

measurement register

KEYPOLICY_MRSIGNER 0x00-

Derive key using the enclave’s SIGNER meas-

urement register

attribute_mask [in]

Identifies which platform/enclave attributes to use in the key derivation. See

the definition of sgx_attributes_t to determine which attributes will be

checked. Function sgx_seal_data uses flags=0xFF0000000000000B,

xfrm=0.

misc_mask [in]

Identifies the mask bits for the Misc feature to enforce. Function sgx_seal_data

uses 0xF0000000.The misc mask bits for the enclave. Reserved for future

function extension.

additional_MACtext_length [in]

Length of the additional data to be MAC’ed in bytes. The additional data is

optional and thus the length can be zero if no data is provided.

p_addtional_MACtext [in]

Pointer to the additional data to be MAC’ed of variable length. This additional

data is optional and no data is necessary (NULL pointer can be passed, but

additional_MACtext_length must be zero in this case).

NOTE:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 157 -

This data will not be encrypted. This data can be within or outside the enclave,

but cannot cross the enclave boundary.

text2encrypt_length [in]

Length of the data stream to be encrypted in bytes. Must be non-zero.

p_text2encrypt [in]

Pointer to the data stream to be encrypted of variable length. Must not be

NULL. Must be within the enclave.

sealed_data_size [in]

Number of bytes allocated for sealed_data_t structure. The calling code

should utilize helper function sgx_calc_sealed_data_size to determine

the required buffer size.

p_sealed_data [out]

Pointer to the buffer that is populated by this function.

NOTE:

The calling code must allocate the memory for this buffer and should utilize

helper function sgx_calc_sealed_data_size to determine the required

buffer size. The sealed data must be within the enclave.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates an error if the parameters do not meet any of the following con-

ditions:

l If additional_MACtext_length is non-zero, p_additional_

MACtext cannot be NULL.

l p_additional_MACtext buffer can be within or outside the enclave,

but cannot cross the enclave boundary.

l p_text2encrypt must be non-zero.

l p_text2encrypt buffer must be within the enclave.

l sealed_data_size must be equal to the required buffer size, which

is calculated by the function sgx_calc_sealed_data_size.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 158 -

l p_sealed_data buffer must be within the enclave.

l Input buffers cannot cross an enclave boundary.

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

SGX_ERROR_UNEXPECTED

Indicates crypto library failure or the RDRAND instruction fails to generate a

random number.

Description

The sgx_seal_data_ex is an extended version of sgx_seal_data. It

provides parameters for you to identify how to derive the sealing key (key

policy and attributes_mask). Typical callers of the seal library should be

able to use sgx_seal_data and the default values provided for key_

policy (MR_SIGNER) and an attribute mask which includes the RESERVED,

INITED and DEBUG bits. Users of this function should have a clear under-

standing of the impact on using a policy and/or attribute_mask that is dif-

ferent from that in sgx_seal_data.

Requirement

Header

sgx_tseal.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_unseal_data

This function is used to AES-GCM decrypt the input sealed data structure.

Two output data sets result: one is the decrypted data; the second is the

optional additional data that was part of the GCM MAC calculation but was not

encrypted. This function provides the converse of sgx_seal_data and

sgx_seal_data_ex.

Syntax

sgx_status_t sgx_unseal_data(

const sgx_sealed_data_t * p_sealed_data,

uint8_t * p_additional_MACtext,

uint32_t * p_additional_MACtext_length,

uint8_t * p_decrypted_text,

uint32_t * p_decrypted_text_length

);

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 159 -

Parameters

p_sealed_data [in]

Pointer to the sealed data buffer to be AES-GCM decrypted. Must be within

the enclave.

p_addtional_MACtext [out]

Pointer to the additional data part of the MAC calculation. This additional data

is optional and no data is necessary. The calling code should call helper func-

tion sgx_get_add_mac_txt_len to determine the required buffer size to

allocate. (NULL pointer can be passed, if additional_MACtext_length is

zero).

p_additional_MACtext_length [in, out]

Pointer to the length of the additional MAC data buffer in bytes. The calling

code should call helper function sgx_get_add_mac_txt_len to determine

the minimum required buffer size. The sgx_unseal_data function returns

the actual length of decrypted addition data stream.

p_decrypted_text [out]

Pointer to the decrypted data buffer which needs to be allocated by the call-

ing code. Use sgx_get_encrypt_txt_len to calculate the minimum num-

ber of bytes to allocate for the p_decrypted_text buffer. Must be

within the enclave.

p_decrypted_text_length [in, out]

Pointer to the length of the decrypted data buffer in byte. The buffer length

of p_decrypted_text must be specified in p_decrypted_text_length as

input. The sgx_unseal_data function returns the actual length of decryp-

ted addition data stream. Use sgx_get_encrypt_txt_len to calculate the

number of bytes to allocate for the p_decrypted_text buffer. Must be

within the enclave.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates an error if the parameters do not meet any of the following con-

ditions:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 160 -

l If additional_mactext_length is non-zero, p_additional_mac-

text cannot be NULL.

l p_additional_mactext buffer can be within or outside the enclave,

but cannot across the enclave boundary.

l p_decrypted_text and p_decrypted_text_length must be

within the enclave.

l p_decrypted_text and p_addtitional_MACtext buffer must be

big enough to receive the decrypted data.

l p_sealed_data buffer must be within the enclave.

l Input buffers cannot cross an enclave boundary.

SGX_ERROR_INVALID_CPUSVN

The CPUSVN in the sealed data blob is beyond the CPUSVN value of the plat-

form.

SGX_ERROR_INVALID_ISVSVN

The ISVSVN in the sealed data blob is greater than the ISVSVN value of the

enclave.

SGX_ERROR_MAC_MISMATCH

The tag verification failed during unsealing. The error may be caused by a plat-

form update, software update, or sealed data blob corruption. This error is

also reported if other corruption of the sealed data structure is detected.

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

SGX_ERROR_UNEXPECTED

Indicates a cryptography library failure.

Description

The sgx_unseal_data function AES-GCM decrypts the sealed data so that

the enclave data can be restored. This function can be utilized to restore

secret data that was preserved after an earlier instantiation of this enclave

saved this data.

The calling code needs to allocate the additional data buffer and the decryp-

ted data buffer. To determine the minimum memory to allocate for these buf-

fers, helper functions sgx_get_add_mac_txt_len and sgx_get_

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 161 -

encrypt_txt_len are provided. The decrypted text buffer must be alloc-

ated within the enclave.

Requirements

Header

sgx_tseal.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_mac_aadata

This function is used to authenticate the input data with AES-GMAC.

Syntax

sgx_status_t sgx_mac_aadata(

const uint32_t additional_MACtext_length,

const uint8_t * p_additional_MACtext,

const uint32_t sealed_data_size,

sgx_sealed_data_t * p_sealed_data

);

Parameters

additional_MACtext_length [in]

Length of the plain text to provide authentication for in bytes.

p_addtional_MACtext [in]

Pointer to the plain text to provide authentication for.

NOTE:

This data is not encrypted. This data can be within or outside the enclave, but

cannot cross the enclave boundary.

sealed_data_size [in]

Number of bytes allocated for the sealed_data_t structure. The calling

code should utilize the helper function sgx_calc_sealed_data_size to

determine the required buffer size.

p_sealed_data [out]

Pointer to the buffer to store the sealed_data_t structure.

NOTE:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 162 -

The calling code must allocate the memory for this buffer and should utilize

the helper function sgx_calc_sealed_data_size with 0 as the txt_

encrypt_size to determine the required buffer size. The sealed_data_t

structure must be within the enclave.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates an error if the parameters do not meet any of the following con-

ditions:

l p_additional_mactext buffer can be within or outside the enclave,

but cannot cross the enclave boundary.

l sealed_data_size must be equal to the required buffer size, which

is calculated by the function sgx_calc_sealed_data_size.

l p_sealed_data buffer must be within the enclave.

l Input buffers cannot cross an enclave boundary.

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

SGX_ERROR_UNEXPECTED

Indicates a crypto library failure, or the RDRAND instruction fails to generate a

random number.

Description

The sgx_mac_aadata function retrieves a key unique to the enclave and

uses that key to generate the authentication tag based on the input data buf-

fer. This function can be utilized to provide authentication assurance for addi-

tional data (of practically unlimited length per invocation) that is not

encrypted. The data origin authentication can be demonstrated on future

instantiations of the enclave using the MAC stored into the data blob.

Use sgx_calc_sealed_data_size to calculate the number of bytes to

allocate for the sgx_sealed_data_t structure. The input sealed data buffer

must be allocated within the enclave.

Requirements

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 163 -

Header

sgx_tseal.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_mac_aadata_ex

This function is used to authenticate the input data with AES-GMAC. This is

the expert mode version of the function sgx_mac_aadata.

Syntax

sgx_status_t sgx_mac_aadata_ex(

const uint16_t key_policy,

const sgx_attributes_t attribute_mask,

const sgx_misc_select_t misc_mask,

const uint32_t additional_MACtext_length,

const uint8_t * p_additional_MACtext,

const uint32_t sealed_data_size,

sgx_sealed_data_t * p_sealed_data

);

Parameters

key_policy [in]

Specifies the policy to use in the key derivation. Function sgx_mac_aadata

uses the MRSIGNER policy.

Key policy name Value Description

KEYPOLICY_

MRENCLAVE

0x00-

Derive key using the enclave’s ENCLAVE

measurement register

KEYPOLICY_MRSIGNER 0x00-

Derive key using the enclave’s SIGNER meas-

urement register

attribute_mask [in]

Identifies which platform/enclave attributes to use in the key derivation. See

the definition of sgx_attributes_t to determine which attributes will be

checked. Function sgx_mac_aadata uses flag-

s=0xfffffffffffffff3, xfrm=0.

misc_mask [in]

The MISC_SELECT mask bits for the enclave. Reserved for future function

extension.

additional_MACtext_length [in]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 164 -

Length of the plain text data stream to be MAC’ed in bytes.

p_addtional_MACtext [in]

Pointer to the plain text data stream to be MAC’ed of variable length.

NOTE:

This data is not encrypted. This data can be within or outside the enclave, but

cannot cross the enclave boundary.

sealed_data_size [in]

Number of bytes allocated for the sealed_data_t structure. The calling

code should utilize the helper function sgx_calc_sealed_data_size to

determine the required buffer size.

p_sealed_data [out]

Pointer to the buffer that is populated by this function.

NOTE:

The calling code must allocate the memory for this buffer and should utilize

the helper function sgx_calc_sealed_data_size with 0 as the txt_

encrypt_size to determine the required buffer size. The sealed_data_t

structure must be within the enclave.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates an error if the parameters do not meet any of the following con-

ditions:

l p_additional_mactext buffer can be within or outside the enclave,

but cannot cross the enclave boundary.

l sealed_data_size must be equal to the required buffer size, which

is calculated by the function sgx_calc_sealed_data_size.

l p_sealed_data buffer must be within the enclave.

l Input buffers cannot cross an enclave boundary.

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 165 -

SGX_ERROR_UNEXPECTED

Indicates crypto library failure or the RDRAND instruction fails to generate a

random number.

Description

The sgx_mac_aadata_ex is an extended version of sgx_mac_aadata. It

provides parameters for you to identify how to derive the sealing key (key

policy and attributes_mask). Typical callers of the seal library should be

able to use sgx_mac_aadata and the default values provided for key_

policy (MR_SIGNER) and an attribute mask which includes the RESERVED,

INITED and DEBUG bits. Before you use this function, you should have a clear

understanding of the impact of using a policy and/or attribute_mask that

is different from that in sgx_mac_aadata.

Requirement

Header

sgx_tseal.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_unmac_aadata

This function is used to verify the authenticity of the input sealed data struc-

ture using AES-GMAC. This function verifies the MAC generated with sgx_

mac_aadataorsgx_mac_aadata_ex.

Syntax

sgx_status_t sgx_unmac_aadata(

const sgx_sealed_data_t * p_sealed_data,

uint8_t * p_additional_MACtext,

uint32_t * p_additional_MACtext_length,

);

Parameters

p_sealed_data [in]

Pointer to the sealed data structure to be authenticated with AES-GMAC. Must

be within the enclave.

p_addtional_MACtext [out]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 166 -

Pointer to the plain text data stream that was AES-GMAC protected. You

should call the helper function sgx_get_add_mac_txt_len to determine

the required buffer size to allocate.

p_additional_MACtext_length [in, out]

Pointer to the length of the plain text data stream in bytes. Upon successful

tag matching,sgx_unmac_datasets this parameter with the actual length of

the plaintext stored in p_additional_MACtext.

Return value

SGX_SUCCESS

The authentication tag in the sealed_data_t structure matches the expec-

ted value.

SGX_ERROR_INVALID_PARAMETER

This parameter indicates an error if the parameters do not meet any of the fol-

lowing conditions:

l p_additional_MACtext buffers can be within or outside the enclave,

but cannot cross the enclave boundary.

l p_addtitional_MACtext buffers must be big enough to receive the

plain text data.

l p_sealed_data buffers must be within the enclave.

l Input buffers cannot cross an enclave boundary.

SGX_ERROR_INVALID_CPUSVN

The CPUSVN in the data blob is beyond the CPUSVN value of the platform.

SGX_ERROR_INVALID_ISVSVN

The ISVSVN in the data blob is greater than the ISVSVN value of the enclave.

SGX_ERROR_MAC_MISMATCH

The tag verification fails. The error may be caused by a platform update, soft-

ware update, or corruption of the sealed_data_t structure.

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

SGX_ERROR_UNEXPECTED

Indicates a cryptography library failure.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 167 -

Description

The sgx_unmac_aadata function verifies the tag with AES-GMAC. Use this

function to demonstrate the authenticity of data that was preserved by an

earlier instantiation of this enclave.

You need to allocate additional data buffer. To determine the minimum

memory to allocate for additional data buffers, use the helper function sgx_

get_add_mac_txt_len.

Requirements

Header

sgx_tseal.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_sha256_msg

The sgx_sha256_msg function performs a standard SHA256 hash over the

input data buffer.

Syntax

sgx_status_t sgx_sha256_msg(

const uint8_t *p_src,

uint32_t src_len,

sgx_sha256_hash_t *p_hash

);

Parameters

p_src [in]

A pointer to the input data stream to be hashed. A zero length input buffer is

supported, but the pointer must be non-NULL.

src_len [in]

Specifies the length on the input data stream to be hashed. A zero length

input buffer is supported.

p_hash [out]

A pointer to the output 256bit hash resulting from the SHA256 calculation.

This pointer must be non-NULL and the caller allocates memory for this buffer.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 168 -

Return value

SGX_SUCCESS

The SHA256 hash function is performed successfully.

SGX_ERROR_INVALID_PARAMETER

Input pointers are invalid.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The SHA256 hash calculation failed.

Description

The sgx_sha256_msg function performs a standard SHA256 hash over the

input data buffer. Only a 256-bit version of the SHA hash is supported. (Other

sizes, for example 512, are not supported in this minimal cryptography lib-

rary).

The function should be used if the complete input data stream is available.

Otherwise, the Init, Update… Update, Final procedure should be used to com-

pute a SHA256 bit hash over multiple input data sets.

A zero-length input data buffer is supported but the pointer must be non-

NULL.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

or

libsgx_tcrypto_opt.a

sgx_sha256_init

sgx_sha256_init returns an allocated and initialized SHA algorithm con-

text state. This should be part of the Init, Update … Update, Final process

when the SHA hash is to be performed over multiple datasets. If a complete

dataset is available, the recommend call is sgx_sha256_msg to perform the

hash in a single call.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 169 -

sgx_status_t sgx_sha256_init(

sgx_sha_state_handle_t* p_sha_handle

);

Parameters

p_sha_handle [out]

This is a handle to the context state used by the cryptography library to per-

form an iterative SHA256 hash. The algorithm stores the intermediate results

of performing the hash calculation over data sets.

Return value

SGX_SUCCESS

The SHA256 state is allocated and initialized properly.

SGX_ERROR_INVALID_PARAMETER

The pointer p_sha_handle is invalid.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The SHA256 state is not initialized properly due to an internal cryptography

library failure.

Description

Calling sgx_sha256_init is the first set in performing a SHA256 hash over

multiple datasets. The caller does not allocate memory for the SHA256 state

that this function returns. The state is specific to the implementation of the

cryptography library; thus the allocation is performed by the library itself. If

the hash over the desired datasets is completed or any error occurs during

the hash calculation process, sgx_sha256_close should be called to free

the state allocated by this algorithm.

Requirements

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 170 -

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_sha256_update

sgx_sha256_update performs a SHA256 hash over the input dataset

provided. This function supports an iterative calculation of the hash over mul-

tiple datasets where the sha_handle contains the intermediate results of the

hash calculation over previous datasets.

Syntax

sgx_status_t sgx_sha256_update(

const uint8_t *p_src,

uint32_t src_len,

sgx_sha_state_handle_t sha_handle

);

Parameters

p_src [in]

A pointer to the input data stream to be hashed. A zero length input buffer is

supported, but the pointer must be non-NULL.

src_len [in]

Specifies the length on the input data stream to be hashed. A zero length

input buffer is supported.

sha_handle [in]

This is a handle to the context state used by the cryptography library to per-

form an iterative SHA256 hash. The algorithm stores the intermediate results

of performing the hash calculation over multiple data sets.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

The input parameter(s) are NULL.

SGX_ERROR_UNEXPECTED

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 171 -

An internal cryptography library failure occurred while performing the

SHA256 hash calculation.

Description

This function should be used as part of a SHA256 calculation over multiple

datasets. If a SHA256 hash is needed over a single data set, function sgx_

sha256_msg should be used instead. Prior to calling this function on the first

dataset, the sgx_sha256_init function must be called first to allocate and ini-

tialize the SHA256 state structure which will hold intermediate hash results

over earlier datasets. The function sgx_sha256_get_hash should be used

to obtain the hash after the final dataset has been processed by this function.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_sha256_get_hash

sgx_sha256_get_hash obtains the SHA256 hash after the final dataset has

been processed (by calls to sgx_sha256_update).

Syntax

sgx_status_t sgx_sha256_get_hash(

sgx_sha_state_handle_t sha_handle,

sgx_sha256_hash_t* p_hash

);

Parameters

sha_handle [in]

This is a handle to the context state used by the cryptography library to per-

form an iterative SHA256 hash. The algorithm stores the intermediate results

of performing the hash calculation over multiple datasets.

p_hash [out]

This is a pointer to the 256-bit hash that has been calculated. The memory for

the hash should be allocated by the calling code.

Return value

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 172 -

SGX_SUCCESS

The hash is obtained successfully.

SGX_ERROR_INVALID_PARAMETER

The pointers are NULL.

SGX_ERROR_UNEXPECTED

The SHA256 state passed in is likely problematic causing an internal cryp-

tography library failure.

Description

This function returns the hash after performing the SHA256 calculation over

one or more datasets using the sgx_sha256_update function. Memory for

the hash should be allocated by the calling function. The handle to SHA256

state used in the sgx_sha256_update calls must be passed in as input.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_sha256_close

sgx_sha256_close cleans up and deallocates the SHA256 state that was

allocated in function sgx_sha256_init.

Syntax

sgx_status_t sgx_sha256_close(

sgx_sha_state_handle_t sha_handle

);

Parameters

sha_handle [in]

This is a handle to the context state used by the cryptography library to per-

form an iterative SHA256 hash. The algorithm stores the intermediate results

of performing the hash calculation over data sets.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 173 -

Return value

SGX_SUCCESS

The SHA256 state was deallocated successfully.

SGX_ERROR_INVALID_PARAMETER

The input handle is NULL.

Description

Calling sgx_sha256_close is the last step after performing a SHA256 hash

over multiple datasets. The caller uses this function to deallocate memory

used to store the SHA256 calculation state.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_rijndael128GCM_encrypt

sgx_rijndael128GCM_encrypt performs a Rijndael AES-GCM encryption

operation. Only a 128bit key size is supported by this Intel(R) SGX SDK cryp-

tography library.

Syntax

sgx_status_t sgx_rijndael128GCM_encrypt(

const sgx_aes_gcm_128bit_key_t *p_key,

const uint8_t *p_src,

uint32_t src_len,

uint8_t *p_dst,

const uint8_t *p_iv,

uint32_t iv_len,

const uint8_t *p_aad,

uint32_t aad_len,

sgx_aes_gcm_128bit_tag_t *p_out_mac

);

Parameters

p_key [in]

A pointer to key to be used in the AES-GCM encryption operation. The size

must be 128 bits.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 174 -

p_src [in]

A pointer to the input data stream to be encrypted. Buffer could be NULL if

there is AAD text.

src_len [in]

Specifies the length on the input data stream to be encrypted. This could be

zero but p_src and p_dst should be NULL and aad_len must be greater

than zero.

p_dst [out]

A pointer to the output encrypted data buffer. This buffer should be allocated

by the calling code.

p_iv [in]

A pointer to the initialization vector to be used in the AES-GCM calculation.

NIST AES-GCM recommended IV size is 96 bits (12 bytes).

iv_len [in]

Specifies the length on input initialization vector. The length should be 12 as

recommended by NIST.

p_aad [in]

A pointer to an optional additional authentication data buffer which is used in

the GCM MAC calculation. The data in this buffer will not be encrypted. The

field is optional and could be NULL.

aad_len [in]

Specifies the length of the additional authentication data buffer. This buffer is

optional and thus the size can be zero.

p_out_mac [out]

This is the output GCM MAC performed over the input data buffer (data to be

encrypted) as well as the additional authentication data (this is optional data).

The calling code should allocate this buffer.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

If key, MAC, or IV pointer is NULL.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 175 -

If AAD size is > 0 and the AAD pointer is NULL.

If source size is > 0 and the source pointer or destination pointer are NULL.

If both source pointer and AAD pointer are NULL.

If IV Length is not equal to 12 (bytes).

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

An internal cryptography library failure occurred.

Description

The Galois/Counter Mode (GCM) is a mode of operation of the AES algorithm.

GCM [NIST SP 800-38D] uses a variation of the counter mode of operation for

encryption. GCM assures authenticity of the confidential data (of up to about

64 GB per invocation) using a universal hash function defined over a binary

finite field (the Galois field).

GCM can also provide authentication assurance for additional data (of prac-

tically unlimited length per invocation) that is not encrypted. GCM provides

stronger authentication assurance than a (non-cryptographic) checksum or

error detecting code. In particular, GCM can detect both accidental modi-

fications of the data and intentional, unauthorized modifications.

It is recommended that the source and destination data buffers are allocated

within the enclave. The AAD buffer could be allocated within or outside

enclave memory. The use of AAD data buffer could be information identifying

the encrypted data since it will remain in clear text.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_rijndael128GCM_decrypt

sgx_rijndael128GCM_decrypt performs a Rijndael AES-GCM decryption

operation. Only a 128bit key size is supported by this Intel(R) SGX SDK cryp-

tography library.

Syntax

sgx_status_t sgx_rijndael128GCM_decrypt(

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 176 -

const sgx_aes_gcm_128bit_key_t *p_key,

const uint8_t *p_src,

uint32_t src_len,

uint8_t *p_dst,

const uint8_t *p_iv,

uint32_t iv_len,

const uint8_t *p_aad,

uint32_t aad_len,

const sgx_aes_gcm_128bit_tag_t *p_in_mac

);

Parameters

p_key [in]

A pointer to key to be used in the AES-GCM decryption operation. The size

must be 128 bits.

p_src [in]

A pointer to the input data stream to be decrypted. Buffer could be NULL if

there is AAD text.

src_len [in]

Specifies the length on the input data stream to be decrypted. This could be

zero but p_src and p_dst should be NULL and aad_len must be greater

than zero.

p_dst [out]

A pointer to the output decrypted data buffer. This buffer should be allocated

by the calling code.

p_iv [in]

A pointer to the initialization vector to be used in the AES-GCM calculation.

NIST AES-GCM recommended IV size is 96 bits (12 bytes).

iv_len [in]

Specifies the length on input initialization vector. The length should be 12 as

recommended by NIST.

p_aad [in]

A pointer to an optional additional authentication data buffer which is

provided for the GCM MAC calculation when encrypting. The data in this buf-

fer was not encrypted. The field is optional and could be NULL.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 177 -

aad_len [in]

Specifies the length of the additional authentication data buffer. This buffer is

optional and thus the size can be zero.

p_in_mac [in]

This is the GCM MAC that was performed over the input data buffer (data to

be encrypted) as well as the additional authentication data (this is optional

data) during the encryption process (call to sgx_rijndael128GCM_

encrypt).

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

If key, MAC, or IV pointer is NULL.

If AAD size is > 0 and the AAD pointer is NULL.

If source size is > 0 and the source pointer or destination pointer are NULL.

If both source pointer and AAD pointer are NULL.

If IV Length is not equal to 12 (bytes).

SGX_ERROR_MAC_MISMATCH

The input MAC does not match the MAC calculated.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

An internal cryptography library failure occurred.

Description

The Galois/Counter Mode (GCM) is a mode of operation of the AES algorithm.

GCM [NIST SP 800-38D] uses a variation of the counter mode of operation for

encryption. GCM assures authenticity of the confidential data (of up to about

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 178 -

64 GB per invocation) using a universal hash function defined over a binary

finite field (the Galois field).

GCM can also provide authentication assurance for additional data (of prac-

tically unlimited length per invocation) that is not encrypted. GCM provides

stronger authentication assurance than a (non-cryptographic) checksum or

error detecting code. In particular, GCM can detect both accidental modi-

fications of the data and intentional, unauthorized modifications.

It is recommended that the destination data buffer is allocated within the

enclave. The AAD buffer could be allocated within or outside enclave memory.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_rijndael128_cmac_msg

The sgx_rijndael128_cmac_msg function performs a standard 128bit

CMAC hash over the input data buffer.

Syntax

sgx_status_t sgx_rijndael128_cmac_msg(

const sgx_cmac_128bit_key_t *p_key,

const uint8_t *p_src,

uint32_t src_len,

sgx_cmac_128bit_tag_t *p_mac

);

Parameters

p_key [in]

A pointer to key to be used in the CMAC hash operation. The size must be 128

bits.

p_src [in]

A pointer to the input data stream to be hashed. A zero length input buffer is

supported, but the pointer must be non-NULL.

src_len [in]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 179 -

Specifies the length on the input data stream to be hashed. A zero length

input buffer is supported.

p_mac [out]

A pointer to the output 128-bit hash resulting from the CMAC calculation. This

pointer must be non-NULL and the caller allocates memory for this buffer.

Return value

SGX_SUCCESS

The CMAC hash function is performed successfully.

SGX_ERROR_INVALID_PARAMETER

The key, source or MAC pointer is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

An unexpected internal cryptography library.

Description

The sgx_rijndael128_cmac_msg function performs a standard CMAC

hash over the input data buffer. Only a 128-bit version of the CMAC hash is

supported.

The function should be used if the complete input data stream is available.

Otherwise, the Init, Update… Update, Final procedure should be used to com-

pute a CMAC hash over multiple input data sets.

A zero-length input data buffer is supported, but the pointer must be non-

NULL.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 180 -

sgx_cmac128_init

sgx_cmac128_init returns an allocated and initialized CMAC algorithm con-

text state. This should be part of the Init, Update … Update, Final process

when the CMAC hash is to be performed over multiple datasets. If a complete

dataset is available, the recommended call is sgx_rijndael128_cmac_

msg to perform the hash in a single call.

Syntax

sgx_status_t sgx_cmac128_init(

const sgx_cmac_128bit_key_t *p_key,

sgx_cmac_state_handle_t* p_cmac_handle

);

Parameters

p_key [in]

A pointer to key to be used in the CMAC hash operation. The size must be 128

bits.

p_cmac_handle [out]

This is a handle to the context state used by the cryptography library to per-

form an iterative CMAC 128-bit hash. The algorithm stores the intermediate

results of performing the hash calculation over data sets.

Return value

SGX_SUCCESS

The CMAC hash state is successfully allocated and initialized.

SGX_ERROR_INVALID_PARAMETER

The key or handle pointer is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

An internal cryptography library failure occurred.

Description

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 181 -

Calling sgx_cmac128_init is the first set in performing a CMAC 128-bit

hash over multiple datasets. The caller does not allocate memory for the

CMAC state that this function returns. The state is specific to the imple-

mentation of the cryptography library and thus the allocation is performed by

the library itself. If the hash over the desired datasets is completed or any

error occurs during the hash calculation process, sgx_cmac128_close should

be called to free the state allocated by this algorithm.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_cmac128_update

sgx_cmac128_update performs a CMAC 128-bit hash over the input data-

set provided. This function supports an iterative calculation of the hash over

multiple datasets where the cmac_handle contains the intermediate results of

the hash calculation over previous datasets.

Syntax

sgx_status_t sgx_cmac128_update(

const uint8_t *p_src,

uint32_t src_len,

sgx_cmac_state_handle_t cmac_handle

);

Parameters

p_src [in]

A pointer to the input data stream to be hashed. A zero length input buffer is

supported, but the pointer must be non-NULL.

src_len [in]

Specifies the length on the input data stream to be hashed. A zero length

input buffer is supported.

cmac_handle [in]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 182 -

This is a handle to the context state used by the cryptography library to per-

form an iterative CMAC hash. The algorithm stores the intermediate results of

performing the hash calculation over multiple data sets.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

The source pointer or cmac handle is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

An internal cryptography library failure occurred while performing the CMAC

hash calculation.

NOTE:

If an unexpected error occurs, then the CMAC state is not freed (CMAC

handle). In this case, call sgx_cmac128_close to free the CMAC state to

avoid memory leak.

Description

This function should be used as part of a CMAC 128-bit hash calculation over

multiple datasets. If a CMAC hash is needed over a single data set, function

sgx_rijndael128_cmac128_msg should be used instead. Prior to calling

this function on the first dataset, the sgx_cmac128_init function must be

called first to allocate and initialize the CMAC state structure which will hold

intermediate hash results over earlier datasets. The function sgx_cmac128_

final should be used to obtain the hash after the final dataset has been pro-

cessed by this function.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 183 -

sgx_cmac128_final

sgx_cmac128_final obtains the CMAC 128-bit hash after the final dataset

has been processed (by calls to sgx_cmac128_update).

Syntax

sgx_status_t sgx_cmac128_final(

sgx_cmac_state_handle_t cmac_handle,

sgx_cmac_128bit_tag_t* p_hash

);

Parameters

cmac_handle [in]

This is a handle to the context state used by the cryptography library to per-

form an iterative CMAC hash. The algorithm stores the intermediate results of

performing the hash calculation over multiple data sets.

p_hash [out]

This is a pointer to the 128-bit hash that has been calculated. The memory for

the hash should be allocated by the calling code.

Return value

SGX_SUCCESS

The hash is obtained successfully.

SGX_ERROR_INVALID_PARAMETER

The hash pointer or CMAC handle is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The CMAC state passed in is likely problematic causing an internal cryp-

tography library failure.

NOTE:

If an unexpected error occurs, then the CMAC state is freed (CMAC handle). In

this case, please call sgx_cmac128_close to free the CMAC state to avoid

memory leak.

Description

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 184 -

This function returns the hash after performing the CMAC 128-bit hash cal-

culation over one or more datasets using the sgx_cmac128_update func-

tion. Memory for the hash should be allocated by the calling code. The handle

to CMACstate used in the sgx_cmac128_update calls must be passed in

as input.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_cmac128_close

sgx_cmac128_close cleans up and deallocates the CMAC algorithm con-

text state that was allocated in function sgx_cmac128_init.

Syntax

sgx_status_t sgx_cmac128_close(

sgx_cmac_state_handle_t cmac_handle

);

Parameters

cmac_handle [in]

This is a handle to the context state used by the cryptography library to per-

form an iterative CMAC hash. The algorithm stores the intermediate results of

performing the hash calculation over multiple data sets.

Return value

SGX_SUCCESS

The CMAC state was deallocated successfully.

SGX_ERROR_INVALID_PARAMETER

The CMAC handle is NULL.

Description

Calling sgx_cmac128_close is the last step after performing a CMAC hash

over multiple datasets. The caller uses this function to deallocate memory

used for storing the CMAC algorithm context state.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 185 -

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_aes_ctr_encrypt

sgx_aes_ctr_encrypt performs a Rijndael AES-CTR encryption operation

(counter mode). Only a 128bit key size is supported by this Intel(R) SGX SDK

cryptography library.

Syntax

sgx_status_t sgx_aes_ctr_encrypt(

const sgx_aes_ctr_128bit_key_t *p_key,

const uint8_t *p_src,

const uint32_t src_len,

uint8_t *p_ctr,

const uint32_t ctr_inc_bits,

uint8_t *p_dst,

);

Parameters

p_key [in]

A pointer to key to be used in the AES-CTR encryption operation. The size

must be 128 bits.

p_src [in]

A pointer to the input data stream to be encrypted.

src_len [in]

Specifies the length on the input data stream to be encrypted.

p_ctr [in]

A pointer to the initialization vector to be used in the AES-CTR calculation.

ctr_inc_bits [in]

Specifies the number of bits in the counter to be incremented.

p_dst [out]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 186 -

A pointer to the output encrypted data buffer. This buffer should be allocated

by the calling code.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

If key, source, destination, or counter pointer is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

An internal cryptography library failure occurred.

Description

This function encrypts the input data stream of a variable length according to

the CTR mode as specified in [NIST SP 800-38A]. The counter can be thought

of as an IV which increments on successive encryption or decryption calls. For

a given dataset or data stream, the incremented counter block should be used

on successive calls of the encryption process for that given stream. However,

for new or different datasets/streams, the same counter should not be reused,

instead initialize the counter for the new data set.

It is recommended that the source, destination and counter data buffers are

allocated within the enclave.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_aes_ctr_decrypt

sgx_aes_ctr_decrypt performs a Rijndael AES-CTR decryption operation

(counter mode). Only a 128bit key size is supported by this Intel(R) SGX SDK

cryptography library.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 187 -

sgx_status_t sgx_aes_ctr_decrypt(

const sgx_aes_gcm_128bit_key_t *p_key,

const uint8_t *p_src,

const uint32_t src_len,

uint8_t *p_ctr,

const uint32_t ctr_inc_bits,

uint8_t *p_dst

);

Parameters

p_key [in]

A pointer to key to be used in the AES-CTR decryption operation. The size

must be 128 bits.

p_src [in]

A pointer to the input data stream to be decrypted.

src_len [in]

Specifies the length of the input data stream to be decrypted.

p_ctr [in]

A pointer to the initialization vector to be used in the AES-CTR calculation.

ctr_inc_bits [in]

Specifies the number of bits in the counter to be incremented.

p_dst [out]

A pointer to the output decrypted data buffer. This buffer should be allocated

by the calling code.

Return value

SGX_SUCCESS

All the outputs are generated successfully.

SGX_ERROR_INVALID_PARAMETER

If key, source, destination, or counter pointer is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 188 -

An internal cryptography library failure occurred.

Description

This function decrypts the input data stream of a variable length according to

the CTR mode as specified in [NIST SP 800-38A]. The counter can be thought

of as an IV which increments on successive encryption or decryption calls. For

a given dataset or data stream, the incremented counter block should be used

on successive calls of the decryption process for that given stream. However,

for new or different datasets/streams, the same counter should not be reused,

instead initialize the counter for the new data set.

It is recommended that the source, destination and counter data buffers are

allocated within the enclave.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_ecc256_open_context

sgx_ecc256_open_context returns an allocated and initialized context

for the elliptic curve cryptosystem over a prime finite field, GF(p). This context

must be created prior to calling sgx_ecc256_create_key_pair or sgx_

ecc256_compute_shared_dhkey. When the calling code has completed

its set of ECC operations, sgx_ecc256_close_context should be called to

cleanup and deallocate the ECC context.

NOTE:

Only a field element size of 256 bits is supported.

Syntax

sgx_status_t sgx_ecc256_open_context(

sgx_ecc_state_handle_t *p_ecc_handle

);

Parameters

p_ecc_handle [out]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 189 -

This is a handle to the ECC GF(p) context state allocated and initialized used

to perform elliptic curve cryptosystem standard functions. The algorithm

stores the intermediate results of calculations performed using this context.

NOTE:

The ECC set of APIs only support a 256-bit GF(p) cryptography system.

Return value

SGX_SUCCESS

The ECC256 GF(p) state is allocated and initialized properly.

SGX_ERROR_INVALID_PARAMETER

The ECC context handle is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The ECC context state was not initialized properly due to an internal cryp-

tography library failure.

Description

sgx_ecc256_open_context is utilized to allocate and initialize a 256-bit

GF(p) cryptographic system. The caller does not allocate memory for the ECC

state that this function returns. The state is specific to the implementation of

the cryptography library and thus the allocation is performed by the library

itself. If the ECC cryptographic function using this cryptographic system is com-

pleted or any error occurs, sgx_sha256_close_context should be called

to free the state allocated by this algorithm.

Public key cryptography successfully allows to solving problems of information

safety by enabling trusted communication over insecure channels. Although

elliptic curves are well studied as a branch of mathematics, an interest to the

cryptographic schemes based on elliptic curves is constantly rising due to the

advantages that the elliptic curve algorithms provide in the wireless com-

munications: shorter processing time and key length.

Elliptic curve cryptosystems (ECCs) implement a different way of creating pub-

lic keys. As elliptic curve calculation is based on the addition of the rational

points in the (x,y) plane and it is difficult to solve a discrete logarithm from

these points, a higher level of safety is achieved through the cryptographic

schemes that use the elliptic curves. The cryptographic systems that encrypt

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 190 -

messages by using the properties of elliptic curves are hard to attack due to

the extreme complexity of deciphering the private key.

Using of elliptic curves allows shorter public key length and encourages cryp-

tographers to create cryptosystems with the same or higher encryption

strength as the RSA or DSA cryptosystems. Because of the relatively short key

length, ECCs do encryption and decryption faster on the hardware that

requires less computation processing volumes.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_ecc256_close_context

sgx_ecc256_close_context cleans up and deallocates the ECC 256 GF

(p) state that was allocated in function sgx_ecc256_open_context.

NOTE:

Only a field element size of 256 bits is supported.

Syntax

sgx_status_t sgx_ecc256_close_context(

sgx_ecc_state_handle_t ecc_handle

);

Parameters

ecc_handle [in]

This is a handle to the ECC GF(p) context state allocated and initialized used

to perform elliptic curve cryptosystem standard functions. The algorithm

stores the intermediate results of calculations performed using this context.

NOTE:

The ECC set of APIs only support a 256-bit GF(p) cryptography system.

Return value

SGX_SUCCESS

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 191 -

The ECC 256 GF(p) state was deallocated successfully.

SGX_ERROR_INVALID_PARAMETER

The input handle is NULL.

Description

sgx_ecc256_close_context is used by calling code to deallocate

memory used for storing the ECC 256 GF(p) state used in ECC cryptographic

calculations.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_ecc256_create_key_pair

sgx_ecc256_create_key_pair generates a private/public key pair on

the ECC curve for the given cryptographic system. The calling code is respons-

ible for allocating memory for the public and private keys. sgx_ecc256_

open_context must be called to allocate and initialize the ECC context prior

to making this call.

Syntax

sgx_status_t sgx_ecc256_create_key_pair(

sgx_ec256_private_t *p_private,

sgx_ec256_public_t *p_public,

sgx_ecc_state_handle_t ecc_handle

);

Parameters

p_private [out]

A pointer to the private key which is a number that lies in the range of [1, n-1]

where n is the order of the elliptic curve base point.

NOTE:

Value is LITTLE ENDIAN.

p_public [out]

A pointer to the public key which is an elliptic curve point such that:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 192 -

public key = private key * G, where G is the base point of the elliptic curve.

NOTE:

Value is LITTLE ENDIAN.

ecc_handle [in]

This is a handle to the ECC GF(p) context state allocated and initialized used

to perform elliptic curve cryptosystem standard functions. The algorithm

stores the intermediate results of calculations performed using this context.

NOTE:

The ECC set of APIs only support a 256-bit GF(p) cryptography system.

Return value

SGX_SUCCESS

The public/private key pair was successfully generated.

SGX_ERROR_INVALID_PARAMETER

The ECC context handle, private key or public key is invalid.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The key creation process failed due to an internal cryptography library failure.

Description

This function populates private/public key pair. The calling code allocates

memory for the private and public key pointers to be populated. The function

generates a private key p_private and computes a public key p_public of

the elliptic cryptosystem over a finite field GF(p).

The private key p_private is a number that lies in the range of [1, n-1]

where n is the order of the elliptic curve base point.

The public key p_public is an elliptic curve point such that p_public =

p_private *G, where G is the base point of the elliptic curve.

The context of the point p_public as an elliptic curve point must be created

by using the function sgx_ecc256_open_context.

Requirements

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 193 -

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_ecc256_compute_shared_dhkey

sgx_ecc256_compute_shared_dhkey generates a secret key shared

between two participants of the cryptosystem. The calling code should alloc-

ate memory for the shared key to be generated by this function.

Syntax

sgx_status_t sgx_ecc256_compute_shared_dhkey(

sgx_ec256_private_t *p_private_b,

sgx_ec256_public_t *p_public_ga,

sgx_ec256_dh_shared_t *p_shared_key,

sgx_ecc_state_handle_t ecc_handle

);

Parameters

p_private_b [in]

A pointer to the local private key.

NOTE:

Value is LITTLE ENDIAN.

p_public_ga [in]

A pointer to the remote public key.

NOTE:

Value is LITTLE ENDIAN.

p_shared_key [out]

A pointer to the secret key generated by this function which is a common

point on the elliptic curve.

NOTE:

Value is LITTLE ENDIAN.

ecc_handle [in]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 194 -

This is a handle to the ECC GF(p) context state allocated and initialized used

to perform elliptic curve cryptosystem standard functions. The algorithm

stores the intermediate results of calculations performed using this context.

NOTE:

The ECC set of APIs only support a 256-bit GF(p) cryptography system.

Return value

SGX_SUCCESS

The public/private key pair was successfully generated.

SGX_ERROR_INVALID_PARAMETER

The ECC context handle, private key, public key, or shared key pointer is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The key creation process failed due to an internal cryptography library failure.

Description

This function computes the Diffie-Hellman shared key based on the enclave’s

own (local) private key and remote enclave’s public Ga Key. The calling code

allocates memory for shared key to be populated by this function.

The function computes a secret number sharedKey, which is a secret key

shared between two participants of the cryptosystem.

In cryptography, metasyntactic names such as Alice as Bob are normally used

as examples and in discussions and stand for participant A and participant B.

Both participants (Alice and Bob) use the cryptosystem for receiving a com-

mon secret point on the elliptic curve called a secret key (sharedKey). To

receive a secret key, participants apply the Diffie-Hellman key-agreement

scheme involving public key exchange. The value of the secret key entirely

depends on participants.

According to the scheme, Alice and Bob perform the following operations:

1. Alice calculates her own public key pubKeyA by using her private key

privKeyA: pubKeyA = privKeyA * G, where G is the base point of the

elliptic curve.

2. Alice passes the public key to Bob.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 195 -

3. Bob calculates his own public key pubKeyB by using his private key

privKeyB: pubKeyB = privKeyB * G, where G is a base point of the elliptic

curve.

4. Bob passes the public key to Alice.

5. Alice gets Bob's public key and calculates the secret point shareKeyA. When

calculating, she uses her own private key and Bob's public key and applies the

following formula:

shareKeyA = privKeyA * pubKeyB = privKeyA * privKeyB *

6. Bob gets Alice's public key and calculates the secret point shareKeyB. When

calculating, he uses his own private key and Alice's public key and applies the

following formula:

shareKeyB = privKeyB * pubKeyA = privKeyB * privKeyA *

As the following equation is true privKeyA * privKeyB * G =

privKeyB * privKeyA * G, the result of both calculations is the same,

that is, the equation shareKeyA = shareKeyB is true. The secret point serves as

a secret key.

Shared secret shareKey is an x-coordinate of the secret point on the elliptic

curve. The elliptic curve domain parameters must be hitherto defined by the

function: sgx_ecc256_open_context.

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_ecc256_check_point

sgx_ecc256_check_point checks whether the input point is a valid point

on the ECC curve for the given cryptographic system. sgx_ecc256_open_

context must be called to allocate and initialize the ECC context prior to

making this call.

Syntax

sgx_status_t sgx_ecc256_check_point(

const sgx_ec256_public_t *p_point,

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 196 -

const sgx_ecc_state_handle_t ecc_handle,

int *p_valid

);

Parameters

p_point [in]

A pointer to the point to perform validity check on.

NOTE:

Value is LITTLE ENDIAN.

ecc_handle [in]

This is a handle to the ECC GF(p) context state allocated and initialized used

to perform elliptic curve cryptosystem standard functions. The algorithm

stores the intermediate results of calculations performed using this context.

NOTE:

The ECC set of APIs only support a 256-bit GF(p) cryptography system.

p_valid [out]

A pointer to the validation result.

Return value

SGX_SUCCESS

The validation process is performed successfully. Check p_valid to get the val-

idation result.

SGX_ERROR_INVALID_PARAMETER

If the input ecc handle, p_point or p_valid is NULL.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

An internal cryptography library failure occurred.

Description

sgx_ecc256_check_point validates whether the input point is a valid

point on the ECC curve for the given cryptographic system.

The typical validation result is one of the two values:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 197 -

1 - The input point is valid

0 – The input point is not valid

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_ecdsa_sign

sgx_ecdsa_sign computes a digital signature with a given private key over

an input dataset.

Syntax

sgx_status_t sgx_ecdsa_sign(

const uint8_t *p_data,

uint32_t data_size,

sgx_ec256_private_t *p_private,

sgx_ec256_signature_t *p_signature,

sgx_ecc_state_handle_t ecc_handle

);

Parameters

p_data [in]

A pointer to the data to calculate the signature over.

data_size [in]

The size of the data to be signed.

p_private [in]

A pointer to the signature generated by this function.

NOTE:

Value is LITTLE ENDIAN.

p_signature [out]

A pointer to the signature generated by this function.

NOTE:

Value is LITTLE ENDIAN.

ecc_handle [in]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 198 -

This is a handle to the ECC GF(p) context state allocated and initialized used

to perform elliptic curve cryptosystem standard functions. The algorithm

stores the intermediate results of calculations performed using this context.

NOTE:

The ECC set of APIs only support a 256-bit GF(p) cryptography system.

Return value

SGX_SUCCESS

The digital signature is successfully generated.

SGX_ERROR_INVALID_PARAMETER

The ECC context handle, private key, data, or signature pointer is NULL. If the

data size is 0.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The signature generation process failed due to an internal cryptography lib-

rary failure.

Description

This function computes a digital signature over the input dataset based on the

input private key.

A message digest is a fixed size number derived from the original message

with an applied hash function over the binary code of the message. (SHA256

in this case)

The signer's private key and the message digest are used to create a sig-

nature.

A digital signature over a message consists of a pair of large numbers, 256-bits

each, which the given function computes.

The scheme used for computing a digital signature is of the ECDSA scheme, an

elliptic curve of the DSA scheme.

The keys can be generated and set up by the function: sgx_ecc256_cre-

ate_key_pair.

The elliptic curve domain parameters must be created by function: sgx_

ecc256_open_context.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 199 -

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_ecdsa_verify

sgx_ecdsa_verify verifies the input digital signature with a given public

key over an input dataset.

Syntax

sgx_status_t sgx_ecdsa_verify(

const uint8_t *p_data,

uint32_t data_size,

const sgx_ec256_public_t *p_public,

sgx_ec256_signature_t *p_signature,

uint8_t *p_result,

sgx_ecc_state_handle_t ecc_handle

);

Parameters

p_data [in]

A pointer to the signed dataset to verify.

data_size [in]

The size of the dataset to have its signature verified.

p_public [in]

A pointer to the public key to be used in the calculation of the signature.

NOTE:

Value is LITTLE ENDIAN.

p_signature [in]

A pointer to the signature to be verified.

NOTE:

Value is LITTLE ENDIAN.

p_result [out]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 200 -

A pointer to the result of the verification check populated by this function.

ecc_handle [in]

This is a handle to the ECC GF(p) context state allocated and initialized used

to perform elliptic curve cryptosystem standard functions. The algorithm

stores the intermediate results of calculations performed using this context.

NOTE:

The ECC set of APIs only support a 256-bit GF(p) cryptography system.

Return value

SGX_SUCCESS

The digital signature verification was performed successfully. Check p_result

to get the verification result.

SGX_ERROR_INVALID_PARAMETER

The ECC context handle, public key, data, result or signature pointer is NULL or

the data size is 0.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_UNEXPECTED

The verification process failed due to an internal cryptography library failure.

Description

This function verifies the signature for the given data set based on the input

public key.

A digital signature over a message consists of a pair of large numbers, 256-bits

each, which could be created by function: sgx_ecdsa_sign. The scheme

used for computing a digital signature is of the ECDSA scheme, an elliptic

curve of the DSA scheme.

The typical result of the digital signature verification is one of the two values:

SGX_ECValid - Digital signature is valid

SGX_ECInvalidSignature - Digital signature is not valid

The elliptic curve domain parameters must be created by function: sgx_

ecc256_open_context.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 201 -

Requirements

Header

sgx_tcrypto.h

Library

libsgx_tcrypto.a

libsgx_tcrypto_opt.a

sgx_create_pse_session

sgx_create_pse_session creates a session with the PSE.

Syntax

sgx_status_t sgx_create_pse_session(

void

);

Return value

SGX_SUCCESS

Session is created successfully.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UPDATE_NEEDED

Intel(R) SGX needs to be updated.

SGX_ERROR_KDF_MISMATCH

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 202 -

Indicates the key derivation function does not match.

SGX_ERROR_UNRECOGNIZED_PLATFORM

Intel(R) EPID Provisioning failed because the platform was not recognized by

the back-end server.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurred.

Description

An Intel(R) SGX enclave first calls sgx_create_pse_session()in the pro-

cess to request platform service.

It's suggested that the caller should wait (typically several seconds to tens of

seconds) and retry this API if SGX_ERROR_BUSY is returned.

Requirements

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_close_pse_session

sgx_close_pse_session closes a session created by sgx_create_pse_

session.

Syntax

sgx_status_t sgx_close_pse_session(

void

);

Return value

SGX_SUCCESS

Session is closed successfully.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 203 -

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

Description

An Intel(R) SGX enclave calls sgx_close_pse_session() when there is no

need to request platform service.

Requirements

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_get_ps_sec_prop

sgx_get_ps_sec_prop gets a data structure describing the security prop-

erty of the platform service.

Syntax

sgx_status_t sgx_get_ps_sec_prop (

sgx_ps_sec_prop_desc_t* security_property

);

Parameters

security_property [out]

A pointer to the buffer that receives the security property descriptor of the

platform service. The pointer cannot be NULL.

Return value

SGX_SUCCESS

Security property is returned successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

Description

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 204 -

Gets a data structure that describes the security property of the platform ser-

vice.

The caller should call sgx_create_pse_session to establish a session

with the platform service enclave before calling this API.

Requirements

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_get_ps_sec_prop_ex

sgx_get_ps_sec_prop_ex gets a data structure describing the security

property of the platform service with extended platform service information.

Syntax

sgx_status_t sgx_get_ps_sec_prop_ex (

sgx_ps_sec_prop_desc_ex_t* security_property

);

Parameters

security_property [out]

A pointer to the buffer that receives the security property descriptor of the

platform service and platform service information. The pointer cannot be

NULL.

Return value

SGX_SUCCESS

Security property is returned successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

Description

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 205 -

Gets a data structure that describes the security property of the platform ser-

vice.

The caller should call sgx_create_pse_session to establish a session

with the platform service enclave before calling this API.

Requirements

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_get_trusted_time

sgx_get_trusted_time gets trusted time from the AE service.

Syntax

sgx_status_t sgx_get_trusted_time(

sgx_time_t* current_time,

sgx_time_source_nonce_t* time_source_nonce

);

Parameters

current_time [out]

Trusted Time Stamp in seconds relative to a reference point. The reference

point does not change as long as the time_source_nonce has not changed.

The pointer cannot be NULL.

time_source_nonce [out]

A pointer to the buffer that receives the nonce which indicates time source.

The pointer cannot be NULL.

Return value

SGX_SUCCESS

Trusted time is obtained successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 206 -

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

Description

current_time contains time in seconds and time_source_nonce con-

tains nonce associate with the time. The caller should compare time_

source_nonce against the value returned from the previous call of this API if

it needs to calculate the time passed between two readings of the Trusted

Timer. If the time_source_nonce of the two readings do not match, the dif-

ference between the two readings does not necessarily reflect time passed.

The caller should call sgx_create_pse_session to establish a session

with the platform service enclave before calling this API.

Requirements

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_create_monotonic_counter_ex

sgx_create_monotonic_counter_ex creates a monotonic counter.

Syntax

sgx_status_t sgx_create_monotonic_counter_ex(

uint16_t owner_policy,

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 207 -

const sgx_attributes_t * owner_attribute_mask,

sgx_mc_uuid_t * counter_uuid,

uint32_t * counter_value

);

Parameters

owner_policy [in]

The owner policy of the monotonic counter.

l 0x1 means enclaves with same signing key can access the monotonic

counter

l 0x2 means enclave with same measurement can access the monotonic

counter

l 0x3 means enclave with same measurement as well as signing key can

access the monotonic counter.

l Owner policy values of 0x0 or any bits set beyond bits 0 and 1 will cause

SGX_ERROR_INVALID_PARAMETER

owner_attribute_mask [in]

Mask of owner attribute, in the format of sgx_attributes_t.

counter_uuid [out]

A pointer to the buffer that receives the monotonic counter ID. The pointer

cannot be NULL.

counter_value [out]

A pointer to the buffer that receives the monotonic counter value. The pointer

cannot be NULL.

Return value

SGX_SUCCESS

Monotonic counter is created successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the parameters is invalid.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_MC_OVER_QUOTA

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 208 -

The enclave has reached the quota of Monotonic Counters it can maintain.

SGX_ERROR_MC_USED_UP

Monotonic counters are used out.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by the architectural enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

Description

Call sgx_create_monotonic_counter_ex to create a monotonic counter

with the given owner_policy and owner_attribute_mask.

The caller should call sgx_create_pse_session to establish a session

with the platform service enclave before calling this API.

Creating a monotonic counter (MC) involves writing to the non-volatile

memory available in the platform. Repeated writeoperations could cause the

memory to wear out during the normal lifecycle of the platform. Intel(R) SGX

prevents this by limiting the rate at which MC operations can be performed. If

you exceed the limit, the MC operation may return SGX_ERROR_BUSY for sev-

eral minutes.

Intel(R) SGX limits the number of monotonic counters (MC) an enclave can cre-

ate. To avoid exhausting the available quota, an Intel SGX application should

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 209 -

record the MC UUID that sgx_create_monotonic_counter_ex returns

and destroy a MC when it is not needed any more. If an enclave reaches its

quota and previously created MC UUIDs have not been recorded, you may

restore the MC service after uninstalling the Intel(R) SGX PSW and installing it

again. This procedure deletes all MCs created by any enclave in that system.

NOTE

One application is not able to access the monotonic counter created by

another application in simulation mode. This also affects two different applic-

ations using the same enclave.

Requirements

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_create_monotonic_counter

sgx_create_monotonic_counter creates a monotonic counter with

default owner policy and default user attribute mask.

Syntax

sgx_status_t sgx_create_monotonic_counter(

sgx_mc_uuid_t * counter_uuid,

uint32_t * counter_value

);

Parameters

counter_uuid [out]

A pointer to the buffer that receives the monotonic counter ID. The pointer

cannot be NULL.

counter_value [out]

A pointer to the buffer that receives the monotonic counter value. The pointer

cannot be NULL.

Return value

SGX_SUCCESS

Monotonic counter is created successfully.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 210 -

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_MC_OVER_QUOTA

The enclave has reached the quota of Monotonic Counters it can maintain.

SGX_ERROR_MC_USED_UP

Monotonic counters are used out.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

Description

Call sgx_create_monotonic_counter to create a monotonic counter

with the default owner policy 0x1, which means enclaves with same signing

key can access the monotonic counter and default owner_attribute_mask

0xFFFFFFFFFFFFFFCB.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 211 -

The caller should call sgx_create_pse_session to establish a session

with the platform service enclave before calling this API.

Creating a monotonic counter (MC) involves writing to the non-volatile

memory available in the platform. Repeated writeoperations could cause the

memory to wear out during the normal lifecycle of the platform. Intel(R) SGX

prevents this by limiting the rate at which MC operations can be performed. If

you exceed the limit, the MC operation may return SGX_ERROR_BUSY for sev-

eral minutes.

Intel(R) SGX limits the number of MCs an enclave can create. To avoid exhaust-

ing the available quota, an Intel SGX application should record the MC UUID

that sgx_create_monotonic_counter returns and destroy a MC when it

is not needed any more. If an enclave reaches its quota and previously created

MC UUIDs have not been recorded, you may restore the MC service after unin-

stalling the Intel(R) SGX PSW and installing it again. This procedure deletes all

MCs created by any enclave in that system.

NOTE

One application is not able to access the monotonic counter created by

another application in simulation mode. This also affects two different applic-

ations using the same enclave.

Requirements

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_destroy_monotonic_counter

sgx_destroy_monotonic_counter destroys a monotonic counter cre-

ated by sgx_create_monotonic_counter or sgx_create_mono-

tonic_counter_ex.

Syntax

sgx_status_t sgx_destroy_monotonic_counter(

const sgx_mc_uuid_t * counter_uuid

);

Parameters

counter_uuid [in]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 212 -

The monotonic counter ID to be destroyed.

Return value

SGX_SUCCESS

Monotonic counter is destroyed successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_MC_NOT_FOUND

The Monotonic Counter does not exist or has been invalidated.

SGX_ERROR_MC_NO_ACCESS_RIGHT

The enclave doesn't have the access right to specified Monotonic Counter.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

Description

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 213 -

Calling sgx_destroy_monotonic_counter after a monotonic counter is

not needed anymore.

The caller should call sgx_create_pse_session to establish a session

with the platform service enclave before calling this API.

sgx_destroy_monotonic_counter fails if the calling enclave does not

match the owner policy and the attributes specified in the call that created

the monotonic counter.

Destroying a Monotonic Counter (MC) involves writing to the non-volatile

memory available in the platform. Repeated writeoperations could cause the

memory to wear out during the normal lifecycle of the platform. Intel(R) SGX

prevents this by limiting the rate at which MC operations can be performed. If

you exceed the limit, the MC operation may return SGX_ERROR_BUSY for sev-

eral minutes.

Requirements

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_increment_monotonic_counter

sgx_increment_monotonic_counter increments a monotonic counter

value by 1.

Syntax

sgx_status_t sgx_increment_monotonic_counter(

const sgx_mc_uuid_t * counter_uuid,

uint32_t * counter_value

);

Parameters

counter_uuid [in]

The Monotonic Counter ID to be incremented.

counter_value [out]

A pointer to the buffer that receives the Monotonic Counter value. The pointer

cannot be NULL.

Return value

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 214 -

SGX_SUCCESS

Monotonic Counter is incremented successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_BUSY

The requested service is temporarily not available.

SGX_ERROR_MC_NOT_FOUND

The Monotonic Counter does not exist or has been invalidated.

SGX_ERROR_MC_NO_ACCESS_RIGHT

The enclave does not have the access right to specified Monotonic Counter.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by architectural enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurs.

Description

Call sgx_increment_monotonic_counter to increase a monotonic

counter value by 1.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 215 -

The caller should call sgx_create_pse_session to establish a session

with the platform service enclave before calling this API.

sgx_increment_monotonic_counter fails if the calling enclave does not

match the owner policy and the attributes specified in the call that created

the monotonic counter.

Incrementing a monotonic counter (MC) involves writing to the non-volatile

memory available in the platform. Repeated writeoperations could cause the

memory to wear out during the normal lifecycle of the platform. Intel(R) SGX

prevents this by limiting the rate at which MC operations can be performed. If

you exceed the limit, the MC operation may return SGX_ERROR_BUSY for sev-

eral minutes.

Requirements

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_read_monotonic_counter

sgx_read_monotonic_counter returns the value of a monotonic counter.

Syntax

sgx_status_t sgx_increment_monotonic_counter(

const sgx_mc_uuid_t * counter_uuid,

uint32_t * counter_value

);

Parameters

counter_uuid [in]

The monotonic counter ID to be read.

counter_value [out]

A pointer to the buffer that receives the monotonic counter value. The pointer

cannot be NULL.

Return value

SGX_SUCCESS

Monotonic counter is read successfully.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 216 -

SGX_ERROR_INVALID_PARAMETER

Any of the pointers is invalid.

SGX_ERROR_MC_NOT_FOUND

the Monotonic Counter does not exist or has been invalidated.

SGX_ERROR_AE_SESSION_INVALID

Session is not created or has been closed by the user or the Architectural

Enclave service.

SGX_ERROR_SERVICE_UNAVAILABLE

The AE service did not respond or the requested service is not supported.

SGX_ERROR_SERVICE_TIMEOUT

A request to the AE service timed out.

SGX_ERROR_NETWORK_FAILURE

Network connecting or proxy setting issue was encountered.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation.

SGX_ERROR_OUT_OF_EPC

There is not enough EPCmemory to load one of the Architecture Enclaves

needed to complete this operation.

SGX_ERROR_UNEXPECTED

Indicates an unexpected error occurred.

Description

Call sgx_read_monotonic_counter to read the value of a monotonic

counter.

The caller should call sgx_create_pse_session to establish a session

with the platform service enclave before calling this API.

sgx_read_monotonic_counter fails if the calling enclave does not match

the owner policy and the attributes specified in the call that created the mono-

tonic counter.

Requirements

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 217 -

Header

sgx_tae_service.h sgx_tae_service.edl

Library libsgx_tservice.a or libsgx_tservice_sim.a (sim-

ulation)

sgx_ra_init

The sgx_ra_init function creates a context for the remote attestation and

key exchange process.

Syntax

sgx_status_t sgx_ra_init(

const sgx_ec256_public_t * p_pub_key,

int b_pse,

sgx_ra_context_t * p_context

);

Parameters

p_pub_key [in] (Little Endian)

The EC public key of the service provider based on the NIST P-256 elliptic

curve.

b_pse [in]

If true, platform service information is needed in message 3. The caller should

make sure a PSE session has been established using sgx_create_pse_ses-

sion before attempting to establish a remote attestation and key exchange

session involving platform service information.

p_context [out]

The output context for the subsequent remote attestation and key exchange

process, to be used in sgx_ra_get_msg1 and sgx_ra_proc_msg2.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates an error that the input parameters are invalid.

SGX_ERROR_OUT_OF_MEMORY

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 218 -

Not enough memory is available to complete this operation, or contexts reach

the limits.

SGX_ERROR_AE_SESSION_INVALID

The session is invalid or ended by the server.

SGX_ERROR_UNEXPECTED

Indicates that an unexpected error occurred.

Description

This is the first API user should call for a key exchange process. The context

returned from this function is used as a handle for other APIs in the key

exchange library.

Requirements

Header

sgx_tkey_exchange.h sgx_tkey_exchange.edl

Library

libsgx_tkey_exchange.a

sgx_ra_init_ex

The sgx_ra_init_ex function creates a context for the remote attestation

and key exchange process while it allows the use of a custom defined Key

Derivation Function (KDF).

Syntax

sgx_status_t sgx_ra_init_ex(

const sgx_ec256_public_t * p_pub_key,

int b_pse,

sgx_ra_derive_secret_keys_t derive_key_cb,

sgx_ra_context_t * p_context

);

Parameters

p_pub_key [in] (Little Endian)

The EC public key of the service provider based on the NIST P-256 elliptic

curve.

b_pse [in]

If true, platform service information is needed in message 3. The caller should

make sure a PSE session has been established using sgx_create_pse_

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 219 -

session before attempting to establish a remote attestation and key

exchange session involving platform service information.

derive_key_cb [in]

This a pointer to a call back routine matching the funtion prototype ofsgx_

ra_derive_secret_keys_t . This function takes the Diffie-Hellman shared

secret as input to allow the ISV enclave to generate their own derived shared

keys (SMK, SK, MK and VK).

p_context [out]

The output context for the subsequent remote attestation and key exchange

process, to be used in sgx_ra_get_msg1 and sgx_ra_proc_msg2.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates an error that the input parameters are invalid.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation, or contexts reach

the limits.

SGX_ERROR_AE_SESSION_INVALID

The session is invalid or ended by the server.

SGX_ERROR_UNEXPECTED

Indicates that an unexpected error occurred.

Description

This is the first API user should call for a key exchange process. The context

returned from this function is used as a handle for other APIs in the key

exchange library.

Requirements

Header

sgx_tkey_exchange.h sgx_tkey_exchange.edl

Library

libsgx_tkey_exchange.a

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 220 -

sgx_ra_get_keys

The sgx_ra_get_keys function is used to get the negotiated keys of a

remote attestation and key exchange session. This function should only be

called after the service provider accepts the remote attestation and key

exchange protocol message 3 produced by sgx_ra_proc_msg2.

Syntax

sgx_status_t sgx_ra_get_keys(

sgx_ra_context_t context,

sgx_ra_key_type_t type,

sgx_ra_key_128_t *p_key

);

Parameters

context [in]

Context returned by sgx_ra_init.

type [in]

The type of the keys, which can be SGX_RA_KEY_MK, SGX_RA_KEY_SK, or

SGX_RA_VK.

If the RAcontext was generated by sgx_ra_init, the returned SGX_RA_

KEY_MK, SGX_RA_KEY_SK or SGX_RA_VK is derived from the Diffie-Hellman

shared secret elliptic curve field element between the service provider and

the application enclave using the following Key Derivation Function (KDF):

KDK = AES-CMAC(key0, gab x-coordinate)

SGX_RA_KEY_VK = AES-CMAC(KDK,

0x01||’VK’||0x00||0x80||0x00)

SGX_RA_KEY_MK = AES-CMAC(KDK,

0x01||’MK’||0x00||0x80||0x00)

SGX_RA_KEY_SK = AES-CMAC(KDK,

0x01||’SK’||0x00||0x80||0x00)

The key0 used in the key extraction operation is 16 bytes of 0x00. The plain

text used in the Key derivation calculation is the Diffie-Hellman shared secret

elliptic curve field element in Little Endian format. The plain text used in each

key calculation includes:

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 221 -

l a counter (0x01)

l a label: the ASCII representation of one of the strings 'VK', 'MK' or 'SK' in

Little Endian format

l a bit length (0x80)

If the RA context was generated by the sgx_ra_init_ex API, the KDF used

to generate SGX_RA_KEY_MK, SGX_RA_KEY_SK and SGX_RA_VK is defined

in the implementation of the call back function provided to the sgx_ra_

init_ex function.

p_key [out]

The key returned.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates an error that the input parameters are invalid.

SGX_ERROR_INVALID_STATE

Indicates this API is invoked in incorrect order, it can be called only after a suc-

cess session has been established. In other words, sgx_ra_proc_msg2

should have been called and no error returned.

Description

After a successful key exchange process, this API can be used in the enclave to

get specific key associated with this remote attestation and key exchange ses-

sion.

Requirements

Header

sgx_tkey_exchange.h sgx_tkey_exchange.edl

Library

libsgx_tkey_exchange.a

sgx_ra_close

Call the sgx_ra_close function to release the remote attestation and key

exchange context after the process is done and the context isn’t needed any-

more.

Syntax

sgx_status_t sgx_ra_close(

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 222 -

sgx_ra_context_t context

);

Parameters

context [in]

Context returned by sgx_ra_init.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates the context is invalid.

Description

At the end of a key exchange process, the caller needs to use this API in an

enclave to clear and free memory associated with this remote attestation ses-

sion.

Requirements

Header

sgx_tkey_exchange.h sgx_key_exchange.edl

Library

libsgx_tkey_exchange.a

sgx_dh_init_session

Initialize DH secure session according to the caller’s role in the establishment.

Syntax

sgx_status_t sgx_dh_init_session(

sgx_dh_session_role_t role,

sgx_dh_session_t * session

);

Parameters

role [in]

Indicates which role the caller plays in the secure session establishment.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 223 -

The value of role of the initiator of the session establishment must be SGX_

DH_SESSION_INITIATOR.

The value of role of the responder of the session establishment must be SGX_

DH_SESSION_RESPONDER.

session [out]

A pointer to the instance of the DH session which contains entire information

about session establishment.

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

Return value

SGX_SUCCESS

Session is initialized successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the input parameters is incorrect.

Requirements

Header

sgx_dh.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_dh_responder_gen_msg1

Generates MSG1 for the responder of DH secure session establishment and

records ECC key pair in session structure.

Syntax

sgx_status_t sgx_dh_responder_gen_msg1(

sgx_dh_msg1_t * msg1,

sgx_dh_session_t * dh_session

);

Parameters

msg1 [out]

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 224 -

A pointer to an sgx_dh_msg1_t msg1 buffer. The buffer holding the msg1

message, which is referenced by this parameter, must be within the enclave.

The DH msg1 contains the responder’s public key and report based target

info.

dh_session [in/out]

A pointer that points to the instance of sgx_dh_session_t. The buffer hold-

ing the DHsession information, which is referenced by this parameter, must

be within the enclave.

NOTE

As output, the DH session structure contains the responder’s public key and

private key for the current session.

Return value

SGX_SUCCESS

MSG1 is generated successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the input parameters is incorrect.

SGX_ERROR_INVALID_STATE

The API is invoked in incorrect order or state.

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

SGX_ERROR_UNEXPECTED

An unexpected error occurred.

Requirements

Header

sgx_dh.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_dh_initiator_proc_msg1

The initiator of DH secure session establishment handles msg1 sent by respon-

der and then generates msg2, and records initiator’s ECC key pair in DH ses-

sion structure.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 225 -

sgx_status_t sgx_dh_initiator_proc_msg1(

const sgx_dh_msg1_t * msg1,

sgx_dh_msg2_t * msg2,

sgx_dh_session_t * dh_session

);

Parameters

msg1 [in]

Point to dh message 1 buffer generated by session responder, and the buffer

must be in enclave address space.

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

msg2 [out]

Point to dh message 2 buffer, and the buffer must be in enclave address

space.

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

dh_session [in/out]

Point to dh session structure that is used during establishment, and the buffer

must be in enclave address space.

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

Return value

SGX_SUCCESS

msg1 is processed and msg2 is generated successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the input parameters is incorrect.

SGX_ERROR_INVALID_STATE

The API is invoked in incorrect order or state.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 226 -

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

SGX_ERROR_UNEXPECTED

An unexpected error occurred.

Requirements

Header

sgx_dh.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_dh_responder_proc_msg2

The responder handles msg2 sent by initiator and then derives AEK, updates

session information and generates msg3.

Syntax

sgx_status_t sgx_dh_responder_proc_msg2(

const sgx_dh_msg2_t * msg2,

sgx_dh_msg3_t * msg3,

sgx_dh_session_t * dh_session,

sgx_key_128bit_t * aek,

sgx_dh_session_enclave_identity_t * initiator_identity

);

Parameters

msg2 [in]

Point to dh message 2 buffer generated by session initiator, and the buffer

must be in enclave address space.

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

msg3 [out]

Point to dh message 3 buffer generated by session responder in this function,

and the buffer must be in enclave address space.

NOTE

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 227 -

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

dh_session [in/out]

Point to dh session structure that is used during establishment, and the buffer

must be in enclave address space.

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

aek [out]

A pointer that points to instance of sgx_key_128bit_t. The aek is derived

as follows:

KDK := CMAC(key0, LittleEndian(gab x-coordinate))

AEK = AES-CMAC(KDK, 0x01||’AEK’||0x00||0x80||0x00)

The key0 used in the key extraction operation is 16 bytes of 0x00. The plain

text used in the AES-CMAC calculation of the KDK is the Diffie-Hellman shared

secret elliptic curve field element in Little Endian format.

The plain text used in the AEK calculation includes:

l a counter (0x01)

l a label: the ASCII representation of the string 'AEK' in Little Endian

format)

l a bit length (0x80)

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

initiator_identity [out]

A pointer that points to instance of sgx_dh_session_enclave_iden-

tity_t. Identity information of initiator includes isv svn, isv product id, the

enclave attributes, MRSIGNER, and MRENCLAVE. The buffer must be in

enclave address space. The caller should check the identity of the peer and

decide whether to trust the peer and use the aek.

NOTE

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 228 -

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

Return value

SGX_SUCCESS

msg2 is processed and msg3 is generated successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the input parameters is incorrect.

SGX_ERROR_INVALID_STATE

The API is invoked in incorrect order or state.

SGX_ERROR_KDF_MISMATCH

Indicates the key derivation function does not match.

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

SGX_ERROR_UNEXPECTED

An unexpected error occurred.

Requirements

Header

sgx_dh.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

sgx_dh_initiator_proc_msg3

The initiator handles msg3 sent by responder and then derives AEK, updates

session information and gets responder’s identity information.

Syntax

sgx_status_t sgx_dh_initiator_proc_msg3(

const sgx_dh_msg3_t * msg3,

sgx_dh_session_t * dh_session,

sgx_key_128bit_t * aek,

sgx_dh_session_enclave_identity_t * responder_identity

);

Parameters

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 229 -

msg3 [in]

Point to dh message 3 buffer generated by session responder, and the buffer

must be in enclave address space.

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

dh_session [in]

Point to dh session structure that is used during establishment, and the buffer

must be in enclave address space.

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

aek [out]

A pointer that points to instance of sgx_key_128bit_t. The aek is derived

as follows:

KDK:= CMAC(key0, LittleEndian(gab x-coordinate))

AEK = AES-CMAC(KDK, 0x01||’AEK’||0x00||0x80||0x00)

The key0 used in the key extraction operation is 16 bytes of 0x00. The plain

text used in the AES-CMAC calculation of the KDK is the Diffie-Hellman shared

secret elliptic curve field element in Little Endian format.

The plain text used in the AEK calculation includes:

l a counter (0x01)

l a label: the ASCII representation of the string 'AEK' in Little Endian format

l a bit length (0x80)

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

responder_identity [out]

Identity information of responder including isv svn, isv product id, the enclave

attributes, MRSIGNER, and MRENCLAVE. The buffer must be in enclave

address space. The caller should check the identity of the peer and decide

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 230 -

whether to trust the peer and use the aek or the msg3_body.additional_

prop field of msg3.

NOTE

The value of the pointer must be a valid address within an enclave, as well as

the end address of the session structure.

Return value

SGX_SUCCESS

The function is done successfully.

SGX_ERROR_INVALID_PARAMETER

Any of the input parameters is incorrect.

SGX_ERROR_INVALID_STATE

The API is invoked in incorrect order or state.

SGX_ERROR_OUT_OF_MEMORY

The enclave is out of memory.

SGX_ERROR_UNEXPECTED

An unexpected error occurred.

Requirements

Header

sgx_dh.h

Library

libsgx_tservice.a

libsgx_tservice_sim.a

(sim-

ulation)

Types and Enumerations

This topic introduces the types and error codes in the following topics:

l Type Descriptions

l Error Codes

Type Descriptions

This topic section describes the following data types provided by the Intel(R)

SGX:

l sgx_enclave_id_t

l sgx_status_t

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 231 -

l sgx_launch_token_t

l sgx_exception_vector_t

l sgx_exception_type_t

l sgx_cpu_context_t

l sgx_exception_info_t

l sgx_exception_handler_t

l sgx_spinlock_t

l sgx_thread_t

l sgx_thread_mutex_t

l sgx_thread_mutexattr_t

l sgx_thread_cond_t

l sgx_thread_condattr_t

l sgx_misc_select_t

l sgx_attributes_t

l sgx_misc_attribute_t

l sgx_isv_svn_t

l sgx_cpu_svn_t

l sgx_key_id_t

l sgx_key_128bit_t

l sgx_key_request_t

l sgx_measurement_t

l sgx_mac_t

l sgx_report_data_t

l sgx_prod_id_t

l sgx_target_info_t

l sgx_report_body_t

l sgx_report_t

l sgx_aes_gcm_data_t

l sgx_sealed_data_t

l sgx_epid_group_id_t

l sgx_basename_t

l sgx_quote_t

l sgx_quote_sign_type_t

l sgx_spid_t

l sgx_quote_nonce_t

l sgx_time_source_nonce_t

l sgx_time_t

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 232 -

l sgx_ps_cap_t

l sgx_ps_sec_prop_desc_t

l sgx_mc_uuid_t

l sgx_ra_context_t

l sgx_ra_key_128_t

l sgx_ra_key_type_t

l sgx_ra_msg1_t

l sgx_ra_msg2_t

l sgx_ra_msg3_t

l sgx_ecall_get_ga_trusted_t

l sgx_ecall_get_msg3_trusted_t

l sgx_ecall_proc_msg2_trusted_t

l sgx_platform_info_t

l sgx_update_info_bit_t

l sgx_dh_msg1_t

l sgx_dh_msg2_t

l sgx_dh_msg3_t

l sgx_dh_msg3_body_t

l sgx_dh_session_enclave_identity_t

l sgx_dh_session_role_t

l sgx_dh_session_t

sgx_enclave_id_t

An enclave ID, also referred to as an enclave handle. Used as a handle to an

enclave by various functions.

Enclave IDs are locally unique, i.e. within the platform, and the uniqueness is

guaranteed until the next machine restart.

Syntax

typedef uint64_t sgx_enclave_id_t;

Requirements

Header

sgx_eid.h

sgx_status_t

Specifies the return status from an Intel SGXfunction call. For a list containing

all possible values of this data type, see Error Codes.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 233 -

typedef enum _status_t { . . . } sgx_status_t;

Requirements

Header

sgx_error.h

sgx_launch_token_t

An opaque type used to hold enclave launch information. Used by sgx_create_

enclave to initialize an enclave. The license is generated by the Launch

Enclave.

See more details in Loading and Unloading an Enclave.

Syntax

typedef uint8_t sgx_launch_token_t[1024];

Requirements

Header

sgx_urts.h

sgx_exception_vector_t

The sgx_exception_vector_t enumeration contains the enclave sup-

ported exception vectors. If the exception vector is #BP, the exception type is

SGX_EXCEPTION_SOFTWARE; otherwise, the exception type is SGX_

EXCEPTION_HARDWARE.

Syntax

typedef enum _sgx_exception_vector_t

{

SGX_EXCEPTION_VECTOR_DE = 0, /* DIV and DIV instructions */

SGX_EXCEPTION_VECTOR_DB = 1, /* For Intel use only */

SGX_EXCEPTION_VECTOR_BP = 3, /* INT 3 instruction */

SGX_EXCEPTION_VECTOR_BR = 5, /* BOUND instruction */

SGX_EXCEPTION_VECTOR_UD = 6, /* UD2 instruction or reserved

opcode */

SGX_EXCEPTION_VECTOR_MF = 16, /* x87 FPU floating-point or

WAIT/FWAI instruction. */

SGX_EXCEPTION_VECTOR_AC = 17, /* Any data reference in memory */

SGX_EXCEPTION_VECTOR_XM = 19, /* SSE/SSE2/SSE3 instruction */

} sgx_exception_vector_t;

Requirements

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 234 -

Header

sgx_trts_exception.h

sgx_exception_type_t

The sgx_exception_type_t enumeration contains values that specify the

exception type. If the exception vector is #BP (BreakPoint), the exception

type is SGX_EXCEPTION_SOFTWARE; otherwise, the exception type is SGX_

EXCEPTION_HARDWARE.

Syntax

typedef enum _sgx_exception_type_t

{

SGX_EXCEPTION_HARDWARE = 3,

SGX_EXCEPTION_SOFTWARE = 6,

} sgx_exception_type_t;

Requirements

Header

sgx_trts_exception.h

sgx_cpu_context_t

The sgx_cpu_content_t structure contains processor-specific register

data. Custom exception handling uses sgx_cpu_context_t structure to

record the CPU context at exception time.

Syntax

#if defined (_M_X64) || defined (__x86_64__)

typedef struct _cpu_context_t

{

uint64_t rax;

uint64_t rcx;

uint64_t rdx;

uint64_t rbx;

uint64_t rsp;

uint64_t rbp;

uint64_t rsi;

uint64_t rdi;

uint64_t r8;

uint64_t r9;

uint64_t r10;

uint64_t r11;

uint64_t r12;

uint64_t r13;

uint64_t r14;

uint64_t r15;

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 235 -

uint64_t rflags;

uint64_t rip;

} sgx_cpu_context_t;

#else

typedef struct _cpu_context_t

{

uint32_t eax;

uint32_t ecx;

uint32_t edx;

uint32_t ebx;

uint32_t esp;

uint32_t ebp;

uint32_t esi;

uint32_t edi;

uint32_t eflags;

uint32_t eip;

} sgx_cpu_context_t;

#endif

Members

rax, rcx, rdx, rbx, rsp, rbp, rsi, rdi, r8 – r15

64-bit general purpose registers

rflags

64-bit program status and control register

rip

64-bit instruction pointer

eax, ecx, edx, ebx, esp, ebp, esi, edi

32-bit general purpose registers

eflags

32-bit program status and control register

eip

32-bit instruction pointer

Requirements

Header

sgx_trts_exception.h

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 236 -

sgx_exception_info_t

A structure of this type contains an exception record with a description of the

exception and processor context record at the time of exception.

Syntax

typedef struct _exception_info_t

{

sgx_cpu_context_t cpu_context;

sgx_exception_vector_t exception_vector;

sgx_exception_type_t exception_type;

} sgx_exception_info_t;

Members

cpu_context

The context record that contains the processor context at the exception time.

exception_vector

The reason the exception occurs. This is the code generated by a hardware

exception.

exception_type

The exception type.

SGX_EXCEPTION_HARDWARE(3) indicates a HW exception.

SGX_EXCEPTION_SOFTWARE(6) indicates a SW exception.

Requirements

Header

sgx_trts_exception.h

sgx_exception_handler_t

Callback function that serves as a custom exception handler.

Syntax

typedef int (* sgx_exception_handler_t) (sgx_exception_

info_t *info);

Members

info

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 237 -

A pointer to sgx_exception_info_t structure that receives the exception

information.

Return value

EXCEPTION_CONTINUE_SEARCH (0)

The exception handler did not handle the exception and the RTSshould call

the next exception handler in the chain.

EXCEPTION_CONTINUE_EXECUTION (-1)

The exception handler handled the exception and the RTSshould continue

the execution of the enclave.

Requirements

Header

sgx_trts_exception.h

sgx_spinlock_t

Data type for a trusted spin lock.

Syntax

typedef volatile uint32_t sgx_spinlock_t;

Members

sgx_spinlock_t defines a spin lock object inside the enclave.

Requirements

Header

sgx_spinlock.h

sgx_thread_t

Data type to uniquely identify a trusted thread.

Syntax

typedef uintptr * sgx_thread_t;

Members

sgx_thread_t is an opaque data type with no member fields visible to

users. This data type is subject to change. Thus, enclave code should not rely

on the contents of this data object.

Requirements

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 238 -

Header

sgx_thread.h

sgx_thread_mutex_t

Data type for a trusted mutex object.

Syntax

typedef struct sgx_thread_mutex

{

size_t m_refcount;

uint32_t m_control;

volatile uint32_t m_lock;

sgx_thread_t m_owner;

sgx_thread_queue_t m_queue;

} sgx_thread_mutex_t;

Members

m_control

Flags to define whether a mutex is recursive or not.

m_refcount

Reference counter of the mutex object. It will be increased by 1 if the mutex is

successfully acquired, and be decreased by 1 if the mutex is released.

NOTE

The counter will be greater than one only if the mutex is recursive.

m_lock

The spin lock used to guarantee atomic updates to the mutex object.

m_owner

The thread that currently owns the mutex writes its unique thread identifier in

this field, which otherwise is NULL. This field is used for error checking, for

instance to ensure that only the owner of a mutex releases it.

m_queue

Ordered list of threads waiting to acquire the ownership of the mutex. The

queue itself is a structure containing a head and a tail for quick insertion and

removal under FIFO semantics.

Requirements

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 239 -

Header

sgx_thread.h

sgx_thread_mutexattr_t

Attribute for the trusted mutex object.

Syntax

typedef struct sgx_thread_mutex_attr

{

unsigned char m_dummy;

} sgx_thread_mutexattr_t;

Members

m_dummy

Dummy member not supposed to be used.

Requirements

Header

sgx_thread.h

sgx_thread_cond_t

Data type for a trusted condition variable.

Syntax

typedef struct sgx_thread_cond

{

sgx_spinlock_t m_lock;

sgx_thread_queue_t m_queue;

} sgx_thread_cond_t;

Members

m_lock

The spin lock used to guarantee atomic updates to the condition variable.

m_queue

Ordered list of threads waiting on the condition variable. The queue itself is a

structure containing a head and a tail for quick insertion and removal under

FIFO semantics.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 240 -

Requirements

Header

sgx_thread.h

sgx_thread_condattr_t

Attribute for the trusted condition variable.

Syntax

typedef struct sgx_thread_cond_attr

{

unsigned char m_dummy;

} sgx_thread_condattr_t;

Members

m_dummy

Dummy member not supposed to be used.

Requirements

Header

sgx_thread.h

sgx_misc_select_t

Enclave misc select bits. The value is 4 byte in length. Currently all the bits are

reserved for future extension.

Requirements

Header

sgx_attributes.h

sgx_attributes_t

Enclave attributes definition structure.

NOTE

When specifying an attributes mask used in key derivation, at a minimum the

flags that should be set are INITED, DEBUG and RESERVED bits.

NOTE

The XGETBV instruction can be executed to determine the register sets which

are part of the XSAVE state which corresponds to the xfrm value of attributes.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 241 -

Since the save state is dependent on the host system and operating system,

an attributes mask generally does not include these bits (XFRM is set to 0).

Syntax

typedef struct _sgx_attributes_t

{

uint64_t flags;

uint64_t xfrm;

} sgx_attributes_t;

Members

flags

Flags is a combination of the following values.

Value Description

SGX_FLAGS_INITTED

0x0000000000000001ULL

The enclave is initialized

SGX_FLAGS_DEBUG

0x0000000000000002ULL

The enclave is a debug enclave

SGX_FLAGS_MODE64BIT

0x0000000000000004ULL

The enclave runs in 64 bit mode

SGX_FLAGS_PROVISION_KEY

0x0000000000000010ULL

The enclave has access to a provision key

SGX_FLAGS_EINITTOKEN_KEY

0x0000000000000020ULL

The enclave has access to a launch key

SGX_FLAGS_RESERVED

0xFFFFFFFFFFFFFFC8ULL

A mask used to ensure that reserved bits are zero.

Reserved bits are bit 3 and bits 6-63.

xfrm

Similar to XCR0, xfrm is a combination of the following values.

Value Description

SGX_XFRM_LEGACY

0x0000000000000003ULL

FPU and Intel(R) Streaming SIMD Extensions states are

saved

SGX_XFRM_AVX

0x0000000000000006ULL

Intel(R) Advanced Vector Extensions state is saved

Requirements

Header sgx_attributes.h

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 242 -

sgx_misc_attribute_t

Enclave misc_select and attributes definition structure.

Syntax

typedef struct _sgx_misc_attributes_t

{

sgx_attributes_t secs_attr;

sgx_misc_select_t misc_select;

} sgx_misc_attribute_t;

Members

secs_attr

The Enclave attributes.

misc_select

The Enclave misc select configuration.

Requirements

Header

sgx_attributes.h

sgx_isv_svn_t

ISV security version. The value is 2 bytes in length. Use this value in key deriv-

ation and obtain it by getting an enclave report (sgx_create_report).

Requirements

Header

sgx_key.h

sgx_cpu_svn_t

sgx_cpu_svn_t is a 128-bit value representing the CPU security version.

Use this value in key derivation and obtain it by getting an enclave report

(sgx_create_report).

Syntax

#define SGX_CPUSVN_SIZE 16

typedef struct _sgx_cpu_svn_t {

uint8_t svn[SGX_CPUSVN_SIZE];

} sgx_cpu_svn_t;

Requirements

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 243 -

Header

sgx_key.h

sgx_key_id_t

sgx_key_id_t is a 256 bit value used in the key request structure. The

value is generally populated with a random value to provide key wear-out pro-

tection.

Syntax

#define SGX_KEYID_SIZE 32

typedef struct _sgx_key_id_t {

uint8_t id[SGX_KEYID_SIZE];

} sgx_key_id_t;

Requirements

Header

sgx_key.h

sgx_key_128bit_t

A 128 bit value that is the used to store a derived key from for example the

sgx_get_key function.

Requirements

Header

sgx_key.h

sgx_key_request_t

Data structure of key request which is used for selecting the appropriate key

and any additional parameters required in the derivation of that key. This is

the input parameter for the sgx_get_key function.

Syntax

typedef struct _key_request_t {

uint16_t key_name;

uint16_t key_policy;

sgx_isv_svn_t isv_svn;

uint16_t reserved1;

sgx_cpu_svn_t cpu_svn;

sgx_attributes_t attribute_mask;

sgx_key_id_t key_id;

sgx_misc_select_t misc_mask;

uint8_t reserved2[436];

} sgx_key_request_t;

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 244 -

Members

key_name

The name of the key requested. Possible values are below:

Key Name Value Description

SGX_KEYSELECT_

EINITTOKEN

0x0000

Launch key

SGX_KEYSELECT_

PROVISION

0x0001

Provisioning key

SGX_KEYSELECT_

PROVISION_SEAL

0x0002

Provisioning seal key

SGX_KEYSELECT_

REPORT

0x0003

Report key

SGX_KEYSELECT_

SEAL

0x0004

Seal key

key_policy

Identify which inputs are required to be used in the key derivation. Possible

values are below:

Key policy name Value Description

SGX_KEYPOLICY_

MRENCLAVE

0x0001

Derive key using the enclave’s

ENCLAVE measurement

SGX_KEYPOLICY_

MRSIGNER

0x0002

Derive key using the enclave’s

SIGNER measurement register

NOTE

If MRENCLAVE is used, then that key can only be rederived by that particular

enclave.

NOTE

If MRSIGNER is used, then another enclave with the same ISV_SVN could

derive the key as well which is useful for applications that instantiate more

than one enclave and would like to pass data. The key derived could be used

in the encryption process for the data passed between the enclaves.

isv_svn

The ISV security version number that should be used in the key derivation.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 245 -

reserved1

Reserved for future use. Must be zero.

cpu_svn

The TCB security version number that should be used in the key derivation.

attribute_mask

The attributes mask used to determine which enclave attributes must be

included in the key. It only impacts the derivation of seal key, provisioning key

and provisioning seal key. See the definition of sgx_attributes_t.

key_id

Value for key wear-out protection. Generally initialized with a random number.

misc_mask

The misc mask used to determine which enclave misc select must be included

in the key. Reserved for future function extension.

reserved2

Reserved for future use. Must be set to zero.

Requirements

Header

sgx_key.h

sgx_measurement_t

sgx_measurement_t is a 256-bit value representing the enclave meas-

urement.

Syntax

#define SGX_HASH_SIZE 32

typedef struct _sgx_measurement_t {

uint8_t m[SGX_HASH_SIZE];

} sgx_measurement_t;

Requirements

Header

sgx_report.h

sgx_mac_t

This type is utilized as storage for the 128-bit CMAC value of the report data.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 246 -

Requirements

Header

sgx_report.h

sgx_report_data_t

sgx_report_data_t is a 512-bit value used for communication between

the enclave and the target enclave. This is one of the inputs to the sgx_cre-

ate_report function.

Syntax

#define SGX_REPORT_DATA_SIZE 64

typedef struct _sgx_report_data_t {

uint8_t d[SGX_REPORT_DATA_SIZE];

} sgx_report_data_t;

Requirements

Header

sgx_report.h

sgx_prod_id_t

A 16-bit value representing the ISV enclave product ID. This value is used in

the derivation of some keys.

Requirements

Header

sgx_report.h

sgx_target_info_t

Data structure of report target information. This is an input to function sgx_

create_report and sgx_init_quote which is used to identify the

enclave (its measurement and attributes) which will be able to verify the

REPORT that is generated.

Syntax

typedef struct _targe_info_t

{

sgx_measurement_t mr_enclave;

sgx_attributes_t attributes;

uint8_t reserved1[4];

sgx_misc_select_t misc_select;

uint8_t reserved2[456];

} sgx_target_info_t;

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 247 -

Members

mr_enclave

The enclave hash of the target enclave

attributes

The attributes of the target enclave

reserved1

Reserved for future use. Must be set to zero.

misc_select

The misc select bits for the target enclave. Reserved for future function exten-

sion.

reserved2

Reserved for future use. Must be set to zero.

Requirements

Header

sgx_report.h

sgx_report_body_t

This data structure, which is part of the sgx_report_t structure, contains

information about the enclave.

Syntax

typedef struct _report_body_t

{

sgx_cpu_svn_t cpu_svn;

sgx_misc_select_t misc_select;

uint8_t reserved1[28];

sgx_attributes_t attributes;

sgx_measurement_t mr_enclave;

uint8_t reserved2[32];

sgx_measurement_t mr_signer;

uint8_t reserved3[96];

sgx_prod_id_t isv_prod_id;

sgx_isv_svn_t isv_svn;

uint8_t reserved4[60];

sgx_report_data_t report_data;

} sgx_report_body_t;

Members

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 248 -

cpu_svn

The security version number of the host system TCB (CPU).

misc_select

The misc select bits for the target enclave. Reserved for future function exten-

sion.

reserved1

Reserved for future use. Must be set to zero.

attributes

The attributes for the enclave. See sgx_attributes_t for the definitions of these

flags.

mr_enclave

The measurement value of the enclave.

reserved2

Reserved for future use. Must be set to zero.

mr_signer

The measurement value of the public key that verified the enclave.

reserved3

Reserved for future use. Must be set to zero.

isv_prod_id

The ISV Product ID of the enclave.

isv_svn

The ISV security version number of the enclave.

reserved4

Reserved for future use. Must be set to zero.

report_data

A set of data used for communication between the enclave and the target

enclave.

Requirements

Header

sgx_report.h

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 249 -

sgx_report_t

Data structure that contains the report information for the enclave. This is the

output parameter from the sgx_create_report function. This is the input

parameter for the sgx_init_quote function.

Syntax

typedef struct _report_t

{

sgx_report_body_t body;

sgx_key_id_t key_id;

sgx_mac_t mac;

} sgx_report_t;

Members

body

The data structure containing information about the enclave.

key_id

Value for key wear-out protection.

mac

The CMAC value of the report data using report key.

Requirements

Header

sgx_report.h

sgx_aes_gcm_data_t

The structure contains the AES GCM* data, payload size, MAC* and payload.

Syntax

typedef struct _aes_gcm_data_t

{

uint32_t payload_size;

uint8_t reserved[12];

uint8_t payload_tag[SGX_SEAL_TAG_SIZE];

uint8_t payload[];

} sgx_aes_gcm_data_t;

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 250 -

Members

payload_size

Size of the payload data which includes both the encrypted data followed by

the additional authenticated data (plain text). The full payload array is part of

the AES GCM MAC calculation.

reserved

Padding to allow the data to be 16 byte aligned.

payload_tag

AES-GMAC of the plain text, payload, and the sizes

payload

The payload data buffer includes the encrypted data followed by the optional

additional authenticated data (plain text),which is not encrypted.

NOTE

The optional additional authenticated data (MAC or plain text) could be data

which identifies the seal data blob and when it was created.

Requirements

Header

sgx_tseal.h

sgx_sealed_data_t

Sealed data blob structure containing the key request structure used in the

key derivation. The data structure has been laid out to achieve 16 byte align-

ment. This structure should be allocated within the enclave when the seal

operation is performed. After the seal operation, the structure can be copied

outside the enclave for preservation before the enclave is destroyed. The

sealed_data structure needs to be copied back within the enclave before

unsealing.

Syntax

typedef struct _sealed_data_t

{

sgx_key_request_t key_request;

uint32_t plain_text_offset;

uint8_t reserved[12];

sgx_aes_gcm_data_t aes_data;

} sgx_sealed_data_t;

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 251 -

Members

key_request

The key request used to derive the seal key.

plain_text_offset

The offset within the aes_data structure payload to the start of the optional

additional MAC text.

reserved

Padding to allow the data to be 16 byte aligned.

aes_data

Structure contains the AES GCM data (payload size, MAC, and payload).

Requirements

Header

sgx_tseal.h

sgx_epid_group_id_t

Type for Intel(R) EPID group id

Syntax

typedef uint8_t sgx_epid_group_id_t[4];

Requirements

Header

sgx_quote.h

sgx_basename_t

Type for base name used in sgx_quote.

Syntax

typedef struct _basename_t

{

uint8_t name[32];

} sgx_basename_t;

Members

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 252 -

name

The base name used in sgx_quote.

Requirements

Header

sgx_quote.h

sgx_quote_t

Type for quote used in remote attestation.

Syntax

typedef struct _quote_t

{

uint16_t version;

uint16_t sign_type;

sgx_epid_group_id_t epid_group_id;

sgx_isv_svn_t qe_svn;

sgx_isv_svn_t pce_svn;

uint32 xeid;

sgx_basename_t basename;

sgx_report_body_t report_body;

uint32_t signature_len;

uint8_t signature[];

} sgx_quote_t;

Members

version

The version of the quote structure.

sign_type

The indicator of the Intel(R) EPID signature type.

epid_group_id

The Intel(R) EPID group id of the platform belongs to.

qe_svn

The svn of the QE.

pce_svn

The svn of the PCE.

xeid

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 253 -

The extended Intel(R) EPIDgroup ID.

basename

The base name used in sgx_quote.

report_body

The report body of the application enclave.

signature_len

The size in byte of the following signature.

signature

The place holder of the variable length signature.

Requirements

Header

sgx_quote.h

sgx_quote_sign_type_t

Enum indicates the quote type, linkable or un-linkable

Syntax

typedef enum {

SGX_UNLINKABLE_SIGNATURE,

SGX_LINKABLE_SIGNATURE

} sgx_quote_sign_type_t;

Requirements

Header

sgx_quote.h

sgx_spid_t

Type for a service provider ID.

Syntax

typedef struct _spid_t

{

uint8_t id[16];

} sgx_spid_t;

Members

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 254 -

The ID of the service provider.

Requirements

Header

sgx_quote.h

sgx_quote_nonce_t

This data structure indicates the quote nonce.

Syntax

typedef struct _sgx_quote_nonce

{

uint8_t rand[16];

} sgx_quote_nonce_t;

Members

rand

The 16 bytes random number used as nonce.

Requirements

Header

sgx_quote.h

sgx_time_source_nonce_t

Nonce of time source. It’s opaque to users.

Syntax

typedef uint8_t sgx_time_source_nonce_t[32];

Requirements

Header

sgx_tae_service.h

sgx_time_t

Type for trusted time.

Syntax

typedef uint64_t sgx_time_t;

Requirements

Header

sgx_tae_service.h

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 255 -

sgx_ps_cap_t

Type indicating the platform service capability.

Syntax

typedef struct _sgx_ps_cap_t

{

uint32_t ps_cap0;

uint32_t ps_cap1;

} sgx_ps_cap_t;

Members

ps_cap0

Bit 0 : Trusted Time service

Bit 1 : Monotonic Counter service

Bit 2-31 : Reserved

ps_cap1

Bit 0-31 : Reserved

Requirements

Header

sgx_uae_service.h

sgx_ps_sec_prop_desc_t

Security property descriptor of platform service. It’s opaque to users.

Syntax

typedef struct _ps_sec_prop_desc

{

uint8_t sgx_ps_sec_prop_desc[256];

} sgx_ps_sec_prop_desc_t;

Requirements

Header

sgx_tae_service.h

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 256 -

sgx_ps_sec_prop_desc_ex_t

Security property descriptor of platform service with extended platform ser-

vice information.

Syntax

typedef struct _ps_sec_prop_desc_ex

{

sgx_ps_sec_prop_desc_t ps_sec_prop_desc;

sgx_measurement_t pse_mrsigner;

sgx_prod_id_t pse_prod_id;

sgx_isv_svn_t pse_isv_svn;

} sgx_ps_sec_prop_desc_ex_t;

Requirements

Header

sgx_tae_service.h

sgx_mc_uuid_t

The data structure of a monotonic counter.

Syntax

#define SGX_MC_UUID_COUNTER_ID_SIZE 3

#define SGX_MC_UUID_NONCE_SIZE 13

typedef struct _mc_uuid

{

uint8_t counter_id[SGX_MC_UUID_COUNTER_ID_SIZE];

uint8_t nonce[SGX_MC_UUID_NONCE_SIZE];

} sgx_mc_uuid_t;

Members

counter_id

ID number of the monotonic counter.

nonce

Nonce associated with the monotonic counter.

Requirements

Header

sgx_tae_service.h

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 257 -

sgx_ra_context_t

Type for a context returned by the key exchange library.

Syntax

typedef uint32_t sgx_ra_context_t;

Requirements

Header

sgx_key_exchange.h

sgx_ra_key_128_t

Type for 128 bit key used in remote attestation.

Syntax

typedef uint8_t sgx_ra_key_128_t[16];

Requirements

Header

sgx_key_exchange.h

sgx_ra_derive_secret_keys_t

The sgx_ra_derive_secret_keys_t function should take the Diffie-Hell-

man shared secret as input to allow the ISV enclave to generate their own

derived shared keys (SMK, SK, MK and VK). Implementation of the function

should return the appropriate return value.

Syntax

typedef sgx_status_t(*sgx_ra_derive_secret_keys_t)(

const sgx_ec256_dh_shared_t* p_shared_key,

uint16_t kdf_id,

sgx_ec_key_128bit_t* p_smk_key,

sgx_ec_key_128bit_t* p_sk_key,

sgx_ec_key_128bit_t* p_mk_key,

sgx_ec_key_128bit_t* p_vk_key

);

Parameters

p_shared_key [in]

The the Diffie-Hellman shared secret.

kdf_id [in]

Key Derivation Function ID.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 258 -

p_smk_key [out]

The output SMK.

p_sk_key [out]

The output SK.

p_mk_key [out]

The output MK.

p_vk_key [out]

The output VK.

Return value

SGX_SUCCESS

Indicates success.

SGX_ERROR_INVALID_PARAMETER

Indicates an error that the input parameters are invalid.

SGX_ERROR_KDF_MISMATCH

Indicates key derivation function does not match.

SGX_ERROR_OUT_OF_MEMORY

Not enough memory is available to complete this operation, or contexts reach

the limits.

SGX_ERROR_UNEXPECTED

Indicates that an unexpected error occurred.

Description

A pointer to a call back routine matching the function prototype.

Requirements

Header

sgx_tkey_exchange.h

sgx_ra_key_type_t

Enum of the key types used in remote attestation.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 259 -

typedef enum _sgx_ra_key_type_t

{

SGX_RA_KEY_SK = 1,

SGX_RA_KEY_MK,

SGX_RA_KEY_VK,

} sgx_ra_key_type_t;

Requirements

Header

sgx_key_exchange.h

sgx_ra_msg1_t

This data structure describes the message 1 that is used in remote attestation

and key exchange protocol.

Syntax

typedef struct _sgx_ra_msg1_t

{

sgx_ec256_public_t g_a;

sgx_epid_group_id_t gid;

} sgx_ra_msg1_t;

Members

g_a (Little Endian)

The public EC key of an application enclave, based on NISTP-256 elliptic

curve.

gid (Little Endian)

ID of the Intel(R) EPID group of the platform belongs to.

Requirements

Header

sgx_key_exchange.h

sgx_ra_msg2_t

This data structure describes the message 2 that is used in the remote attest-

ation and key exchange protocol.

Syntax

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 260 -

typedef struct _sgx_ra_msg2_t

{

sgx_ec256_public_t g_b;

sgx_spid_t spid;

uint16_t quote_type;

uint16_t kdf_id;

sgx_ec256_signature_t sign_gb_ga;

sgx_mac_t mac;

uint32_t sig_rl_size;

uint8_t sig_rl[];

} sgx_ra_msg2_t;

Members

g_b (Little Endian)

Public EC key of service provider, based on the NISTP-256 elliptic curve.

spid

ID of the service provider

quote_type (Little Endian)

Indicates the quote type, linkable (1) or un-linkable (0).

kdf_id (Litte Endian)

Key derivation function id.

sign_gb_ga (Litte Endian)

ECDSA Signature of (g_b||g_a), using the service provider’s ECDSA private key

corresponding to the public key specified in sgx_ra_initor sgx_ra_

init_ex function, where g_b is the public EC key of the service provider and

g_a is the public key of application enclave, provided by the application

enclave, in the remote attestation and key exchange message 1.

mac

AES-CMAC of gb, spid 2-byte TYPE, 2-byte KDF-ID, and sign_gb_ga using

SMK as the AES-CMAC key. SMK is derived as follows:

KDK= AES-CMAC(key0, LittleEndian(gab x-coordinate))

SMK = AES-CMAC(KDK, 0x01||’SMK’||0x00||0x80||0x00)

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 261 -

The key0 used in the key extraction operation is 16 bytes of 0x00. The plain

text used in the AES-CMAC calculation of the KDK is the Diffie-Hellman shared

secret elliptic curve field element in Little Endian format.

The plain text used in the SMK calculation includes:

l a counter (0x01)

l a label: the ASCII representation of the string 'SMK' in Little Endian

format

l a bit length (0x80)

If the ISV needs to use a different KDF than the default KDF used by Intel(R)

SGX PSW, the ISV can use the sgx_ra_init_ex API to provide a callback

function to generate the remote attestation keys used in the SIGMA protocol

(SMK) and returned by the API sgx_ra_get_keys (SK, MK, and VK).

sig_rl_size

Size of the sig_rl, in bytes.

sig_rl

Pointer to the Intel(R) EPIDSignature Revocation List Certificate of the Intel(R)

EPIDgroup identified by the gid in the remote attestation and key exchange

message 1.

Requirements

Header

sgx_key_exchange.h

sgx_ra_msg3_t

This data structure describes message 3 that is used in the remote attestation

and key exchange protocol.

Syntax

typedef struct _sgx_ra_msg3_t

{

sgx_mac_t mac;

sgx_ec256_public_t g_a;

sgx_ps_sec_prop_desc_t ps_sec_prop;

uint8_t quote[];

} sgx_ra_msg3_t;

Members

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 262 -

mac

AES-CMAC of g_a, ps_sec_prop, GID, and quote[], using SMK. SMK is derived

follows:

KDK = AES-CMAC(key0, LittleEndian(gab x-coordinate))

SMK = AES-CMAC(KDK, 0x01||’SMK’||0x00||0x80||0x00)

The key0 used in the key extraction operation is 16 bytes of 0x00. The plain

text used in the AES-CMAC calculation of the KDK is the Diffie-Hellman shared

secret elliptic curve field element in Little Endian format.

The plain text used in the SMK calculation includes:

l a counter (0x01)

l a label (the ASCII representation of the string 'SMK' in Little Endian

format)

l a bit length (0x80)

If the ISV needs to use a different KDF than the default KDF used by Intel(R)

SGX PSW, the ISV can use the sgx_ra_init_ex API to provide a callback

function to generate the remote attestation keys used in the SIGMA protocol

(SMK) and returned by the API sgx_ra_get_keys (SK, MK, and VK).

g_a (Little Endian)

Public EC key of application enclave

ps_sec_prop

Security property of the Intel(R) SGX Platform Service. If the Intel(R) SGX Plat-

form Service security property information is not required in the remote

attestation and key exchange process, this field will be all 0s.

quote

Quote returned from sgx_get_quote. The first 32-byte report_body.re-

port_data field in Quote is set to SHA256 hash of ga, gb and VK, and the

second 32-byte is set to all 0s. VK is derived from the Diffie-Hellman shared

secret elliptic curve field element between the service provider and the

application enclave:

KDK= AES-CMAC(key0, LittleEndian(gab x-coordinate))

SMK = AES-CMAC(KDK, 0x01||’VK’||0x00||0x80||0x00)

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 263 -

The key0 used in the key extraction operation is 16 bytes of 0x00. The plain

text used in the AES-CMAC calculation of the KDK is the Diffie-Hellman shared

secret elliptic curve field element in Little Endian format.

The plain text used in the SMK calculation includes:

l a counter (0x01)

l a label (the ASCII representation of the string 'SMK' in Little Endian

format)

l a bit length (0x80).

If the ISV needs to use a different KDF than the default KDF used by Intel(R)

SGX PSW, the ISV can use the sgx_ra_init_ex API to provide a callback

function to generate the remote attestation keys used in the SIGMA protocol

(SMK) and returned by the API sgx_ra_get_keys (SK, MK, and VK).

Requirements

Header

sgx_key_exchange.h

sgx_ecall_get_ga_trusted_t

Function pointer of proxy function generated from sgx_tkey_

exchange.edl.

Syntax

typedef sgx_status_t (* sgx_ecall_get_ga_trusted_t)(

sgx_enclave_id_t eid,

int* retval,

sgx_ra_context_t context,

sgx_ec256_public_t *g_a // Little Endian

);

Note that the 4th parameter this function takes should be in little endian

format.

Requirements

Header

sgx_ukey_exchange.h

sgx_ecall_proc_msg2_trusted_t

Function pointer of proxy function generated from sgx_tkey_

exchange.edl.

Syntax

typedef sgx_status_t (* sgx_ecall_proc_msg2_trusted_t)(

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 264 -

sgx_enclave_id_t eid,

int* retval,

sgx_ra_context_t context,

const sgx_ra_msg2_t *p_msg2,

const sgx_target_info_t *p_qe_target,

sgx_report_t *p_report,

sgx_quote_nonce_t *p_nonce

);

Requirements

Header

sgx_ukey_exchange.h

sgx_ecall_get_msg3_trusted_t

Function pointer of proxy function generated from sgx_tkey_

exchange.edl.

Syntax

typedef sgx_status_t (* sgx_ecall_get_msg3_trusted_t)(

sgx_enclave_id_t eid,

int* retval,

sgx_ra_context_t context,

uint32_t quote_size,

sgx_report_t* qe_report,

sgx_ra_msg3_t *p_msg3,

uint32_t msg3_size

);

Requirements

Header

sgx_ukey_exchange.h

sgx_platform_info_t

This opaque data structure indicates the platform information received from

Intel Attestation Server.

Syntax

#define SGX_PLATFORM_INFO_SIZE 101

typedef struct _platform_info

{

uint8_t platform_info[SGX_PLATFORM_INFO_SIZE];

} sgx_platform_info_t;

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 265 -

Members

platform_info

The platform information.

Requirements

Header

sgx_quote.h

sgx_update_info_bit_t

Type for information of what components of Intel SGX need to be updated

and how to update them.

Syntax

typedef struct _update_info_bit

{

int ucodeUpdate;

int csmeFwUpdate;

int pswUpdate;

} sgx_update_info_bit_t;

Members

ucodeUpdate

Whether the ucode needs to be updated.

csmeFwUpdate

Whether the csme firmware needs to be updated.

pswUpdate

Whether the platform software needs to be updated.

Requirements

Header

sgx_quote.h

sgx_dh_msg1_t

Type for MSG1 used in DH secure session establishment.

Syntax

typedef struct _sgx_dh_msg1_t

{

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 266 -

sgx_ec256_public_t g_a;

sgx_target_info_t target;

} sgx_dh_msg1_t;

Members

g_a (Little Endian)

Public EC key of responder enclave of DH session establishment, based on the

NISTP-256 elliptic curve.

target

Report target info to be used by the peer enclave to generate the Intel(R) SGX

report in the message 2 of the DH secure session protocol.

Requirements

Header

sgx_dh.h

sgx_dh_msg2_t

Type for MSG2 used in DH secure session establishment.

Syntax

typedef struct _sgx_dh_msg2_t

{

sgx_ec256_public_t g_b;

sgx_report_t report;

uint8_t cmac[SGX_DH_MAC_SIZE];

} sgx_dh_msg2_t;

Members

g_b (Little Endian)

Public EC key of initiator enclave of DH session establishment, based on the

NISTP-256 elliptic curve.

report

Intel(R) SGX report of initiator enclave of DH session establishment. The first

32-byte of the report_data field of the report is set to SHA256 hash of g_a

and g_b, where g_a is the EC Public key of the responder enclave and g_b is

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 267 -

the EC public key of the initiator enclave. The second 32-byte of the report_

data field is set to all 0s.

cmac[SGX_DH_MAC_SIZE]

AES-CMAC value of g_b,report, 2-byte KDF-ID, and 0x00s using SMK as the

AES-CMAC key. SMK is derived as follows:

KDK= AES-CMAC(key0, LittleEndian(gab x-coordinate))

SMK = AES-CMAC(KDK, 0x01||’SMK’||0x00||0x80||0x00)

The key0 used in the key extraction operation is 16 bytes of 0x00. The plain

text used in the AES-CMAC calculation of the KDK is the Diffie-Hellman shared

secret elliptic curve field element in Little Endian format.

The plain text used in the SMK calculation includes:

l a counter (0x01)

l a label: the ASCII representation of the string 'SMK' in Little Endian

format

l a bit length (0x80)

Requirements

Header

sgx_dh.h

sgx_dh_msg3_t

Type for MSG3 used in DH secure session establishment.

Syntax

typedef struct _sgx_dh_msg3_t

{

uint8_t cmac[SGX_DH_MAC_SIZE];

sgx_dh_msg3_body_t msg3_body;

} sgx_dh_msg3_t;

Members

cmac[SGX_DH_MAC_SIZE]

CMAC value of message body of MSG3, using SMK as the AES-CMAC key. SMK

is derived as follows:

KDK= AES-CMAC(key0, LittleEndian(gab x-coordinate))

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 268 -

SMK = AES-CMAC(KDK, 0x01||’SMK’||0x00||0x80||0x00)

The key0 used in the key extraction operation is 16 bytes of 0x00. The plain

text used in the AES-CMAC calculation of the KDK is the Diffie-Hellman shared

secret elliptic curve field element in Little Endian format.

The plain text used in the SMK calculation includes:

l a counter (0x01)

l a label: the ASCII representation of the string 'SMK' in Little Endian

format

l a bit length (0x80)

msg3_body

Variable length message body of MSG3.

Requirements

Header

sgx_dh.h

sgx_dh_msg3_body_t

Type for message body of the MSG3 structure used in DH secure session

establishment.

Syntax

typedef struct _sgx_dh_msg3_body_t

{

sgx_report_t report;

uint32_t additional_prop_length;

uint8_t additional_prop[0];

} sgx_dh_msg3_body_t;

Members

report

Intel(R) SGX report of responder enclave. The first 32-byte of the report_data

field of the report is set to SHA256 hash of g_b and g_a, where g_a is the EC

Public key of the responder enclave and g_b is the EC public key of the ini-

tiator enclave. The second 32-byte of the report_data field is set to all 0s.

additional_prop_length

Length of additional property field in bytes.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 269 -

additional_prop[0]

Variable length buffer holding additional data that the responder enclave may

provide.

Requirements

Header

sgx_dh.h

sgx_dh_session_enclave_identity_t

Type for enclave identity of initiator or responder used in DH secure session

establishment.

Syntax

typedef struct _sgx_dh_session_enclave_identity_t

{

sgx_cpu_svn_t cpu_svn;

uint8_t reserved_1[32];

sgx_attributes_t attributes;

sgx_measurement_t mr_enclave;

uint8_t reserved_2[32];

sgx_measurement_t mr_signer;

uint8_t reserved_3[96];

sgx_prod_id_t isv_prod_id;

sgx_isv_svn_t isv_svn;

} sgx_dh_session_enclave_identity_t;

Members

cpu_svn

Security version number of CPU.

reserved_1[32]

Reserved 32 bytes.

attributes

Intel SGX attributes of enclave.

mr_enclave

Measurement of enclave.

reserved_2[32]

Reserved 32 bytes.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 270 -

mr_signer

Measurement of enclave signer.

reserved_3[96]

Reserved 96 bytes.

isv_prod_id (Little Endian)

Product ID of ISV enclave.

isv_svn (Little Endian)

Security version number of ISV enclave.

Requirements

Header

sgx_dh.h

sgx_dh_session_role_t

Type for role of establishing a DH secure session used in DH secure session

establishment.

Syntax

typedef enum _sgx_dh_session_role_t

{

SGX_DH_SESSION_INITIATOR,

SGX_DH_SESSION_RESPONDER

} sgx_dh_session_role_t;

Members

SGX_DH_SESSION_INITIATOR

Initiator of a DH session establishment.

SGX_DH_SESSION_RESPONDER

Responder of a DH session establishment.

Requirements

Header

sgx_dh.h

sgx_dh_session_t

Type for session used in DH secure session establishment.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 271 -

Syntax

typedef struct _sgx_dh_session_t

{

uint8_t sgx_dh_session[SGX_DH_SESSION_DATA_SIZE];

} sgx_dh_session_t;

Members

sgx_dh_session

Data of DHsession.

The array size of sgx_dh_session SGX_DH_SESSION_DATA_SIZE is defined as

200 bytes.

Requirements

Header

sgx_dh.h

Error Codes

Table 14 Error code

Value Error Name Description

0x0000 SGX_SUCCESS

0x0001 SGX_ERROR_

UNEXPECTED

An unexpected error.

0x0002 SGX_ERROR_

INVALID_

PARAMETER

The parameter is incorrect.

0x0003 SGX_ERROR_

OUT_OF_

MEMORY

There is not enough memory available to com-

plete this operation.

0x0004 SGX_ERROR_

ENCLAVE_LOST

The enclave is lost after power transition or used

in child process created by fork().

0x0005 SGX_ERROR_

INVALID_STATE

The API is invoked in incorrect order or state.

0x1001 SGX_ERROR_

INVALID_

FUNCTION

The ECALL/OCALL function index is incorrect.

0x1003 SGX_ERROR_ The enclave is out of TCS.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 272 -

OUT_OF_TCS

0x1006 SGX_ERROR_

ENCLAVE_

CRASHED

The enclave has crashed.

0x1007 SGX_ERROR_

ECALL_NOT_

ALLOWED

ECALL is not allowed at this time. For examples:

l ECALL is not public.

l ECALL is blocked by the dynamic entry table.

l A nested ECALL is not allowed during global

initialization.

0x1008 SGX_ERROR_

OCALL_NOT_

ALLOWED

OCALL is not allowed during exception handling.

0x1009 SGX_ERROR_

STACK_

OVERRUN

Stack overrun occurs within the enclave.

0x2000 SGX_ERROR_

UNDEFINED_

SYMBOL

The enclave contains an undefined symbol.

0x2001 SGX_ERROR_

INVALID_

ENCLAVE

The enclave image is incorrect.

0x2002 SGX_ERROR_

INVALID_

ENCLAVE_ID

The enclave ID is invalid.

0x2003 SGX_ERROR_

INVALID_

SIGNATURE

The signature is invalid.

0x2004 SGX_ERROR_

NDEBUG_

ENCLAVE

The enclave is signed as product enclave and can-

not be created as a debuggable enclave.

0x2005 SGX_ERROR_

OUT_OF_EPC

There is not enough EPC available to load the

enclave or one of the Architecture Enclaves

needed to complete the operation requested.

0x2006 SGX_ERROR_

NO_DEVICE

Cannot open device.

0x2007 SGX_ERROR_

MEMORY_MAP_

CONFLICT

Page mapping failed in driver.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 273 -

0x2009 SGX_EEROR_

INVALID_

METADATA

The metadata is incorrect.

0x200C SGX_ERROR_

DEVICE_BUSY

Device is busy.

0x200D SGX_ERROR_

INVALID_

VERSION

Metadata version is inconsistent between uRTS

and sgx_sign or the uRTS is incompatible with

the current platform.

0x200E SGX_ERROR_

MODE_

INCOMPATIBLE

The target enclave (32/64 bit or HS/Sim) mode is

incompatible with the uRTS mode.

0x200F SGX_ERROR_

ENCLAVE_FILE_

ACCESS

Can’t open enclave file.

0x2010 SGX_ERROR_

INVALID_MISC

The MiscSelect/MiscMask settings are incorrect.

0x3001 SGX_ERROR_

MAC_MISMATCH

Indicates report verification error.

0x3002 SGX_ERROR_

INVALID_

ATTRIBUTE

The enclave is not authorized.

0x3003 SGX_ERROR_

INVALID_

CPUSVN

The CPU SVN is beyond the CPU SVN value of the

platform.

0x3004 SGX_ERROR_

INVALID_ISVSVN

The ISV SVN is greater than the ISV SVN value of

the enclave.

0x3005 SGX_ERROR_

INVALID_

KEYNAME

Unsupported key name value.

0x4001 SGX_ERROR_

SERVICE_

UNAVAILABLE

AE service did not respond or the requested ser-

vice is not supported.

0x4002 SGX_ERROR_

SERVICE_

TIMEOUT

The request to AE service timed out.

0x4003 SGX_ERROR_AE_

INVALID_

EPIDBLOB

Indicates an Intel(R) EPID blob verification error.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 274 -

0x4004 SGX_ERROR_

SERVICE_

INVALID_

PRIVILEDGE

Enclave has no privilege to get launch token.

0x4005 SGX_ERROR_

EPID_MEMBER_

REVOKED

The Intel(R) EPID group membership has been

revoked. The platform is not trusted. Updating the

platform and retrying will not remedy the revoc-

ation.

0x4006 SGX_ERROR_

UPDATE_

NEEDED

Intel(R) SGX needs to be updated.

0x4007 SGX_ERROR_

NETWORK_

FAILURE

Network connecting or proxy setting issue is

encountered.

0x4008 SGX_ERROR_AE_

SESSION_

INVALID

The session is invalid or ended by server.

0x400a SGX_ERROR_

BUSY

The requested service is temporarily not available.

0x400c SGX_ERROR_

MC_NOT_FOUND

The Monotonic Counter does not exist or has been

invalidated.

0x400d SGX_ERROR_

MC_NO_

ACCESS_RIGHT

The caller does not have the access right to the

specified VMC.

0x400e SGX_ERROR_

MC_USED_UP

No monotonic counter is available.

0x400f SGX_ERROR_

MC_OVER_

QUOTA

Monotonic counters reached quota limit.

0x4011 SGX_ERROR_

KDF_MISMATCH

Key derivation function does not match during key

exchange.

0x4012 SGX_ERROR_

UNRECOGNIZED_

PLATFORM

Intel(R) EPID Provisioning failed because the plat-

form was not recognized by the back-end server.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 275 -

Appendix

This topic provides the following reference information:

l Unsupported GCC*Compiler Options for Enclaves

l Unsupported Intel(R)C++ Compiler Options for Enclaves

l Unsupported Intel(R) C++ Compiler Libraries

l Unsupported GCC* Built-in Functions

l Unsupported C Standard Functions

l Unsupported C++ Standard Classes and Functions

l Unsupported C and C++ Keywords

Unsupported GCC*Compiler Options for Enclaves

The following GCC* options are not supported to build enclaves.

Table 15 Unsupported GCCCompiler Options

Option Category Remark

-fopenmp Options con-

trolling C dia-

lect.

Depends on Pthreads.

-fgnu-tm

Depends on libitm (transactional memory).

-fhosted

OS functions not supported within

enclaves.

-fuse-cxa-atexit Options con-

trolling C++ dia-

lect.

Depends on atexit(), which is not supported within

an enclave.

All options Options con-

trolling object-

ive-C and

objective-C++.

Objective C/C++ not supported.

All options Options for

debugging a pro-

gram.

All options because of runtime support required.

Separate Intel(R) SGX debugger support provided.

-fmudflap, -fmud-

flapth, –fmudflapir

Optimization

options.

Dependent on libmudflap.

-fexec-char-

set=charset,

-fwide-exec-char-

set=charset

Options con-

trolling the pre-

processor.

Only providing partial support for UTF-8.

-x objective-c

Objective-C is not supported within an

enclave.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 276 -

-lobjc Linker options. Objective C not supported.

-pie, -s Used for executables.

-shared-libgcc,

-static-libgcc

Enclaves cannot depend on libgcc.

-static-libstdc++ Intel(R) SGX SDK provides an Intel SGX version of

the C++ standard library.

-T script

Need to control the format of enclave

code.

-mglibc

Hardware

models and

configurations

for

GNU*/Linux*

options.

Intel SGX SDK provides an Intel SGX compatible C

standard library.

-muclibc, -mbionic, -

mandroid, -tno-

android-cc, -tno-

android-ld

Not applicable.

-msoft-float Hardware mod-

els and con-

figurations for

Intel & AMD*

x86-x64

options.

Run-time emulation of floating point is not sup-

ported.

-m96bit-long-double 96-bit not supported.

-mthreads Depends on mingwthrd.

-mcmodel=small, -

mcmodel=kernel, -

mcmodel=medium, -

mcmodel=large

Linker will fail.

All options Hardware mod-

els and con-

figurations for

Intel & AMD*

x86-x64 Win-

dows* options

All options because these are only used with Cyg-

win* or MinGW*.

-fbounds-check Options for code

generation con-

ventions

Currently for Java* and Fortran* front-ends, not

C/C++.

-fpie, -fPIE Only pertains to executable files.

-fpie, -pie compilation option -fpie and linking option -pie can-

not be used at the same time under simulation

mode if TLS support is required.

-fpie, -shared -fpic compilation option -fpie and linking option -shared

-fpic cannot be used at the same time under both

simulation mode and 64-bit hardware mode if TLS

support is required.

-finstrument-functions ISV would need to provide support for functions

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 277 -

_cyg_profile_func_enter

and

cyg_profile_func_exit

if this option is

needed.

-fsplit-stack Requires libgcc runtime support.

Unsupported Intel(R)C++ Compiler Options for Enclaves

The following Intel(R) C++ Compiler options are not supported to build

enclaves.

Table 16 Unsupported Intel C++ Compiler Options

Option Description

-hotpatch[=n] This code generation option is not applicable.

-xcode This option does not apply to Intel(R) SGX because for

this check to be effective, the source file containing the

main program or the dynamic library main function

should be compiled with this option enabled. Since this

compiler option does not have the intended behavior

(host architecture check), then the /Qax or /arch

options are recommended.

-cilk-serialize -

guide-file[=fil-

lename]

-guide-file-append

[=filename]

-ipp[=lib] -[no ]opt

calloc -[no-]opt-

matmul -tbb

These advanced optimization options are not supported.

-f[no-]instrument-

functions -prof-

data-order

-no-prof-data-

order -prof-dir -

prof-file <f>

-prof-func-groups -

no-prof-func-

groups

-prof-func-order -

These Profile-guided Optimization (PGO) options are not

supported.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 278 -

Option Description

no-prof-func-order

-prof-gen[x] -prof-

hotness-

threshold=n

-[-no]-prof-src-dir -

prof-src-root=dir

-prof-src-root-cwd

-prof-use

[=keyword]

-prof-value-pro-

filing[=keyword]

-profile-functions -

profile-loops-

s=keyword

-profile-loops-

report[=n]

-tcollect[lib] -tcol-

lect-filter filename

–tcheck

These optimization report options are not supported.

-openmp -

openmp-stubs

-openmp-report

{0|1|2} -openmp-

report[=n]

-openmp-lib=type

-openmp-link-

k=library -openmp-

task=model

-openmp-

threadprivate=type

-openmp-

threadprivate=type

These OpenMP* and parallel processing options are not

supported.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 279 -

Option Description

-par-affinity=[mod-

ifier,...]type[,per-

mute][,offset]

-par-num-thread-

s=n -par-report[n]

-par-runtime-con-

trol[n] -no-par-

runtime-control

-par-schedule-

keyword[=n] -par-

threshold[n]

-parallel -parallel-

source-info[=n]

-no-parallel-

source-info

-[no-]inline-calloc This inline option is not supported.

-check=keyword[,

keyword...]

This language option is not supported.

-Bdynamic -

dynamic-linker -

shared-intel

These linker options are not supported.

Unsupported Intel(R) C++ Compiler Libraries

The Intel(R) C++ Compiler libraries that are not supported within an enclave

are:

Table 17 Unsupported Intel C++ Compiler Libraries

Option Description Remark

cilkrts.lib

Cilk runtime system.

libchkp.lib

libchkpwrap.lib

Run-time pointer checker lib-

raries.

libiomp5mt.lib,

libiompprof5mt.lib,

OpenMP* libraries.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 280 -

libiompstubs5mt.lib

libipgo.lib

Profile-Guided Optimization

(PGO) runtime support library.

pdbx.lib,

pdbxinst.lib

Intel(R) Parallel Debugger

Extension runtime libraries.

libicaio.lib

Asynchronous I/O library. I/O is not sup-

ported in an

enclave.

libbfp754.lib

Binary floating-point math lib-

rary.

It is not utilized by

the compiler.

libmatmul.lib

Matrix multiplication library. It depends on the

OpenMP library.

Unsupported GCC* Built-in Functions

The following table illustrates unsupported GCC* built-in functions inside the

enclave. Using any of these built-in functions will result in a linker error during

the compilation of the enclave.

The complete list of GCC built-in functions is available at http://gc-

c.gnu.org/onlinedocs/gcc-4.7.2/gcc/X86-Built_002din-Functions.html#X86-

Built_002din-Functions.

Table 18 Unsupported GCCCompiler Built-in Functions

Non supported: Math built-ins

__builtin_signbitd32 __builtin_signbitd64 __builtin_signbitd128

__builtin_finited32 __builtin_finited64 __builtin_finited128

__builtin_isinfd32 __builtin_isinfd64 __builtin_isinfd128

__builtin_isnand32 __builtin_isnand64 __builtin_isnand64

Not Supported: String/memory built-ins

__builtin_strcat __builtin_strcpy __builtin_strdup

__builtin_stpcpy

Not Supported: I/O related built-ins

__builtin_fprintf __builtin_fprintf_unlocked __builtin_putc

__builtin_putc_unlocked __builtin_fputc __builtin_fputc_unlocked

__builtin_fputs __builtin_fputs_unlocked __builtin_fscanf

__builtin_fwrite __builtin_fwrite_unlocked __builtin_printf

__builtin_printf_unlocked __builtin_putchar __builtin_putchar_unlocked

__builtin_puts __builtin_puts_unlocked __builtin_scanf

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 281 -

__builtin_sprintf __builtin_sscanf __builtin_vfprintf

__builtin_vfscanf __builtin_vprintf __builtin_vscanf

__builtin_vsprintf __builtin_vsscanf

Not Supported: wctype built-in

__builtin_iswalnum __builtin_iswalpha __builtin_iswblank

__builtin_iswcntrl __builtin_iswdigit __builtin_iswgraph

__builtin_iswlower __builtin_iswprint __builtin_iswpunct

__builtin_iswspace __builtin_iswupper __builtin_iswxdigit

__builtin_towlower __builtin_towupper

Not Supported: Process control built-ins

__builtin_execl __builtin_execlp __builtin_execle

__builtin_execv __builtin_execvp __builtin_execve

__builtin_exit __builtin_fork __builtin__exit

__builtin__Exit

Non Supported: Object size checking built-ins

__builtin___fprintf_chk __builtin___printf_chk __builtin___vfprintf_chk

__builtin___vprintf_chk

Non Supported: Miscellaneous built-ins

__builtin_dcgettext __builtin_dgettext __builtin_gettext

__builtin_strfmon

Non Supported: Profiling Hooks

__cyg_profile_func_enter __cyg_profile_func_exit

Non Supported: TLS Emulation

target.emutls.get_address target.emutls.register_common

Non supported: Ring 0 built-ins

_writefsbase_u32 _writefsbase_u64 _writegsbase_u32

_writegsbase_u64 __rdpmc __rdtsc

__rdtscp

Non Supported: OpenMP* built-ins

__builtin_omp_get_thread_num __builtin_omp_get_num_threads

__builtin_GOMP_atomic_start __builtin_GOMP_atomic_end

__builtin_GOMP_barrier __builtin_GOMP_taskwait

__builtin_GOMP_taskyield __builtin_GOMP_critical_start

__builtin_GOMP_critical_end __builtin_GOMP_critical_name_start

__builtin_GOMP_critical_name_end __builtin_GOMP_loop_static_start

__builtin_GOMP_loop_dynamic_start __builtin_GOMP_loop_guided_start

__builtin_GOMP_loop_runtime_start __builtin_GOMP_loop_ordered_static_start

__builtin_GOMP_loop_ordered_dynamic_start __builtin_GOMP_loop_ordered_guided_

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 282 -

start

__builtin_GOMP_loop_ordered_runtime_start __builtin_GOMP_loop_static_next

__builtin_GOMP_loop_dynamic_next __builtin_GOMP_loop_guided_next

__builtin_GOMP_loop_runtime_next __builtin_GOMP_loop_ordered_static_next

__builtin_GOMP_loop_ordered_dynamic_next __builtin_GOMP_loop_ordered_guided_next

__builtin_GOMP_loop_ordered_runtime_next __builtin_GOMP_loop_ull_static_start

__builtin_GOMP_loop_ull_dynamic_start __builtin_GOMP_loop_ull_guided_start

__builtin_GOMP_loop_ull_runtime_start __builtin_GOMP_loop_ull_ordered_static_

start

__builtin_GOMP_loop_ull_ordered_dynamic_

start

__builtin_GOMP_loop_ull_static_next

__builtin_GOMP_loop_ull_ordered_guided_

start

__builtin_GOMP_loop_ull_dynamic_next

__builtin_GOMP_loop_ull_ordered_runtime_

start

__builtin_GOMP_loop_ull_guided_next

__builtin_GOMP_loop_ull_runtime_next __builtin_GOMP_loop_ull_ordered_static_

__builtin_GOMP_loop_ull_ordered_dynamic_

__builtin_GOMP_parallel_loop_static_start

__builtin_GOMP_loop_ull_ordered_guided_

__builtin_GOMP_parallel_loop_dynamic_

start

__builtin_GOMP_loop_ull_ordered_runtime_

__builtin_GOMP_parallel_loop_guided_start

__builtin_GOMP_parallel_loop_runtime_start __builtin_GOMP_loop_end

__builtin_GOMP_loop_end_nowait __builtin_GOMP_ordered_start

__builtin_GOMP_ordered_end __builtin_GOMP_parallel_start

__builtin_GOMP_parallel_end __builtin_GOMP_task

__builtin_GOMP_sections_start __builtin_GOMP_sections_next

__builtin_GOMP_parallel_sections_start __builtin_GOMP_sections_end

__builtin_GOMP_sections_end_nowait __builtin_GOMP_single_start

__builtin_GOMP_single_copy_start __builtin_GOMP_single_copy_end

Unsupported C Standard Functions

You cannot use the following Standard C functions within the enclave; oth-

erwise, the compilation would fail.

Table 19 Unsupported C Standard Functions

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 283 -

Header

file

Header

file in

Intel

SGX?

Unsupported Definition

Macros/Types Functions

complex.h No

complex, _complex_

imaginary, _ima-

ginary_I,

#pragma STDC CX_

LIMITED_RANGE on-

off-switch

cacos(), cacosf(), cacosl(), casin(), casinf(), casinl

(), catan(), catanf(), catanl(), ccos(), ccosf(), ccosl

(), csin(), csinf(), csinl(), ctan(), ctanf(), ctanl(),

cacosh(), cacoshf(), cacoshl(), casinh(), casinhf(),

casinhl(), catanh(), catanhf(), catanhl(), ccosh(),

ccoshf(), ccoshl(), csinh(), csinhf(), csinhl(),

ctanh(), ctanhf(), ctanhl(), cexp(), cexpf(), cexpl(),

clog(), clogf(), clogl(), cabs(), cabsf(), cabsl(),

cpow(), cpowf(), cpowl(), csqrt(), csqrtf(), csqrtl

(), carg(), cargf(), cargl(), cimag(), cimagf(), cimagl

(), conj(), conjf(), conjl(), cproj(), cprojf(), cprojl(),

creal(), crealf(), creall()

fenv.h No

fenv_t, fexcept_t,

FE_DIVBYZERO,

FE_INEXACT,

FE_INVALID,

FE_OVERFLOW,

FE_UNDERFLOW,

FE_ALL_EXCEPT,

FE_DOWNWARD,

FE_TONEAREST,

FE_TOWARDZERO,

FE_UPWARD,

FE_DFL_ENV,

#pragma STDC

FENV_ACCESS on-

off-switch

feclearexcept(), fegetexceptflag(),

feraiseexcept(), fesetexceptflag(),

fetestexcept(), fegetround(), feset-

round(), fegetenv(), feholdexcept(),

fesetenv(), feupdateenv()

inttypes.h Yes SCNdN, SCNiN, SCNoN,

SCNuN, SCNxN,

SCNdLEASTN,

wcstoimax(),

wcstoumax()

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 284 -

Header

file

Header

file in

Intel

SGX?

Unsupported Definition

Macros/Types Functions

SCNiLEASTN,

SCNoLEASTN,

SCNuLEASTN,

SCNxLEASTN,

SCNdFASTN, SCNiFASTN,

SCNoFASTN,

SCNuFASTN,

SCNxFASTN, SCNdMAX,

SCNiMAX, SCNoMAX,

SCNuMAX, SCNxMAX,

SCNdPTR, SCNiPTR,

SCNoPTR, SCNuPTR,

SCNxPTR

locale.h No

LC_ALL, LC_

COLLATE,

LC_CTYPE,

LC_MONETARY,

LC_NUMERIC,

LC_TIME, struct

lconv

setlocale(),

localeconv()

signal.h No sig_atomic_t, SIG_DFL,

SIG_ERR, SIG_IGN,

SIGABRT, SIGFPE, SIGILL,

SIGINT, SIGSEGV,

SIGTERM

signal(),

raise()

stdio.h Yes

fpos_t,

_IOFBF, _IOLBF,

_IONBF,

FILENAME_MAX,

FOPEN_MAX,

L_tmpnam,

remove(), rename(), tmpfile(), tmpnam

(), fclose(), fflush(), fopen(), freopen(),

setbuf(), setvbuf(), fprintf(), fscanf(),

printf(), scanf(), sprintf(), sscanf(),

vfprintf(), vfscanf(), vprintf(), vscanf(),

vsprintf(), vsscanf(), fgetc(), fgets(),

fputc(), fputs(), getc(), getchar(), gets(),

putc(), putchar(), puts(), ungetc(), fread

(), fwrite(), fgetpos(), fseek(), fsetpos(),

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 285 -

Header

file

Header

file in

Intel

SGX?

Unsupported Definition

Macros/Types Functions

SEEK_CUR, SEEK_

END, SEEK_SET,

TMP_MAX, stderr,

stdin, stdout

ftell(), rewind(), clearerr(), feof(), ferror

(), perror()

stdlib.h Yes rand(), srand(), atexit(), exit(), _Exit(), getenv(),

system()

string.h Yes strcpy(), strcat(), strstr()

tgmath.h No

time.h Yes clock(), mktime(), time(), ctime(), gmtime(), loc-

altime()

wchar.h Yes fwprintf(), fwscanf(), swscanf(), vfwprintf(), vfws-

canf(), vswscanf(), vwprintf(), vwscanf(), wprintf

(), wscanf(), fgetwc(), fgetws(), fputwc(), fputws

(), fwide(), getwc(), getwchar(), putwc(), put-

wchar(), ungetwc(), wcstod(), wcstof(), wcstold

(), wcstol(), wcstoll(), wcstoul(), wcstoull(),

wcscpy(), wcscat(), wcsftime(),wctob()

wctype.h Yes iswalnum(), iswalpha(), iswblank(), iswcntrl(),

iswdigit(), iswgraph(), iswlower(), iswprint(), isw-

punct(), iswspace(), iswupper(), iswxdigit(),

wctype(), towlower(), towupper(), towctrans(),

wctrans(),

(*) The trusted standard C library does not support char strstr(const

char*, const char*). However, it does support the variant const

char* strstr (const char*, const char*) is supported.

NOTE

Trusted C library is enhanced to avoid format string attacks. Any attempts to

use %n in printf-family functions such as snprintf will result in a run-time

error.

Unsupported C++ Standard Classes and Functions

The following table lists unsupported C++03 classes and functions inside an

enclave. Also, the table does not include unsupported C functions. See Unsup-

ported C Standard Functions for detailed information.

Intel(R) Software Guard Extensions SDKDeveloper Reference for Linux* OS

- 286 -

Table 20 Unsupported C++ Standard Classes and Functions

Class Cat-

egory

Partially

Supported

Unsupported Classes

Stream Iter-

ators

No istream_iterator, ostream_iterator, istreambuf_iterator, ostre-

ambuf_iterator

Input/Output

Library

No basic_streambuf, basic_istream, basic_ostream, basic_iostream,

basic_filebuf, basic_ifstream, basic_ofstream, basic_fstream,

basic_stringbuf, basic_istringstream, basic_ostringstream, basic_

stringstream

Locales No locale, use_facet, has_facet

Unsupported C and C++ Keywords

The following keywords are not supported in an enclave.

Table 21 Unsupported Cand C++Keywords

__transaction_atomic __transaction_relaxed __transaction_cancel

The following GCC* specific attributes are not supported in an enclave.

Table 22 Unsupported GCC*Compiler Attributes

destructor transaction_callable transaction_unsafe

transaction_safe transaction_may_cancel_outer transaction_pure

transaction_wrap disinterrupt