Skip to content

Latest commit

 

History

History
134 lines (90 loc) · 6.22 KB

BuildSamplesLinux.md

File metadata and controls

134 lines (90 loc) · 6.22 KB
Raw

Building and Running the Samples on Linux

All the samples that come with the Open Enclave SDK installation are structured into two subdirectories (one for enclave and one for host) accordingly.

Files/dir contents
Makefile Makefile for building all samples
CMakeLists.txt CMake file for building for all samples
./enclave Files needed for building the sample enclave
./host Files needed for building the host

For example:

/home/yourusername:~/openenclave/share/openenclave/samples/helloworld$ ls -l
total 12
drwxr-xr-x 2 yourusername yourusername 4096 Aug 16 13:59 enclave
drwxr-xr-x 2 yourusername yourusername 4096 Aug 16 13:59 host
-rw-r--r-- 1 yourusername yourusername  245 Aug 16 13:57 Makefile

Install prerequisites

Before you can build and run samples, you would need to install the prerequisites as described in the getting started documentation.

Prepare samples

Building samples involves writing files into the working directory, which is not allowed in /opt unless it's running in the context of superuser (sudo).

Before building any of the samples, please copy them out of the /opt/openenclave/share/openenclave/samples directory to a directory where your current user has write permissions.

For example, assuming the Open Enclave SDK is installed to the default location /opt/openenclave:

cp -r /opt/openenclave/share/openenclave/samples ~/mysamples

Steps to build and run samples

Each sample comes with two different build systems: one using GNU Make and pkg-config, the other using CMake. They help simplify the sample building process, which involves building and signing binaries.

Source the openenclaverc file

Before building any samples, you need to source the openenclaverc file to set up environment variables for sample building. The openenclaverc file can be found in the share/openenclave subdirectory of the package installation destination.

You can use . in Bash to source:

. <package_installation_destination>/share/openenclave/openenclaverc

For example, if your package_installation_destination is /opt/openenclave:

. /opt/openenclave/share/openenclave/openenclaverc

Note: You will get error messages like the following if this sourcing step was skipped.

make[2]: Entering directory '.../openenclave/samples/helloworld/enclave`
Package oeenclave-clang was not found in the pkg-config search path.
Perhaps you should add the directory containing `oeenclave-clang.pc`

After this you can use either GNU make or CMake to build the samples.

Build the samples using GNU Make

The Makefile in the root of each sample directory has three rules

  • build: Calls into the Makefiles in the host and enclave directories to build
  • clean: Calls in to the Makefiles in the host and enclave directories to clean all generated files
  • run: Runs the generated host executable, passing the signed enclave executable as a parameter To build a sample using GNU Make, change directory to your target sample directory and run make build to build the sample. Then execute "make run" to run the sample.

For example, for the helloworld sample:

~/openenclave/share/openenclave/samples$ cd helloworld/
~/openenclave/share/openenclave/samples/helloworld$ make build
~/openenclave/share/openenclave/samples/helloworld$ make run

Build the samples using CMake

To build a sample using CMake, change directory to your target sample directory and execute the following commands:

mkdir build && cd build
cmake ..
make

Then execute "make run" to run the sample.

For example:

~/openenclave/share/openenclave/samples$ cd helloworld/
~/openenclave/share/openenclave/samples/helloworld$ mkdir build && cd build
~/openenclave/share/openenclave/samples/helloworld/build$ cmake ..
~/openenclave/share/openenclave/samples/helloworld/build$ make
~/openenclave/share/openenclave/samples/helloworld/build$ make run

Determine call path for SGX quote generation in attestation sample

In the attestation sample, you can either take the in-process call path or out-of-process call path to generate evidence of format OE_FORMAT_UUID_SGX_ECDSA. If you wish to specify the call path it takes to generate a quote, here is what you can do:

  • To perform in-process quote generation, unset the environment variable SGX_AESM_ADDR and ensure that the DCAP library is installed.
  • To perform out-of-process quote generation, set the environment variable SGX_AESM_ADDR to any value and ensure that SGX SDK quote-ex Library is installed.

If SGX_AESM_ADDR is not set, one can run an existing OE app with out-of-process attestation, using $ SGX_AESM_ADDR=1 <app_name>.

  • If SGX_AESM_ADDR=1 is added to /etc/environment instead, then it will set SGX_AESM_ADDR for the whole system. To unset it for the whole system, simply remove the line. These actions require elevated privileges.
  • If SGX_AESM_ADDR is set by default globally, to run an existing OE app with in-process attestation, one can use $ env -u SGX_AESM_ADDR <app_name>.

Please refer to the following document for more information:

Running the sample in simulation mode

Some of the samples can be run in simulation mode. To run the sample in simulation mode, use make simulate.

Note

More detailed information on what the samples contain, how oeedger8r is used and what files are generated during the build process can be found in the helloworld sample README.

For details on how to configure build and sign options, refer to Enclave Building and Signing.

Build and Run samples with LVI mitigation

Refer to the LVI section in the helloworld sample for more details.