/*
* Copyright (c) 2024 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __TEE_OBJECT_API_H
#define __TEE_OBJECT_API_H
/**
* @addtogroup TeeTrusted
* @{
*
* @brief TEE(Trusted Excution Environment) API.
* Provides security capability APIs such as trusted storage, encryption and decryption,
* and trusted time for trusted application development.
*
* @since 12
*/
/**
* @file tee_object_api.h
*
* @brief Provides trusted storage APIs.
*
* You can use these APIs to implement trusted storage features.
*
* @library NA
* @kit TEEKit
* @syscap SystemCapability.Tee.TeeClient
* @since 12
* @version 1.0
*/
#include "tee_defines.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Defines HANDLE_NULL, which is used to denote the absence of a handle.
*
* @since 12
*/
#define TEE_HANDLE_NULL 0x00000000
/**
* @brief Enumerates the usages of the key of the TEE_ObjectHandle.
*
* @since 12
*/
enum Usage_Constants {
/** The object's key is extractable. */
TEE_USAGE_EXTRACTABLE = 0x00000001,
/** Used for encryption. */
TEE_USAGE_ENCRYPT = 0x00000002,
/** Used for decryption. */
TEE_USAGE_DECRYPT = 0x00000004,
/** Used for hash calculation. */
TEE_USAGE_MAC = 0x00000008,
/** Used for creating a signature. */
TEE_USAGE_SIGN = 0x00000010,
/** Used for signature verification. */
TEE_USAGE_VERIFY = 0x00000020,
/** Used for key derivation. */
TEE_USAGE_DERIVE = 0x00000040,
/** Used for object initialization, with all permissions assigned by default. */
TEE_USAGE_DEFAULT = 0xFFFFFFFF,
};
/**
* @brief Defines information about the object pointed to by the flag of the TEE_ObjectHandle,
* for example, whether the object is a persistent object or is initialized.
*
* @since 12
*/
enum Handle_Flag_Constants {
/** The object is a persistent object. */
TEE_HANDLE_FLAG_PERSISTENT = 0x00010000,
/** The object is initialized. */
TEE_HANDLE_FLAG_INITIALIZED = 0x00020000,
/** Reserved */
TEE_HANDLE_FLAG_KEY_SET = 0x00040000,
/** Reserved */
TEE_HANDLE_FLAG_EXPECT_TWO_KEYS = 0x00080000,
};
/**
* @brief Defines a value attribute identifier flag.
*
* @since 12
*/
#define TEE_ATTR_FLAG_VALUE 0x20000000
/**
* @brief Defines a public attribute identifier flag.
*
* @since 12
*/
#define TEE_ATTR_FLAG_PUBLIC 0x10000000
/**
* @brief Check whether the attribute is a buffer.
*
* @since 12
*/
#define TEE_ATTR_IS_BUFFER(attribute_id) ((((attribute_id) << 2) >> 31) == 0)
/**
* @brief Check whether the attribute is a value.
*
* @since 12
*/
#define TEE_ATTR_IS_VALUE(attribute_id) ((((attribute_id) << 2) >> 31) == 1)
/**
* @brief Check whether the attribute is protected.
*
* @since 12
*/
#define TEE_ATTR_IS_PROTECTED(attribute_id) ((((attribute_id) << 3) >> 31) == 0)
/**
* @brief Check whether the attribute is public.
*
* @since 12
*/
#define TEE_ATTR_IS_PUBLIC(attribute_id) ((((attribute_id) << 3) >> 31) == 1)
/**
* @brief Obtains a buffer attribute from the TEE_Attribute struct of the object pointed
* to by TEE_ObjectHandle.
*
* The members in the TEE_Attribute struct must be ref. If the TEE_Attribute is private,
* the Usage_Constants of the object must include TEE_USAGE_EXTRACTABLE.
*
* @param object Indicates the handle of the object.
* @param attributeID Indicates the ID of the attribute to obtain, for example, TEE_ObjectAttribute.
* The attribute ID can also be customized.
* @param buffer Indicates the pointer to the buffer that stores the attribute obtained.
* @param size Indicates the pointer to the length of the content stored.
*
* @return Returns TEE_SUCCESS if the operation is successful.
* @return Returns TEE_ERROR_ITEM_NOT_FOUND if the TEE_Attribute cannot be found in the object
* or the object is not initialized.
* @return Returns TEE_ERROR_SHORT_BUFFER if the buffer is too small to store the content obtained.
*
* @since 12
* @version 1.0
*/
TEE_Result TEE_GetObjectBufferAttribute(TEE_ObjectHandle object, uint32_t attributeID, void *buffer, size_t *size);
/**
* @brief Obtains a value attribute from the TEE_Attribute of an object.
*
* The members of the TEE_Attribute struct must be values. If the TEE_Attribute is private,
* the Usage_Constants of the object must include TEE_USAGE_EXTRACTABLE.
*
* @param object Indicates the handle of the object.
* @param attributeID Indicates the ID of the attribute to obtain, for example, TEE_ObjectAttribute.
* The attribute ID can also be customized.
* @param a Indicates the pointer to the placeholder filled with the attribute field a.
* @param b Indicates the pointer to the placeholder filled with the attribute field b.
*
* @return Returns TEE_SUCCESS if the operation is successful.
* @return Returns TEE_ERROR_ITEM_NOT_FOUND if the TEE_Attribute cannot be found in the object
* or the object is not initialized.
* @return Returns TEE_ERROR_ACCESS_DENIED if TEE_Attribute is private
* but the object Usage_Constants does not contain the TEE_USAGE_EXTRACTABLE flag.
*
* @since 12
* @version 1.0
*/
TEE_Result TEE_GetObjectValueAttribute(TEE_ObjectHandle object, uint32_t attributeID, uint32_t *a, uint32_t *b);
/**
* @brief Closes a TEE_ObjectHandle object.
*
* The object can be persistent or transient.
*
* @param object Indicates the TEE_ObjectHandle object to close.
*
* @since 12
* @version 1.0
*/
void TEE_CloseObject(TEE_ObjectHandle object);
/**
* @brief Allocates an uninitialized object to store keys.
*
* objectType and maxObjectSize must be specified.
*
* @param objectType Indicates the type of the object to create. The value is TEE_ObjectType.
* @param maxObjectSize Indicates the maximum number of bytes of the object.
* @param object Indicates the pointer to the handle of the newly created object.
*
* @return Returns TEE_SUCCESS if the operation is successful.
* @return Returns TEE_ERROR_OUT_OF_MEMORY if the memory is insufficient.
* @return Returns TEE_ERROR_NOT_SUPPORTED if the object type is not supported.
*
* @since 12
* @version 1.0
*/
TEE_Result TEE_AllocateTransientObject(uint32_t objectType, uint32_t maxObjectSize, TEE_ObjectHandle *object);
/**
* @brief Releases a transient object that is previously allocated with TEE_AllocateTransientObject.
*
* After the function is called, the handle becomes invalid and all allocated resources are released.
* TEE_FreeTransientObject and TEE_AllocateTransientObject are used in pairs.
*
* @param object Indicates the TEE_ObjectHandle to release.
*
* @since 12
* @version 1.0
*/
void TEE_FreeTransientObject(TEE_ObjectHandle object);
/**
* @brief Resets a transient object to its initial state after allocation.
*
* You can use an allocated object, which has not been initialized or used to store a key, to store a key.
*
* @param object Indicates the TEE_ObjectHandle to reset.
*
* @since 12
* @version 1.0
*/
void TEE_ResetTransientObject(TEE_ObjectHandle object);
/**
* @brief Populates an uninitialized object with object attributes passed by the TA in the attrs parameter.
*
* The object must be uninitialized. \n
* The attrs parameter is passed by a TA.
*
* @param object Indicates the handle on a created but uninitialized object.
* @param attrs Indicates the pointer to an array of object attributes, which can be one or more TEE_Attributes.
* @param attrCount Indicates the number of members in the attribute array.
*
* @return Returns TEE_SUCCESS if the operation is successful.
* @return Returns TEE_ERROR_BAD_PARAMETERS if an incorrect or inconsistent attribute value is detected.
*
* @since 12
* @version 1.0
*/
TEE_Result TEE_PopulateTransientObject(TEE_ObjectHandle object, TEE_Attribute *attrs, uint32_t attrCount);
/**
* @brief Initializes the TEE_Attribute of the buffer type.
*
* The members in the TEE_Attribute struct must be ref.
*
* @param attr Indicates the pointer to the TEE_Attribute initialized.
* @param attributeID Indicates the ID assigned to the TEE_Attribute.
* @param buffer Indicates the pointer to the buffer that stores the content to be allocated.
* @param length Indicates the length of the assigned value, in bytes.
*
* @since 12
* @version 1.0
*/
void TEE_InitRefAttribute(TEE_Attribute *attr, uint32_t attributeID, void *buffer, size_t length);
/**
* @brief Initializes a TEE_Attribute.
*
* @param attr Indicates the pointer to the TEE_Attribute initialized.
* @param attributeID Indicates the ID assigned to the TEE_Attribute.
* @param a Indicates the value to be assigned to the member a in the TEE_Attribute.
* @param b Indicates the value to be assigned to the member b in the TEE_Attribute.
*
* @since 12
* @version 1.0
*/
void TEE_InitValueAttribute(TEE_Attribute *attr, uint32_t attributeID, uint32_t a, uint32_t b);
/**
* @brief Generates a random key or a key pair and populates a transient key object with the generated key.
*
* @param object Indicates a transient object used to hold the generated key.
* @param keySize Indicates the number of bytes of the key.
* @param params Indicates the pointer to the parameters for key generation.
* @param paramCount Indicates the number of parameters required for key generation.
*
* @return Returns TEE_SUCCESS if the operation is successful.
* @return Returns TEE_ERROR_BAD_PARAMETERS if the type of the key generated does not match
* the key that can be held in the transient object.
*
* @since 12
* @version 1.0
*/
TEE_Result TEE_GenerateKey(TEE_ObjectHandle object, uint32_t keySize, TEE_Attribute *params, uint32_t paramCount);
/**
* @brief Get the information of the object data part, the total length of the data part and the current
* position of the data stream.
*
* @param object Indicates the handle of the object.
* @param pos Indicates the data stream position.
* @param len Indicates the data stream length.
*
* @return Returns TEE_SUCCESS if the operation is successful.
* @return Returns others if the operation is failed.
*
* @since 12
* @version 1.0
*/
TEE_Result TEE_InfoObjectData(TEE_ObjectHandle object, uint32_t *pos, uint32_t *len);
/**
* @brief Obtains TEE_ObjectInfo.
*
* This function obtains TEE_ObjectInfo and copies the obtained information to the pre-allocated space
* pointed to by objectInfo.
*
* @param object Indicates the handle of the object.
* @param objectInfo Indicates the pointer to the TEE_ObjectInfo obtained.
*
* @return Returns TEE_SUCCESS if the operation is successful.
* @return Returns TEE_ERROR_CORRUPT_OBJECT if the object is corrupted and the object handle will be closed.
* @return Returns TEE_ERROR_STORAGE_NOT_AVAILABLE if the object is stored
* in a storage area that is inaccessible currently.
*
* @since 12
* @version 1.0
*/
TEE_Result TEE_GetObjectInfo1(TEE_ObjectHandle object, TEE_ObjectInfo *objectInfo);
/**
* @brief Assigns the TEE_Attribute of an initialized object to an uninitialized object.
*
* This function populates an uninitialized object with TEE_Attribute.
* That is, it copies TEE_Attribute of srcobject to destobject.
* The TEE_Attribute types and IDs of the two objects must match.
*
* @param destObject Indicates the uninitialized object.
* @param srcObject Indicates the initialized object.
*
* @return Returns TEE_SUCCESS if the operation is successful.
* @return Returns TEE_ERROR_CORRUPT_OBJECT if the object is corrupted and the object handle will be closed.
* @return Returns TEE_ERROR_STORAGE_NOT_AVAILABLE if the object is stored
* in a storage area that is inaccessible currently.
*
* @since 12
* @version 1.0
*/
TEE_Result TEE_CopyObjectAttributes1(TEE_ObjectHandle destObject, TEE_ObjectHandle srcObject);
/**
* @brief Restricts the objectUse bit of an object.
*
* This bit determines the usage of the key in the object. The value range is Usage_Constant.
* The bit in the objectUse parameter can be set as follows: \n
* If it is set to 1, the corresponding usage flag in the object is left unchanged. \n
* If it is set to 0, the corresponding usage flag in the object is cleared. \n
* The newly created object contains all Usage_Constant, and the usage flag can be cleared only.
*
* @param object Indicates the TEE_ObjectHandle of the target object.
* @param objectUsage Indicates the new object usage.
*
* @return Returns TEE_SUCCESS if the operation is successful.
* @return Returns TEE_ERROR_CORRUPT_OBJECT if the object is corrupted and the object handle will be closed.
* @return Returns TEE_ERROR_STORAGE_NOT_AVAILABLE if the object is stored
* in a storage area that is inaccessible currently.
*
* @since 12
* @version 1.0
*/
TEE_Result TEE_RestrictObjectUsage1(TEE_ObjectHandle object, uint32_t objectUsage);
#ifdef __cplusplus
}
#endif
/** @} */
#endif