Documentation
Rate This Document
Findability
Accuracy
Completeness
Readability
SubmitClose

APIs

  • The KunpengSecL 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 in the way of calling another TA. 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.

QSI

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 a private attestation key and an attestation key certificate. Perform this operation before 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. In the Attestation Service scenario, the payload of the output parameter contains the QTA measurement, randomly generated public attestation key, and signature of the device certificate on the payload.
  • SaveAKCert: This API is called to save the certificate returned by the Attestation Service when the Attestation Service is deployed. The input parameter contains the certificate returned by the Attestation Service. There is no input parameter if Direct Anonymous Attestation (DAA) is not deployed. If DAA is deployed, a randomized attestation key certificate is returned.
  • ValidateAKCert: When the Attestation Service and DAA are deployed, this API is called to verify the attestation key certificate and save the original certificate after the randomized attestation key certificate is returned by SaveAKCert.
  • 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 base value of the TA.

QAIs

# 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 QCA lib on the host to support remote attestation within containers since TEE OS 1.4.0. container_info is a serialized JSON structure.
    {
    "container_id": container ID
    "nsid": container NSID
}

The QCA lib-report and QTA-report encapsulate the calls of TEE OS APIs in containers. The QCA lib-report has only the RemoteAttest API, which is used to obtain reports. If a container calls the QCA lib-report, add the following container information to the JSON structure:

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