API Reference

The secGear unified programming framework for confidential computing provides basic APIs that shields the differences between TEE SDKs, as well as advanced features such as switchless, remote attestation, and secure channel.

Basic APIs

cc_enclave_create

Creates an enclave.

Function:

Initialization API. The function calls different TEE creation functions based on the type to initialize the enclave context in different TEE solutions. This API is called by the REE.

Note: Due to Intel SGX restrictions, memory mapping contention exists when multiple thread invoke cc_enclave_create concurrently. As a result, the creation of the enclave API may fail. Avoid concurrent invocations of cc_enclave_create in your code.

Function Declaration:

cc_enclave_result_t cc_enclave_create(const char* path, enclave_type_t type, uint32_t version,uint32_t flags,const enclave_features_t* features,uint32_t features_count,
 cc_enclave_t  ** enclave);

Parameters:

• path: input parameter, which specifies a path of the enclave to be loaded.
• type: input parameter, which specifies the TEE solution, for example, SGX_ENCLAVE_TYPE, GP_ENCLAVE_TYPE and AUTO_ENCLAVE_TYPE.
• version: input parameter, which specifies the enclave engine version. Currently, there is only one version, and the value is 0.
• flags: input parameter, which specifies the running status of the enclave. For example, SECGEAR_DEBUG_FLAG indicates the debugging status, and SECGEAR_SIMULATE_FLAG indicates the simulation status (not supported currently).
• features: input parameter, which specifies some features supported by the enclave, for example, PCL and switchless of the SGX. This parameter is not supported currently. Set it to NULL.
• features_count: input parameter, which specifies the number of features. This parameter is not supported currently. Set it to 0.
• enclave: output parameter, which specifies the created enclave context.

Return Values:

• CE_SUCCESS: The authentication information is verified successfully.
• CE_ERROR_INVALID_PARAMETER: The input parameter is incorrect.
• CE_ERROR_OUT_OF_MEMORY: No memory is available.
• CC_FAIL: Common failure.
• CC_ERROR_UNEXPECTED: Unexpected error.
• CC_ERROR_ENCLAVE_MAXIMUM: The number of enclaves created by a single app reaches the maximum.
• CC_ERROR_INVALID_PATH: The secure binary path is invalid.
• CC_ERROR_NO_FIND_REGFUNC: The enclave search fails.

cc_enclave_destroy

Destroys an enclave.

Function:

This API is called by the REE to call the exit functions of different TEEs to release the created enclave entities.

Function Declaration:

cc_enclave_result_t cc_enclave_destroy (cc_enclave_t ** enclave);

Parameter:

• enclave: input parameter, which specifies the context of the created enclave.

Return Values:

• CE_SUCCESS: The authentication information is verified successfully.
• CE_ERROR_INVALID_PARAMETER: The input parameter is incorrect.
• CE_ERROR_OUT_OF_MEMORY: No memory is available.
• CC_ERROR_NO_FIND_UNREGFUNC: The enclave search fails.
• CC_FAIL: common failure.
• CC_ERROR_UNEXPECTED: unexpected error.

cc_malloc_shared_memory

Creates the shared memory.

Functions

After the switchless feature is enabled, this API is called by the REE to create the shared memory that can be accessed by both the TEE and REE.

Function Declaration:

void *cc_malloc_shared_memory(cc_enclave_t *enclave, size_t size);

Parameters:

• enclave: input parameter, which indicates the context handle of the secure environment. Different platforms have different shared memory models. To ensure cross-platform interface consistency, this parameter is used only on the ARM platform and is ignored on the SGX platform.
• size: input parameter, which indicates the size of the shared memory.

Return Values:

• NULL: Failed to apply for the shared memory.
• Other values: start address of the created shared memory.

cc_free_shared_memory

Releases the shared memory.

Functions

This API is called by the REE to release the shared memory after the switchless feature is enabled.

Function Declaration:

cc_enclave_result_t cc_free_shared_memory(cc_enclave_t *enclave, void *ptr);

Parameters:

• enclave: input parameter, which indicates the context handle of the secure environment. Different platforms have different shared memory models. To ensure cross-platform interface consistency, this parameter is used only on the ARM platform (the value of this parameter must be the same as the value of enclave passed when cc_malloc_shared_memory is invoked). It is ignored on the SGX platform.
• ptr: input parameter, which indicates the shared memory address returned by cc_malloc_shared_memory.

Return Values:

• CC_ERROR_BAD_PARAMETERS: invalid input parameter.
• CC_ERROR_INVALID_HANDLE: The enclave is invalid or the input enclave does not match the enclave corresponding to the ptr. (It takes effect only on the ARM platform. The SGX platform ignores the enclave and therefore does not check the enclave.)
• CC_ERROR_NOT_IMPLEMENTED: The API is not implemented.
• CC_ERROR_SHARED_MEMORY_START_ADDR_INVALID: ptr is not the shared memory address returned by cc_malloc_shared_memory (valid only on the ARM platform).
• CC_ERROR_OUT_OF_MEMORY: insufficient memory (valid only on the ARM platform).
• CC_FAIL: common failure.
• CC_SUCCESS: success

cc_enclave_generate_random

Generates random numbers.

Function:

Generate a secure random number for the password on the TEE.

Function Declaration:

cc_enclave_result_t cc_enclave_generate_random(void *buffer, size_t size)

Parameters:

• buffer: input parameter, which specifies the buffer for generating random numbers.
• size: input parameter, which specifies the buffer length.

Return Values:

• CE_OK: Authentication information is verified successfully.
• CE_ERROR_INVALID_PARAMETER: incorrect input parameter.
• CE_ERROR_OUT_OF_MEMORY: no memory is available.

cc_enclave_seal_data

Ensures data persistence.

Function:

This API is called by the TEE to encrypt the internal data of the enclave so that the data can be persistently stored outside the enclave.

Function Declaration:

cc_enclave_result_t cc_enclave_seal_data(uint8_t *seal_data, uint32_t seal_data_len,

    cc_enclave_sealed_data_t *sealed_data, uint32_t sealed_data_len,

    uint8_t *additional_text, uint32_t additional_text_len)

Parameters:

• seal_data: input parameter, which specifies the data to be encrypted.
• seal_data_len: input parameter, which specifies the length of the data to be encrypted.
• sealed_data: output parameter, which specifies the encrypted data processing handle.
• sealed_data_len: output parameter, which specifies the length of the encrypted ciphertext.
• additional_text: input parameter, which specifies the additional message required for encryption.
• additional_text_len: input parameter, which specifies the additional message length.

Return Values:

• CE_SUCCESS: Data encryption succeeds.
• CE_ERROR_INVALID_PARAMETER: incorrect input parameter.
• CE_ERROR_OUT_OF_MEMORY: no memory is available.
• CC_ERROR_SHORT_BUFFER: The input buffer is too small.
• CC_ERROR_GENERIC: Common bottom-layer hardware error.

cc_enclave_unseal_data

Decrypts data.

Function:

This API is called by the TEE to decrypt the data sealed by the enclave and import the external persistent data back to the enclave.

Function Declaration:

cc_enclave_result_t cc_enclave_unseal_data(cc_enclave_sealed_data_t *sealed_data,

    uint8_t *decrypted_data, uint32_t *decrypted_data_len,

    uint8_t *additional_text, uint32_t *additional_text_len)

Parameters:

• sealed_data: input parameter, which specifies the handle of the encrypted data.
• decrypted_data: output parameter, which specifies the buffer of the decrypted ciphertext data.
• decrypted_data_len: output parameter, which specifies the length of the decrypted ciphertext.
• additional_text: output parameter, which specifies an additional message after decryption.
• additional_text_len: output parameter, which specifies the length of the additional message after decryption.

Return Values:

• CE_SUCCESS: Data decryption is successful.
• CE_ERROR_INVALID_PARAMETER: incorrect input parameter.
• CE_ERROR_OUT_OF_MEMORY: no memory is available.
• CC_ERROR_SHORT_BUFFER: The input buffer is too small.
• CC_ERROR_GENERIC: common bottom-layer hardware error.

cc_enclave_get_sealed_data_size

Obtains the size of the encrypted data.

Function:

Obtain the size of the sealed_data data. This API can be called by the TEE and REE to allocate the decrypted data space.

Function Declaration:

uint32_t cc_enclave_get_sealed_data_size(const uint32_t add_len, const uint32_t seal_data_len);

Parameters:

• add_len: input parameter, which specifies the additional message length.
• sealed_data_len: input parameter, which specifies the length of the encrypted information.

Return Values:

• UINT32_MAX: Parameter error or function execution error.
• others: The function is successfully executed, and the return value is the size of the sealed_data structure.

cc_enclave_get_encrypted_text_size

Obtains the length of an encrypted message.

Function:

This API is called by the TEE to obtain the length of the encrypted message in the encrypted data.

Function Declaration:

uint32_t cc_enclave_get_encrypted_text_size(const cc_enclave_sealed_data_t *sealed_data);

Parameter:

• sealed_data: input parameter, which specifies the handle of the encrypted data

Return Values:

• UINT32_MAX: Parameter error or function execution error.
• others: The function is executed successfully, and the return value is the length of the encrypted message in sealed_data.

cc_enclave_get_add_text_size

Obtains the length of an additional message.

Function:

This API is called by the TEE to obtain the length of the additional message in the encrypted data.

Function Declaration:

uint32_t cc_enclave_get_add_text_size(const cc_enclave_sealed_data_t *sealed_data);

Parameter:

• sealed_data: input parameter, handle of the encrypted data.

Return Values:

• UINT32_MAX: Parameter error or function execution error.
• others: The function is successfully executed, and the return value is the length of the additional message in sealed_data.

cc_enclave_memory_in_enclave

Performs security memory check.

Function:

This API is called by the TEE to check whether the memory addresses of the specified length belong to the TEE.

Function Declaration:

bool cc_enclave_memory_in_enclave(const void *addr, size_t size)

Parameters:

• *addr: input parameter, which specifies the memory address to be verified.
• size: input parameter, which specifies the length to be verified starting from the memory address.

Return Values:

• true: The memory in the specified zone is in the secure zone.
• false: Some or all memory in the specified area is not within the secure range.

cc_enclave_memory_out_enclave

Performs security memory check.

Function:

This API is called by the TEE to check whether the memory addresses of the specified length belong to the REE.

Function Declaration:

bool cc_enclave_memory_out_enclave(const void *addr, size_t size)

Parameters:

• *addr: input parameter, which specifies the memory address to be verified.
• size: input parameter, length to be verified starting from the memory address.

Return Values:

• true: The memory of the specified area is in the non-secure area.
• false: Some or all of the memory in the specified zone is in the secure area.

PrintInfo

Prints messages.

Function:

Print TEE logs. This API outputs the information that the TEE user wants to print. The input logs are stored in the REE /var/log/secgear/secgear.log.

Function Declaration:

void PrintInfo(int level, const char *fmt, ...);

Parameters:

• level: log print level, which is an input parameter. The value can be PRINT_ERROR, PRINT_WARNING, PRINT_STRACE, and PRINT_DEBUG.
• fmt: Input parameter, and a character to be output.

Return Value:

• None

Switchless

Switchless optimizes the performance of regular ecalls (for the REE to call the TEE). You can enable switchless in two steps as follows.

Enabling Switchless

Use the enclave_features_t parameter of cc_enclave_create to enable the switchless feature. For details, see the switchless example. The configuration items are as follows:

typedef struct {
uint32_t num_uworkers;
uint32_t num_tworkers;
uint32_t switchless_calls_pool_size;
uint32_t retries_before_fallback;
uint32_t retries_before_sleep;
uint32_t parameter_num;
uint32_t workers_policy;
uint32_t rollback_to_common;
} cc_sl_config_t;

Enabling ecall

Use transition_using_threads to enable swicthless for ecall.

enclave {
    include "secgear_urts.h"
    from "secgear_tstdc.edl" import *;
    from "secgear_tswitchless.edl" import *;
    trusted {
        public int get_string([out, size=32]char *buf);
        public int get_string_switchless([out, size=32]char *buf) transition_using_threads;
    };
};

Remote Attestation

The following remote attestation APIs are provided. For details, see the remote attestation example and local attestation example.

Secure Channel

The secure channel is provided as a library and consists of the client, host, and enclave, which are icalled by the client, server client application (CA), and server trusted application (TA) of the service program respectively.

APIs

Precautions

• A secure channel encapsulates only the key negotiation process and encryption and decryption APIs, but does not establish any network connection. The negotiation process reuses the network connection of the service. The network connection between the client and server is established and maintained by the service. The message sending hook function and network connection pointer are transferred during the initialization of the secure channel on the client and the server.
• The read buffer of the network message receiving function on the client and server must be big enough to contain the secure channel initialization message of 12,320 bytes. For details, see secure channel examples.

Development Tools

secGear provides a tool set to facilitate application development. This document describes the tools and how to use them.

Code Generation Tool

Overview

secGear codegen 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 codegen 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:

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:

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

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

Usage Instructions

Command Format

The sign_tool contains the sign command (for signing the enclave) and the digest command (for generating the digest value).

sign_tool.sh -d [sign | digest] -x <parameter> -i <file> -p <file> -s <file> [OPTIONS] –o <file>

Parameter Description

Single-Step Signing

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 Signing

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

Secure Application Development Guide

The following example describes how to use secGear to develop a helloworld program using the C language.

Example Download

git clone https://gitee.com/openeuler/secGear.git

Directory Structure

cd examples/helloworld

#Directory structure:
├── helloworld
│   ├── CMakeLists.txt
│   ├── enclave
│   │   ├── CMakeLists.txt
│   │   ├── Enclave.config.xml
│   │   ├── Enclave.lds
│   │   ├── hello.c
│   │   ├── manifest.txt
│   │   └── config_cloud.ini
│   ├── helloworld.edl
│   └── host
│       ├── CMakeLists.txt
│       └── main.c

The code body consists of three parts:

• main.c: REE program
• helloworld.edl: header file of the APIs called by the REE and TEE
• hello.c: TEE program

Preparations

In addition to the preceding three parts, there are compilation project file (CMakeLists.txt) and developer licenses (Enclave.config.xml/Enclave.lds of Intel SGX and manifest.txt/config_cloud.ini of Kunpeng).

NOTE:

• The Kunpeng developer license needs to be applied for from the Huawei service owner.
• Because Intel SGX is debugged in debug mode, you do not need to apply for a developer license currently. If the remote attestation service of Intel is required for commercial use, you need to apply for a license from Intel.

After the application is successful, the developer license file is obtained and needs to be stored in the corresponding code directory.

Development Procedure

Reconstructing a confidential computing application based on secGear is similar to independently extracting functional modules. The procedure is as follows: Identify sensitive data processing logic, extract it into an independent library, deploy it in the TEE, and define APIs provided by the REE in the EDL file.

The following figure shows the development procedure.

1. Develop the main function and APIs in the REE, manage the enclave, and call functions in the TEE.
2. Develop the EDL file (similar to the C language header file that defines the interaction APIs between the REE and TEE).
3. Develop TEE APIs.
4. Call the code generation tool codegener to automatically generate the interaction source code between the REE and TEE based on the EDL file and compile the source code to the binary files of the REE and TEE. The REE logic directly calls the corresponding API of the TEE without considering the automatically generated interaction code, reducing the development cost.
5. Call the signing tool to sign binary files in the TEE to implement trusted boot of the TEE program.

Build and Run

Arm Environment

# Clone secGear repository
git clone https://gitee.com/openeuler/secGear.git

# Build secGear and examples
cd secGear
source environment
mkdir debug && cd debug && cmake -DENCLAVE=GP .. && make && sudo make install

# Run helloworld
/vendor/bin/secgear_helloworld

x86 Environment

# Clone secGear repository
git clone https://gitee.com/openeuler/secGear.git

# Build secGear and examples
cd secGear
source /opt/intel/sgxsdk/environment && source environment
mkdir debug && cd debug && cmake .. && make && sudo make install

# Run helloworld
./examples/helloworld/host/secgear_helloworld