Intel® Software Guard Extensions (Intel® SGX) Web-Based Training

This web-based training class is designed for software developers who wish to learn the fundamentals of building Intel® SGX applications. Through a series of videos, sample code, and lab exercises, the developer will learn key concepts around the Intel SGX technology and writing Intel SGX application development. Developers will learn how to:

• design and build enclaves
• interact with enclaves
• maintain state across power events and application restarts
• debug enclaves

This course was developed in conjunction with Prowess* Consulting.

Pre-Requisites

To get the most out of the class, software developers will require:

• C/C++ programming experience.
• A system with an 6th Generation Intel® Core™ processor, with BIOS support for Intel SGX, running Windows® 10.
• Microsoft Visual Studio* 2015 Professional Edition or better.
• The Intel® Software Guard Extensions SDK for Windows* (Intel® SGX SDK for Windows).
• The Intel® Software Guard Extensions Platform Software (PSW) for Windows.
• A hex editor utility such as HxD.
• The Intel SGX Web-Based Training lab bundle, which contains the sample applications, source code, and exercises. (This download requires acceptance of the Intel Software Export Warning License).

Course Content

Each part of the course covers a separate topic in Intel SGX application development, and most include labs. The Intel SGX Web Training Hands-on Lab Manual will step you through the various exercises.

Part 1: Introduction to Intel SGX and Detecting and Enabling Intel SGX

Part 2: Introduction to Intel SGX applications

Part 3: Sample application overview

Part 4: Fundamentals of the Enclave Definition Language

Part 5: Advanced topics in the Enclave Definition Language

Part 6: Debugging Intel SGX applications

Part 7: Data sealing

Part 1: Introduction to Intel® SGX

Intel SGX protects an application’s secrets from malicious software by creating isolated memory regions of code and data called enclaves. These non-addressable memory pages are reserved from the system’s physical RAM and then encrypted, allowing the application to access its secrets without fear of exposure. With Intel SGX, secrets remain secret even if the application, Operating System, BIOS, or VMM are compromised

Intel SGX applications are built a trusted part, and and untrusted part. When the application needs to work with a secret, it creates an enclave which is placed in trusted memory. It then calls a trusted function to enter the enclave, where it is given a view of its secrets in clear text.

All other attempts to access enclave memory from outside the enclave are denied by the processor, even those made by privileged users. This prevents secrets in the enclave from being exposed.

Before an application can use Intel SGX, four conditions have to be met:

• The CPU in the system must support the Intel SGX instructions.
• The system BIOS must support Intel SGX.
• Intel SGX must be enabled in the BIOS, and
• The Intel SGX Platform Software, or PSW, must be installed on that system.

This means that Intel SGX may not be available for use by applications even if it’s supported by the CPU. Applications, and application installers, need to be able to detect Intel SGX availability at run time, and take appropriate action based on the system’s configuration.

The video below explains the application detection procedures in greater detail.

Lab Exercises

The exercises in Task 1 of the Intel SGX Web Training Hands-on Lab Manual provide an overview of the Intel SGX components, system configuration, and feature detection. They also demonstrate why secrets should never be statically compiled into enclaves.

• Task 1.1: Intel SGX settings in the BIOS
• Task 1.2: The Intel SGX AESM service
• Task 1.3: Testing for Intel SGX support in your application
• Task 1.4: Review of the Intel SGX feature detection procedure
• Task 1.5: Never compile secrets into enclaves

Part 2: Introduction to Intel SGX Applications

Intel SGX applications are built with two parts: the trusted part, and the untrusted part.

• The trusted part of consists of the enclaves. They reside in encrypted memory and are protected by Intel SGX. Enclaves are considered trusted because they cannot be modified after they have been built. If an enclave is modified by a malicious user or software, it will be detected by the CPU and it won’t load.
• The untrusted part is the rest of the application. Any application or memory region not protected by Intel SGX is considered untrusted.

Designing an Intel SGX application requires that the code be partitioned. You need to identify which code belongs in the enclave, which code belongs outside of it, and how the untrusted and trusted parts interact.

The video discusses Intel SGX application design, and gives recommendations on defining the enclave boundary.

Lab Exercises

The exercises in Task 2 of the Intel SGX Web Training Hands-on Lab Manual step through creating a simple "Hello World" enclave application in Microsoft Visual Studio. This application is not designed to show off the security features of Intel SGX. It's purpose is to introduce developers to the process of setting up an enclave project, and making a simple call into the enclave.

• Task 2.1: Create a Win32 Console application project
• Task 2.2: Create the Intel SGX enclave project
• Task 2.3: Add the enclave project to the console application solution
• Task 2.4: Import the enclave configuration into the console application solution
• Task 2.5: Add a trusted call to the enclave
• Task 2.6: Implement the enclave function

Part 3: Sample Application Overview

Several of the lab exercises from this point on consist of making code changes to a sample Intel SGX application called the File Encrypter. This is a very simple program that encrypts and decrypts files using a password that you provide. The application's user interface is written in C#, and it uses C++/CLI to get to native Win32 code so that it can call into the enclave. The majority of the code for this application has already been written, but you'll be adding ECALL and OCALL definitions, as well as implementing some of the code that links the untrusted application to the enclave.

Warning: The File Encrypter is a sample application with minimal error handling, created for training purposes only. It is not robust enough for general use as a security application. You should only use it in this training class, and you should never use it to encrypt critical files.

The application package consists of four components:

• A C# executable which implements the user interface.
• A mixed-mode DLL that uses C++/CLI to get from managed code to native.
• A bridge DLL consisting of 100% native C code that interacts with the enclave.
• The Intel SGX enclave which implements the encryption routines.

Lab Exercises

The exercises in Task 3 of the Intel SGX Web Training Hands-on Lab Manual are designed to get you familiar with the File Encrypter project and its source code.

• Task 3.1: Run the File Encrypter application.
• Task 3.2: Review the File Encrypter solution and project files in Microsoft Visual Studio.
• Task 3.3: Review the File Encrypter application components.

Part 4: The Enclave Definition Language

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 ECALLS, which are the entry points into the enclave from the untrusted application. An enclave may also have Outside Calls, or OCALLS, which allow enclave functions to call out to the untrusted application and then return to the enclave. These ECALLs and OCALLs make up an enclave’s interface, which is defined in the encave's 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.

enclave {

	trusted {
		public void store_secret([in, string] char *msg);
		public int print_hash([out] sgx_status_t *error); 
	};
	untrusted {
		void o_print_hash([in] unsigned char hash[32]); 
	};

}; 

The video explains the basics of EDL, such as passing parameters into and out of enclaves, both by value and by reference.

Lab Exercises

In Task 4 of the Intel SGX Web Training Hands-on Lab Manual, you'll be adding code to the sample File Encrypter application. You'll fill in the EDL file, and add the ECALLs to the EnclaveWrapper project. The lab document will step you through what needs to be done, and the sections of code that you will modify are clearly indicated in comment blocks. The comments will tell you what you need to know to implement the missing code.

• Task 4.1: The EDL file
• Task 4.2: Adding ECALLs
• Task 4.3: Compiling and testing
• Task 4.4: Advanced exercises

Part 5: Advanced Enclave Definition Language

The Enclave Definition Language allows you to marshal data buffers in and out of your ECALLs and OCALLs. Sometimes, however, you need to provide additional information when passing pointers as parameters. There are also situations where you need direct control over how the pointers are handled.

The video discusses some of the advanced feartures of EDL, such as passing void pointers, raw pointers addresses, and specifying ECALLs that can only be called from within an OCALL.

Lab Exercises

In Task 5 of the Intel SGX Web Training Hands-on Lab Manual, you'll be using some of the advanced features of EDL to pass raw pointers into the enclave. You'll also implement an OCALL that demonstrates a technique for calling back to managed code.

• Task 5.1, Part 1: Advanced EDL
• Task 5.1, Part 2: Implementing an OCALL

Part 6: Debugging Enclaves

Intel SGX enclaves can be built in debug mode or in release mode.

• A debug mode enclave is inspectable. You can attach to it with the Intel SGX debugger, examine its state, and step through its code just as you would when debugging any other application. When you are actively developing your Intel SGX application, you are probably building your enclave in debug mode. The CPU will allow any debug-mode enclave to launch, but because you can attach to them with the Intel SGX debugger they are not secure. Enclaves built in debug mode should never be deployed in a production application.
• A release mode cannot be debugged under any circumstances and this restriction is enforced by the CPU.

Debugging an Intel SGX enclave requires the use of special CPU instructions, and that means you must use the Intel SGX debugger that is included with the Intel SGX Software Development Kit. Debuggers without Intel SGX will simply skip over enclave code.

When developing a managed application, such as one written in C#, you can’t run the Intel SGX debugger directly from within Visual Studio. Managed applications must be debugged by attaching to the running process.

The video shows the use of hte debugger on life applications, and discusses some of the nuances of using the Intel SGX debugger in detail.

Lab Exercises

In Task 6 of the Intel SGX Web Training Hands-on Lab Manual, you'll use the debugger on a small, native Intel SGX application.

• Task 6.1: Debugging Intel SGX applications

Part 7: Data Sealing

Enclaves are essentially stateless: they are destroyed when the system goes to sleep, when the application exits, and of course when the application explicitly destroys them. When an enclave is destroyed, all of its contents are lost.

To preserve the information that’s stored in an enclave, you must explicitly send it outside the enclave to untrusted memory. Intel SGX provides a capability called data sealing which encrypts enclave data in the enclave using an encryption key that is derived from the CPU. This encrypted data block, also called the sealed data, can only be decrypted, or unsealed, on the same system (and, typically, in the exact same enclave) where it was created. The encryption itself provides assurances of confidentiality, integrity, and authenticity on the data.

There is an important caveat with data sealing that can have significant security implications: enclaves do not authenticate the untrusted application. You must not assume that only your application will load your enclave, or that your ECALLs will be invoked in a specific order. Anyone can load your enclave and execute its ECALLs in any order they choose. Your enclave’s API must not allow the sealing and unsealing capability to leak secrets, or grant unauthorized access to them.

The video discusses data sealing in detail, and explains the difference between the two sealing policies: MRENCLAVE and MRSIGNER.

Lab Exercises

In Task 7 of the Intel SGX Web Training Hands-on Lab Manual, we return to the File Encrypter sample application. You'll modify the enclave to use data sealing on the password so it can be safely sent to unprotected memory. This allows the enclave to effectively preserve the password across power events.

• Task 7.1: Add data sealing to the application.