Using the secGear Tool
secGear provides a tool set to facilitate application development. This document describes the tools and how to use them.
Codegener: Code Generation Tool
Overview
secGear codegener is a tool developed based on Intel SGX SDK edger8r. It is used to parse the EDL file to generate intermediate C code, that is, to assist in generating code that is called between the TEE and REE.
The EDL file format defined by secGear codegener is the same as that defined by Intel SGX SDK edger8r, but the complete syntax definition of Intel is not supported:
- The public can be used only in methods. Functions without public are declared as private by default.
- Switchless calls from the REE to the TEE and from the TEE to the REE are not supported.
- The Outside Call (OCALL) does not support some calling modes (such as cdecl, stdcall, and fastcall).
The EDL file syntax is similar to the C language syntax. The following describes parts different from the C language syntax:
| Member | Description |
|---|---|
| include "my_type.h" | Uses the type defined in the external inclusion file. After the type is added, you need to use --search-path to specify the search path when running the codegen command. |
| trusted | Declares that secure functions are available on the trusted application (TA) side. |
| untrusted | Declares that insecure functions are available on the TA side. |
| return_type | Defines the return value type. |
| parameter_type | Defines the parameter type. |
| [in, size = len] | For the ECALL, this parameter indicates that data needs to be transferred from the REE to the TEE. For the OCALL, this parameter is required for the pointer type, and size indicates the buffer that is actually used. |
| [out, size = len] | For the ECALL, this parameter indicates that data needs to be transferred from the TEE to the REE. For the OCALL, this parameter needs to be used for the pointer type, and size indicates the buffer that is actually used. |
Usage Instructions
Command Format
The format of the codegen command is as follows:
- x86_64 architecture:
codegen_x86_64 < --trustzone | --sgx > [--trusted-dir <path> | --untrusted-dir <path>| --trusted | --untrusted ] edlfile
ARM architecture
codegen_arm64 < --trustzone | --sgx > [--trusted-dir <path> | --untrusted-dir <path>| --trusted | --untrusted ] edlfile
Parameter Description
The parameters are described as follows:
| Parameter | Mandatory/Optional | Description |
|---|---|---|
| --trustzone | --sgx | Mandatory | Generates the API function corresponding to the confidential computing architecture only in the current command directory. If no parameter is specified, the SGX API function is generated by default. |
| --search-path <path> | Optional | Specifies the search path of the file that the EDL file to be converted depends on. |
| --use-prefix | Optional | Adds a prefix to the proxy function name. The prefix is the name of the EDL file. |
| --header-only | Optional | Specifies that the code generation tool generates only header files. |
| --trusted-dir <path> | Optional | Specifies the directory where the generated TEE auxiliary code is stored. If this parameter is not specified, the current path is used by default. |
| --untrusted-dir <path> | Optional | Specifies the directory where the auxiliary code for generating insecure functions is located. |
| --trusted | Optional | Generates TEE auxiliary code. |
| --untrusted | Optional | Generates REE auxiliary code. |
| edlfile | Mandatory | EDL file to be converted, for example, hello.edl. |
Examples
- Convert helloworld.edl to generate TEE auxiliary code in enclave-directory and generate REE auxiliary code in host-directory. An example command is as follows:
codegen_x86_64 --sgx --trusted-dir enclave-directory --untrusted-dir host-directory helloworld.edl
- Convert helloworld.edl to generate TEE auxiliary code in the current directory. The following is a command example for not generating REE auxiliary code:
codegen_x86_64 --sgx --trusted helloworld.edl
- Convert helloworld.edl to generate REE auxiliary code in the current directory. The following is a command example that does not generate TEE auxiliary code:
codegen_x86_64 --sgx --untrusted helloworld.edl
- Convert helloworld.edl. An example of the command for generating TEE and REE auxiliary code in the current directory is as follows:
codegen_x86_64 --sgx helloworld.edl
Signature Tool: sign_tool
Overview
secGear sign_tool is a command line tool, including the compilation tool chain and signature tool, which are used for enclave signing. The sign_tool has two signature modes:
- Single-step signature: applies only to the debugging mode.
- Two-step signature: applies to the commercial scenario. Obtain the signature private key from a third-party platform or an independent security device to sign the enclave.
Operation Instructions
Format
The sign_tool contains the sign command (for signing the enclave) and the digest command (for generating the digest value). Command format:
sign_tool.sh -d [sign | digest] -x <parameter> -i <file> -p <file> -s <file> [OPTIONS] –o <file>
Parameter Description
| sign Command Parameter | Description | Mandatory/Optional |
|---|---|---|
| -a <parameter> | api_level, which identifies the GP API version of the iTrustee TA. The default value is 1. | Optional |
| -c <file> | Configuration file | Optional |
| -d <parameter> | Specifies the operation (sign or digest) to be performed by the signature tool. | Only the sign operation is performed in single-step mode. In two-step mode, the digest operation must be performed before the sign operation. |
| -e <file> | Public key certificate of the device, which is used to protect the AES key for encrypting rawdata (mandatory for iTrustee). | This parameter is mandatory only for the iTrustee type. |
| -f <parameter> | OTRP_FLAG, which determines whether to support the OTRP standard protocol. The default value is 0. | Optional |
| -i <file> | Library file to be signed. | Mandatory |
| -k <file> | Private key (PEM file) required for one-step signature. | This parameter is mandatory only for the SGX type. |
| -m <file> | Security configuration file mainfest.txt, which is configured by users. | Only the iTrustee type is mandatory. |
| -o <file> | Output file. | Mandatory |
| -p <file> | Public key certificate (PEM file) of the signature server required for two-step signing. | Mandatory |
| -s <file> | Signed digest value required for two-step signing. | Mandatory |
| -t <parameter> | TA_TYPA, which identifies TA binary format of the iTrustee. The default value is 1. | Optional |
| -x <parameter> | enclave type (sgx or trustzone) | Mandatory |
| -h | Prints the help information. | Optional |
Single-Step Signature
Set the enclave type is SGX, sign the test.enclave, and generate the signature file signed.enclave. The following is an example:
sign_tool.sh –d sign –x sgx –i test.enclave -k private_test.pem –o signed.enclave
Two-Step Signature
The following uses SGX as an example to describe the two-step signature procedure:
Generate digest value.
Use the sign_tool to generate the digest value digest.data and the temporary intermediate file signdata. The file is used when the signature file is generated and is automatically deleted after being signed. Example:
sign_tool.sh –d digest –x sgx –i input –o digest.dataSend digest.data to the signature authority or platform and obtain the corresponding signature.
Use the obtained signature to generate the signed dynamic library signed.enclave.
sign_tool.sh –d sign –x sgx–i input –p pub.pem –s signature –o signed.enclave
Note: To release an official version of applications supported by Intel SGX, you need to apply for an Intel whitelist. For details about the process, see the Intel document at https://software.intel.com/content/www/us/en/develop/download/overview-on-signing-and-whitelisting-for-intel-software-guard-extensions-enclaves.html.
