API Documentation

This section documents the Trusted Application (TA) interface exposed through the TEE Client API. The TA provides five main commands for secure off-chain storage and attestation.

—

Store JSON Data

Command ID: TA_OFF_CHAIN_SECURE_STORAGE_STORE_JSON

Purpose: Securely store JSON data by encrypting it with AES and generating a SHA-256 hash for reference.

C Function Parameters:

1/**
2 * Store JSON data in off-chain secure storage (persistent object)
3 * @param param[0] (memref) IoT Device ID used the identify the persistent object
4 * @param param[1] (memref) JSON data to be written in the persistent object
5 * @param param[2] (memref) Buffer to store the SHA256 hash of the JSON data
6 * @param param[3] unused
7 */
8#define TA_OFF_CHAIN_SECURE_STORAGE_STORE_JSON 0

Operation Flow:

  1. Allocate secure memory

  2. Compute SHA-256 hash of input JSON data

  3. Encrypt data using AES-CTR mode with a randomly generated IV

  4. Store the encrypted payload in TEE persistent storage, keyed by the hash

  5. Return the hash to the client as a reference handle

—

Retrieve JSON Data

Command ID: TA_OFF_CHAIN_SECURE_STORAGE_RETRIEVE_JSON

Purpose: Retrieve and decrypt previously stored JSON data using its SHA-256 hash as a lookup key.

C Function Parameters:

1/**
2 * Retrieve JSON data from off-chain secure storage (persistent object)
3 * @param param[0] (memref) JSON hash to retrieve JSON data
4 * @param param[1] (memref) Buffer to store the JSON data
5 * @param param[2] unused
6 * @param param[3] unused
7 */
8#define TA_OFF_CHAIN_SECURE_STORAGE_RETRIEVE_JSON 1

Operation Flow:

  1. Validate input hash and allocate secure buffers

  2. Locate and open the object in TEE persistent storage using the hash

  3. Read the encrypted data

  4. Decrypt using stored AES key and IV

  5. Return decrypted JSON data to client

Error Conditions:

  • TEE_ERROR_ITEM_NOT_FOUND — No object found for given hash

  • TEE_ERROR_SHORT_BUFFER — Provided buffer size is insufficient

  • TEE_ERROR_OUT_OF_MEMORY — Failed to allocate memory for operation

—

Hash JSON Data

Command ID: TA_OFF_CHAIN_SECURE_STORAGE_HASH_JSON

Purpose: Generate a SHA-256 hash from JSON data without storing it.

C Function Parameters:

1/**
2 * Get the SHA256 hash of a JSON data (persistent object)
3 * @param param[0] (memref) JSON data to be hashed
4 * @param param[1] (memref) Buffer to store the SHA256 hash of the JSON data
5 * @param param[2] unused
6 * @param param[3] unused
7 */
8#define TA_OFF_CHAIN_SECURE_STORAGE_HASH_JSON 2

Use Cases:

  • Blockchain anchoring (e.g., for off-chain data proofs)

  • Verifying data integrity before or after transmission

  • Pre-hashing content for comparison or deduplication

—

Get Attestation

Command ID: TA_OFF_CHAIN_SECURE_STORAGE_GET_ATTESTATION

Purpose: Generate a cryptographic signature that attests to the identity of the Trusted Application (TA).

C Function Parameters:

1/**
2 * Get attestation of the TA
3 * @param param[0] (memref) Nonce provided by the verifier (generated automatically on host side)
4 * @param param[1] (memref) Buffer to store the attestation data
5 * @param param[2] unused
6 * @param param[3] unused
7 */
8#define TA_OFF_CHAIN_SECURE_STORAGE_GET_ATTESTATION 3

Attestation Process:

  1. Compute SHA-256 hash of the TA’s UUID

  2. Sign the hash using an RSA-2048 private key with PSS (Probabilistic Signature Scheme) padding

  3. Return the digital signature to the client

—

Get Public Key

Command ID: TA_OFF_CHAIN_SECURE_STORAGE_GET_PUBLIC_KEY

Purpose: Retrieve the RSA public key associated with the TA for verifying signatures.

C Function Parameters:

1/**
2 * Get the public key of the TA
3 * @param param[0] (memref) Buffer to store the public key
4 * @param param[1] unused
5 * @param param[2] unused
6 * @param param[3] unused
7 */
8#define TA_OFF_CHAIN_SECURE_STORAGE_GET_PUBLIC_KEY 4

Public Key Format:

The returned public key is encoded as a hexadecimal string in the following format:

Public key: <HEXADECIMAL VALUE>