This repository has been archived by the owner on Dec 20, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 29
/
Copy pathREADME.html
105 lines (105 loc) · 11.9 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<title></title>
<style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<h1 id="introduction">Introduction</h1>
<p>This project provides a proof-of-concept implementation on how to integrate Intel SGX remote attestation into the TLS connection setup. Conceptually, we extend the standard X.509 certificate with SGX-related information. The additional information allows the receiver of the certificate to verify that it is indeed communicating with an SGX enclave. The accompanying <a href="whitepaper.pdf">white paper</a> "Integrating Remote Attestation with Transport Layer Security" provides more details. RA-TLS supports <a href="https://software.intel.com/sites/default/files/managed/57/0e/ww10-2016-sgx-provisioning-and-attestation-final.pdf">EPID</a> and <a href="https://software.intel.com/sites/default/files/managed/f1/b8/intel-sgx-support-for-third-party-attestation.pdf">ECDSA</a>-based attestation.</p>
<p>Documentation on ECDSA-based attestation is <a href="README-ECDSA.html">split out into a separate document</a>.</p>
<h2 id="repository-structure">Repository Structure</h2>
<p>The repository root directory contains code to generate and parse extended X.509 certificates. The build system creates the following executables:</p>
<ul>
<li><p>Sample server (attester)</p>
<ul>
<li>using the SGX SDK based on <a href="deps/wolfssl-examples/SGX_Linux">wolfSSL</a></li>
<li>using <a href="https://github.com/oscarlab/graphene">Graphene</a>, <a href="https://sconedocs.github.io">SCONE</a> or <a href="https://github.com/lsds/sgx-lkl">SGX-LKL</a> based on <a href="deps/wolfssl-examples/tls/server-tls.c">wolfSSL</a></li>
<li>using <a href="https://github.com/oscarlab/graphene">Graphene</a> based on <a href="deps/mbedtls/programs/ssl/ssl_server.c">mbedtls</a></li>
<li><a href="sgxlkl/https-server/https-server.py">Python-based HTTPS web server</a> running on SGX-LKL</li>
</ul></li>
<li><p>Non-SGX clients (challengers) based on different TLS libraries</p>
<ul>
<li><a href="deps/mbedtls/programs/ssl/ssl_client1.c">mbedtls</a></li>
<li><a href="deps/wolfssl-examples/tls/client-tls.c">wolfSSL</a></li>
<li><a href="openssl-client.c">OpenSSL</a></li>
</ul></li>
<li><p>Graphene client and server doing mutual attestation</p>
<ul>
<li><a href="deps/wolfssl-examples/tls/server-tls.c">server-tls.c</a></li>
<li><a href="deps/wolfssl-examples/tls/client-tls.c">client-tls.c</a></li>
</ul></li>
</ul>
<p>Some files may only exist after building the sources.</p>
<h2 id="code-structure">Code Structure</h2>
<p>The code is split into two parts: the attester and the challenger. The challenger parses certificates, computes signatures and hashsums. The attester generates keys, certificates and interfaces with SGX. The challenger and attester are implemented with three different TLS libraries: wolfSSL (<a href="wolfssl-ra-challenger.c">challenger</a>, <a href="wolfssl-ra-attester.c">attester</a>), mbedtls (<a href="mbedtls-ra-challenger.c">challenger</a>, <a href="mbedtls-ra-attester.c">attester</a>) and OpenSSL (<a href="openssl-ra-challenger.c">challenger</a>, <a href="openssl-ra-attester.c">attester</a>).</p>
<p>The attester's code consists of <a href="sgxsdk-ra-attester_t.c">trusted</a> and <a href="sgxsdk-ra-attester_u.c">untrusted</a> SGX-SDK specific code to produce a quote using the SGX SDK. If the SGX SDK is not used, e.g., when using Graphene, there is code to <a href="nonsdk-ra-attester.c">obtain the SGX quote</a> by directly communicating with the platform's architectural enclave.</p>
<p>Given a quote, there is <a href="ias-ra.c">code to obtain an attestation verification report</a> from the Intel Attestation Service. This code depends on libcurl.</p>
<p><a href="deps/wolfssl-examples/SGX_Linux">An SGX SDK-based server</a> based on wolfSSL demonstrates how to use the <a href="ra-attester.h">public attester API</a>.</p>
<p>We provide three non-SGX clients (<a href="deps/mbedtls/programs/ssl/ssl_client1.c">mbedtls</a>, <a href="deps/wolfssl-examples/tls/client-tls.c">wolfSSL</a>, <a href="openssl-client.c">OpenSSL</a>) to show how seamless remote attestation works with different TLS libraries. They use the public <a href="ra-challenger.h">challenger's API</a>. There is one SGX client demonstrating mutual authentication (code: <a href="deps/wolfssl-examples/tls/client-tls.c">client-tls.c</a>, binary: wolfssl-client-mutual).</p>
<h1 id="build">Build</h1>
<p>We have tested the code with enclaves created using the Intel SGX SDK, Graphene, SCONE and SGX-LKL.</p>
<h2 id="prerequisites">Prerequisites</h2>
<p>The code is tested with the <a href="https://01.org/intel-softwareguard-extensions/downloads/intel-sgx-linux-2.4-release">Intel SGX Linux 2.4 Release</a> installed on the host. Results may vary with different versions. Follow the official instructions to install the components and ensure they are working as intended. For Graphene, follow <a href="https://github.com/oscarlab/graphene/wiki/SGX-Quick-Start">their instructions</a> to build and load the Graphene kernel module. Only the Graphene kernel module is required as a prerequisite. Graphene itself is built by the scripts.</p>
<p>To use the Intel Attestation Service for EPID-based attestation an <a href="https://api.portal.trustedservices.intel.com/EPID-attestation">account must be created</a>. The registration process will provide a subscription key and a software provider ID (SPID). The script <a href="ra_tls_options.c.sh" class="uri">ra_tls_options.c.sh</a> generates a C source file with these values. Either define the environment variables before building or invoke the script manually, i.e., <code>SPID=... EPID_SUBSCRIPTION_KEY=... ECDSA_SUBSCRIPTION_KEY=... QUOTE_TYPE=... bash ra_tls_options.c.sh</code>. See <a href="ra_tls_options.c.sh" class="uri">ra_tls_options.c.sh</a> for the specific format of each variable. ECDSA-based attestation <a href="https://api.portal.trustedservices.intel.com/provisioning-certification">requires a separate registration.</a></p>
<p>We support building the code in a Docker container. We provide a <a href="Dockerfile" class="uri">Dockerfile</a> to install all the required packages. If you prefer to build on your host system, the Dockerfile documents which packages and additional software to install. You can create an image based on the Dockerfile as such</p>
<pre><code>docker build -t ratls .</code></pre>
<p>If you want to use SCONE and have access to their Docker images, edit the Dockerfile to use their image as the base instead of the default Ubuntu 16.04 (see first two lines of Dockerfile)</p>
<pre><code>docker build -t ratls-scone .</code></pre>
<h2 id="build-instructions">Build Instructions</h2>
<p>The <a href="build.sh">build script</a> creates executables based on either the Intel SGX SDK, Graphene, SCONE or SGX-LKL, depending on the first parameter</p>
<pre><code>./build.sh sgxsdk|graphene|scone|sgxlkl</code></pre>
<p>To build in a container using the Docker image created earlier, execute the following command in the project's root directory</p>
<pre><code>docker run --device=/dev/isgx --device=/dev/gsgx \
--privileged=true \
-v /var/run/aesmd:/var/run/aesmd \
-v$(pwd):/project -it [Docker image] bash</code></pre>
<p>where [Docker image] is the name of the Docker image created earlier, i.e., either ratls or ratls-scone. The parameter --privileged=true is only needed for SGX-LKL to be able to mount loopback devices and change iptables.</p>
<p>In the running container, change the directory and kick-off the build process</p>
<pre><code>cd /project
./build.sh sgxsdk|graphene|scone|sgxlkl</code></pre>
<h1 id="run">Run</h1>
<h2 id="intel-sgx-sdk">Intel SGX SDK</h2>
<p>To start the Intel SGX SDK based wolfSSL server execute</p>
<pre><code>( cd deps/wolfssl-examples/SGX_Linux ; ./App -s )</code></pre>
<p>With the server up and running, execute any of the <a href="#the-clients">clients</a>. If you are running in a container, you can get a 2nd console as follows (or run the server in the background by appending & at the end of the above command).</p>
<pre><code>docker ps</code></pre>
<p>Use the container's ID with the following command for a 2nd console.</p>
<pre><code>docker exec -ti --user root [container id] bash</code></pre>
<h2 id="graphene">Graphene</h2>
<p>First, start a socat instance to make AESM's named Unix socket accessible over TCP/IP.</p>
<pre><code>socat -t10 TCP-LISTEN:1234,bind=127.0.0.1,reuseaddr,fork,range=127.0.0.0/8 UNIX-CLIENT:/var/run/aesmd/aesm.socket &</code></pre>
<p>Next, start the server application on Graphene</p>
<pre><code>SGX=1 ./deps/graphene/Runtime/pal_loader ./[binary]</code></pre>
<p>where [binary] can be mbedtls-ssl-server, wolfssl-ssl-server or wolfssl-ssl-server-mutual.</p>
<h2 id="scone">SCONE</h2>
<p>Similar to Graphene, we use socat to make AESM accessible over TCP/IP. SCONE can in principle to talk to AESM's named Unix socket directly, but support for this is currently not implemented.</p>
<pre><code>socat -t10 TCP-LISTEN:1234,bind=127.0.0.1,reuseaddr,fork,range=127.0.0.0/8 UNIX-CLIENT:/var/run/aesmd/aesm.socket &</code></pre>
<p>Next, execute the SCONE binary as such</p>
<pre><code>./scone-wolfssl-ssl-server</code></pre>
<h2 id="sgx-lkl">SGX-LKL</h2>
<p>To set up the TAP device (used by SGX-LKL for networking), iptables (required for SGX-LKL to be able to reach the internet) and starts an socat daemon (to talk to the host's AESMD). EXTERNAL_INTERFACE specifies your "external" interface (typically eth0), i.e., the one which connects you to the internet.</p>
<pre><code>EXTERNAL_IFACE=eth0 make -C sgxlkl up-sgxlkl-network</code></pre>
<p>We provide two applications for SGX-LKL. First, a simple server based on wolfssl. This is similar to the examples provided for the other systems. Use Ctrl-C to stop the server.</p>
<pre><code>make -C sgxlkl run-wolfssl-server</code></pre>
<p>Use the openssl-client to connect to the server and print its SGX identity</p>
<pre><code>echo -n hello | ./openssl-client -p 11111 -h 10.0.1.1</code></pre>
<p>Second, there is a <a href="sgxlkl/https-server/https-server.py">Python-based HTTPS server</a>. We preload (LD_PRELOAD) a library with the server. The <a href="sgxlkl/ldpreload.c">preloaded library's</a> initialization routine writes the key and certificate to /tmp/key and /tmp/crt, respectively. The server reads the RA-TLS key and certificate from the file system instead of calling the library directly.</p>
<pre><code>make -C sgxlkl run-https-server</code></pre>
<p>Warnings about LD_PRELOAD not being able to find /ldpreload.so can be ignored. LD_PRELOAD is also applied to the sgx-lkl-run binary, but ldpreload.so only exists within the LKL environment. The server listens on 10.0.1.1:4443. Using the RA-TLS-aware openssl-client you can connect to it as such</p>
<pre><code>./openssl-client -p 4443 -h 10.0.1.1</code></pre>
<p>To stop socat, remove iptable rules and the TAP interface issue</p>
<pre><code>EXTERNAL_IFACE=eth0 make -C sgxlkl down-sgxlkl-network</code></pre>
<h2 id="the-clients">The clients</h2>
<h3 id="non-sgx-clients">Non-SGX clients</h3>
<p>Execute any one of the non-SGX binaries wolfssl-client, mbedtls-client or openssl-client in the project's root directory.<br />
The openssl-client is most versatile as it allows to specify the IP and port to connect to via command line parameters.<br />
Each client outputs a bunch of connection-related information, such as the server's SGX identity (MRENCLAVE, MRSIGNER). You can cross-check this with what the server reports in its output.</p>
<h3 id="sgx-client">SGX client</h3>
<p>The Graphene client wolfssl-client-mutual only works in combination with wolfssl-ssl-server-mutual.</p>
<pre><code>SGX=1 ./deps/graphene/Runtime/pal_loader ./wolfssl-client-mutual</code></pre>
</body>
</html>