Video Series: Intel® Software Guard Extensions—Part 4: Introduction: Enclave Definition Language

Learn about the Enclave Definition Language file that an educator tool uses to read the interface definition of an enclave.

Hi, I'm John Mechalas with Intel. In this video we're going to discuss the Enclave Definition Language used by Intel® Software Guard Extensions, or Intel® SGX. The fundamental protection provided by Intel SGX is that an enclave's secrets can only be accessed by the code that is inside the enclave. The only way to execute that code is through the interface functions that the enclave developer has created. The CPU enforces this restriction, and even privileged users can't circumvent it.

Each enclave defines one or more enclave calls (or ECALL), calls which are entry points into the enclave from the untrusted application. An enclave may also have outside calls (or OCALLs). These allow enclave functions to call out to the untrusted application, and then return to the enclave. Collectively, these ECALLs and OCALLs make up an enclave's interface, but these functions are not directly executed by your program. Because access to enclaves place entry and exit points is tightly controlled by the processor special CPU instructions are required in order to make these transitions.

The Intel SGX software developer kit abstracts these low-level details in order to provide software developers with the familiar programming environment. A special tool called the Edger8r, automatically generates proxy functions named after your ECALLs and OCALLs so that your application can invoke them as it would any other C function. To create these proxy functions, the educator tool reads the enclave interface definition from the EDL file.

EDL stands for enclave definition language. An EDL file loosely resembles a C-style header file with function prototypes, and in fact shares much of that syntax. The EDL file contains two sections, the trusted section and the untrusted section. ECALL functions are defined in the trusted section, and OCALL functions are defined in the untrusted section. These functions are prototyped much like they are for the C programming language, but there are some additional keywords that are needed. We'll review some of them here.

All ECALLs that are meant to be invoked by the untrusted application must be declared as public. Every enclave must have at least one public ECALL. The public keyword precedes your function name. An ECALL without the public designation can only be executed from within another OCALL. When an ECALL or OCALL is made, the function parameters are marshalled between untrusted memory and trusted memory. When a parameter is passed by value this marshalling is one way. Changes made inside the ECALL or OCALL are not propagated back to the calling function.

When a parameter is passed by reference however, you must completely describe the data marshalling. Each point or parameter must be preceded by keywords in square brackets that describe the direction of the data marshalling, and optionally the number of elements to be marshalled. The end keyword means that the data buffer should be marshalled in to the ECALL or OCALL. The out keyword means that the data should be marshalled out of the ECALL or OCALL back to the calling function.

When passing data out, the data buffer must be allocated before the ECALL or OCALL both in and out means data should be marshalled in both directions. By default the Edger8r utility assumes that the data buffer consists of one element with the size of the argument type. In the example shown, one 32-bit integer will be marshalled.

If your pointer refers to an array of values, then you can also indicate the number of elements to copy by supplying the count parameter. This example marshals a buffer of ten 32-bit integers. If the number of elements is variable, you can refer to another function parameter to provide the length. When passing null-terminated strings in, you can use the shortcuts string or w string in place of account. This shortcut cannot be combined with the out keyword.

This was an introduction to the enclave definition language. Be sure to watch the rest of this playlist to learn more about Intel SGX application development. And remember to like this video and subscribe.