LTS

    Innovation Version

      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:

      MemberDescription
      include "my_type.h”Uses the type defined in the external inclusion file.
      trustedDeclares that secure functions are available on the trusted application (TA) side.
      untrustedDeclares that insecure functions are available on the TA side.
      return_typeDefines the return value type.
      parameter_typeDefines 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:

      codegen < --trustzone | --sgx > [--trusted-dir <path> | --untrusted-dir <path>| --trusted | --untrusted ] edlfile

      Parameter Description

      The parameters are described as follows:

      ParameterMandatory/OptionalDescription
      --trustzone | --sgxMandatoryGenerates 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>OptionalSpecifies the search path of the file that the EDL file to be converted depends on.
      --use-prefixOptionalAdds a prefix to the proxy function name. The prefix is the name of the EDL file.
      --header-onlyOptionalSpecifies that the code generation tool generates only header files.
      --trusted-dir <path>OptionalSpecifies 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>OptionalSpecifies the directory where the auxiliary code for generating insecure functions is located.
      --trustedOptionalGenerates TEE auxiliary code.
      --untrustedOptionalGenerates REE auxiliary code.
      edlfileMandatoryEDL 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 --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

      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 | dump] -x <parameter> -i <file> -s <file> [OPTIONS] –o <file>

      Parameter Description

      sign Command ParameterDescriptionMandatory/Optional
      -c <file>Basic configuration fileThe 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
      -hPrints 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:

      1. 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
        
      2. Send digest.data to the signature authority or platform and obtain the corresponding signature.

      3. 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.

      Bug Catching

      Buggy Content

      Bug Description

      Submit As Issue

      It's a little complicated....

      I'd like to ask someone.

      PR

      Just a small problem.

      I can fix it online!

      Bug Type
      Specifications and Common Mistakes

      ● Misspellings or punctuation mistakes;

      ● Incorrect links, empty cells, or wrong formats;

      ● Chinese characters in English context;

      ● Minor inconsistencies between the UI and descriptions;

      ● Low writing fluency that does not affect understanding;

      ● Incorrect version numbers, including software package names and version numbers on the UI.

      Usability

      ● Incorrect or missing key steps;

      ● Missing prerequisites or precautions;

      ● Ambiguous figures, tables, or texts;

      ● Unclear logic, such as missing classifications, items, and steps.

      Correctness

      ● Technical principles, function descriptions, or specifications inconsistent with those of the software;

      ● Incorrect schematic or architecture diagrams;

      ● Incorrect commands or command parameters;

      ● Incorrect code;

      ● Commands inconsistent with the functions;

      ● Wrong screenshots.

      Risk Warnings

      ● Lack of risk warnings for operations that may damage the system or important data.

      Content Compliance

      ● Contents that may violate applicable laws and regulations or geo-cultural context-sensitive words and expressions;

      ● Copyright infringement.

      How satisfied are you with this document

      Not satisfied at all
      Very satisfied
      Submit
      Click to create an issue. An issue template will be automatically generated based on your feedback.
      Bug Catching
      编组 3备份