API Overview

The KunpengSecL open-source library implements the overall remote attestation process. You can directly use this library to familiarize yourself with the remote attestation process and components.
If you require in-depth customization, you can learn about the bottom-layer APIs based on the following description and the iTrustee SDK Developer Guide. Please contact the Huawei service owner for this guide.

To implement remote attestation, the TEE OS provides two types of APIs at the bottom layer: the Quoting System Interface (QSI) for the QTA and the Quoting Application Interfaces (QAIs) for non-privileged TAs. A TA invokes the APIs provided by the QTA via inter-TA invocation. There is one QSI and three QAIs. In addition, the QCA lib and QTA have encapsulated the calls of bottom-layer APIs in the TEE OS. You can use the APIs provided by the QCA lib to call the bottom-layer APIs. The following describes the APIs.

QSI in the TEE

struct ra_buffer_data {
    uint32_t length;
    uint8_t *buffer;
};
TEE_Result ra_qsi_invoke(struct ra_buffer_data *in, struct ra_buffer_data *out);

This API is available only to the QTA. The buffers of input and output parameters are formatted JSON character strings. The JSON structure is as follows. For details, see the iTrustee SDK Developer Guide.

{
    "handler": "xxxxx",
    "payload": {....}
    ...
}

You can perform the following operations based on the handler values:

Provision: Generate the attestation key (AK) and AK certificate. This operation is a prerequisite for obtaining the measurement report. The payload of the input parameter can specify the remote attestation scenario. There is no output parameter in the non-attestation service scenario (NO AS). In the attestation service (AS) scenario, the payload of the output parameter contains the QTA measurement, randomly generated public AK, and device-certificate-based signature over the payload.
SaveAKCert: In the AS scenario, this API is called to save the certificate returned by the AS. The input parameters include the certificate returned by the AS. A randomized AK certificate is returned in Direct Anonymous Attestation (DAA) scenarios; there are no output parameters in non-DAA scenarios.
ValidateAKCert: Only when both the AS and DAA mode are enabled, once SaveAKCert returns the randomized AK certificate, this API is called to verify the AK certificate and save the original certificate.
Report: This API is called to obtain the measurement report. The input parameter includes the UUID of the TA to be measured, and the output parameter includes the reference measurement of the TA.

QAIs in the TEE

// Obtain the measurement report. The input and output parameters are the same as those used by the QSI to obtain the measurement report.
TEE_Result ra_local_report(struct ra_buffer_data *in, struct ra_buffer_data *out);
# This API is bound to the TA measurement value to generate a random key and also encrypt and decrypt data. The previously encrypted data can be decrypted only when the TA and measurement value remain unchanged.
TEE_Result ra_seal(uint8_t *data, size_t in_size, uint8_t *cipher_data, size_t *cipher_size, uint32_t alg);
TEE_Result ra_unseal(uint8_t *cipher_data, size_t cipher_size, uint8_t *data, size_t *out_size, uint32_t alg);

This API can be invoked by any non-privileged TA.

APIs in the REE

To facilitate the development of remote attestation applications, the QCA lib and QTA have encapsulated the calls of bottom-layer APIs in the TEE OS. You only need to develop REE applications to invoke those APIs.

TEEC_Result RemoteAttest(struct ra_buffer_data *in, struct ra_buffer_data *out);
TEEC_Result RegisterContainer(struct ra_buffer_data *container_info, TEEC_Context *context, TEEC_Session *session, uint32_t *origin);

RemoteAttest: encapsulates the ra_qsi_invoke API. Its input parameters are the same as those of the ra_qsi_invoke API, which are serialized JSON character strings.
RegisterContainer: This API is added to the host-side QCA lib since TEE OS 1.4.0 to support in-container remote attestation. The container_info parameter is a serialized JSON string.
1 2 3 4
{ "container_id": "container ID" "nsid": "container NSID" }

libqca-report and QTA-report encapsulate TEE OS API calls within containers. libqca-report has only the RemoteAttest API, which is used to obtain reports. If a container calls libqca-report, add the following container information to the JSON structure:

{
    ......
    "payload": {
        .....
        "container_info": {
            "id": "container ID"
            "type": "container type"
        }
    }
}

Parent topic: Remote and Local Attestation