Edl.md

What are .edl files

EDL (enclave definition language) is an open file format created by Intel, originally for their SGX hardware enclaves. It's a text format (loosely resembling C), with a simple grammar, that can be used as an intermediary definition language (idl) to declare functions that can be called between both the hostApp and the enclave. You define your own types (such as enums and structs), declare host-to-enclave function calls in the trusted scope, and enclave-to-host function calls in the untrusted scope.

What the VbsEnclaveTooling project uses .edl files for

An .edl file is what our code generation tool uses to generate functions that interact with our ABI layer to marshal data between the hostApp and the enclave.

The tool generates stub functions and function declarations based on the content of the .edl file. The developer is expected to implement the generated function declarations.

Some basics

Note

Both Open Enclave's and Intel's parsers were made specifically for working in a C environment, however we're using it for higher level languages like C++. Because of this, we have updated our parser to be C++ centric, to allow for more types. See the supported types below for more information.

Here is the general structure and grammar of our .edl format.

\\ Single line comment
\* Multi line comment *\

enclave 
{
    import "<path_to_edl_file.edl>"; // Importing another edl file

    enum // Anonymous enum
    {
        <enum_name>,
    };   
    
    enum <Enum> // Regular enum
    {
        // enum_value can only be a decimal, Hexidecimal or value from an anonymous enum
        <enum_field> = <enum_value>, 
    };

    struct <Struct>
    {
        // field_type can be any supported edl type.
        <field_type> <field_name>;
    };

    trusted 
    {
        <return_type> <EnclaveMethod>(
            [attr] <parameter_type> <parameter_name>
            );
    };

    untrusted 
    {
        <return_type> <HostappMethod>(
            [attr] <parameter_type> <parameter_name>
            );
    };
};

Term	Description
return_type	Defines the return value type, which must be one of the supported types.
parameter_type	Defines a parameter's type. Must be one of the supported types.
parameter_name	Defines a parameter's name.
attr	Directives describing the parameter's direction (e.g., [in], [in, out], [out]).
EnclaveMethod	Methods exposed from the secure enclave to the unsecure hostApp. The hostApp calls stub functions, while the implementation is inside the enclave.
HostappMethod	Methods exposed from the unsecure hostApp to the secure enclave. The enclave calls stub functions, while the implementation is inside the hostApp.

A simple example of a .edl file.

enclave {
    import "EdlFiles\Crypto\Types.edl";

    struct ExampleStruct
    {
        int32_t int_field;
        vector<wstring> wstrings;
    };

    trusted {
        int32_t EnclaveAddTwoNums(
            int32_t num1,
            int32_t num2
        );

        HRESULT SecondaryExample (
            [in, out] ExampleStruct,
            vector<int8_t> bytes // a data blob
        );
    };

    untrusted {
        int32_t HostAddTwoNums(
            int32_t num1,
            int32_t num2
        );
    };
};

What the VbsEnclaveTooling project supports within .edl files.

Built-in Data Types

Category	Types
Basic Types	char, wchar_t, float, double, size_t, HRESULT
Integer Types	int8_t, int16_t, int32_t, int64_t uint8_t, uint16_t,uint32_t, uint64_t, uintptr_t
String Types	string, wstring
Complex Types	enum, struct
Array Types	Arrays in the form of type name[value] (e.g., uint8_t numbers[10])
Vector Types	Vectors in the form of vector<type> (e.g., vector<string>)
Optional Types	Optionals in the form of optional<type> (e.g., optional<MyStruct>)

Note

• vectors, arrays and structs only support the types outlined above. vectors and arrays can be used as internal struct fields or function parameters.
• arrays can contain a non-numeric value within the edl file. The only value it supports other than numeric values is a value from an anonymous enum. arrays are considered fixed-sized, and in C++ are generated as a std::array during code generation.
• optional types only support basic types, integer types, enums and struct types.

Example showing how using an anonymous enum value can be used with an array in a .edl file.

enum
{
    my_number = 50
};

struct
{
    uint32_t my_array[my_number]; // This also works in a function declaration.
};

Edl Generated Type Rules

Struct Fields

Applies To	C++ Generated Type
All types	<Type>

Function Parameters

With [in] attribute

Applies To	C++ Generated Type
string, wstring, array, vector, struct, optional	const <Type>&
basic, integer, enum	<Type>

With [in, out] attribute

Applies To	C++ Generated Type
All types	<Type>&

With [out] attribute

Applies To	C++ Generated Type
All types	<Type>&

Function Return Values

Applies To	C++ Generated Type
All types	<Type>

Importing other .edl files

You can import other .edl files into your .edl file using the import keyword. This allows you to reuse types and function declarations across multiple .edl files.

Note

The edlcodegen.exe provides the --ImportDirectories option to specify the directories where it should look for imported .edl files. The paths inside --ImportDirectories must be absolute paths to directories that exist. You can specify multiple directories by separating them with a semicolon (;).

Unsupported functionality

While our .edl parser is based on Open Enclave's implementation of Intel's .edl parser, there are some things we do not support:

• private and public keywords for the function names of both trusted and untrusted functions.
• COM\WinRT is not supported inside a vbs enclave. e.g Events, RuntimeClasses etc.
• The concept of switchless calls is not encouraged, so the switchless keyword is unsupported.
• Calling conventions (like cdecl, stdcall, fastcall) are not supported.
• Ability to import C headers into an .edl file to allow for types defined outside the .edl file is not supported. Only types defined in the .edl are supported.
• The words string and wstring are supported type keywords within an .edl file. Using the word string or wstring as an attribute is not supported.
• Only the following attributes are supported [in], [in, out], [out] in function declarations. The [in] attribute means the parameter is expected to only be used in the function as input. The [out] attribute means the parameter is expected to be used as output and lastly [in, out] means the parameter can be used for both. If no attributes are specified, parameters default to [in].
• Pointers (*) are not supported.
• void* is not supported in struct fields or function parameters. Use uintptr_t for arbitrary pointers or handles, and manually cast and manage the memory when moving data into or out of the enclave
• The const keyword is not supported.