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
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:
|include "my_type.h”||Uses the type defined in the external inclusion file.|
|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.|
The format of the codegen command is as follows:
codegen < --trustzone | --sgx > [--trusted-dir <path> | --untrusted-dir <path>| --trusted | --untrusted ] edlfile
The parameters are described as follows:
|--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.|
- 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 --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 --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 --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 --sgx helloworld.edl
Signature Tool: sign_tool
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.
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 | dump] -x <parameter> -i <file> -s <file> [OPTIONS] –o <file>
|sign Command Parameter||Description||Mandatory/Optional|
|-c <file>||Basic configuration file||The parameter is mandatory only for the trustzone type.|
|-d <parameter>||Specifies the operation (sign or digest or dump) 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. The dump operation is used to generate metadata for SGX signed enclave which is submitted to Intel for whitelisting.|
|-i <file>||Library file to be signed for digest/sign operation, and signed enclavae for dump operation.||Mandatory|
|-k <file>||Private key (PEM file) required for one-step signature.||This parameter is mandatory only for the SGX type.|
|-m <file>||Additional config_cloud.ini file.||This parameter is mandatory only for the trustzone type.|
|-o <file>||Output file.||Mandatory|
|-p <file>||Public key certificate (PEM file) of the signature server required for two-step signing.||This parameter is mandatory only for the SGX type.|
|-s <file>||Signed digest value required for two-step signing.||Mandatory|
|-x <parameter>||encalve type (sgx or trustzone)||Mandatory|
|-h||Prints the help information.||Optional|
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
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.data
Send 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: 1.When signing the trustzone enclave, it is recommended that use the absolute path to specify the file parameters, if provide a relative path, it should be a path relative to 'signtool_v3.py'. 2. 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.