content.html 40 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557
  1. <?xml version='1.0' encoding='utf-8'?>
  2. <!--
  3. Copyright (c) 2016 Intel Corporation.
  4. All rights reserved. This program and the accompanying materials
  5. are made available under the terms of the Eclipse Public License v1.0
  6. which accompanies this distribution, and is available at
  7. http://www.eclipse.org/legal/epl-v10.html
  8. Contributors:
  9. Intel Corporation - initial implementation and documentation
  10. -->
  11. <html xmlns:MadCap='http://www.madcapsoftware.com/Schemas/MadCap.xsd' MadCap:lastBlockDepth='4' MadCap:lastHeight='1043' MadCap:lastWidth='652'>
  12. <head>
  13. <link href='Resources/Stylesheets/intel_css_styles.css' rel='stylesheet' type='text/css' />
  14. </head>
  15. <body>
  16. <div id='SGX_title'>
  17. <h1 class="firsttitle">Intel(R) Software Guard Extensions Plug-in for Eclipse*</h1>
  18. <h2>Developer Guide</h2>
  19. <p>Intel(R) Software Guard Extensions (Intel(R) SGX) is an Intel technology for application developers seeking to protect select code and data from disclosure or
  20. modification. Intel(R) SGX makes such protections possible through the use of
  21. enclaves. Enclaves are protected areas of execution. Application code can be put
  22. into an enclave through special instructions and software made available to
  23. developers by the Intel(R) SGX SDK.</p>
  24. <p><a href="#Legal_Information">Legal Information</a>
  25. </p>
  26. </div>
  27. <div id='Legal_Information'>
  28. <h1>Legal Information</h1>
  29. <p>No license (express or implied, by estoppel or otherwise) to any intellectual
  30. property rights is granted by this document.</p>
  31. <p>Intel disclaims all express and implied warranties, including without
  32. limitation, the implied warranties of merchantability, fitness for a particular
  33. purpose, and non-infringement, as well as any warranty arising from course
  34. of performance, course of dealing, or usage in trade.</p>
  35. <p>This document contains information on products, services and/or processes
  36. in development. &#160;All information provided here is subject to change
  37. without notice. Contact your Intel representative to obtain the latest
  38. forecast, schedule, specifications and roadmaps.</p>
  39. <p>The products and services described may contain defects or errors known
  40. as errata which may cause deviations from published specifications. Current
  41. characterized errata are available on request.</p>
  42. <p>Intel technologies features and benefits depend on system configuration
  43. and may require enabled hardware, software or service activation. Learn
  44. more at Intel.com, or from the OEM or retailer.</p>
  45. <p>Copies of documents which have an order number and are referenced in
  46. this document may be obtained by calling 1-800-548-4725 or by visiting
  47. <a href="http://www.intel.com/design/literature.htm">www.intel.com/design/literature.htm</a>.</p>
  48. <p>Intel, the Intel logo, Xeon, and Xeon Phi are trademarks of Intel Corporation
  49. in the U.S. and/or other countries. </p>
  50. <table style="border-left-style: solid;border-left-width: 1px;border-right-style: solid;border-right-width: 1px;border-top-style: solid;border-top-width: 1px;border-bottom-style: solid;border-bottom-width: 1px;">
  51. <col />
  52. <tr>
  53. <th>
  54. <p>Optimization Notice</p>
  55. </th>
  56. </tr>
  57. <tr bgcolor="#CCECFF">
  58. <td>
  59. <p>Intel's compilers may or may not optimize to the same degree
  60. for non-Intel microprocessors for optimizations that are not unique
  61. to Intel microprocessors. These optimizations include SSE2, SSE3,
  62. and SSSE3 instruction sets and other optimizations. Intel does
  63. not guarantee the availability, functionality, or effectiveness
  64. of any optimization on microprocessors not manufactured by Intel.
  65. Microprocessor-dependent optimizations in this product are intended
  66. for use with Intel microprocessors. Certain optimizations not
  67. specific to Intel microarchitecture are reserved for Intel microprocessors.
  68. Please refer to the applicable product User and Reference Guides
  69. for more information regarding the specific instruction sets covered
  70. by this notice.</p>
  71. <p style="text-align: right;">Notice revision #20110804</p>
  72. </td>
  73. </tr>
  74. </table>
  75. <p>* Other names and brands may be claimed as the property of others.</p>
  76. <p>© 2016 Intel Corporation.</p>
  77. </div>
  78. <div id='Introduction'>
  79. <h1>Introduction</h1>
  80. <p>This <i>Developer Guide</i> is intended for use by Independent Service Vendors who wish to harden their Linux* applications using Intel(R) SGX Technology, code named Intel(R) Software Guard Extensions. The guide describes the procedure for installation of Intel(R) SGX Plugin for Eclipse* IDE and development of Intel(R) SGX components using the plugin. The Intel(R) SGX Plugin for Eclipse leverages on the Intel(R) Software Guard Extensions SDK, which is a collection of APIs, libraries and tools that enable you to develop, build and debug Intel(R) SGX applications in C/C++.</p>
  81. <p>To learn more about the Intel(R) Software Guard Extensions SDK, see the <i>Intel(R) Software Guard Extensions SDK for Linux* OS Developer Reference</i>.</p>&#160;</div>
  82. <div id='Introducing_Intel_Software_Guard _Extensions_Eclipse_Plugin'>
  83. <h2>Introducing Intel(R) Software Guard Extensions</h2>
  84. <p>Intel(R) Software Guard Extensions is a new Intel technology, whose objective is to enable a high level of protection of secrets. It operates by allocating hardware-protected memory where code and data reside. The protected memory area within an application process is called an enclave. Data within the enclave memory can only be accessed by code that resides within that enclave. Enclave code can be invoked by special instructions.</p>
  85. <p>An enclave can be built and loaded as a shared object.</p>
  86. <p>Throughout this document, Intel(R) SGX refers to Intel(R) Software Guard Extensions.</p>
  87. <p>An Intel(R) SGX application design is different from the design of non- Intel(R) SGX application as it specifies dividing the application into two logical parts:</p>
  88. <ul>
  89. <li><i>Trusted</i> part. The code that accesses the secret resides here and it is called an enclave. More than one enclave can exist in an application.</li>
  90. <li><i>Untrusted</i> part. This includes the rest of the modules in the application, that is outside in an enclave.</li>
  91. </ul>
  92. <p>The trusted components and untrusted components are developed as separate modules.</p>
  93. <p>The trusted part or the enclave is implemented in C or C++. It is supplied as a collection of functions and data packaged in the form of a dynamically loaded library, a DLL in Windows* OS and a shared object in Linux* OS. It may be supplied either as a pre-built signed library or as a signed shared library built during compilation of the untrusted component.</p>
  94. <p>Enclave functions within an enclave library are wrapped by auto-generated proxy and bridge functions that simplify the mechanism of using the Intel(R) SGX technology by developers.</p>
  95. <p>The role of these functions is to handle the following tasks:</p>
  96. <ul>
  97. <li>Call an enclave function from untrusted code, also called an ECALL (enclave call).</li>
  98. <li>Call an untrusted function from within an enclave, also called an OCALL (outside call).</li>
  99. <li>Handle interrupts.</li>
  100. <li>Handle exceptions.</li>
  101. </ul>
  102. <p>The proxy and bridge functions are generated by the <code>sgx_edger8r</code> tool provided by Intel(R) SGX SDK. It reads an <i>edl</i> file (Enclave Descriptor Language) which describes the functions that form the <i>trusted</i> and <i>untrusted</i> component boundaries within the application.</p>
  103. <p>After the enclave is built, a signed version of it is created using the tool <code>sgx_sign</code> also provided by Intel(R) SGX SDK. It is this signed version may be loaded and executed in the encrypted memory.</p>
  104. <p>Enclaves may have some specific properties which are added as meta-information during the signing process. The meta-information is stored in one configuration xml file per enclave. See more details about meta-information in <i>Intel(R) Software Guard Extensions SDK for Linux* OS Developer Reference</i>.</p>
  105. </div>
  106. <div id='Introducing_Intel_Software_Guard_Extensions'>
  107. <h2>Introducing Intel(R) Software Guard Extensions Eclipse* Plug-in</h2>
  108. <p>The Intel(R) Software Guard Extensions Eclipse* Plug-in helps the enclave developer to maintain enclaves and untrusted related code inside Eclipse* C/C++ projects. To use this support, add SGX nature to the C/C++ project. See <a href="#Adding_SGX_Nature_to_a_Project">Adding SGX Nature to a Project</a> for details.</p>
  109. <p>Once the SGX nature is added to a project, you will have access to the SGX commands. SGX nature adds also a folder called <code>sgx</code> to the root of the project, and a Makefile inside it. All resources of the project managed by Intel(R) Software Guard Extensions Eclipse Plug-inare located inside this directory. You can build and run enclaves related code using GNU* Make tool through the Makefile.</p>
  110. <p>The plugin is generating minimal but ready-to-work code skeletons, complete with their own Makefile having all the required make targets as to call <code>sgx_edger8r</code> tool to generate the proxies and bridges, compile these source, generate a shared object and finally, to sign the enclave with the <code>sgx_sign</code> tool. This provide a starting point you may build upon.</p>
  111. </div>
  112. <div id='Getting_Started'>
  113. <h1>Getting Started with Intel(R) Software Guard Extensions Eclipse* Plug-in</h1>
  114. <p>This section contains steps to set up your Intel(R) Software Guard Extensions Eclipse* Plug-in on a Linux* system, including necessary softwares, steps to install the product, and steps to configure your preferred product directory.</p>
  115. <p>• Pre-requisites</p>
  116. <p>• Installing Intel(R) Software Guard Extensions Eclipse* Plug-in</p>
  117. <p>• Configuring Intel(R) Software Guard Extensions Eclipse* Plug-in</p>&#160;</div>
  118. <div id='Prerequisites'>
  119. <h2>Pre-requisites</h2>
  120. <p>To use Intel(R) Software Guard Extensions Eclipse Plug-in, install the following softwares:</p>
  121. <ul>
  122. <li>Eclipse* Mars 1 with CDT IDE for C/C++ Developpers (version 4.5.1). To use this version, install Java* Development Kit (JDK) or Java* Runtime Environment (JRE) version 1.8 or above.</li>
  123. <li>gcc/g++ tools</li>
  124. <li>Openssl*</li>
  125. <li>Intel(R) SGX SDK for Linux* OS</li>
  126. </ul>
  127. </div>
  128. <div id='Installing_Intel_Software_Guard_Extensions_Eclipse_Plugin'>
  129. <h2>Installing Intel(R) Software Guard Extensions Eclipse* Plug-in</h2>
  130. <p>Install Intel(R) Software Guard Extensions Eclipse* Plug-in as a regular Eclipse Plugin:</p>
  131. <ol>
  132. <li>Download the zip archive of Intel(R) Software Guard Extensions Eclipse Plug-in from Intel Site</li>
  133. <li>
  134. <p>Go to <b>Help menu -&gt; Install New Software</b>. Click the <b>Add</b> button for the <b>Work with</b> field to open the <b>Add Repository</b> dialog as shown in the following graphic:</p>
  135. <p>
  136. <img src="Resources/Images/Add_Repository_Dialog.png" />
  137. </p>
  138. <p class="figcap">Add Repository Dialog</p>
  139. </li>
  140. <li>
  141. <p>Enter <code>SGX Archive</code> in the <b>Name</b> field . Click the <b>Archive...</b> button and select the location of the downloaded archive as shown in the following graphic:</p>
  142. <p>
  143. <img src="Resources/Images/The_Location_of_the_Plugin_zip_Archive.png" />
  144. </p>
  145. <p class="figcap">The Location of the Plugin zip Archive</p>
  146. </li>
  147. <li>Press <b>OK</b> to add the archive as a repository.</li>
  148. <li>In the <b>Install</b> dialog, select the <b>Software Guard Extensions Plugin</b> check-box and proceed with the usual steps.</li>
  149. </ol>
  150. </div>
  151. <div id='Configuring_Intel_Software_Guard_Extensions_Eclipse_Plug-in'>
  152. <h2>Configuring Intel(R) Software Guard Extensions Eclipse* Plug-in</h2>
  153. <p>If you do not install Intel(R) SGX SDK for Linux* OS in the default location, you need to specify the path for Intel SGX SDK using the following steps:</p>
  154. <ol>
  155. <li>
  156. <p>Go to <b>Window menu -&gt;Preferences</b>. Enter SGX in the filter text field to quickly locate the <b>SGX Preferences</b> page.</p>
  157. <p>
  158. <img src="Resources/Images/SGX_Preference_Page.png" />
  159. </p>
  160. <p class="figcap">SGX Preference Page</p>
  161. </li>
  162. <li>Enter the path for Intel SGX SDK for Linux OS in the <b>SGX SDK Directory</b> field.</li>
  163. </ol>
  164. </div>
  165. <div id='Command_Reference'>
  166. <h1>Command Reference</h1>
  167. <p>This topic provides the command reference for the following scenarios of using Intel(R) Software Guard Extensions Eclipse* Plug-in:</p>
  168. <ul>
  169. <li>Adding SGX nature to a project</li>
  170. <li>Adding an SGX enclave</li>
  171. <li>Adding an SGX trusted library</li>
  172. <li>Adding an SGX untrusted module</li>
  173. <li>Updating SGX enclave signing key</li>
  174. <li>Updating enclave configuration files</li>
  175. <li>Two steps sign enclave</li>
  176. </ul>
  177. <p>All commands brought by Intel(R) Software Guard Extensions Eclipse Plug-in are available by right-clicking on the Project root in Project explorer view in menu <b>Software Guard Extension Tools</b>:</p>&#160;<p><img src="Resources/Images/Project_Explorer.png" /></p><p class="figcap">Project Explorer</p>&#160;</div>
  178. <div id='Adding_SGX_Nature_to_a_Project'>
  179. <h2>Adding SGX Nature to a Project</h2>
  180. <p>The <i>nature</i> of an Eclipse project is a concept defined by an Eclipse Platform which allows a plug-in to tag a project as a specific kind of project. Intel(R) Software Guard Extensions uses an <i>SGX nature</i> to add SGX-specific behavior to projects. Project natures are defined by plug-ins, and are typically added or removed per-project when the user performs some action defined by the plug-in.</p>
  181. <p>To use Intel(R) Software Guard Extensions Eclipse Plug-in in your project, you need to add SGX nature to it. You may either add SGX nature to a pre-existing C/C++ project or create a project with SGX nature from start. See <a href="#Adding_SGX_Nature_to_a_non_SGX_project">Adding SGX Nature to a non-SGX project</a> and <a href="#Creating_a_New_C_C_Project_with_SGX_Nature">Creating a New C/C++ Project with SGX Nature</a> for how to complete these tasks.</p>
  182. </div>
  183. <div id='Adding_SGX_Nature_to_a_non_SGX_project'>
  184. <h3>Adding SGX Nature to a non-SGX project</h3>
  185. <p>When you have a C/C++ project created without Intel SGX, you cannot use Intel SGX support. In this case, you need to add SGX nature to this project to use Intel SGX support:</p>
  186. <ol>
  187. <li>Right-click on the project root <![CDATA[ ]]></li>
  188. <li>
  189. <p>Select <b>Software Guard Extension Tools → Add SGX Nature</b></p>
  190. <p>
  191. <img src="Resources/Images/Add_SGX_Nature.png" />
  192. </p>
  193. <p class="figcap">Add SGX Nature</p>
  194. </li>
  195. </ol>
  196. <p>After you add the SGX nature to your project, you should see:</p>
  197. <ul>
  198. <li>
  199. <p>A subdirectory <code>sgx</code> in the project which contains a Makefile file.</p>
  200. <p>
  201. <img src="Resources/Images/Makefile_for_Intel_SGX.png" />
  202. </p>
  203. <p class="figcap">Makefile for Intel(R) SGX</p>
  204. </li>
  205. <li>
  206. <p>The Intel SGX tools as shown in the following graphic:</p>
  207. <p>
  208. <img src="Resources/Images/Intel_SGX_Tools.png" />
  209. </p>
  210. <p class="figcap">Intel(R) SGX Tools</p>
  211. </li>
  212. <li>
  213. <p>New configurations specific to SGX technology. You may see the configurations for the project by clicking to the down arrow of button <img src="Resources/Images/Down_Arrow_Button.png" /> usually found at the top of the Eclipse window:</p>
  214. <p>
  215. <img src="Resources/Images/Configurations_Specific_to_Intel_SGX_Technology.png" />
  216. </p>
  217. <p class="figcap">Configurations Specific to Intel(R) SGX Technology</p>
  218. </li>
  219. </ul>
  220. </div>
  221. <div id='Creating_a_New_C_C_Project_with_SGX_Nature'>
  222. <h3>Creating a New C/C++ Project with SGX Nature</h3>
  223. <p>You can create a new project with SGX nature. To create such a project, follow these steps:</p>
  224. <ol>
  225. <li>
  226. <p>Open a standard Eclipse new project: <b>File menu → Project...</b> . If you have installed Intel® Software Guard Extensions Eclipse Plug-in, you can see the category C/C++ with SGX Enabled in the <b>New Project</b> dialog.</p>
  227. <p>
  228. <img src="Resources/Images/New_Project.png" />
  229. </p>
  230. <p class="figcap">New Project</p>
  231. <p>This category has 2 sub-categories, <b>SGX C project</b> and <b>SGX C++ project</b>. These sub-categories are similar to the sub-categories C Project and C++ Project of standard C/C++ category.</p>
  232. </li>
  233. <li>Select one of the 2 sub-categories, SGX C project or SGX C++ project, and click <b>Next</b>.</li>
  234. <li>Complete creating the project using the regular process of creating a standard C or C++ project.</li>
  235. </ol>
  236. <div class="NoteCont">
  237. <p class="NoteTipHead">NOTE:</p>
  238. <p>Projects created following the subcategories under <b>C/C++ with SGX Enabled</b> are identical with their standard counterparts, except that they have SGX Nature added. There is no difference between creating a C or C++ project with SGX enabled, or creating a standard C/C++ project and launch <b>Add SGX nature</b> from it, as described in precedent paragraph.</p>
  239. </div>
  240. </div>
  241. <div id='Adding_an_SGX_Enclave'>
  242. <h2>Adding an SGX Enclave</h2>
  243. <p>After you add the SGX nature to a project, you can start creating a minimal but complete skeleton for a new enclave:</p>
  244. <ol>
  245. <li>Right-click on the project root in <b>Project Explorer</b>.</li>
  246. <li>
  247. <p>Open the dialog <b>Add New SGX Enclave</b> by selecting <b>Software Guard Extensions Tools → Add SGX Enclave</b> from the contextual menu.</p>
  248. <p>
  249. <img src="Resources/Images/Add_New_Intel_SGX_Enclave_Dialog.png" />
  250. </p>
  251. <p class="figcap">Add New Intel® SGX Enclave Dialog</p>
  252. </li>
  253. <li>
  254. <p>Choose a name for the enclave in <b>Enclave name</b> field. This name is used in the process of generation of the skeleton to give unicity to the source files and the name of the resulting executable, so you can add more than one enclave to the same project.</p>
  255. <ul>
  256. <li>
  257. <p>If you do not select the <b>Generate sample untrusted application</b> checkbox, the plugin generates only a trusted file and a Makefile fragment to build and compile the trusted part. See the following graphic. All the code for the enclave, including build Makefile, is put in a directory <code>&lt;root&gt;/sgx/enclave_&lt;name&gt;</code> . C/C++ code for the enclave proper are in <code>&lt;root&gt;/sgx/enclave_&lt;name&gt;/trusted</code>.</p>
  258. <p>
  259. <img src="Resources/Images/Generated_Skeleton_for_an_Enclave.png" />
  260. </p>
  261. <p class="figcap">Generated Skeleton for an Enclave. The option to Generate Sample was not Used</p>
  262. </li>
  263. <li>
  264. <p>If you select <b>Generate sample untrusted application</b> checkbox, a simple ready to work sample application is generated, including untrusted stubs and implementation for a sample OCALL and ECALL.</p>
  265. <p>
  266. <img src="Resources/Images/Generated_Sample_Untrusted_Application.png" />
  267. </p>
  268. <p class="figcap">Generated Sample Untrusted Application</p>
  269. </li>
  270. </ul>
  271. </li>
  272. </ol>
  273. <div class="NoteCont">
  274. <p class="NoteTipHead">NOTE:</p>
  275. <p>If you select the <b>Generate sample untrusted application</b> checkbox, ecalls from the untrusted part are not be resolved by Eclipse C/C++ indexer. These functions are marked with a red line. The declaration of these ecalls resides in the unstrusted stub header which is generated during the build proces and is not indexed by Eclipse. To resolve this problem, right-click on project root and select <b>Index → Freshen All Files</b>.</p>
  276. </div>
  277. </div>
  278. <div id='Adding_an_SGX_Trusted_Library'>
  279. <h2>Adding an SGX Trusted Library</h2>
  280. <p>Trusted Static Libraries helps enclave author have libraries of shared code to be reused by enclaves, in exactly the same manner as usual static <code>libxxx.a</code> libraries are used to share code between regular non-SGX applications. The plugin adds a command to generate the skeleton of a trusted shared library.</p>
  281. <p>To add a new SGX Trusted Library:</p>
  282. <ol>
  283. <li>
  284. <p>Open <b>Add New SGX Static Trusted Library</b> dialog by right-click on the root of the project and select the appropriate command from <b>Software Guard Extensions Tools</b> menu:</p>
  285. <p>
  286. <img src="Resources/Images/Add_New_SGX_Static_Trusted_Library_Dialog.png" />
  287. </p>
  288. <p class="figcap">Add New SGX Static Trusted Library Dialog</p>
  289. </li>
  290. <li>
  291. <p>Choose a name for the library and click <b>OK</b>. A skeleton for a trusted library is generated in directory <code>&lt;root&gt;/sgx/trustedlib_&lt;name&gt;</code>:</p>
  292. <p>
  293. <img src="Resources/Images/A_Generated_Trusted_Library.png" />
  294. </p>
  295. <p class="figcap">A Generated Trusted Library</p>
  296. </li>
  297. </ol>
  298. </div>
  299. <div id='Adding_an_SGX_Untrusted_Module'>
  300. <h2>Adding an SGX Untrusted Module</h2>
  301. <p>Add an untrusted module to generate the untrusted stubs so you use an enclave, provided you have access to its <code>.edl</code> file. The enclave might have been built in the current project or in a different project.</p>
  302. <p>To use trusted functionality of an enclave for which its <code>*.edl</code> is known, use the command <b>Add SGX Untrusted Module</b>:</p>
  303. <ol>
  304. <li>
  305. <p>Open dialog <b>Add Sgx Untrusted Module</b> by right-click-ing the project root in <b>Package Explorer</b> and chose the command from <b>Software Guard Extension Tools</b>.</p>
  306. <p>
  307. <img src="Resources/Images/Add_SGX_Untrusted_Module.png" />
  308. </p>
  309. <p class="figcap">Add SGX Untrusted Module</p>
  310. </li>
  311. <li>
  312. <p>Use the <b>Browse</b> button to navigate the file system using a file dialog, and click <b>OK</b>. The untrusted module is copied to <code>&lt;root&gt;/sgx/untrusted_&lt;edl file name&gt;</code>. The selected <code>*.edl</code> is copied to the project.</p>
  313. <p>
  314. <img src="Resources/Images/Copying_the_Untrusted_Module_to_a_Project.png" />
  315. </p>
  316. <p class="figcap">Copying the Untrusted Module to a Project</p>
  317. </li>
  318. </ol>
  319. </div>
  320. <div id='Updating_SGX_Enclave_Signing_Key'>
  321. <h2>Updating SGX Enclave Signing Key</h2>
  322. <p>All skeletons enclave samples produced by the plugin contain a sample signing key. You might want to import another sign key that you already have, or generate a new one. Use the command <b>Update SGX Enclave Signing Key</b> to complete this task.</p>
  323. <ol>
  324. <li>Choose <b>Update SGX Enclave Signing Key</b> by right-click on the project in <b>Project Explorer -&gt; Software Guard Extension Tools</b> menu. The <b>Import or (Re)Generate Enclave Signing Key</b> dialog appears.</li>
  325. <li>In the <b>Import or (Re)Generate Enclave Signing Key</b> dialog, click <b>Select</b> to open a file dialog to select the output key.</li>
  326. <li>
  327. <p>Click <b>Improt Key</b> to update a selected signing key by copying another existing key or click <b>Generate Key</b> to update the selected signing key by generating a new key. In both cases, the new signature key is put into the file in text field <b>Enclave Signing Key</b>.</p>
  328. <p>
  329. <img src="Resources/Images/Import_or_Re_Generate_Enclave_Signing_Key.png" />
  330. </p>
  331. <p class="figcap">Import or (Re)Generate Enclave Signing Key</p>
  332. </li>
  333. <li>Click <b>OK</b> to update the enclave signing key.</li>
  334. </ol>
  335. <p>Under the hood, a new key is generated using openssl*, which needs to be installed on the machine:</p>
  336. <p><code>openssl genrsa -out ../../../encl1_private.pem.key.pem -3 3072</code>
  337. </p>
  338. <p><![CDATA[ ]]></p>
  339. </div>
  340. <div id='Updating_Enclave_Configuration_Files'>
  341. <h2>Updating Enclave Configuration Files</h2>
  342. <p>A configuration file is an important part in the definition of an enclave. Intel(R) SGX SDK signer tool requires such *.xml configuration file as necessary input.</p>
  343. <p>To update this configuration file, use the <b>Update Config</b> command:</p>
  344. <ol>
  345. <li>
  346. <p>Right-click on the root project, <b>Software Extension Guards Tools-&gt;Select Config File</b>.</p>
  347. <p>
  348. <img src="Resources/Images/Select_Configuration_File.png" />
  349. </p>
  350. <p class="figcap">Select Configuration File</p>
  351. </li>
  352. <li>
  353. <p>Click <b>OK</b> or double-click the selected configuration file to open the <b>Enclave Configuration Settings</b> dialog.</p>
  354. <p>
  355. <img src="Resources/Images/Enclave_Configuration_Settings.png" />
  356. </p>
  357. <p class="figcap">Enclave Configuration Settings</p>
  358. <p>For details on the meaning of the fields, see <i>Intel(R) Software Guard Extensions Developer Guide</i>.</p>
  359. </li>
  360. </ol>
  361. </div>
  362. <div id='Two_Steps_Sign_Enclave'>
  363. <h2>Two Steps Sign Enclave</h2>
  364. <p>To help you develop enclaves, Intel(R) Software Guard Extensions Eclipse Plug-in generates all required structure including:</p>
  365. <ul>
  366. <li>c/c++ files and header files</li>
  367. <li><code>.edl</code> file</li>
  368. <li><code>*.config.xml</code> file</li>
  369. <li>a sample Makefile</li>
  370. <li>a sample signing key</li>
  371. </ul>
  372. <p>While these structure might be appropriate for development and debugging, you need a 2-step process to integrate your own signing schema for generating production enclaves.</p>
  373. <ol>
  374. <li>Generate hash: the signer tool generates signing material from the unsigned compiled enclave and from the configuration file for the enclave. The signed material comes as an opaque sequence of bytes which are put in a file with extension <code>.hex</code>. This file is used with the external signing facility. You come back with a signature for the <code>.hex</code> file plus the public key of your signing facility, and proceed to Step 2.</li>
  375. <li>Generate signed enclaves : the signer tool generates the final signed enclave.</li>
  376. </ol>
  377. <p>To complete this task, provide the following input parameters:</p>
  378. <ul>
  379. <li>The unsigned enclave</li>
  380. <li>The configuration file</li>
  381. <li>The output file produced when you generate hash (the <code>.hex</code> file)</li>
  382. <li>The files produced by the external signing facility: the signature of the .hex file and public key for it</li>
  383. <li>The plugin checks if the input parameters are consistent:</li>
  384. <li>The <code>.hex</code> file matches the unsigned enclave and the configuration file,</li>
  385. <li>The signed material is verified with the public key</li>
  386. </ul>
  387. <p>If the parameters are consistenet, the production signed enclave is produced.</p>
  388. <div class="NoteCont">
  389. <p class="NoteTipHead">NOTE:</p>
  390. <p>If you generate signed enclave right after generating hash, you can only enter the parameters specific for generating signed enclave.</p>
  391. </div>
  392. <p>To use the two-step signing function, activate the configuration <b>SGX Hardware Release mode</b>. When this configuration is active, the compilation does not produce a signed enclave, as in the other SGX configurations; the process only produces unsigned enclaves.</p>
  393. <p>
  394. <img src="Resources/Images/Configure_SGX_Hardware_Release_Mode.png" />
  395. </p>
  396. <p class="figcap">Configure SGX Hardware Release Mode</p>
  397. <p>When you configure the plugin in the <b>SGX Hardware Release Mode</b>, you can see the <b>Generate Hash</b> and <b>Generate Signed Enclave</b> options through <b>Software Guard Extension Tools-&gt;Two Step Sign Enclave</b>.</p>
  398. <p>
  399. <img src="Resources/Images/Two_Step_Sign_Enclave_Menu.png" />
  400. </p>
  401. <p class="figcap">Two Step Sign Enclave Menu</p>
  402. </div>
  403. <div id='Generate_Hash'>
  404. <h3>Generate Hash</h3>
  405. <p>Generating hash is the first step in the 2-Steps signing process.To generate hash, use the following steps:</p>
  406. <ol>
  407. <li>
  408. <p>Right-click on project root, go to <b>Software Guard Extensions Tools menu → Two StepSigne Enclave → Generate Hash</b></p>
  409. <p>
  410. <img src="Resources/Images/Two_StepSigne_Enclave_Generate_Hash.png" />
  411. </p>
  412. <p class="figcap">Two StepSigne Enclave - Generate Hash</p>
  413. </li>
  414. <li> In the <b>Generate Hash</b> dialog, enter the required inputs to the corresponding fields:<ul><li>Enter the path to the compiled enclave to be signed in the <b>Enclave Path</b> field. Click <b>Select Enclave</b> to open a file dialog to select the enclave.</li><li>In the <b>Hash File Location</b> field , enter the path of the output file that will contain signing materials. By default this file has the same file name as the unsigned enclave, with <code>.hex</code> extension added. To change the path, click <b>Select File Path</b> to open a file dialog to select the file path.</li><li>In the <b>Configuration File</b> path field, enter the path of the configuration filefor the generated hash. Click <b>Select Config</b> to open a dialog to select from all enclave configuration files in the project (similar with the one of the command <b>Update Config</b>).</li></ul></li>
  415. <li>
  416. <p>Click <b>OK</b> after you fill in all the fields. The Intel(R) SGX SDK is launched under the hood with the provided parameters and the hash file is generated. A dialog box appears to confirm the completion:</p>
  417. <p>
  418. <img src="Resources/Images/Generating_Hash_Completion_Dialog.png" />
  419. </p>
  420. <p class="figcap">Generating Hash Completion Dialog</p>
  421. </li>
  422. </ol>
  423. <p>You complete the first step, generating hash, in the two step signing enclave. The <code>*.hex</code> file may be signed with the external facility, which generates a signature for it and a public verification key.</p>
  424. <p>If you click <b>OK</b>, the <b>Generate Signed Enclave</b> dialog appears. The required fileds in this dialog have been pre-configured with the paths of the unsigned enclave, the configuration file and of the <code>*.hex</code> file. To generated the final signed enclave ready for production immediately, click <b>OK</b>.</p>
  425. <p>
  426. <img src="Resources/Images/Generate_Signed_Enclave_Dialog_with_Pre_configurations.png" />
  427. </p>
  428. <p class="figcap">Generate Signed Enclave Dialog with Pre-configurations</p>
  429. <p>If you click <b>Cancel</b> in the <b>Generate Signed Enclave</b> dialog, you can continue the signing process later using the <b>Generate Signed Enclave</b> command.</p>
  430. </div>
  431. <div id='Generate_Signed_Enclaves'>
  432. <h3>Generate Signed Enclaves</h3>
  433. <p>Generating signed enclave is the second step in the 2-Steps signing process. You should have the following files to complete this step:</p>
  434. <ul>
  435. <li>The <code>.hex</code> file generated with <b>Generate Hash</b> command</li>
  436. <li>The files produced from the external signing facility</li>
  437. <li>The signature of the <code>.hex</code> file</li>
  438. <li>The public verification key</li>
  439. </ul>
  440. <p>To generate signed encalves, use the following steps:</p>
  441. <ol>
  442. <li>
  443. <p>Right-click on the project root, and go to <b>Software Guard Extensions Tools menu → Two Step Sign Enclave → Generate Signed Enclave</b>.</p>
  444. <p>
  445. <img src="Resources/Images/Generate_Signed_Enclave_Dialog.png" />
  446. </p>
  447. <p>Generate Signed Enclave Dialog</p>
  448. </li>
  449. <li>Enter the inputs to all the fields and click <b>OK</b>.</li>
  450. </ol>
  451. </div>
  452. <div id='Building_and_Running_SGX_Code'>
  453. <h1>Building and Running SGX Code</h1>
  454. <p>This section describes the following topics about building and running SGX code:</p>
  455. <ul>
  456. <li>SGX build configurations</li>
  457. <li>Running samples generated for enclaves</li>
  458. </ul>&#160;</div>
  459. <div id='SGX_Build_Configurations'>
  460. <h2>SGX Build Configurations</h2>
  461. <p>There are usually two types of builds that a regular non-SGX project defines:</p>
  462. <ul>
  463. <li>Debug</li>
  464. <li>Release</li>
  465. </ul>
  466. <p>SGX-enabled projects add to this picture support to build and test SGX-enabled application on non-SGX platforms (or emulator) using simulation libraries. This approach doubles the set of build types, creating four possible combinations. For these combinations, you need to use different sets of compilation and linking flags and link different libraries.</p>
  467. <p>The non-debug hardware build is meant to give production code, so it requires the maximum attention when signed. The Two Steps Sign schema is required for production enclaves, which involves an external signing facility, not part of Intel SGX SDK. The other configurations are not meant for production but they have to be signed too. The simplest and more convenient Single Step schema is used for them.</p>
  468. <p>Again for testing purpose, you might want to experiment with a non-production enclave built with release compilation and linking flags, on a real hardware SGX-enabled platform. That would be an enclave built exactly as a production enclave, except for the sign process which would be Single Step. To support the construction of such enclave, there is a hardware non-debug build configuration dubbed <i>Prerelease</i>.</p>
  469. <p>So there are five SGX related configurations when SGX Nature is added to a project:</p>
  470. <p>
  471. <img src="Resources/Images/Intel_SGX_Configurations.png" />
  472. </p>
  473. <p>Intel(R) SGX Configurations</p>
  474. <p>The following table resumes the existing SGX configurations and relate them with compilation/linking flags (debug/non-debug) and signing scheme (single vs. two steps):</p>
  475. <p class="tablecap">Intel(R) SGX Configurations</p>
  476. <table style="width: 100%;border-left-style: solid;border-left-width: 1px;border-right-style: solid;border-right-width: 1px;border-top-style: solid;border-top-width: 1px;border-bottom-style: solid;border-bottom-width: 1px;">
  477. <col />
  478. <col />
  479. <col />
  480. <col />
  481. <tbody>
  482. <tr>
  483. <th>Configuration Name</th>
  484. <th>Simulation?</th>
  485. <th>Debug?</th>
  486. <th>Signing Schema</th>
  487. </tr>
  488. <tr>
  489. <td>SGX Hardware Debug</td>
  490. <td>Hardware</td>
  491. <td>Debug</td>
  492. <td>Single Step</td>
  493. </tr>
  494. <tr>
  495. <td>SGX Hardware Pre-release</td>
  496. <td>Hardware</td>
  497. <td>Non-debug</td>
  498. <td>Single Step</td>
  499. </tr>
  500. <tr>
  501. <td>SGX Hardware Release</td>
  502. <td>Hardware</td>
  503. <td>Non-debug</td>
  504. <td>Two Step</td>
  505. </tr>
  506. <tr>
  507. <td>SGX Simulation</td>
  508. <td>Simulation</td>
  509. <td>Non-debug</td>
  510. <td>Single Step</td>
  511. </tr>
  512. <tr>
  513. <td>SGX Simulation</td>
  514. <td>Debug Simulation</td>
  515. <td>Debug</td>
  516. <td>Single step</td>
  517. </tr>
  518. </tbody>
  519. </table>
  520. <p>Intel® Software Guard Extensions Eclipse Plug-in uses standard GNU* make tool to build the trusted and the untrusted code, using the generated file <code>sgx/Makefile</code>.</p>
  521. <p>This fact does not impose any restriction on the build tool chosen for the hosting project. Intel® Software Guard Extensions Eclipse* Plug-in uses its own build configurations which do not interfere with the configurations that you might have in your project.</p>
  522. <p>When SGX configurations are selected, by default only code under <code>&lt;root&gt;/sgx</code> directory get built.</p>
  523. <p>You can customize SGX configurations as any other Eclipse build configurations from the project properties dialog. For example:</p>
  524. <ol>
  525. <li>Right-click in Project Explorer Properties → C/C++ Build</li>
  526. <li>Uncheck the Use default build command checkbox.</li>
  527. </ol>
  528. <p>Then you can customize and integrate SGX build process. You can use Makefile instead of <code>sgx/Makefile</code> in the example shown in the following figure:</p>
  529. <p>
  530. <img src="Resources/Images/Customization_of_SGX_build_command.png" />
  531. </p>
  532. <p class="figcap">Customization of SGX Build Command </p>
  533. <p>The build process is done using standard Eclipse interface for build, by example from the main <b>Project</b> menu: </p>
  534. <p>
  535. <img src="Resources/Images/Project_Menu.png" />
  536. </p>
  537. <p class="figcap">Project Menu </p>
  538. </div>
  539. <div id='Running_Samples_Generated_for_Enclaves'>
  540. <h2>Running Samples Generated for Enclaves</h2>
  541. <p>Intel(R) Software Guard Extensions Eclipse* Plugin provides an option to generate a sample application together with the enclave code when the enclave is created. After the project is build, the sample application is built also and ready to run. You can see the sample application named sample in the enclave directory in Project Explorer. You can run this sample as a local C/C++ application as shown in the following figure:</p>
  542. <p>
  543. <img src="Resources/Images/Sample_Application.png" />
  544. </p>
  545. <p class="figcap">Sample Application</p>
  546. <p>See the result of the execution in Eclipse console window as shown below:</p>
  547. <p>
  548. <img src="Resources/Images/The_Result_of_Running_Samples_Generated_for_Enclaves.png" />
  549. </p>
  550. <p class="figcap">The Result of Running Samples Generated for Enclaves</p>
  551. </div>
  552. </body>
  553. </html>