diff --git a/sdk/include/TA/ext/oemkey.h b/sdk/include/TA/ext/oemkey.h index a250167..56e6fd3 100644 --- a/sdk/include/TA/ext/oemkey.h +++ b/sdk/include/TA/ext/oemkey.h @@ -13,9 +13,9 @@ /** * @file oemkey.h * - * @brief Interfaces related to the provision key function. + * @brief Provides the method for obtaining the hardware provision key. * - * Provides the function of reading the hardware provision key. + * * * @since 1 */ @@ -26,13 +26,13 @@ #include /** - * @brief Get provision Key + * @brief Obtains the provision key. * - * @param oem_key [IN]Buffer for storing provision keys. - * @param key_size [IN]The length of the buffer used to store the provision key is 16. + * @param oem_key Indicates the pointer to the buffer for storing the provision key. + * @param key_size Indicates the length of the buffer used to store the provision key, which is 16. * - * @return 0 Indicates that the function executed successfully. - * @return others Failed to obtain the provision key + * @return Returns 0 if the operation is successful. + * @return Returns other values otherwise. * */ uint32_t tee_hal_get_provision_key(uint8_t *oem_key, size_t key_size); diff --git a/sdk/include/TA/ext/tee_crypto_hal.h b/sdk/include/TA/ext/tee_crypto_hal.h index 2ef8f81..27c0f68 100644 --- a/sdk/include/TA/ext/tee_crypto_hal.h +++ b/sdk/include/TA/ext/tee_crypto_hal.h @@ -13,9 +13,9 @@ /** * @file tee_crypto_hal.h * - * @brief ¼Ó½âÃÜ½Ó¿Ú + * @brief Provides APIs for cryptographic operations. * - * ¿ª·¢Õß¿ÉÒÔʹÓÃÕâЩ½Ó¿ÚʵÏÖ¼Ó½âÃܵÄÏà¹Ø¹¦ÄÜ¡£ + * You can use these APIs to implement encryption and decryption. * * @since 1 */ @@ -28,25 +28,25 @@ enum CRYPTO_ENGINE { }; /** - * @brief ½«¼ÓÃܺͽâÃÜÒýÇæÉèÖÃΪÔËÐÐ + * @brief Sets the encryption and decryption engines to an operation. * - * @param operation [IN/OUT]²Ù×÷µÄ¾ä±ú - * @param crypto [IN]ÒªÉèÖõÄengine + * @param operation Indicates the handle of the operation to set. + * @param crypto Indicates the engines to set. * - * @return TEE_SUCCESS ÉèÖüÓÃÜÒýÇæ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ²Ù×÷ΪNULLi»ò¼ÓÃÜÎÞЧ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if operation is null or crypto is invalid. * */ TEE_Result TEE_SetCryptoFlag(TEE_OperationHandle operation, uint32_t crypto); /** - * @brief ÉèÖüӽâÃÜÒýÇæΪobject + * @brief Sets the encryption and decryption engines to an object. * - * @param operation [IN/OUT]¶ÔÏóµÄ¾ä±ú - * @param crypto [IN]ÒªÉèÖõÄengine + * @param object Indicates the handle of the object to set. + * @param crypto Indicates the engines to set. * - * @return TEE_SUCCESS ÉèÖüÓÃÜÒýÇæ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ²Ù×÷ΪNULLi»ò¼ÓÃÜÎÞЧ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if object is null or crypto is invalid. * */ TEE_Result TEE_SetObjectFlag(TEE_ObjectHandle object, uint32_t crypto); diff --git a/sdk/include/TA/ext/tee_ext_api.h b/sdk/include/TA/ext/tee_ext_api.h index 281e381..5d89d4c 100644 --- a/sdk/include/TA/ext/tee_ext_api.h +++ b/sdk/include/TA/ext/tee_ext_api.h @@ -13,7 +13,7 @@ /** * @file tee_ext_api.h * - * @brief À©Õ¹½Ó¿Ú + * @brief Provides extended interfaces. * * @since 1 */ @@ -31,21 +31,22 @@ extern "C" { /** - * @brief TA¿ÉÒÔµ÷ÓôËAPIÌí¼Óµ÷ÓÃÕßÐÅÏ¢£¬ÔÊÐíµ÷ÓôËTA¡£´ËAPIÓÃÓÚCA£¬ÒÔ¶þ½øÖÆ¿ÉÖ´ÐÐÎļþµÄÐÎʽ + * @brief Adds information about a caller that can invoke this TA. + * This API applies to the client applications (CAs) in the binary executable file format. * - * @param ca_name[IN]CAµ÷Ó÷½µÄ½ø³ÌÃû³Æ - * @param ca_uid[IN]CAµ÷Ó÷½µÄuid + * @param ca_name Indicates the process name of the caller of the CA. + * @param ca_uid Indicates the UID of the caller. * - * @return TEE_SUCCESS ²Ù×÷³É¹¦ - * @return others ÎÞ·¨ÎªÄ¿±êCAÌí¼ÓÖ÷½Ð·½ÐÅÏ¢ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns other information otherwise. * */ TEE_Result AddCaller_CA_exec(const char *ca_name, uint32_t ca_uid); /** - * @brief »ñÈ¡µ±Ç°»á»°ÀàÐÍ + * @brief Obtains the session type. * - * @return µ±Ç°»á»°µÄ»á»°ÀàÐÍ + * @return Returns the session type obtained. * */ uint32_t TEE_GetSessionType(void); diff --git a/sdk/include/TA/ext/tee_hw_ext_api.h b/sdk/include/TA/ext/tee_hw_ext_api.h index 5178784..7242054 100644 --- a/sdk/include/TA/ext/tee_hw_ext_api.h +++ b/sdk/include/TA/ext/tee_hw_ext_api.h @@ -13,7 +13,7 @@ /** * @file tee_hw_ext_api.h * - * @brief À©Õ¹½Ó¿Ú + * @brief Provides extended interfaces. * * @since 1 */ @@ -23,13 +23,13 @@ #include "tee_defines.h" /** - * @brief ÔÚTEEÖлñÈ¡É豸ΨһID + * @brief Obtains the unique device ID from the TEE. * - * @param device_unique_id [IN]ÓÃÓÚ´æ´¢½á¹ûµÄ»º³åÇø - * @param length [IN/OUT]É豸ID»º³åÇø³¤¶È + * @param device_unique_id Indicates the pointer to the buffer for storing the device ID. + * @param length Indicates the pointer to the buffer length. * - * @return TEE_SUCCESS ²Ù×÷³É¹¦ - * @return others ²Ù×÷ʧ°Ü + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns other information otherwise. * */ TEE_Result TEE_EXT_GetDeviceUniqueId(uint8_t *device_unique_id, uint32_t *length); diff --git a/sdk/include/TA/ext/tee_log.h b/sdk/include/TA/ext/tee_log.h index 7ed3d68..53fa460 100644 --- a/sdk/include/TA/ext/tee_log.h +++ b/sdk/include/TA/ext/tee_log.h @@ -13,9 +13,9 @@ /** * @file tee_log.h * - * @brief tee log api + * @brief Provides TEE log APIs. * - * Reference of TEE log api and internal definitions. + * Reference of TEE log APIs and internal definitions. * * @since 1 */ @@ -115,7 +115,7 @@ extern const char *g_debug_prefix; #endif /* TA_LOG_LEVEL >= TA_LOG_LEVEL_WARNING */ /* tloge */ -#if (TA_LOG_LEVEL >= TA_LOG_LEVEL_ERROR) /* Always meet this condition */ +#if (TA_LOG_LEVEL >= TA_LOG_LEVEL_ERROR) /* Always meet this condition. */ #ifndef TLOGE_NO_TIMESTAMP #ifdef DRIVER_LOG_TAG #define tloge(fmt, args...) \ @@ -132,4 +132,4 @@ extern const char *g_debug_prefix; } while (0) #endif /* TA_LOG_LEVEL >= TA_LOG_LEVEL_ERROR */ -#endif /* __TEE_LOG_H */ \ No newline at end of file +#endif /* __TEE_LOG_H */ diff --git a/sdk/include/TA/tee_arith_api.h b/sdk/include/TA/tee_arith_api.h index 6f0d072..63291cd 100644 --- a/sdk/include/TA/tee_arith_api.h +++ b/sdk/include/TA/tee_arith_api.h @@ -13,7 +13,7 @@ /** * @file tee_arith_api.h * - * @brief ´óÊý²Ù×÷½Ó¿Ú + * @brief Provides APIs for operating big integers. * * @since 1 */ @@ -24,440 +24,456 @@ #include /** - * below definitions are defined by Global Platform - * for compatibility: - * don't make any change to the content below + * The definitions below are defined by Global Platform + * for compatibility. + * Do not make any change to the content below. */ typedef uint32_t TEE_BigInt; typedef uint32_t TEE_BigIntFMM; typedef uint32_t TEE_BigIntFMMContext; /** - * @brief ·µ»Øu32ÖеÄBigIntµÄ´óС + * @brief Obtains the size of the array of uint32_t values required to represent a BigInt. * - * @param n [IN]TEE_BigIntÀàÐÍ + * @param n Indicates the TEE_BigInt type. * - * @return 32ÖеÄBigIntµÄ´óС + * @return Returns the BigInt size obtained. * */ #define TEE_BigIntSizeInU32(n) ((((n) + 31) / 32) + 2) /** - * @brief ·µ»Øuint32_tÖµÊý×éµÄ´óС + * @brief Obtains the size of the array of uint32_t values. * - * @param modulusSizeInBits [IN]Ä£ÊýµÄ´óС£¨ÒÔbitsΪµ¥Î»£© + * @param modulusSizeInBits Indicates the modulus size, in bits. * - * @return ¸ø¶¨³¤¶ÈÄ£ÊýmodSizeInBits£¬´æ´¢TEE_BigIntFMMËùÐèµÄ×Ö½ÚÊý + * @return Returns the number of bytes required to store a TEE_BigIntFMM, + * given a modulus of length modSizeInBits. * */ size_t TEE_BigIntFMMSizeInU32(size_t modulusSizeInBits); /** - * @brief ·µ»Ø±íʾ¿ìËÙÄ£¿é»¯ÉÏÏÂÎÄËùÐèµÄuint32_tÖµÊý×éµÄ´óС + * @brief Obtains the size of an array of uint32_t values required to represent a fast modular context. * - * @param modulusSizeInBits [IN]Ä£ÊýµÄ´óС£¨ÒÔbitsΪµ¥Î»£© + * @param modulusSizeInBits Indicates the modulus size, in bits. * - * @return ´æ´¢TEE_BigIntFMMContextËùÐèµÄ×Ö½ÚÊý£¬¸ø¶¨³¤¶ÈÄ£ÊýmodSizeInBits + * @return Returns the number of bytes required to store a TEE_BigIntFMMContext, + * given a modulus of length modSizeInBits. * */ size_t TEE_BigIntFMMContextSizeInU32(size_t modulusSizeInBits); /** - * @brief ³õʼ»¯bigInt + * @brief Initializes a TEE_BigInt. * - * @param bigInt [OUT]Ö¸ÏòÒª³õʼ»¯µÄTEE_BigIntµÄÖ¸Õë - * @param len [IN]bigIntÖ¸ÏòµÄÄÚ´æµÄ´óС£¬µ¥Î»Îªuint32_t + * @param bigInt Indicates the pointer to the TEE_BigInt to initialize. + * @param len Indicates the size of the memory pointed to by TEE_BigInt, in uint32_t. * */ void TEE_BigIntInit(TEE_BigInt *bigInt, size_t len); /** - * @brief ¼ÆËã¿ìËÙÄ£³Ë·¨µÄ±ØÒªÏȾöÌõ¼þ£¬²¢½«ËüÃÇ´æ´¢ÔÚÉÏÏÂÎÄÖÐ + * @brief Calculates the necessary prerequisites for fast modular multiplication and stores them in a context. * - * @param context [OUT]Òª³õʼ»¯µÄTEE_BigIntFMMContextÖ¸Õë - * @param len [IN]ÉÏÏÂÎÄÖ¸ÏòµÄÄÚ´æµÄ´óС£¨ÒÔuint32_tΪµ¥Î»£© - * @param modulus [IN]Ä£Êý + * @param context Indicates the pointer to the TEE_BigIntFMMContext to initialize. + * @param len Indicates the size of the memory pointed to by context, in uint32_t. + * @param modulus Indicates the pointer to the modulus. * */ void TEE_BigIntInitFMMContext(TEE_BigIntFMMContext *context, size_t len, const TEE_BigInt *modulus); /** - * @brief ¼ÆËã¿ìËÙÄ£³Ë·¨µÄ±ØÒªÏȾöÌõ¼þ£¬²¢½«ËüÃÇ´æ´¢ÔÚÉÏÏÂÎÄÖÐ + * @brief Calculates the necessary prerequisites for fast modular multiplication and stores them in a context. * - * @param context [OUT]Òª³õʼ»¯µÄTEE_BigIntFMMContextÖ¸Õë - * @param len [IN]ÉÏÏÂÎÄÖ¸ÏòµÄÄÚ´æµÄ´óС£¨ÒÔuint32_tΪµ¥Î»£© - * @param modulus [IN]Ä£Êý + * @param context Indicates the pointer to the TEE_BigIntFMMContext to initialize. + * @param len Indicates the size of the memory pointed to by context, in uint32_t. + * @param modulus Indicates the pointer to the modulus. * - * @return TEE_SUCCESS ³É¹¦ - * @return ÆäËü·µ»ØÖµ ʧ°Ü + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns other values if the operation fails. * */ TEE_Result TEE_BigIntInitFMMContext1(TEE_BigIntFMMContext *context, size_t len, const TEE_BigInt *modulus); /** - * @brief ³õʼ»¯bigIntFMM²¢½«Æä±íʾµÄÖµÉèÖÃΪÁã + * @brief Initializes a TEE_BigIntFMM and sets its represented value to zero. * - * @param bigIntFMM [IN]Òª³õʼ»¯µÄTEE_BigIntFMMÖ¸Õë - * @param len [IN]bigIntFMMÖ¸ÏòµÄÄÚ´æ´óС£¬µ¥Î»Îªuint32_t + * @param bigIntFMM Indicates the pointer to the TEE_BigIntFMM to initialize. + * @param len Indicates the size of the memory pointed to by bigIntFMM, in uint32_t. * */ void TEE_BigIntInitFMM(TEE_BigIntFMM *bigIntFMM, size_t len); /** - * @brief ½«bufferLen×Ö½Ú°Ëλ×Ö½Ú×Ö·û´®»º³åÇøת»»ÎªTEE_BigInt¸ñʽ + * @brief Converts an octet string buffer into the TEE_BigInt format. * - * @param dest [OUT]Ö¸ÏòÓÃÓÚ±£´æ½á¹ûµÄTEE_BigIntµÄÖ¸Õë - * @param buffer [IN]Ö¸Ïò°üº¬ÕûÊýµÄ°Ëλ×Ö½Ú×Ö·û´®±íʾÐÎʽµÄ»º³åÇøµÄÖ¸Õë - * @param bufferLen [IN]bufferµÄ³¤¶È£¨ÒÔ×Ö½ÚΪµ¥Î»£© - * @param sign [IN]destµÄ±êÖ¾±»ÉèÖÃΪ±êÖ¾µÄ±êÖ¾ + * @param dest Indicates the pointer to the TEE_BigInt that holds the result. + * @param buffer Indicates the pointer to the buffer that holds the octet string representation of the integer. + * @param bufferLen Indicates the buffer length, in bytes. + * @param sign Indicates the sign of dest, which is set to the sign of sign. * - * @return TEE_SUCCESS Ö§³Ö - * @return TEE_ERROR_OVERFLOW Ϊdest·ÖÅäµÄÄÚ´æ̫С + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OVERFLOW if the memory allocated for dest is too small. * */ TEE_Result TEE_BigIntConvertFromOctetString(TEE_BigInt *dest, const uint8_t *buffer, size_t bufferLen, int32_t sign); /** - * @brief ½«TEE_BigInt¸ñʽµÄÕûÊýµÄ¾ø¶Ôֵת»»Îª°Ëλ×Ö½Ú×Ö·û´® + * @brief Converts the absolute value of an integer in TEE_BigInt format into an octet string. * - * @param buffer [OUT]дÈëÕûÊýµÄת»»°Ëλ×Ö½Ú×Ö·û´®±íʾµÄÊä³ö»º³åÇø - * @param bufferLen [IN]bufferµÄ³¤¶È£¨ÒÔ×Ö½ÚΪµ¥Î»£© - * @param bigInt [IN]Ö¸Ïò½«×ª»»Îª°Ëλ×Ö½Ú×Ö·û´®µÄÕûÊýµÄÖ¸Õë + * @param buffer Indicates the pointer to the output buffer that holds the converted octet string representation + * of the integer. + * @param bufferLen Indicates the pointer to the buffer length, in bytes. + * @param bigInt Indicates the pointer to the integer to convert. * - * @return TEE_SUCCESS Ö§³Ö - * @return TEE_ERROR_SHORT_BUFFER Êä³ö»º³åÇø̫С£¬ÎÞ·¨°üº¬°Ëλ×Ö½Ú×Ö·û´® + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_SHORT_BUFFER if the output buffer is too small to hold the octet string. * */ TEE_Result TEE_BigIntConvertToOctetString(void *buffer, size_t *bufferLen, const TEE_BigInt *bigInt); /** - * @brief ½«*destÉèÖÃΪֵshortVal + * @brief Sets dest to the value shortVal. * - * @param dest [OUT]Ö¸ÏòÓÃÓÚ´æ´¢½á¹ûµÄTEE_BigIntµÄÖ¸Õë - * @param shortVal [IN]ÊäÈëÖµ + * @param dest Indicates the pointer to the TEE_BigInt that holds the result. + * @param shortVal Indicates the value to set. * */ void TEE_BigIntConvertFromS32(TEE_BigInt *dest, int32_t shortVal); /** - * @brief ½«*destÉèÖÃΪsrcµÄÖµ£¬°üÀ¨srcµÄ·ûºÅ + * @brief Sets dest to the value of src, including the sign of src. * - * @param dest [OUT]Ö¸ÏòÓÃÓÚ´æ´¢½á¹ûµÄint32_tµÄÖ¸Õë - * @param src [IN]ÊäÈëÖµÖ¸Õë + * @param dest Indicates the pointer to the int32_t that holds the result. + * @param src Indicates the pointer to the value to set. * - * @return TEE_SUCCESS Ö§³Ö - * @return TEE_ERROR_OVERFLOW src²»ÊʺÏint32_t + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OVERFLOW if src does not fit within an int32_t. * */ TEE_Result TEE_BigIntConvertToS32(int32_t *dest, const TEE_BigInt *src); /** - * @brief ¼ì²éop1>op2¡¢op1==op2»òop1 op2, op1 == op2, or op1 < op2. * - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. * - * @return 0 op1==op2 - * @return ÕýÊý op1>op2 + * @return Returns 0 if op1 == op2. + * @return Returns a positive number if op1 > op2. * */ int32_t TEE_BigIntCmp(const TEE_BigInt *op1, const TEE_BigInt *op2); /** - * @brief ¼ì²éÊÇop>shortVal¡¢op==shortVal»òop shortVal, op == shortVal, or op < shortVal. * - * @param op [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param shortVal [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë + * @param op Indicates the pointer to the first operand. + * @param shortVal Indicates the pointer to the second operand. * - * @return 0 op1==shortVal - * @return ÕýÊý op1>shortVal + * @return Returns 0 if op1 == shortVal. + * @return Returns a positive number if op1 > shortVal. * */ int32_t TEE_BigIntCmpS32(const TEE_BigInt *op, int32_t shortVal); /** - * @brief ¼ÆËã |dest| = |op| >> bits + * @brief Computes |dest| = |op| >> bits. * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ±£´æÒÆλµÄ½á¹û - * @param op [IN]Ö¸ÏòÒªÒÆλµÄ²Ù×÷ÊýµÄÖ¸Õë - * @param bits [IN]ÒªÒÆλµÄλÊý + * @param dest Indicates the pointer to the TEE_BigInt that holds the shifted result. + * @param op Indicates the pointer to the operand to be shifted. + * @param bits Indicates the number of bits to shift. * */ void TEE_BigIntShiftRight(TEE_BigInt *dest, const TEE_BigInt *op, size_t bits); /** - * @brief ·µ»Ø|src|µÄ×ÔÈ»¶þ½øÖƱíʾµÄbitIndexλ + * @brief Obtains the bitIndex bit of the natural binary representation of |src|. * - * @param src [IN]ÕûÊýÖ¸Õë - * @param bitIndex [IN]Òª¶ÁÈ¡µÄλµÄÆ«ÒÆÁ¿£¬´Ó×îµÍÓÐЧλµÄÆ«ÒÆÁ¿0¿ªÊ¼ + * @param src Indicates the pointer to the integer. + * @param bitIndex Indicates the offset of the bit to read, starting from offset 0 of the least significant bit. * - * @return true |src|ÖÐbitIndexthλµÄ²¼¶ûֵΪ¡°1¡± - * @return false |src|ÖÐbitIndexthλµÄ²¼¶ûֵΪ¡°0¡± + * @return Returns the Boolean value of bitIndexth in |src|. The value true represents a 1, + * @return and false represents a 0. * */ bool TEE_BigIntGetBit(const TEE_BigInt *src, uint32_t bitIndex); /** - * @brief ·µ»Ø|src|µÄ×ÔÈ»¶þ½øÖƱíʾÖеÄλÊý£»¼´srcµÄ´óС + * @brief Obtains the number of bits in the natural binary representation of |src|, + * that is, the magnitude of src. * - * @param src [IN]ÕûÊýÖ¸Õë + * @param src Indicates the pointer to the integer. * - * @return 0 src=0 - * @return srcµÄ×ÔÈ»¶þ½øÖƱíʾÖеÄλÊý¡£ + * @return Returns 0 if src is 0. + * @return Returns the number of bits in the natural binary representation of src. * */ uint32_t TEE_BigIntGetBitCount(const TEE_BigInt *src); #if defined(API_LEVEL) && (API_LEVEL >= API_LEVEL1_2) /** - * @brief ½«opµÄ×ÔÈ»¶þ½øÖƱíʾµÄbitIndexµÚ1λÉèÖÃΪ1»ò0 + * @brief Sets the first bit of bitIndex in the natural binary representation of op to + * 1 or 0. * - * @param op [IN/OUT]ÕûÊýÖ¸Õë - * @param bitIndex [IN]ÒªÉèÖõÄλµÄÆ«ÒÆÁ¿£¬´Ó×îµÍÓÐЧλµÄÆ«ÒÆÁ¿0¿ªÊ¼ - * @param value [IN]ÒªÉèÖõÄλֵ£¬ÆäÖÐtrue±íʾ¡°1¡±£¬false±íʾ¡°0¡± + * @param op Indicates the pointer to the integer. + * @param bitIndex Indicates the offset of the bit to set, starting from offset 0 of the least significant bit. + * @param value Indicates the bit value to set. The value true represents a 1, and the value false + * represents a 0. * - * @return TEE_SUCCESS Ö§³Ö - * @return TEE_ERROR_OVERFLOW bitIndexthλ´óÓÚopµÄ·ÖÅä볤¶È + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OVERFLOW bitIndexth if the bitIndexth bit is larger than the allocated bit + * length of op. * */ TEE_Result TEE_BigIntSetBit(TEE_BigInt *op, uint32_t bitIndex, bool value); /** - * @brief ½«srcµÄÖµ¸³Öµ¸ødest + * @brief Assigns the value of src to dest. * - * @param dest [OUT]Òª·ÖÅäµÄTEE_BigIntÖ¸Õë - * @param src [IN]Ö¸ÏòÔ´²Ù×÷ÊýµÄÖ¸Õë + * @param dest Indicates the pointer to the TEE_BigInt to be assigned. + * @param src Indicates the pointer to the source operand. * - * @return TEE_SUCCESS Ö§³Ö - * @return TEE_ERROR_OVERFLOW Èç¹ûdest²Ù×÷Êý²»ÄÜÈÝÄÉsrcµÄÖµ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OVERFLOW if the dest operand cannot hold the value of src. * */ TEE_Result TEE_BigIntAssign(TEE_BigInt *dest, const TEE_BigInt *src); /** - * @brief ½«srcµÄÖµ¸³¸ødest + * @brief Assigns the value of src to dest. * - * @param dest [OUT]Òª·ÖÅäµÄTEE_BigIntÖ¸Õë - * @param src [IN]Ö¸ÏòÔ´²Ù×÷ÊýµÄÖ¸Õë + * @param dest Indicates the pointer to the TEE_BigInt to be assigned. + * @param src Indicates the pointer to the source operand. * - * @return TEE_SUCCESS Ö§³Ö - * @return TEE_ERROR_OVERFLOW Èç¹ûdest²Ù×÷Êý²»ÄÜÈÝÄÉsrcµÄÖµ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OVERFLOW if the dest operand cannot hold the value of src. * */ TEE_Result TEE_BigIntAbs(TEE_BigInt *dest, const TEE_BigInt *src); #endif /* API_LEVEL */ /** - * @brief ¼ÆËã dest= op1 + op2 + * @brief Computes dest = op1 + op2. * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ´æ´¢½á¹ûop1 + op2 - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë + * @param dest Indicates the pointer to the TEE_BigInt that holds the sum of op1 and op2. + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. * */ void TEE_BigIntAdd(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); /** - * @brief ¼ÆËã dest= op1 - op2 + * @brief Computes dest = op1 – op2. * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ´æ´¢½á¹ûop1 - op2 - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë + * @param dest Indicates the pointer to the TEE_BigInt that holds the difference between op1 + * and op2. + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. * */ void TEE_BigIntSub(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); /** - * @brief È¡·´²Ù×÷Êý£ºdest = -op + * @brief Negates an operand: dest = –op. * - * @param dest [OUT]PÖ¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ´æ´¢½á¹û-op - * @param op [IN]Ö¸ÏòҪȡ·´µÄ²Ù×÷ÊýµÄÖ¸Õë + * @param dest Indicates the pointer to the TEE_BigInt that holds the result –op. + * @param op Indicates the pointer to the operand to be negated. * */ void TEE_BigIntNeg(TEE_BigInt *dest, const TEE_BigInt *op); /** - * @brief ¼ÆËã dest = op1 * op2 + * @brief Computes dest = op1 * op2. * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ´æ´¢½á¹ûop1 * op2 - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë + * @param dest Indicates the pointer to the TEE_BigInt that holds the product of op1 and op2. + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. * */ void TEE_BigIntMul(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2); /** - * @brief ¼ÆËã dest = op * op + * @brief Computes dest = op * op. * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ´æ´¢½á¹ûop * op - * @param op [IN]Ö¸ÏòҪƽ·½µÄ²Ù×÷ÊýµÄÖ¸Õë + * @param dest Indicates the pointer to the TEE_BigInt that holds the result op * op. + * @param op Indicates the pointer to the operand to be squared. * */ void TEE_BigIntSquare(TEE_BigInt *dest, const TEE_BigInt *op); /** - * @brief ¼ÆËãdest_rºÍdest_q£¬Ê¹µÃop1 = dest_q * op2 + dest_r + * @brief Computes dest_r and dest_q to make op1 = dest_q* op2 + dest_r. * - * @param dest_q [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ´æ´¢ÉÌ - * @param dest_r [IN]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ´æ´¢ÓàÊý - * @param op1 [OUT]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õ룬±»³ýÊý - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õ룬³ýÊý + * @param dest_q Indicates the pointer to the TEE_BigInt that holds the quotient. + * @param dest_r Indicates the pointer to the TEE_BigInt that holds the remainder. + * @param op1 Indicates the pointer to the first operand, which is the dividend. + * @param op2 Indicates the pointer to the second operand, which is the divisor. * - * @return TEE_SUCCESS ²Ù×÷³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ÆäÖдæÔÚÖÁÉÙÒ»¸ö²ÎÊýΪNULL + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if at least one parameter is null. * */ void TEE_BigIntDiv(TEE_BigInt *dest_q, TEE_BigInt *dest_r, const TEE_BigInt *op1, const TEE_BigInt *op2); /** - * @brief ¼ÆËãdest = op (mod n)£¬Ê¹µÃ0 <= dest < n + * @brief Computes dest = op (mod n) to make 0 <= dest < n. * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÒÔ±£´æ½á¹ûop (mod n) - * @param op [IN]Ö¸ÏòÒªËõ¼õmod nµÄ²Ù×÷ÊýµÄÖ¸Õë - * @param n [IN]Ö¸ÏòÄ£ÊýµÄÖ¸Õ롣ģÊýÓ¦´óÓÚ1 + * @param dest Indicates the pointer to the TEE_BigInt that holds the result op (mod n). + * @param op Indicates the pointer to the operand to be reduced mod n. + * @param n [IN] Indicates the pointer to the modulus, which must be greater than 1. * */ void TEE_BigIntMod(TEE_BigInt *dest, const TEE_BigInt *op, const TEE_BigInt *n); /** - * @brief ¼ÆËãdest= (op1 + op2) (mod n) + * @brief Computes dest = (op1 + op2) (mod n). * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÒÔ±£´æ½á¹û(op1 + op2)(mod n) - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param n [IN]Ö¸ÏòÄ£ÊýµÄÖ¸Õ룬ģÊýÓ¦´óÓÚ1 + * @param dest Indicates the pointer to the TEE_BigInt that holds the result op (op1 + op2)(mod n). + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. + * @param n Indicates the pointer to the modulus, which must be greater than 1. * */ void TEE_BigIntAddMod(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n); /** - * @brief ¼ÆËãdest = (op1 - op2) (mod n) + * @brief Computes dest = (op1 – op2) (mod n). * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÒÔ±£´æ½á¹û(op1 - op2)(mod n) - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param n [IN]Ö¸ÏòÄ£ÊýµÄÖ¸Õ룬ģÊýÓ¦´óÓÚ1 + * @param dest Indicates the pointer to the TEE_BigInt that holds the result op (op1 – op2)(mod n). + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. + * @param n Indicates the pointer to the modulus, which must be greater than 1. * */ void TEE_BigIntSubMod(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n); /** - * @brief ¼ÆËãdest = (op1 * op2) (mod n) + * @brief Computes dest = (op1* op2)(mod n). * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÒÔ±£´æ½á¹û(op1 * op2)(mod n) - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param n [IN]Ö¸ÏòÄ£ÊýµÄÖ¸Õ룬ģÊýÓ¦´óÓÚ1 + * @param dest Indicates the pointer to the TEE_BigInt that holds the result op (op1 * op2)(mod n). + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. + * @param n Indicates the pointer to the modulus, which must be greater than 1. * */ void TEE_BigIntMulMod(TEE_BigInt *dest, const TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n); /** - * @brief ¼ÆËãdest = (op * op) (mod n) + * @brief Computes dest = (op * op) (mod n). * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÒÔ±£´æ½á¹û(op * op)(mod n) - * @param op [IN]²Ù×÷ÊýÖ¸Õë - * @param n [IN]Ö¸ÏòÄ£ÊýµÄÖ¸Õ롣ģÊýÓ¦´óÓÚ1 + * @param dest Indicates the pointer to the TEE_BigInt that holds the result op (op * op)(mod n). + * @param op Indicates the pointer to the operand. + * @param n [IN] Indicates the pointer to the modulus, which must be greater than 1. * */ void TEE_BigIntSquareMod(TEE_BigInt *dest, const TEE_BigInt *op, const TEE_BigInt *n); /** - * @brief ¼ÆËãdest£¬Ê¹dest * op = 1 (mod n) + * @brief Computes dest to make dest* op = 1 (mod n). * - * @param dest [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÒÔ±£´æ½á¹û£¨op^-1£©(mod n) - * @param op [IN]²Ù×÷ÊýÖ¸Õë - * @param n [IN]Ö¸ÏòÄ£ÊýµÄÖ¸Õ롣ģÊýÓ¦´óÓÚ1 + * @param dest Indicates the pointer to the TEE_BigInt that holds the result (op^–1)(mod n). + * @param op Indicates the pointer to the operand. + * @param n [IN] Indicates the pointer to the modulus, which must be greater than 1. * */ void TEE_BigIntInvMod(TEE_BigInt *dest, const TEE_BigInt *op, const TEE_BigInt *n); /** - * @brief È·¶¨ÊÇ·ñgcd(op1, op2) == 1 + * @brief Checks whether gcd(op1, op2) == 1. * - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. * - * @return true gcd(op1, op2) == 1 - * @return false gcd(op1, op2) != 1 + * @return Returns true if gcd(op1, op2) == 1. + * @return Returns false if gcd(op1, op2) != 1. * */ bool TEE_BigIntRelativePrime(const TEE_BigInt *op1, const TEE_BigInt *op2); /** - * @brief ¼ÆËãÊäÈë²ÎÊýop1ºÍop2µÄ×î´ó¹«Ô¼Êý + * @brief Computes the greatest common divisor of op1 and op2. * - * @param gcd [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ±£´æop1ºÍop2µÄ×î´ó¹«Ô¼Êý - * @param u [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ±£´æµÚÒ»¸öϵÊý - * @param v [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÓÃÓÚ±£´æµÚ¶þ¸öϵÊý - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë + * @param gcd Indicates the pointer to the TEE_BigInt that holds the greatest common divisor of op1 + * and op2. + * @param u Indicates the pointer to the TEE_BigInt that holds the first coefficient. + * @param v Indicates the pointer to the TEE_BigInt that holds the second coefficient. + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. * */ void TEE_BigIntComputeExtendedGcd(TEE_BigInt *gcd, TEE_BigInt *u, TEE_BigInt *v, const TEE_BigInt *op1, const TEE_BigInt *op2); /** - * @brief ¶ÔopÖ´ÐиÅÂÊԭʼÐÔ¼ìÑé + * @brief Performs a probabilistic primality test on op. * - * @param op [IN]¾­¹ýԭʼ²âÊԵĺòÑ¡ºÅÂë - * @param confidenceLevel [IN]·Ç½áÂÛÐÔ²âÊÔµÄÆÚÍûÖÃÐÅˮƽ + * @param op Indicates the pointer to the candidate number that is tested for primality. + * @param confidenceLevel Indicates the expected confidence level for a non-conclusive test. * - * @return 0 opÊǸ´ºÏÊý - * @return 1 opÊÇËØÊý - * @return -1 ²âÊÔÊǷǽáÂÛÐԵģ¬µ«opÊǸ´ºÏµÄ¸ÅÂÊСÓÚ2^£¨-confidenceLevel£© + * @return Returns 0 if op is a composite number. + * @return Returns 1 if op is a prime number. + * @return Returns –1 if the test is non-conclusive but the probability that op is composite is + * less than 2^(-confidenceLevel). * */ int32_t TEE_BigIntIsProbablePrime(const TEE_BigInt *op, uint32_t confidenceLevel); /** - * @brief ½«srcת»»ÎªÊʺϽøÐпìËÙÄ£³ËµÄ±íʾ + * @brief Converts src into a representation suitable for doing fast modular multiplication. * - * @param dest [OUT]TEE_BigIntFMM³õʼ»¯ÄÚ´æÇøÓòÖ¸Õë - * @param src [IN]Ö¸ÏòҪת»»µÄTEE_BigIntµÄÖ¸Õë - * @param n [IN]Ä£ÊýÖ¸Õë - * @param context [IN]Ö¸ÏòÏÈǰʹÓÃTEE_BigIntInitFMMContext1³õʼ»¯µÄÉÏÏÂÎĵÄÖ¸Õë + * @param dest Indicates the pointer to an initialized TEE_BigIntFMM memory area. + * @param src Indicates the pointer to the TEE_BigInt to convert. + * @param n Indicates the pointer to the modulus. + * @param context Indicates the pointer to the context that is previously initialized using + * {@link TEE_BigIntInitFMMContext1}. * */ void TEE_BigIntConvertToFMM(TEE_BigIntFMM *dest, const TEE_BigInt *src, const TEE_BigInt *n, const TEE_BigIntFMMContext *context); /** - * @brief ½«¿ìËÙÄ£³Ë±íʾÖеÄsrcת»»»ØTEE_BigInt±íʾ + * @brief Converts src in the fast modular multiplication representation back to a + * TEE_BigInt representation. * - * @param dest [OUT]Ö¸ÏòÓÃÓÚ±£´æת»»½á¹ûµÄ³õʼ»¯TEE_BigIntFMMÄÚ´æÇøÓòµÄÖ¸Õë - * @param src [IN]Ö¸Ïò±£´æ¿ìËÙÄ£³Ë±íʾÖÐÖµµÄTEE_BigIntFMMµÄÖ¸Õë - * @param n [IN]Ä£ÊýÖ¸Õë - * @param context [IN]Ö¸ÏòÏÈǰʹÓÃTEE_BigIntInitFMMContext1³õʼ»¯µÄÉÏÏÂÎĵÄÖ¸Õë + * @param dest Indicates the pointer to an initialized TEE_BigIntFMM memory area to store the converted result. + * @param src Indicates the pointer to a TEE_BigIntFMM holding the value in the fast modular multiplication + * representation. + * @param n Indicates the pointer to the modulus. + * @param context Indicates the pointer to the context that is previously initialized using + * {@link TEE_BigIntInitFMMContext1}. * */ void TEE_BigIntConvertFromFMM(TEE_BigInt *dest, const TEE_BigIntFMM *src, const TEE_BigInt *n, const TEE_BigIntFMMContext *context); /** - * @brief ¼ÆËã¿ìËÙÄ£³Ë·¨±íʾÖеÄdest = op1 * op2 + * @brief Computes dest = op1* op2 in the fast modular multiplication representation. * - * @param dest [OUT]Ö¸ÏòTEE_BigIntFMMµÄÖ¸Õ룬ÓÃÓÚ±£´æ½á¹ûop1 * op2 - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param n [IN]Ä£ÊýÖ¸Õë - * @param context[IN]Ö¸ÏòÏÈǰʹÓÃTEE_BigIntInitFMMContext1³õʼ»¯µÄÉÏÏÂÎĵÄÖ¸Õë + * @param dest Indicates the pointer to the TEE_BigIntFMM that holds the result op1* op2. + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. + * @param n Indicates the pointer to the modulus. + * @param context Indicates the pointer to the context that is previously initialized using + * {@link TEE_BigIntInitFMMContext1}. * */ void TEE_BigIntComputeFMM(TEE_BigIntFMM *dest, const TEE_BigIntFMM *op1, const TEE_BigIntFMM *op2, const TEE_BigInt *n, const TEE_BigIntFMMContext *context); /** - * @brief ¼ÆËãdest = (op1 ^ op2) (mod n) + * @brief Computes dest = (op1 ^ op2)(mod n). * - * @param des [OUT]Ö¸ÏòTEE_BigIntµÄÖ¸Õ룬ÒÔ±£´æ½á¹û(op1 ^ op2)(mod n) - * @param op1 [IN]Ö¸ÏòµÚÒ»¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param op2 [IN]Ö¸ÏòµÚ¶þ¸ö²Ù×÷ÊýµÄÖ¸Õë - * @param n [IN]Ä£ÊýÖ¸Õë - * @param context [IN]Ö¸ÏòÒÔǰʹÓÃTEE_BigIntInitFMMContext1»òNULL³õʼ»¯µÄÉÏÏÂÎĵÄÖ¸Õë + * @param des Indicates the pointer to the TEE_BigInt that holds the result (op1 ^ op2)(mod n). + * @param op1 Indicates the pointer to the first operand. + * @param op2 Indicates the pointer to the second operand. + * @param n Indicates the pointer to the modulus. + * @param context Indicates the pointer to the context that is previously initialized using + * {@link TEE_BigIntInitFMMContext1} or initialized to null. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_NOT_SUPPORTED ²»Ö§³ÖnµÄÖµ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_NOT_SUPPORTED if the value of n is not supported. * */ TEE_Result TEE_BigIntExpMod(TEE_BigInt *des, TEE_BigInt *op1, const TEE_BigInt *op2, const TEE_BigInt *n, diff --git a/sdk/include/TA/tee_core_api.h b/sdk/include/TA/tee_core_api.h index c6e6787..71e550a 100644 --- a/sdk/include/TA/tee_core_api.h +++ b/sdk/include/TA/tee_core_api.h @@ -12,7 +12,7 @@ /** * @file tee_core_api.h * - * @brief TA»á»°²Ù×÷½Ó¿Ú + * @brief Provides APIs for managing trusted application (TA) sessions. * * @since 1 */ @@ -26,51 +26,54 @@ typedef uint32_t TEE_TASessionHandle; #endif /** - * @brief ÔÚÊÜÐÅÈεÄÓ¦ÓóÌÐòʵÀýÖÐÒý·¢ËÀ»ú\ + * @brief Raises a panic in the TA instance. * - * @param panicCode [IN]TA¶¨ÒåµÄÐÅÏ¢ÐԿֻŴúÂë + * @param panicCode Indicates an informative panic code defined by the TA. * */ void TEE_Panic(TEE_Result panicCode); /** - * @brief ʹÓÃÊÜÐÅÈÎÓ¦ÓóÌÐò´ò¿ªÐ»Ự + * @brief Opens a new session with a TA. * - * @param destination [IN]Ö¸Ïò°üº¬Ä¿±êÊÜÐÅÈÎÓ¦ÓóÌÐòµÄUUIDµÄTEE_UUID½á¹¹µÄÖ¸Õë - * @param cancellationRequestTimeout [IN]ÒÔºÁÃëΪµ¥Î»µÄ³¬Ê±»òÌØÊâÖµ - * @param paramTypes [IN]²Ù×÷Öд«µÝµÄËùÓвÎÊýµÄÀàÐÍ - * @param params [IN]²Ù×÷Öд«µÝµÄ²ÎÊý - * @param session [OUT]Ö¸Ïò½«½ÓÊÕ¿Í»§¶Ë»á»°¾ä±úµÄ±äÁ¿µÄÖ¸Õë - * @param returnOrigin [OUT]Ö¸Ïò½«°üº¬·µ»ØÔ­µãµÄ±äÁ¿µÄÖ¸Õë + * @param destination Indicates the pointer to the TEE_UUID structure that contains + * the Universal Unique Identifier (UUID) of the target TA. + * @param cancellationRequestTimeout Indicates the timeout period in milliseconds or a special value + * if there is no timeout. + * @param paramTypes Indicates the types of all parameters passed in the operation. + * @param params Indicates the parameters passed in the operation. + * @param session Indicates the pointer to the variable that will receive the client session handle. + * @param returnOrigin Indicates the pointer to the variable that holds the return origin. * - * @return TEE_SUCCESS ³É¹¦´ò¿ª»á»° - * @return TEE_ERROR_ITEM_NOT_FOUND ÔÚTEEÖÐÕÒ²»µ½Ä¿±êTA - * @return TEE_ERROR_ACCESS_DENIED ¶ÔÄ¿±êÊÜÐÅÈÎÓ¦ÓóÌÐòµÄ·ÃÎʱ»¾Ü¾ø + * @return Returns TEE_SUCCESS if the session is opened. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the TA cannot be found in the Trusted Execution Environment (TEE). + * @return Returns TEE_ERROR_ACCESS_DENIED if the access request to the TA is denied. * */ TEE_Result TEE_OpenTASession(const TEE_UUID *destination, uint32_t cancellationRequestTimeout, uint32_t paramTypes, TEE_Param params[TEE_PARAMS_NUM], TEE_TASessionHandle *session, uint32_t *returnOrigin); /** - * @brief ¹Ø±ÕÓÉTEE_OpenTASession´ò¿ªµÄ¿Í»§¶Ë»á»° + * @brief Closes a client session. * - * @param session [IN]TEE_OpenTASession´ò¿ªµÄ»á»°¾ä±ú + * @param session Indicates the handle of the session to close. * */ void TEE_CloseTASession(TEE_TASessionHandle session); /** - * @brief ÔÚ¿Í»§¶ËÊÜÐÅÈÎÓ¦ÓóÌÐòʵÀýºÍÄ¿±êÊÜÐÅÈÎÓ¦ÓóÌÐòʵÀýÖ®¼ä´ò¿ªµÄ»á»°Öе÷ÓÃÃüÁî + * @brief Invokes a command in a session opened between this client TA instance and a target TA instance. * - * @param session [IN]´ò¿ªµÄ»á»°¾ä±ú - * @param cancellationRequestTimeout [IN]ÒÔºÁÃëΪµ¥Î»µÄ³¬Ê±»òÌØÊâÖµ - * @param commandID [IN]Òªµ÷ÓõÄÃüÁîµÄ±êʶ·û - * @param paramTypes [IN]²Ù×÷Öд«µÝµÄËùÓвÎÊýµÄÀàÐÍ - * @param params [IN]²Ù×÷Öд«µÝµÄ²ÎÊý - * @param returnOrigin [IN]Ö¸Ïò½«°üº¬·µ»ØÔ­µãµÄ±äÁ¿µÄÖ¸Õë + * @param session Indicates the handle of the opened session. + * @param cancellationRequestTimeout Indicates the timeout period in milliseconds or a special value + * if there is no timeout. + * @param commandID Indicates the identifier of the command to invoke. + * @param paramTypes Indicates the types of all parameters passed in the operation. + * @param params Indicates the parameters passed in the operation. + * @param returnOrigin Indicates the pointer to the variable that holds the return origin. * - * @return TEE_SUCCESS µ÷ÓòÙ×÷³É¹¦ - * @return TEE_ERROR_ACCESS_DENIED ÏòÄ¿±êTAµ÷ÓÃÃüÁî±»¾Ü¾ø + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ACCESS_DENIED if the command fails to be invoked. * */ TEE_Result TEE_InvokeTACommand(TEE_TASessionHandle session, uint32_t cancellationRequestTimeout, uint32_t commandID, diff --git a/sdk/include/TA/tee_crypto_api.h b/sdk/include/TA/tee_crypto_api.h index 7f84cd6..1b693eb 100644 --- a/sdk/include/TA/tee_crypto_api.h +++ b/sdk/include/TA/tee_crypto_api.h @@ -13,9 +13,9 @@ /** * @file tee_crypto_api.h * - * @brief ¼Ó½âÃÜ½Ó¿Ú + * @brief Provides APIs for cryptographic operations. * - * ¿ª·¢Õß¿ÉÒÔʹÓÃÕâЩ½Ó¿ÚʵÏÖ¼Ó½âÃܵÄÏà¹Ø¹¦ÄÜ¡£ + * You can use these APIs to implement encryption and decryption. * * @since 1 */ @@ -29,30 +29,30 @@ #ifndef NULL /** - * NULL¶¨Òå + * Definition of NULL. */ #define NULL ((void *)0) #endif /** - * @brief ÃÜÔ¿×î´ó³¤¶È£¨ÒÔbitsΪµ¥Î»£© + * @brief Defines the maximum key length, in bits. */ #define TEE_MAX_KEY_SIZE_IN_BITS (1024 * 8) /** - * @brief SW_RSAÃÜÔ¿³¤¶È + * @brief Defines the length of the SW_RSA key, in bytes. */ #define SW_RSA_KEYLEN 1024 /** - * @brief DHÆäËüÐÅÏ¢µÄ×î´ó³¤¶È + * @brief Defines the maximum length of other Diffie-Hellman (DH) information, in bytes. */ #define TEE_DH_MAX_SIZE_OF_OTHER_INFO 64 /* bytes */ /** - * @brief ¼Ó½âÃÜOperation²Ù×÷¾ä±ú + * @brief Enumerates the cryptographic operation handles. */ enum __TEE_Operation_Constants { /** Cipher */ TEE_OPERATION_CIPHER = 0x1, - /** Mac */ + /** MAC */ TEE_OPERATION_MAC = 3, /** AE */ TEE_OPERATION_AE = 4, @@ -62,15 +62,15 @@ enum __TEE_Operation_Constants { TEE_OPERATION_ASYMMETRIC_CIPHER = 6, /** Asymmetric Signature */ TEE_OPERATION_ASYMMETRIC_SIGNATURE = 7, - /** Key Derication */ + /** Key Derivation */ TEE_OPERATION_KEY_DERIVATION = 8, }; /** - * @brief ¼Ó½âÃÜËã·¨±êʶ + * @brief Enumerates the cryptographic algorithms. */ enum __tee_crypto_algorithm_id { - /** ÎÞЧËã·¨ */ + /** Invalid algorithm */ TEE_ALG_INVALID = 0x0, /** AES_ECB_NOPAD */ TEE_ALG_AES_ECB_NOPAD = 0x10000010, @@ -259,12 +259,12 @@ enum __tee_crypto_algorithm_id { */ typedef enum __tee_crypto_algorithm_id tee_crypto_algorithm_id; /** - * @brief ÎÞ¿ÉÑ¡ÔªËØ + * @brief No element is available. */ #define TEE_OPTIONAL_ELEMENT_NONE 0x00000000 /** - * @brief Ö§³ÖµÄECCÇúÏß + * @brief Enumerates the Elliptic-Curve Cryptography (ECC) curves supported. */ typedef enum { /** CURVE_NIST_P192 */ @@ -284,7 +284,7 @@ typedef enum { } TEE_ECC_CURVE; /** - * @brief MGF1ÑÚÂ뺯ÊýÀàÐÍ + * @brief Enumerates the Mask Generation Function (MGF1) modes. */ typedef enum { TEE_DH_HASH_SHA1_mode = 0, @@ -296,32 +296,32 @@ typedef enum { } TEE_DH_HASH_Mode; /** - * @brief ¼Ó½âÃÜË㷨ģʽ + * @brief Enumerates the cryptographic operation modes. */ enum __TEE_OperationMode { - /** ¼ÓÃÜ */ + /** Encryption */ TEE_MODE_ENCRYPT = 0x0, - /** ½âÃÜ */ + /** Decryption */ TEE_MODE_DECRYPT, - /** Ç©Ãû */ + /** Signing */ TEE_MODE_SIGN, - /** ÑéÇ© */ + /** Signature verification */ TEE_MODE_VERIFY, - /** mac */ + /** MAC */ TEE_MODE_MAC, - /** ÕªÒª */ + /** Digest */ TEE_MODE_DIGEST, - /** ÑÜÉú */ + /** Key derivation */ TEE_MODE_DERIVE }; /** - * @brief ¼Ó½âÃÜoperation״̬ + * @brief Enumerates the cryptographic operation states. */ enum tee_operation_state { - /** ³õʼ״̬ */ + /** Initial */ TEE_OPERATION_STATE_INITIAL = 0x00000000, - /** ¼¤»î״̬ */ + /** Active */ TEE_OPERATION_STATE_ACTIVE = 0x00000001, }; @@ -331,95 +331,95 @@ enum tee_operation_state { typedef uint32_t TEE_OperationMode; /** - * @brief OperationÐÅÏ¢ + * @brief Defines the operation information. */ struct __TEE_OperationInfo { - /** Ëã·¨ID */ + /** Algorithm ID */ uint32_t algorithm; /* #__TEE_CRYPTO_ALGORITHM_ID */ - /** operationÀàÐÍ */ + /** Operation type */ uint32_t operationClass; /* #__TEE_Operation_Constants */ - /** Operationģʽ */ + /** Operation mode */ uint32_t mode; /* #__TEE_OperationMode */ - /** ÕªÒª³¤¶È */ + /** Digest length */ uint32_t digestLength; - /** ×î´óÃÜÔ¿³¤¶È */ + /** Maximum key length */ uint32_t maxKeySize; - /** ÃÜÔ¿³¤¶È */ + /** Key length*/ uint32_t keySize; - /** ËùÐèÃÜÔ¿Ó÷¨ */ + /** Required key usage */ uint32_t requiredKeyUsage; - /** ¾ä±ú״̬ */ + /** Handle state */ uint32_t handleState; - /** ÃÜÔ¿ */ + /** Key */ void *keyValue; }; /** - * @brief ÓÃÓÚ¶¨Òå__TEE_OperationInfo½á¹¹ÌåÀàÐÍ + * @brief Defines the __TEE_OperationInfo struct. * * @see __TEE_OperationInfo */ typedef struct __TEE_OperationInfo TEE_OperationInfo; /** - * @brief OperationÖдæ·ÅµÄÃÜÔ¿ÐÅÏ¢ + * @brief Defines the key information stored in the OperationInfo. */ typedef struct { - /** ÃÜÔ¿³¤¶È */ + /** Key length */ uint32_t keySize; - /** ËùÐèÃÜÔ¿Ó÷¨ */ + /** Required key usage */ uint32_t requiredKeyUsage; } TEE_OperationInfoKey; /** - * @brief °üº¬ÁËOperationÖеÄÃÜÔ¿ÐÅÏ¢ + * @brief Defines information about an operation. */ typedef struct { - /** Ëã·¨ID */ + /** Algorithm ID */ uint32_t algorithm; - /** operationÀàÐÍ */ + /** Operation type */ uint32_t operationClass; - /** Operationģʽ */ + /** Operation mode */ uint32_t mode; - /** ÕªÒª³¤¶È */ + /** Digest length */ uint32_t digestLength; - /** ×î´óÃÜÔ¿³¤¶È */ + /** Maximum key length */ uint32_t maxKeySize; - /** ¾ä±ú״̬ */ + /** Handle state */ uint32_t handleState; - /** operation״̬ */ + /** Operation state */ uint32_t operationState; - /** ÃÜÔ¿ÊýÁ¿ */ + /** Number of keys */ uint32_t numberOfKeys; - /** ÃÜÔ¿ÐÅÏ¢ */ + /** Key information */ TEE_OperationInfoKey keyInformation[]; } TEE_OperationInfoMultiple; /** - * @brief ¼Ó½âÃܲÙ×÷ÐèÒªµÄ¾ä±ú + * @brief Defines the cryptographic operation handle. */ struct __TEE_OperationHandle { - /** Ëã·¨ID */ + /** Algorithm ID */ uint32_t algorithm; /* #__TEE_CRYPTO_ALGORITHM_ID */ - /** operationÀàÐÍ */ + /** Operation type */ uint32_t operationClass; /* #__TEE_Operation_Constants */ - /** Operationģʽ */ + /** Operation mode */ uint32_t mode; /* #__TEE_OperationMode */ - /** ÕªÒª³¤¶È */ + /** Digest length */ uint32_t digestLength; - /** ×î´óÃÜÔ¿³¤¶È */ + /** Maximum key length */ uint32_t maxKeySize; - /** ÃÜÔ¿³¤¶È */ + /** Key length */ uint32_t keySize; - /** ÃÜÔ¿³¤¶È */ + /** Key length */ uint32_t keySize2; - /** ËùÐèÃÜÔ¿Ó÷¨ */ + /** Required key usage */ uint32_t requiredKeyUsage; - /** ¾ä±ú״̬ */ + /** Handle state */ uint32_t handleState; - /** ÃÜÔ¿ */ + /** Key */ void *keyValue; - /** ÃÜÔ¿ */ + /** Key */ void *keyValue2; /** */ void *crypto_ctxt; @@ -427,229 +427,230 @@ struct __TEE_OperationHandle { void *hmac_rest_ctext; /** iv */ void *IV; - /** ¹«Ô¿ */ + /** Public key */ void *publicKey; - /** ¹«Ô¿³¤¶È */ + /** Length of the public key */ uint32_t publicKeyLen; - /** ˽Կ */ + /** Private key */ void *privateKey; - /** ˽Կ³¤¶È */ + /** Length of the private key */ uint32_t privateKeyLen; - /** iv³¤¶È */ + /** Length of the IV */ uint32_t IVLen; - /** operationËø */ + /** Operation lock */ pthread_mutex_t operation_lock; - /** halÐÅÏ¢ */ + /** HAL information */ void *hal_info; }; /** - * @brief ÕûÊýÀàÐÍת»» + * @brief Defines the data used for conversion of integers. */ typedef struct { - /** Ô´ */ + /** Source */ uint32_t src; - /** Ä¿±ê */ + /** Destination */ uint32_t dest; } crypto_uint2uint; /** - * @brief RSA¹«Ô¿×î´ó³¤¶È + * @brief Defines the maximum length of an RSA public key. */ #define RSA_PUBKEY_MAXSIZE sizeof(CRYS_RSAUserPubKey_t) /** - * @brief RES˽Կ×î´ó³¤¶È + * @brief Defines the maximum length of an RES private key. */ #define RSA_PRIVKEY_MAXSIZE sizeof(CRYS_RSAUserPrivKey_t) /** - * @brief ´æ·ÅÊäÈëÊä³öÊý¾Ý + * @brief Defines a structure to hold the input and output data. */ typedef struct { - /** Ô´Êý¾Ý */ + /** Source data */ void *src_data; - /** Ô´Êý¾Ý³¤¶È */ + /** Length of the source data */ size_t src_len; - /** Ä¿±êÊý¾Ý */ + /** Destination data */ void *dest_data; - /** Ä¿±êÊý¾Ý³¤¶È */ + /** Length of the destination data */ size_t *dest_len; } operation_src_dest; /** - * @brief ´æ·ÅaeËã·¨³õʼ»¯Ïà¹ØÊý¾Ý + * @brief Defines the AE initialization data. */ typedef struct { /** nonce */ void *nonce; - /** nonce³¤¶È */ + /** Leng of nonce */ size_t nonce_len; - /** tag³¤¶È */ + /** Length of the tag */ uint32_t tag_len; - /** aad³¤¶È */ + /** Length of the additional authenticated data (AAD) */ size_t aad_len; - /** payload³¤¶È */ + /** Length of the payload */ size_t payload_len; } operation_ae_init; /** - * @brief ÓÃÓÚ¶¨Òå__TEE_OperationHandleÖ¸ÕëÀàÐÍ + * @brief Defines the pointer to __TEE_OperationHandle. * * @see __TEE_OperationHandle */ typedef struct __TEE_OperationHandle *TEE_OperationHandle; /** - * @brief ÓÃÓÚ¶¨Òå__TEE_OperationHandle½á¹¹ÌåÀàÐÍ + * @brief Defines the __TEE_OperationHandle struct. * * @see __TEE_OperationHandle */ typedef struct __TEE_OperationHandle TEE_OperationHandleVar; /** - * @brief ÓÃÓÚ¶¨Òå__TEE_ObjectHandle½á¹¹ÌåÀàÐÍ + * @brief Defines the __TEE_ObjectHandle struct. */ typedef struct __TEE_ObjectHandle TEE_ObjectHandleVar; /** - * @brief ÉêÇë²Ù×÷¾ä±ú + * @brief Allocates an operation handle. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param algorithm [IN]¼ÓÃÜËã·¨ID - * @param mode [IN]²Ù×÷ģʽ - * @param maxKeySize [IN]×î´óÃÜÔ¿´óС + * @param operation Indicates the pointer to the operation handle. + * @param algorithm Indicates the cipher algorithm. + * @param mode Indicates the operation mode. + * @param maxKeySize Indicates the maximum length of the key. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_OUT_OF_MEMORY ²Ù×÷¾ä±úÉêÇëʧ°Ü - * @return TEE_ERROR_NOT_SUPPORTE ¼ÓÃÜËã·¨ID²»Ö§³Ö - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation handle is allocated. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if there is no enough memory for this operation. + * @return Returns TEE_ERROR_NOT_SUPPORTED if the specified algorithm is not supported. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_AllocateOperation(TEE_OperationHandle *operation, uint32_t algorithm, uint32_t mode, uint32_t maxKeySize); /** - * @brief ÊͷŲÙ×÷¾ä±ú + * @brief Releases an operation handle. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú + * @param operation Indicates the operation handle to release. * */ void TEE_FreeOperation(TEE_OperationHandle operation); /** - * @brief »ñÈ¡²Ù×÷ÐÅÏ¢ + * @brief Obtains operation information. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param operationInfo [IN/OUT]²Ù×÷ÐÅÏ¢ + * @param operation Indicates the operation handle. + * @param operationInfo Indicates the pointer to the operation information. * */ void TEE_GetOperationInfo(const TEE_OperationHandle operation, TEE_OperationInfo *operationInfo); /** - * @brief ¸´Î»²Ù×÷¾ä±ú + * @brief Resets an operation handle. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú + * @param operation Indicates the operation handle to reset. * */ void TEE_ResetOperation(TEE_OperationHandle operation); /** - * @brief ÉèÖòÙ×÷ÃÜÔ¿ + * @brief Sets the key for an operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param key [IN/OUT]ÃÜÔ¿ + * @param operation Indicates the operation handle. + * @param key Indicates the key. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ·Ç·¨²ÎÊý - * @return TEE_ERROR_OUT_OF_MEMORY ÃÜÔ¿»º³åÇøÉêÇëʧ°Ü + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if the operation fails due to invalid parameters. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if there is no enough memory for this operation. * */ TEE_Result TEE_SetOperationKey(TEE_OperationHandle operation, const TEE_ObjectHandle key); /** - * @brief ÉèÖòÙ×÷ÃÜÔ¿2 + * @brief Sets two keys for an operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param key1 [IN/OUT]ÃÜÔ¿1 - * @param key2 [IN/OUT]ÃÜÔ¿2 + * @param operation Indicates the operation handle. + * @param key1 Indicates key 1. + * @param key2 Indicates key 2. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ·Ç·¨²ÎÊý + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if the operation fails due to invalid parameters. * */ TEE_Result TEE_SetOperationKey2(TEE_OperationHandle operation, const TEE_ObjectHandle key1, const TEE_ObjectHandle key2); /** - * @brief ¸´ÖƲÙ×÷¾ä±ú + * @brief Copies an operation handle. * - * @param dstOperation [IN/OUT]Ä¿±ê²Ù×÷¾ä±ú - * @param srcOperation [IN/OUT]Ô´²Ù×÷¾ä±ú + * @param dstOperation Indicates the destination operation handle. + * @param srcOperation Indicates the source operation handle. * */ void TEE_CopyOperation(TEE_OperationHandle dstOperation, const TEE_OperationHandle srcOperation); /** - * @brief ³õʼ»¯ÃÜÂëÉÏÏÂÎÄ + * @brief Initializes the context to start a cipher operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param IV [IN]iv»º³åÇø£¬Èç¹û²»Ê¹ÓÃÉèÖÃΪNULL - * @param IVLen [IN]iv»º³åÇøµÄ³¤¶È + * @param operation Indicates the operation handle. + * @param IV Indicates the pointer to the buffer storing the operation IV. If this parameter is not used, + * set it to NULL. + * @param IVLen Indicates the length of the IV buffer. * */ void TEE_CipherInit(TEE_OperationHandle operation, const void *IV, size_t IVLen); /** - * @brief Ö´ÐÐÃÜÂë¸üР+ * @brief Updates the data for a cipher operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param srcData [IN]Ô´Êý¾Ý - * @param srcLen [IN]Ô´Êý¾Ý³¤¶È - * @param destData [OUT]Ä¿±êÊý¾Ý - * @param destLen [OUT]Ä¿±êÊý¾Ý³¤¶È + * @param operation Indicates the operation handle. + * @param srcData Indicates the pointer to the source data. + * @param srcLen Indicates the length of the source data. + * @param destData Indicates the pointer to the destination data. + * @param destLen Indicates the pointer to the destination data length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ·Ç·¨²ÎÊý - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if the operation fails due to invalid parameters. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_CipherUpdate(TEE_OperationHandle operation, const void *srcData, size_t srcLen, void *destData, size_t *destLen); /** - * @brief Ö´ÐÐÃÜÂëÍê³É + * @brief Finalizes a cipher operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param srcData [IN]Ô´Êý¾Ý - * @param srcLen [IN]Ô´Êý¾Ý³¤¶È - * @param destData [OUT]Ä¿±êÊý¾Ý - * @param destLen [OUT]Ä¿±êÊý¾Ý³¤¶È + * @param operation Indicates the operation handle. + * @param srcData Indicates the pointer to the source data. + * @param srcLen Indicates the length of the source data. + * @param destData Indicates the pointer to the destination data. + * @param destLen Indicates the pointer to the destination data length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ·Ç·¨²ÎÊý - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if the operation fails due to invalid parameters. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_CipherDoFinal(TEE_OperationHandle operation, const void *srcData, size_t srcLen, void *destData, size_t *destLen); /** - * @brief ÕªÒª¸üР+ * @brief Updates the digest. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param chunk [IN]¿é»º³åÇø - * @param chunkSize [IN]¿é»º³åÇø³¤¶È + * @param operation Indicates the operation handle. + * @param chunk Indicates the pointer to the chunk of data to be hashed. + * @param chunkSize Indicates the length of the chunk. * */ void TEE_DigestUpdate(TEE_OperationHandle operation, const void *chunk, size_t chunkSize); /** - * @brief Ö´ÐÐÕªÒª½áÊø + * @brief Finalizes the message digest operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param chunk [IN]¿é»º³åÇø - * @param chunkLen [IN]¿é»º³åÇø´óС - * @param hash [out]¹þÏ£»º³åÇø + * @param operation Indicates the operation handle. + * @param chunk Indicates the pointer to the chunk of data to be hashed. + * @param chunkLen Indicates the length of the chunk. + * @param hash Indicates the pointer to the buffer storing the message hash. * @param hashLen * */ @@ -657,228 +658,229 @@ TEE_Result TEE_DigestDoFinal(TEE_OperationHandle operation, const void *chunk, s size_t *hashLen); /** - * @brief Ö´ÐÐmac³õʼ»¯ + * @brief Initializes a MAC operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param IV [IN]iv»º³åÇø£¬Èç¹û²»Ê¹ÓÃÉèÖÃΪNULL - * @param IVLen [IN]iv»º³åÇø³¤¶È + * @param operation Indicates the operation handle. + * @param IV Indicates the pointer to the buffer storing the operation IV. If this parameter is not used, + * set it to NULL. + * @param IVLen Indicates the length of the IV buffer. * */ void TEE_MACInit(TEE_OperationHandle operation, void *IV, size_t IVLen); /** - * @brief Ö´ÐÐmac¸üР+ * @brief Updates the MAC. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param chunk [IN]¿é»º³åÇø - * @param chunkSize [IN]¿é»º³åÇø´óС + * @param operation Indicates the operation handle. + * @param chunk Indicates the pointer to the chunk of MAC data. + * @param chunkSize Indicates the size of the chunk. * */ void TEE_MACUpdate(TEE_OperationHandle operation, const void *chunk, size_t chunkSize); /** - * @brief mac¼ÆËãÍê³É + * @brief MAC Finalizes the MAC operation with a last chunk of message and computes the MAC. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param message [IN]message»º³åÇø - * @param messageLen [IN]message»º³åÇøµÄ´óС - * @param mac [OUT]mac»º³åÇø - * @param macLen [OUT]mac»º³åÇø´óС + * @param operation Indicates the operation handle. + * @param message Indicates the pointer to the buffer containing the last message chunk to MAC. + * @param messageLen Indicates the length of the message buffer. + * @param mac Indicates the pointer to the buffer storing the computed MAC. + * @param macLen Indicates the pointer to the MAC buffer length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_MACComputeFinal(TEE_OperationHandle operation, const void *message, size_t messageLen, void *mac, size_t *macLen); /** - * @brief mac±È½ÏÍê³É + * @brief Finalizes the MAC operation and compares the MAC with the one passed in. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param message [IN]message»º³åÇø - * @param messageLen [IN]message»º³åÇø´óС - * @param mac [OUT]mac»º³åÇø - * @param macLen [OUT]mac»º³åÇø´óС + * @param operation Indicates the operation handle. + * @param message Indicates the pointer to the buffer containing the last message chunk to MAC. + * @param messageLen Indicates the length of the buffer. + * @param mac Indicates the pointer to the buffer storing the computed MAC. + * @param macLen Indicates the MAC buffer length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_GENERIC ÆäËü´íÎó - * @return TEE_ERROR_MAC_INVALID ±È½Ïʧ°Ü + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. + * @return Returns TEE_ERROR_MAC_INVALID if the computed MAC is not the same as that passed in. * */ TEE_Result TEE_MACCompareFinal(TEE_OperationHandle operation, const void *message, size_t messageLen, const void *mac, const size_t macLen); /** - * @brief ÅÉÉúÃÜÔ¿ + * @brief Derives a key. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param params [IN]ÊôÐÔ - * @param paramCount [IN]ÊôÐÔµÄÊýÁ¿ - * @param derivedKey [OUT]ÅÉÉúÃÜÔ¿ + * @param operation Indicates the operation handle. + * @param params Indicates the pointer to the parameters for this operation. + * @param paramCount Indicates the number of parameters. + * @param derivedKey Indicates the derived key. * */ void TEE_DeriveKey(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, TEE_ObjectHandle derivedKey); /** - * @brief Éú³ÉËæ»úÊý¾Ý + * @brief Generates random data. * - * @param randomBuffer [IN/OUT]Ëæ»ú»º³åÇø - * @param randomBufferLen [IN]Ëæ»ú»º³åÇø´óС + * @param randomBuffer Indicates the pointer to the buffer storing the random data generated. + * @param randomBufferLen Indicates the length of the buffer storing the random data. * */ void TEE_GenerateRandom(void *randomBuffer, size_t randomBufferLen); /** - * @brief ae³õʼ»¯ + * @brief Initializes an AE operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param nonce [IN]nonce»º³åÇø - * @param nonceLen [IN]nonce»º³åÇø´óС - * @param tagLen [IN]tagµÄ´óС - * @param AADLen [IN]aadµÄ´óС - * @param payloadLen [IN]payloadµÄ´óС + * @param operation Indicates the operation handle. + * @param nonce Indicates the pointer to the buffer for storing the nonce. + * @param nonceLen Indicates the length of the nonce. + * @param tagLen Indicates the length of the tag. + * @param AADLen Indicates the length of the AAD. + * @param payloadLen Indicates the length of the payload. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_AEInit(TEE_OperationHandle operation, void *nonce, size_t nonceLen, uint32_t tagLen, size_t AADLen, size_t payloadLen); /** - * @brief ¸üÐÂae aad + * @brief Updates the AAD in an AE operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param AADdata [IN]aad»º³åÇø - * @param AADdataLen [IN]aad»º³åÇø´óС + * @param operation Indicates the operation handle. + * @param AADdata Indicates the pointer to the new AAD. + * @param AADdataLen Indicates the length of the new AAD. * */ void TEE_AEUpdateAAD(TEE_OperationHandle operation, const void *AADdata, size_t AADdataLen); /** - * @brief ¸üÐÂae + * @brief Updates data for an AE operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param srcData [IN]Ô´Êý¾Ý - * @param srcLen [IN]Ô´Êý¾Ý´óС - * @param destData [OUT]Ä¿±êÊý¾Ý - * @param destLen [OUT]Ä¿±êÊý¾Ý´óС + * @param operation Indicates the operation handle. + * @param srcData Indicates the pointer to the source data. + * @param srcLen Indicates the length of the source data. + * @param destData Indicates the pointer to the destination data. + * @param destLen Indicates the pointer to the destination data length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_AEUpdate(TEE_OperationHandle operation, void *srcData, size_t srcLen, void *destData, size_t *destLen); /** - * @brief ae¼ÓÃÜ + * @brief Finalizes the AE encryption operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param srcData [IN]Ô´Êý¾Ý - * @param srcLen [IN]Ô´Êý¾Ý³¤¶È - * @param destData [OUT]Ä¿±êÊý¾Ý - * @param destLen [OUT]Ä¿±êÊý¾Ý³¤¶È - * @param tag [OUT]tag»º³åÇø - * @param tagLen [OUT]tag»º³åÇø´óС + * @param operation Indicates the operation handle. + * @param srcData Indicates the pointer to the source data. + * @param srcLen Indicates the length of the source data. + * @param destData Indicates the pointer to the destination data. + * @param destLen Indicates the pointer to the destination data length. + * @param tag Indicates the pointer to the buffer storing the computed tag. + * @param tagLen Indicates the pointer to the tag buffer length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_AEEncryptFinal(TEE_OperationHandle operation, void *srcData, size_t srcLen, void *destData, size_t *destLen, void *tag, size_t *tagLen); /** - * @brief ae½âÃÜ + * @brief Finalizes an AE decryption operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param srcData [IN]Ô´Êý¾Ý - * @param srcLen [IN]Ô´Êý¾Ý³¤¶È - * @param destData [OUT]Ä¿±êÊý¾Ý - * @param destLen [OUT]Ä¿±êÊý¾Ý³¤¶È - * @param tag [OUT]tag»º³åÇø - * @param tagLen[OUT]tag»º³åÇø´óС + * @param operation Indicates the operation handle. + * @param srcData Indicates the pointer to the source data. + * @param srcLen Indicates the length of the source data. + * @param destData Indicates the pointer to the destination data. + * @param destLen Indicates the pointer to the destination data length. + * @param tag Indicates the pointer to the buffer storing the computed tag. + * @param tagLen Indicates the tag buffer length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_MAC_INVALID tagÊÇ·Ç·¨µÄ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_MAC_INVALID if the computed tag does not match the provided tag. * */ TEE_Result TEE_AEDecryptFinal(TEE_OperationHandle operation, void *srcData, size_t srcLen, void *destData, size_t *destLen, void *tag, size_t tagLen); /** - * @brief ·Ç¶Ô³Æ¼ÓÃÜ + * @brief Performs asymmetric encryption. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param params [IN]ÊôÐÔ - * @param paramCount [IN]ÊôÐÔÊýÁ¿ - * @param srcData [IN]Ô´Êý¾Ý - * @param srcLen [IN]Ô´Êý¾Ý³¤¶È - * @param destData [OUT]Ä¿±êÊý¾Ý - * @param destLen [OUT]Ä¿±êÊý¾Ý³¤¶È + * @param operation Indicates the operation handle. + * @param params Indicates the pointer to the parameters for this operation. + * @param paramCount Indicates the number of parameters. + * @param srcData Indicates the pointer to the source data. + * @param srcLen Indicates the length of the source data. + * @param destData Indicates the pointer to the destination data. + * @param destLen Indicates the pointer to the destination data length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ·Ç·¨²ÎÊý - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if the operation fails due to invalid parameters. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_AsymmetricEncrypt(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, void *srcData, size_t srcLen, void *destData, size_t *destLen); /** - * @brief ·Ç¶Ô³Æ½âÃÜ + * @brief Performs asymmetric decryption. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param params [IN]ÊôÐÔ - * @param paramCount [IN]ÊôÐÔÊýÁ¿ - * @param srcData [IN]Ô´Êý¾Ý - * @param srcLen [IN]Ô´Êý¾Ý³¤¶È - * @param destData [OUT]Ä¿±êÊý¾Ý - * @param destLen [OUT]Ä¿±êÊý¾Ý³¤¶È + * @param operation Indicates the operation handle. + * @param params Indicates the pointer to the parameters for this operation. + * @param paramCount Indicates the number of parameters. + * @param srcData Indicates the pointer to the source data. + * @param srcLen Indicates the length of the source data. + * @param destData Indicates the pointer to the destination data. + * @param destLen Indicates the pointer to the destination data length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ·Ç·¨²ÎÊý - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if the operation fails due to invalid parameters. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_AsymmetricDecrypt(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, void *srcData, size_t srcLen, void *destData, size_t *destLen); /** - * @brief ·Ç¶Ô³ÆÇ©Ãû + * @brief Signs a message digest in an asymmetric operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param params [IN]ÊôÐÔ - * @param paramCount [IN]ÊôÐÔÊýÁ¿ - * @param digest [IN]ÕªÒª - * @param digestLen [IN]ÕªÒª³¤¶È - * @param signature [OUT]Ç©Ãû - * @param signatureLen [OUT]Ç©Ãû³¤¶È + * @param operation Indicates the operation handle. + * @param params Indicates the pointer to the parameters for this operation. + * @param paramCount Indicates the number of parameters. + * @param digest Indicates the pointer to the message digest. + * @param digestLen Indicates the digest length. + * @param signature Indicates the pointer to the signature. + * @param signatureLen Indicates the pointer to the signature length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ·Ç·¨²ÎÊý - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if the operation fails due to invalid parameters. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_AsymmetricSignDigest(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, void *digest, size_t digestLen, void *signature, size_t *signatureLen); /** - * @brief ·Ç¶Ô³ÆÑéÖ¤ + * @brief Verifies a message digest signature in an asymmetric operation. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param params [IN]ÊôÐÔ - * @param paramCount [IN]ÊôÐÔÊýÁ¿ - * @param digest [IN]ÕªÒª - * @param digestLen [IN]ÕªÒª³¤¶È - * @param signature [OUT]Ç©Ãû - * @param signatureLen [OUT]Ç©Ãû³¤¶È + * @param operation Indicates the operation handle. + * @param params Indicates the pointer to the parameters for this operation. + * @param paramCount Indicates the number of parameters. + * @param digest Indicates the pointer to the message digest. + * @param digestLen Indicates the digest length. + * @param signature Indicates the pointer to the signature. + * @param signatureLen Indicates the signature length. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ·Ç·¨²ÎÊý - * @return TEE_ERROR_GENERIC ÆäËü´íÎó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if the operation fails due to invalid parameters. + * @return Returns TEE_ERROR_GENERIC if the operation fails due to other errors. * */ TEE_Result TEE_AsymmetricVerifyDigest(TEE_OperationHandle operation, const TEE_Attribute *params, uint32_t paramCount, @@ -886,28 +888,29 @@ TEE_Result TEE_AsymmetricVerifyDigest(TEE_OperationHandle operation, const TEE_A /** - * @brief ÅúÁ¿»ñÈ¡²Ù×÷ÐÅÏ¢ + * @brief Obtains information about the operation involving multiple keys. * - * @param operation [IN/OUT]²Ù×÷¾ä±ú - * @param operationInfoMultiple [IN/OUT]ÅúÁ¿²Ù×÷ÐÅÏ¢ - * @param operationSize [IN/OUT]²Ù×÷ÐÅÏ¢ÊýÁ¿ + * @param operation Indicates the operation handle. + * @param operationInfoMultiple Indicates the pointer to the operation information obtained. + * @param operationSize [IN/OUT] Indicates the pointer to the operation information size. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_BAD_PARAMETERS ·Ç·¨²ÎÊý - * @return TEE_ERROR_SHORT_BUFFER »º³åÇø²»×ã + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if the operation fails due to invalid parameters. + * @return Returns TEE_ERROR_SHORT_BUFFER if the operationInfo buffer is not large enough to + * hold the information obtained. * */ TEE_Result TEE_GetOperationInfoMultiple(TEE_OperationHandle operation, TEE_OperationInfoMultiple *operationInfoMultiple, const size_t *operationSize); /** - * @brief ¼ì²éËã·¨ÊÇ·ñ±»Ö§³Ö + * @brief Checks whether the algorithm is supported. * - * @param algId [IN]Ëã·¨ID - * @param element [IN]ÔªËØ + * @param algId Indicates the algorithm to check. + * @param element Indicates the cryptographic element. * - * @return TEE_SUCCESS Ö§³Ö - * @return TEE_ERROR_NOT_SUPPORTED ²»Ö§³Ö + * @return Returns TEE_SUCCESS if the algorithm is supported. + * @return Returns TEE_ERROR_NOT_SUPPORTED otherwise. * */ TEE_Result TEE_IsAlgorithmSupported(uint32_t algId, uint32_t element); diff --git a/sdk/include/TA/tee_defines.h b/sdk/include/TA/tee_defines.h index 7d3ee3a..5c22ccc 100644 --- a/sdk/include/TA/tee_defines.h +++ b/sdk/include/TA/tee_defines.h @@ -60,16 +60,16 @@ typedef union { #define TEE_PARAM_TYPE_GET(paramTypes, index) (((paramTypes) >> (4U * (index))) & 0x0F) /* - * check validation of parameter types + * @brief Checks parameter types. * - * @param param_to_check [IN] expected parameter values - * @param valid0 [IN] first parameter type - * @param valid1 [IN] second parameter type - * @param valid2 [IN] third parameter type - * @param valid3 [IN] fourth parameter type + * @param param_to_check Indicates the expected parameter values. + * @param valid0 Indicates the first parameter type to check. + * @param valid1 Indicates the second parameter type to check. + * @param valid2 Indicates the third parameter type to check. + * @param valid3 Indicates the fourth parameter type to check. * - * @retval true parameter types are correct - * @retval false parameter types are incorrect + * @retval Returns true if the parameter types are correct. + * @retval Returns false otherwise. */ static inline bool check_param_type(uint32_t param_to_check, uint32_t valid0, uint32_t valid1, uint32_t valid2, uint32_t valid3) @@ -233,82 +233,82 @@ typedef struct spawn_uuid { } spawn_uuid_t; enum TEE_Result_Value { - TEE_SUCCESS = 0x00000000, /* success */ - TEE_ERROR_INVALID_CMD = 0x00000001, /* command is invalid */ - TEE_ERROR_SERVICE_NOT_EXIST = 0x00000002, /* service is not exist */ - TEE_ERROR_SESSION_NOT_EXIST = 0x00000003, /* session is not exist */ - TEE_ERROR_SESSION_MAXIMUM = 0x00000004, /* exceeds max session count */ - TEE_ERROR_REGISTER_EXIST_SERVICE = 0x00000005, /* service already registered */ - TEE_ERROR_TARGET_DEAD_FATAL = 0x00000006, /* internal error occurs */ - TEE_ERROR_READ_DATA = 0x00000007, /* read data failed */ - TEE_ERROR_WRITE_DATA = 0x00000008, /* write data failed */ - TEE_ERROR_TRUNCATE_OBJECT = 0x00000009, /* truncate data failed */ - TEE_ERROR_SEEK_DATA = 0x0000000A, /* seek data failed */ - TEE_ERROR_SYNC_DATA = 0x0000000B, /* sync data failed */ - TEE_ERROR_RENAME_OBJECT = 0x0000000C, /* rename file failed */ - TEE_ERROR_TRUSTED_APP_LOAD_ERROR = 0x0000000D, /* error occurs when loading TA */ - TEE_ERROR_STORAGE_EIO = 0x80001001, /* I/O error occurs in storage operation */ - TEE_ERROR_STORAGE_EAGAIN = 0x80001002, /* storage section is unavailable */ - TEE_ERROR_STORAGE_ENOTDIR = 0x80001003, /* operation target is not directory */ - TEE_ERROR_STORAGE_EISDIR = 0x80001004, /* cannot do this operation on directory */ - TEE_ERROR_STORAGE_ENFILE = 0x80001005, /* opened files exceed max count in system */ - TEE_ERROR_STORAGE_EMFILE = 0x80001006, /* opened files exceed max count for this process */ - TEE_ERROR_STORAGE_EROFS = 0x80001007, /* stroage section is read only */ - TEE_ERROR_STORAGE_PATH_WRONG = 0x8000100A, /* File path error */ - TEE_ERROR_MSG_QUEUE_OVERFLOW = 0x8000100B, /* sevice msg queue overflow */ - TEE_ERROR_CORRUPT_OBJECT = 0xF0100001, /* file object has been damaged */ - TEE_ERROR_STORAGE_NOT_AVAILABLE = 0xF0100003, /* storage section is unavailable */ - TEE_ERROR_CIPHERTEXT_INVALID = 0xF0100006, /* cipher text is incorrect */ - TEE_ISOCKET_ERROR_PROTOCOL = 0xF1007001, /* protocol error in socket connection */ - TEE_ISOCKET_ERROR_REMOTE_CLOSED = 0xF1007002, /* socket is closed by remote */ - TEE_ISOCKET_ERROR_TIMEOUT = 0xF1007003, /* socket connection is timeout */ - TEE_ISOCKET_ERROR_OUT_OF_RESOURCES = 0xF1007004, /* no resource avaliable for socket connection */ - TEE_ISOCKET_ERROR_LARGE_BUFFER = 0xF1007005, /* buffer is too large in socket connection */ - TEE_ISOCKET_WARNING_PROTOCOL = 0xF1007006, /* warnning occurs in socket connection */ - TEE_ERROR_GENERIC = 0xFFFF0000, /* generic error */ - TEE_ERROR_ACCESS_DENIED = 0xFFFF0001, /* access is denied */ - TEE_ERROR_CANCEL = 0xFFFF0002, /* operation has been canceled */ - TEE_ERROR_ACCESS_CONFLICT = 0xFFFF0003, /* conflict access error occurs */ - TEE_ERROR_EXCESS_DATA = 0xFFFF0004, /* exceeds max data size */ - TEE_ERROR_BAD_FORMAT = 0xFFFF0005, /* incorrect data format */ - TEE_ERROR_BAD_PARAMETERS = 0xFFFF0006, /* incorrect parameters */ - TEE_ERROR_BAD_STATE = 0xFFFF0007, /* operation is not allowed in current state */ - TEE_ERROR_ITEM_NOT_FOUND = 0xFFFF0008, /* cannot find target item */ - TEE_ERROR_NOT_IMPLEMENTED = 0xFFFF0009, /* api is not implemented */ - TEE_ERROR_NOT_SUPPORTED = 0xFFFF000A, /* api is not supported */ - TEE_ERROR_NO_DATA = 0xFFFF000B, /* no data avaliable for this operation */ - TEE_ERROR_OUT_OF_MEMORY = 0xFFFF000C, /* not memory avaliable for this operation */ - TEE_ERROR_BUSY = 0xFFFF000D, /* system busy to handle this operation */ - TEE_ERROR_COMMUNICATION = 0xFFFF000E, /* communication error with target */ - TEE_ERROR_SECURITY = 0xFFFF000F, /* security error occurs */ - TEE_ERROR_SHORT_BUFFER = 0xFFFF0010, /* buffer is too short for this operation */ - TEE_ERROR_EXTERNAL_CANCEL = 0xFFFF0011, /* operation is canceled */ - TEE_PENDING = 0xFFFF2000, /* service is in pending state(in asynchronous state) */ - TEE_PENDING2 = 0xFFFF2001, /* service is in pending state() */ - TEE_PENDING3 = 0xFFFF2002, /* reserved error definition */ - TEE_ERROR_TIMEOUT = 0xFFFF3001, /* operation is timeout */ - TEE_ERROR_OVERFLOW = 0xFFFF300f, /* operation overflow */ - TEE_ERROR_TARGET_DEAD = 0xFFFF3024, /* TA is crashed */ - TEE_ERROR_STORAGE_NO_SPACE = 0xFFFF3041, /* no enough space to store data */ - TEE_ERROR_MAC_INVALID = 0xFFFF3071, /* MAC operation failed */ - TEE_ERROR_SIGNATURE_INVALID = 0xFFFF3072, /* signature check failed */ - TEE_CLIENT_INTR = 0xFFFF4000, /* Interrupted by CFC. Broken control flow is detected. */ - TEE_ERROR_TIME_NOT_SET = 0xFFFF5000, /* time is not set */ - TEE_ERROR_TIME_NEEDS_RESET = 0xFFFF5001, /* time need to be reset */ - TEE_FAIL = 0xFFFF5002, /* system error */ - TEE_ERROR_TIMER = 0xFFFF6000, /* base value of timer error codes */ - TEE_ERROR_TIMER_CREATE_FAILED = 0xFFFF6001, /* failed to create timer */ - TEE_ERROR_TIMER_DESTORY_FAILED = 0xFFFF6002, /* failed to destory timer */ - TEE_ERROR_TIMER_NOT_FOUND = 0xFFFF6003, /* timer not found */ - TEE_ERROR_SEC_FLASH_NOT_AVAILABLE = 0xFFFF7118, /* sec flash is not available */ - TEE_ERROR_BIOSRV_NOT_AVAILABLE = 0xFFFF711A, /* BIO service is not available */ - TEE_ERROR_ROTSRV_NOT_AVAILABLE = 0xFFFF711B, /* ROT service is not available */ - TEE_ERROR_ARTSRV_NOT_AVAILABLE = 0xFFFF711C, /* ART service is not available */ - TEE_ERROR_HSMSRV_NOT_AVAILABLE = 0xFFFF711D, /* HSM service is not available */ - TEE_ERROR_ANTIROOT_RSP_FAIL = 0xFFFF9110, /* AntiRoot Response verify failed */ - TEE_ERROR_ANTIROOT_INVOKE_ERROR = 0xFFFF9111, /* AntiRoot ERROR during invokecmd */ - TEE_ERROR_AUDIT_FAIL = 0xFFFF9112, /* audit failed */ - TEE_FAIL2 = 0xFFFF9113 /* unused */ + TEE_SUCCESS = 0x00000000, /* The operation is successful. */ + TEE_ERROR_INVALID_CMD = 0x00000001, /* The command is invalid. */ + TEE_ERROR_SERVICE_NOT_EXIST = 0x00000002, /* The service does not exist. */ + TEE_ERROR_SESSION_NOT_EXIST = 0x00000003, /* The session does not exist. */ + TEE_ERROR_SESSION_MAXIMUM = 0x00000004, /* The number of sessions exceeds the limit. */ + TEE_ERROR_REGISTER_EXIST_SERVICE = 0x00000005, /* The service has been already registered. */ + TEE_ERROR_TARGET_DEAD_FATAL = 0x00000006, /* An internal error occurs. */ + TEE_ERROR_READ_DATA = 0x00000007, /* Failed to read data. */ + TEE_ERROR_WRITE_DATA = 0x00000008, /* Failed to write data. */ + TEE_ERROR_TRUNCATE_OBJECT = 0x00000009, /* Failed to truncate data. */ + TEE_ERROR_SEEK_DATA = 0x0000000A, /* Failed to seek data. */ + TEE_ERROR_SYNC_DATA = 0x0000000B, /* Failed to synchronize data. */ + TEE_ERROR_RENAME_OBJECT = 0x0000000C, /* Failed to rename the file. */ + TEE_ERROR_TRUSTED_APP_LOAD_ERROR = 0x0000000D, /* An error occurs when the TA is loaded. */ + TEE_ERROR_STORAGE_EIO = 0x80001001, /* An I/O error occurs when data is stored. */ + TEE_ERROR_STORAGE_EAGAIN = 0x80001002, /* The storage section is unavailable. */ + TEE_ERROR_STORAGE_ENOTDIR = 0x80001003, /* The operation target is not a directory. */ + TEE_ERROR_STORAGE_EISDIR = 0x80001004, /* This operation cannot be performed on a directory. */ + TEE_ERROR_STORAGE_ENFILE = 0x80001005, /* The number of opened files exceeds the limit in system. */ + TEE_ERROR_STORAGE_EMFILE = 0x80001006, /* The number of files opened for the process exceeds the limit.*/ + TEE_ERROR_STORAGE_EROFS = 0x80001007, /* The storage section is read only. */ + TEE_ERROR_STORAGE_PATH_WRONG = 0x8000100A, /* The file path is not correct. */ + TEE_ERROR_MSG_QUEUE_OVERFLOW = 0x8000100B, /* The service message queue overflows. */ + TEE_ERROR_CORRUPT_OBJECT = 0xF0100001, /* The file object is corrupted. */ + TEE_ERROR_STORAGE_NOT_AVAILABLE = 0xF0100003, /* The storage section is unavailable. */ + TEE_ERROR_CIPHERTEXT_INVALID = 0xF0100006, /* The cipher text is incorrect. */ + TEE_ISOCKET_ERROR_PROTOCOL = 0xF1007001, /* Protocol error in socket connection. */ + TEE_ISOCKET_ERROR_REMOTE_CLOSED = 0xF1007002, /* The socket is closed by the remote end. */ + TEE_ISOCKET_ERROR_TIMEOUT = 0xF1007003, /* The socket connection timed out. */ + TEE_ISOCKET_ERROR_OUT_OF_RESOURCES = 0xF1007004, /* There is no resource available for the socket connection. */ + TEE_ISOCKET_ERROR_LARGE_BUFFER = 0xF1007005, /* The buffer is too large for the socket connection. */ + TEE_ISOCKET_WARNING_PROTOCOL = 0xF1007006, /* A warning is given in the socket connection. */ + TEE_ERROR_GENERIC = 0xFFFF0000, /* Generic error. */ + TEE_ERROR_ACCESS_DENIED = 0xFFFF0001, /* The access is denied. */ + TEE_ERROR_CANCEL = 0xFFFF0002, /* The operation has been canceled. */ + TEE_ERROR_ACCESS_CONFLICT = 0xFFFF0003, /* An access conflict occurs. */ + TEE_ERROR_EXCESS_DATA = 0xFFFF0004, /* The data size exceeds the maximum. */ + TEE_ERROR_BAD_FORMAT = 0xFFFF0005, /* Incorrect data format. */ + TEE_ERROR_BAD_PARAMETERS = 0xFFFF0006, /* Incorrect parameters. */ + TEE_ERROR_BAD_STATE = 0xFFFF0007, /* The current state does not support the operation. */ + TEE_ERROR_ITEM_NOT_FOUND = 0xFFFF0008, /* Failed to find the target item. */ + TEE_ERROR_NOT_IMPLEMENTED = 0xFFFF0009, /* The API is not implemented. */ + TEE_ERROR_NOT_SUPPORTED = 0xFFFF000A, /* The API is not supported. */ + TEE_ERROR_NO_DATA = 0xFFFF000B, /* There is no data available for this operation. */ + TEE_ERROR_OUT_OF_MEMORY = 0xFFFF000C, /* There is no memory available for this operation. */ + TEE_ERROR_BUSY = 0xFFFF000D, /* The system does not respond to this operation. */ + TEE_ERROR_COMMUNICATION = 0xFFFF000E, /* Failed to communicate with the target. */ + TEE_ERROR_SECURITY = 0xFFFF000F, /* A security error occurs. */ + TEE_ERROR_SHORT_BUFFER = 0xFFFF0010, /* The buffer is insufficient for this operation. */ + TEE_ERROR_EXTERNAL_CANCEL = 0xFFFF0011, /* The operation has been canceled. */ + TEE_PENDING = 0xFFFF2000, /* The service is in the pending state (asynchronous state). */ + TEE_PENDING2 = 0xFFFF2001, /* The service is in the pending state(). */ + TEE_PENDING3 = 0xFFFF2002, /* Reserved. */ + TEE_ERROR_TIMEOUT = 0xFFFF3001, /* The operation timed out. */ + TEE_ERROR_OVERFLOW = 0xFFFF300f, /* Overflow occurs. */ + TEE_ERROR_TARGET_DEAD = 0xFFFF3024, /* The TA is crashed. */ + TEE_ERROR_STORAGE_NO_SPACE = 0xFFFF3041, /* There is no enough space to store data. */ + TEE_ERROR_MAC_INVALID = 0xFFFF3071, /* The MAC operation failed. */ + TEE_ERROR_SIGNATURE_INVALID = 0xFFFF3072, /* The signature verification failed. */ + TEE_CLIENT_INTR = 0xFFFF4000, /* Interrupted by CFC. Broken control flow is detected. */ + TEE_ERROR_TIME_NOT_SET = 0xFFFF5000, /* Time is not set. */ + TEE_ERROR_TIME_NEEDS_RESET = 0xFFFF5001, /* Time needs to be reset. */ + TEE_FAIL = 0xFFFF5002, /* System error. */ + TEE_ERROR_TIMER = 0xFFFF6000, /* Base value of the timer error code. */ + TEE_ERROR_TIMER_CREATE_FAILED = 0xFFFF6001, /* Failed to create the timer. */ + TEE_ERROR_TIMER_DESTORY_FAILED = 0xFFFF6002, /* Failed to destroy the timer. */ + TEE_ERROR_TIMER_NOT_FOUND = 0xFFFF6003, /* The timer is not found. */ + TEE_ERROR_SEC_FLASH_NOT_AVAILABLE = 0xFFFF7118, /* sec flash is not available. */ + TEE_ERROR_BIOSRV_NOT_AVAILABLE = 0xFFFF711A, /* The BIO service is not available. */ + TEE_ERROR_ROTSRV_NOT_AVAILABLE = 0xFFFF711B, /* The ROT service is not available. */ + TEE_ERROR_ARTSRV_NOT_AVAILABLE = 0xFFFF711C, /* The ART service is not available. */ + TEE_ERROR_HSMSRV_NOT_AVAILABLE = 0xFFFF711D, /* The HSM service is not available. */ + TEE_ERROR_ANTIROOT_RSP_FAIL = 0xFFFF9110, /* Failed to verify AntiRoot response. */ + TEE_ERROR_ANTIROOT_INVOKE_ERROR = 0xFFFF9111, /* AntiRoot error in invokeCmd(). */ + TEE_ERROR_AUDIT_FAIL = 0xFFFF9112, /* Audit failed. */ + TEE_FAIL2 = 0xFFFF9113 /* Unused. */ }; /* @@ -321,7 +321,7 @@ enum TEE_LoginMethod { TEE_LOGIN_APPLICATION = 0x4, TEE_LOGIN_USER_APPLICATION = 0x5, TEE_LOGIN_GROUP_APPLICATION = 0x6, - TEE_LOGIN_IDENTIFY = 0x7, /* defined Lognin type */ + TEE_LOGIN_IDENTIFY = 0x7, /* Customized login type */ }; typedef struct { diff --git a/sdk/include/TA/tee_mem_mgmt_api.h b/sdk/include/TA/tee_mem_mgmt_api.h index e15d7f6..67fb559 100644 --- a/sdk/include/TA/tee_mem_mgmt_api.h +++ b/sdk/include/TA/tee_mem_mgmt_api.h @@ -13,9 +13,9 @@ /** * @file tee_mem_mgmt_api.h * - * @brief ÄÚ´æ²Ù×÷½Ó¿Ú + * @brief Provides APIs for memory management. + * * - * ¿ª·¢Õß¿ÉÒÔʹÓÃÕâЩ½Ó¿ÚʵÏÖ¶ÔÄÚ´æ²Ù×÷Ïà¹ØµÄ¹¦ÄÜ¡£ * * @since 1 */ @@ -26,9 +26,9 @@ #include "tee_mem_monitoring_api.h" /* - * below definitions are defined by Global Platform or Platform SDK released previously - * for compatibility: - * don't make any change to the content below + * The definitions below are defined by Global Platform or Platform SDK released previously + * for compatibility. + * Do not make any change to the content below. */ #ifndef ZERO_SIZE_PTR #define ZERO_SIZE_PTR ((void *)16) @@ -38,14 +38,14 @@ enum MALLOC_HINT { ZERO = 0, NOT_ZERO = 1, - ALIGN_004 = 0x80000002, /* buf align */ + ALIGN_004 = 0x80000002, /* Buffer alignment */ ALIGN_008 = 0x80000003, ALIGN_016 = 0x80000004, ALIGN_032 = 0x80000005, ALIGN_064 = 0x80000006, ALIGN_128 = 0x80000007, ALIGN_256 = 0x80000008, - ALIGN_004_ZERO = 0x80000012, /* buf align and set to zero */ + ALIGN_004_ZERO = 0x80000012, /* The buffer is 4-byte aligned and initialized to zeros. */ ALIGN_008_ZERO = 0x80000013, ALIGN_016_ZERO = 0x80000014, ALIGN_032_ZERO = 0x80000015, @@ -63,11 +63,11 @@ enum MALLOC_HINT { #define TEE_MEMORY_ACCESS_ANY_OWNER 0x00000004 /** - * @brief ÓÃxÌî³ä»º³åÇøµÄµÚÒ»¸ö´óС×Ö½Ú + * @brief Fills x into the first size bytes of the buffer. * - * @param buffer [OUT]»º³åÇøÖ¸Õë - * @param x [IN]Ìî³äÖµ - * @param size [IN]×Ö½ÚÊý + * @param buffer Indicates the pointer to the buffer. + * @param x Indicates the value to fill. + * @param size Indicates the number of bytes to fill. * */ #if defined(API_LEVEL) && (API_LEVEL >= API_LEVEL1_2) @@ -77,94 +77,99 @@ void TEE_MemFill(void *buffer, uint32_t x, size_t size); #endif /** - * @brief ½«´óС×Ö½Ú´Ósrc¸´ÖƵ½dest + * @brief Copies bytes. * - * @param dest [OUT]dest»º³åÇøÖ¸Õë - * @param src [IN]src»º³åÇøÖ¸Õë - * @param size [IN]×Ö½ÚÊý + * @param dest Indicates the pointer to the buffer that holds the bytes copied. + * @param src Indicates the pointer to the buffer that holds the bytes to copy. + * @param size Indicates the number of bytes to copy. * */ void TEE_MemMove(void *dest, const void *src, size_t size); /** - * @brief ʹÓÃÌáʾֵ·ÖÅä´óС×Ö½ÚµÄÄÚ´æ·µ»ØµÄÖ¸Õ뽫¼æÈÝÈκÎC»ù±¾Êý¾ÝÀàÐÍ + * @brief Allocates space of the specified size for an object. * - * @param size [IN]½«·ÖÅäµÄÄÚ´æ´óС - * @param hint [IN]±êÖ¾£¬0±íʾ·µ»ØµÄÄڴ潫Ìî³ä¡°\0¡± + * @param size Indicates the size of the memory to be allocated. + * @param hint Indicates a hint to the allocator. The value 0 indicates that the memory block + * returned is filled with "\0". * - * @return Ö¸ÏòзÖÅäÄÚ´æµÄÖ¸Õë - * @return NULL ±íʾ·ÖÅäʱʧ°Ü + * @return Returns a pointer to the newly allocated space if the operation is successful. + * @return Returns a NULL pointer if the allocation fails. * */ void *TEE_Malloc(size_t size, uint32_t hint); /** - * @brief ÊÍ·ÅTEE_Malloc·ÖÅäµÄÄÚ´æ + * @brief Releases the memory allocated by TEE_Malloc. * - * Èç¹û»º³åÇøµÈÓÚNULL£¬ÔòTEE_Free½«²»Ö´ÐÐÈκβÙ×÷\n - * µ÷ÓÃÕßӦȷ±£»º³åÇøÊÇÓÉTEE_Malloc»òTEE_Realloc´´½¨µÄ£¬²¢ÇÒ²»Ó¦Á½´ÎÊÍ·ÅÒ»¸öÄڴ棬²Ù×÷½á¹û²»¿ÉÔ¤²â + * If the buffer is a NULL pointer, TEE_Free does nothing. + * The buffer to be released must have been allocated by TEE_Malloc or TEE_Realloc and cannot be + * released repeatedly. Otherwise, unexpected result may be caused. * - * @param buffer [IN]Ö¸ÏòÄÚ´æµÄÖ¸Õë + * @param buffer Indicates the pointer to the memory to release. * */ void TEE_Free(void *buffer); /** - * @brief ÖØзÖÅäÄÚ´æ + * @brief Reallocates memory. * - * Èç¹ûnew_size´óÓÚ¾Ésize£¬Ôò¾ÉÄÚ´æµÄÄÚÈݲ»»á¸ü¸Ä£¬Ê£ÓàÄÚ´æÊÇËæ»ú×Ö½Ú\n - * ÐÞ¸ÄÄÚ´æ´óСʱ½«ÓÐÒ»¸öеķÖÅä²Ù×÷\n - * Èç¹û·ÖÅäʧ°Ü£¬½«·µ»Ø¾ÉÄڴ棬´Ëº¯Êý½«·µ»ØNULL\n - * Èç¹û»º³åÇøµÈÓÚNULL£¬Ôò´Ëº¯ÊýÓëTEE_MallocÏàͬ + * If new_size is greater than the old size, the content of the original memory does not change + * and the space in excess of the old size contains unspecified content. + * If the new size of the memory object requires movement of the object, the space for the previous + * instantiation of the object is deallocated. + * If the space cannot be allocated, the original object remains allocated and this function + * returns a NULL pointer. + * If the buffer is NULL, this function is equivalent to TEE_Malloc. * - * @param buffer [IN]Ö¸ÏòÄÚ´æµÄÖ¸Õë - * @param new_size [IN]ÖØзÖÅäµÄ´óС + * @param buffer Indicates the pointer to the memory to reallocate. + * @param new_size Indicates the new size required. * - * @return Ö¸ÏòÐÂÄÚ´æµÄÖ¸Õ룬²»Ó¦ÎªNULL - * @return NULL±íʾʧ°Ü + * @return Returns a pointer to the allocated memory if the operation is successful. + * @return Returns a NULL pointer if the operation fails. * */ void *TEE_Realloc(void *buffer, size_t new_size); /** - * @brief ÄÚ´æÄÚÈÝ±È½Ï + * @brief Compares memory content from the beginning. * - * @param buffer1 [IN]µÚÒ»¸öÖ¸Õë - * @param buffer2 [IN]µÚ¶þ¸öÖ¸Õë - * @param size [IN]Òª±È½ÏµÄ×Ö½Ú´óС + * @param buffer1 Indicates the pointer to the first buffer. + * @param buffer2 Indicates the pointer to the second buffer. + * @param size Indicates the number of the bytes to compare. * - * @return -1 buffer1 < buffer2 - * @return 0 buffer1 == buffer2 - * @return 1 buffer1 > buffer2 + * @return Returns –1 if buffer1 < buffer2. + * @return Returns 0 if buffer1 == buffer2. + * @return Returns 1 if buffer1 > buffer2. * */ int32_t TEE_MemCompare(const void *buffer1, const void *buffer2, size_t size); /** - * @brief ¼ì²é»º³åÇøµÄ·ÃÎÊȨÏÞ + * @brief Checks whether this TA has the requested permissions to access a buffer. * - * @param accessFlags [IN]´ý¼ì²éµÄ·ÃÎÊȨÏÞ - * @param buffer [IN]Ö¸ÏòÄÚ´æµÄÖ¸Õë - * @param size [IN]Òª¼ì²éµÄÄÚ´æ´óС + * @param accessFlags Indicates the access permissions to check. + * @param buffer Indicates the pointer to the target buffer. + * @param size Indicates the size of the buffer to check. * - * @return TEE_SUCCESS ¾ßÓзÃÎÊȨÏÞ - * @return TEE_ERROR_ACCESS_DENIED ûÓзÃÎÊȨÏÞ + * @return Returns TEE_SUCCESS if the TA has the requested permissions. + * @return Returns TEE_ERROR_ACCESS_DENIED otherwise. */ TEE_Result TEE_CheckMemoryAccessRights(uint32_t accessFlags, const void *buffer, size_t size); /** - * @brief ÓÃÓÚÔÚͬһʵÀýµÄ²»Í¬»á»°Öй²ÏíµÄÈ«¾Ö±äÁ¿ + * @brief Sets the TA instance data pointer. * - * @param instanceData [IN]È«¾Ö±äÁ¿µØÖ· + * @param instanceData Indicates the pointer to the global TA instance data. * */ void TEE_SetInstanceData(void *instanceData); /** - * @brief »ñÈ¡TEE_SetInstanceDataÉèÖõÄÖ¸Õë + * @brief Obtains the instance data pointer set by the TA using TEE_SetInstanceData. * - * @return Ö¸ÏòTEE_SetInstanceDataÉèÖõıäÁ¿µÄÖ¸Õ룬ָÕ벻ӦΪNULL - * @return NULL δÉèÖÃInstanceData + * @return Returns the pointer to the instance data set by TEE_SetInstanceData + * @return or NULL if no instance data pointer has been set. * */ void *TEE_GetInstanceData(void); diff --git a/sdk/include/TA/tee_mem_monitoring_api.h b/sdk/include/TA/tee_mem_monitoring_api.h index a8d7a82..0fc97a8 100644 --- a/sdk/include/TA/tee_mem_monitoring_api.h +++ b/sdk/include/TA/tee_mem_monitoring_api.h @@ -16,11 +16,11 @@ #include /* - * get heap usage of current TA + * @brief Obtains the heap usage of this trusted application (TA). * - * @param show [IN] weather need to print result in log file + * @param show Indicates whether to print the result in the log file. * - * @return percentage of heap usage + * @return Returns the heap usage in percentage. */ uint32_t get_heap_usage(bool show); diff --git a/sdk/include/TA/tee_object_api.h b/sdk/include/TA/tee_object_api.h index 1c310d0..9b8aaae 100644 --- a/sdk/include/TA/tee_object_api.h +++ b/sdk/include/TA/tee_object_api.h @@ -13,9 +13,9 @@ /** * @file tee_object_api.h * - * @brief °²È«´æ´¢½Ó¿Ú + * @brief Provides trusted storage APIs. * - * ¿ª·¢Õß¿ÉÒÔʹÓÃÕâЩ½Ó¿ÚʵÏÖ°²È«´æ´¢µÄÏà¹Ø¹¦ÄÜ¡£ + * You can use these APIs to implement trusted storage features. * * @since 1 */ @@ -25,48 +25,49 @@ #include "tee_defines.h" /** - * @brief HANDLE_NULLµÄ¶¨Ò壬ÎÞЧµÄ¶ÔÏó¾ä±ú + * @brief Defines HANDLE_NULL, which is used to denote the absence of a handle. */ #define TEE_HANDLE_NULL 0x00000000 /** - * @brief TEE_ObjectHandleµÄÃÜԿʹÓ÷½Ê½£¬¾ö¶¨Á˶ÔÏóÃÜÔ¿µÄʹÓÃÇé¿ö + * @brief Enumerates the usages of the key of the TEE_ObjectHandle. */ 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 TEE_ObjectHandleµÄ¾ä±ú±ê־ָʾ¶ÔÏóµÄһЩÐÅÏ¢£¬ÊÇ·ñΪÓÀ¾Ã¶ÔÏó£¬ÊÇ·ñÒѳõʼ»¯µÈ¡£ + * @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. */ 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 ÊôÐÔ±êʶ·û±êÖ¾Áбí + * @brief Defines a list of attribute identifier flags. */ #define TEE_ATTR_FLAG_VALUE 0x20000000 #define TEE_ATTR_FLAG_PUBLIC 0x10000000 @@ -78,184 +79,200 @@ enum Handle_Flag_Constants { #define TEE_ATTR_IS_PUBLIC(attribute_id) ((((attribute_id) << 3) >> 31) == 1) /** - * @brief ÔÚTEE_ObjectHandleÖ¸ÏòµÄ¶ÔÏóµÄTEE_Attribute½á¹¹ÖлñÈ¡ÁªºÏµÄ»º³åÇøÄÚÈÝ + * @brief Obtains a buffer attribute from the TEE_Attribute struct of the object pointed + * to by TEE_ObjectHandle. * - * TEE_Attribute½á¹¹ÖеÄÁªºÏ³ÉÔ±ÐèÒªÊÇref¡£Èç¹ûTEE_AttributeÊÇ˽Óеģ¬Ôò¶ÔÏóµÄʹÓó£Êý±ØÐë°üÀ¨TEE_USAGE_EXTRACTABLE + * 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 [IN]Ô´TEE_ObjectHandle - * @param attributeID [IN]Òª»ñÈ¡µÄÊôÐÔID£¬ÈçTEE_ObjectAttribute£¬Ò²¿ÉÒÔ×Ô¶¨Òå - * @param buffer [OUT]Ö¸Õ룬ָÏòµÄ»º³åÇøÓÃÓÚ´æ´¢»ñÈ¡µÄ»º³åÇøµÄÄÚÈÝ - * @param size [IN/OUT]Ö¸Õ룬´æ´¢ÄÚÈÝ×Ö½Ú³¤¶È + * @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 TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_ITEM_NOT_FOUND ÔÚ¶ÔÏóÖÐÕÒ²»µ½Òª²éÕÒµÄTEE_Attribute£¬»òÕ߶ÔÏóδ³õʼ»¯ - * @return TEE_ERROR_SHORT_BUFFERÌṩµÄ»º³åÇø̫С£¬ÎÞ·¨´æ´¢»ñÈ¡µÄÄÚÈÝ + * @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. * */ TEE_Result TEE_GetObjectBufferAttribute(TEE_ObjectHandle object, uint32_t attributeID, void *buffer, size_t *size); /** - * @brief ÔÚ¶ÔÏóÖеÄTEE_AttributeÖлñÈ¡ÁªºÏµÄÖµ + * @brief Obtains a value attribute from the TEE_Attribute of an object. * - * TEE_Attribute½á¹¹ÖÐÁªºÏµÄ³ÉÔ±±ØÐëΪvalue¡£Èç¹ûTEE_AttributeÊÇ˽Óеģ¬Ôò¶ÔÏóµÄUsage_ConstantsÐèÒª°üÀ¨TEE_USAGE_EXTRACTABLE + * 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 [IN]Ô´TEE_ObjectHandle - * @param attributeID [IN]ÐèÒª»ñÈ¡µÄÊôÐÔID£¬ÈçTEE_ObjectAttribute£¬Ò²¿ÉÒÔ×Ô¶¨Òå - * @param a [OUT]Ö¸Õ룬ָÏòµÄ¿Õ¼äÓÃÓÚ´æ´¢ - * @param b [OUT]Ö¸Õ룬ָÏòµÄ¿Õ¼äÓÃÓÚ´æ´¢b + * @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 TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_ITEM_NOT_FOUND ÔÚ¶ÔÏóÖÐÕÒ²»µ½Òª²éÕÒµÄTEE_Attribute£¬»òÕ߶ÔÏóδ³õʼ»¯ - * @return TEE_ERROR_ACCESS_DENIED ³¢ÊÔ»ñȡ˽ÓÐTEE_Attribute£¬µ«Î´ÉèÖÃTEE_USAGE_EXTRACTABLE + * @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. * */ TEE_Result TEE_GetObjectValueAttribute(TEE_ObjectHandle object, uint32_t attributeID, uint32_t *a, uint32_t *b); /** - * @brief ¹Ø±Õ´ò¿ªµÄTEE_ObjectHandle¶ÔÏó + * @brief Closes a TEE_ObjectHandle object. * - * ¶ÔÏó¿ÉÒÔÊdz־öÔÏó£¬Ò²¿ÉÒÔÊÇÁÙʱ¶ÔÏó + * The object can be persistent or transient. * - * @param object [IN]´ý¹Ø±ÕµÄTEE_ObjectHandle¶ÔÏó + * @param object Indicates the TEE_ObjectHandle object to close. * */ void TEE_CloseObject(TEE_ObjectHandle object); /** - * @brief ·ÖÅäÒ»¸öδ³õʼ»¯µÄ¶ÔÏóÀ´´æ´¢¼ü + * @brief Allocates an uninitialized object to store keys. * - * objectTypeºÍmaxObjectSizeÐèÒªÖ¸¶¨ÒÔÔ¤·ÖÅä + * objectType and maxObjectSize must be specified. * - * @param objectType [IN]´ý´´½¨¶ÔÏóµÄÀàÐÍ£¬È¡ÖµÎªTEE_ObjectType - * @param maxObjectSize [IN]¶ÔÏóµÄ×î´ó×Ö½ÚÊý - * @param object [OUT]Ö¸Ïòд´½¨¶ÔÏó¾ä±úµÄÖ¸Õë + * @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 TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_OUT_OF_MEMORY ÄÚ´æ²»×㣬ÎÞ·¨·ÖÅä - * @return TEE_ERROR_NOT_SUPPORTED ²»Ö§³Ö¶ÔÏóÌṩµÄ×Ö½Ú + * @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. * */ TEE_Result TEE_AllocateTransientObject(uint32_t objectType, uint32_t maxObjectSize, TEE_ObjectHandle *object); /** - * @brief ÊÍ·ÅÒÑ·ÖÅäµÄÁÙʱ¶ÔÏó + * @brief Releases a transient object that is previously allocated with TEE_AllocateTransientObject. * - * º¯Êýµ÷Óú󣬾ä±úʧЧ£¬ËùÓзÖÅäµÄ¶¼±»ÊÍ·Å¡£Óë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[IN]ÐèÒªÊͷŵÄTEE_ObjectHandle + * @param object Indicates the TEE_ObjectHandle to release. * */ void TEE_FreeTransientObject(TEE_ObjectHandle object); /** - * @brief ½«Ë²Ì¬¶ÔÏóÖØÖÃΪ³õʼ״̬£¬¼´·ÖÅäºóµÄ״̬ + * @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 [IN]ÐèÒªÖØÖõÄTEE_ObjectHandle + * @param object Indicates the TEE_ObjectHandle to reset. * */ void TEE_ResetTransientObject(TEE_ObjectHandle object); /** - * @brief ½«²ÎÊýattrsÖеÄÊôÐÔ·ÖÅä¸øδ³õʼ»¯µÄ˲̬¶ÔÏó + * @brief Populates an uninitialized object with object attributes passed by the TA in the attrs parameter. * - * È·±£¶ÔÏóÈÔδ³õʼ»¯\n - * ²ÎÊýattrsÓÉ¿ÉÐÅÓ¦ÓóÌÐòÌṩ + * The object must be uninitialized. \n + * The attrs parameter is passed by a TA. * - * @param object [IN/OUT]TEE_ObjectHandleÒÑ´´½¨µ«Î´³õʼ»¯ - * @param attrs [IN]¶ÔÏóÊôÐÔÊý×飬¿ÉÒÔÊÇÒ»¸ö»ò¶à¸öTEE_Attribute - * @param attrCount [IN]Êý×é³ÉÔ±Êý + * @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 TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_BAD_PARAMETERS ÊôÐÔ²»ÕýÈ·»ò²»Ò»Ö + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_BAD_PARAMETERS if an incorrect or inconsistent attribute value is detected. * */ TEE_Result TEE_PopulateTransientObject(TEE_ObjectHandle object, TEE_Attribute *attrs, uint32_t attrCount); /** - * @brief ³õʼ»¯»º³åÇøÀàÐÍTEE_Attribute + * @brief Initializes the TEE_Attribute of the buffer type. * - * TEE_Attribute½á¹¹ÖеÄÁªºÏ³ÉÔ±ÐèÒªÊÇref + * The members in the TEE_Attribute struct must be ref. * - * @param attr [OUT]Òª³õʼ»¯µÄTEE_Attribute - * @param attributeID [IN]·ÖÅä¸øTEE_AttributeµÄID - * @param buffer [IN]»º³åÇø´æ´¢Òª·ÖÅäµÄÄÚÈÝ - * @param length [IN]¸³ÖµÄÚÈݵÄ×Ö½Ú³¤¶È + * @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. * */ void TEE_InitRefAttribute(TEE_Attribute *attr, uint32_t attributeID, void *buffer, size_t length); /** - * @brief ³õʼ»¯TEE_Attribute + * @brief Initializes a TEE_Attribute. * - * @param attr [OUT]Òª³õʼ»¯µÄTEE_Attribute - * @param attributeID [IN]·ÖÅä¸øTEE_AttributeµÄID - * @param a [IN]½«Öµ¸³Öµ¸øTEE_AttributeÖеÄÁªºÏµÄ³ÉÔ±Öµa - * @param b [IN]½«Öµ¸³Öµ¸øTEE_AttributeÖеÄÁªºÏµÄ³ÉÔ±Öµb + * @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. * */ void TEE_InitValueAttribute(TEE_Attribute *attr, uint32_t attributeID, uint32_t a, uint32_t b); /** - * @brief ´Ëº¯ÊýÉú³ÉËæ»úÃÜÔ¿»òÃÜÔ¿¶Ô£¬²¢½«Æä·ÖÅä¸øÁÙʱ¶ÔÏó + * @brief Generates a random key or a key pair and populates a transient key object with the generated key. * - * @param object [IN]˲̬¶ÔÏó£¬ÓÃÓÚ´æ´¢Éú³ÉµÄÃÜÔ¿ - * @param keySize [IN]ËùÐèÃÜÔ¿µÄ×Ö½ÚÊý - * @param params [IN]ÃÜÔ¿Éú³É²ÎÊý˵Ã÷ - * @param paramCount [IN]Éú³ÉÃÜÔ¿ËùÐèµÄ²ÎÊýÊý + * @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 TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_BAD_PARAMETERS Éú³ÉµÄÃÜÔ¿ÓëÁÙʱ¶ÔÏó¿ÉÒÔ´æ´¢µÄÃÜÔ¿ÀàÐͲ»Ò»Ö + * @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. * */ TEE_Result TEE_GenerateKey(TEE_ObjectHandle object, uint32_t keySize, TEE_Attribute *params, uint32_t paramCount); /** - * @brief »ñÈ¡¶ÔÏóµÄTEE_ObjectInfo + * @brief Obtains TEE_ObjectInfo. * - * »ñÈ¡¶ÔÏóµÄTEE_ObjectInfo£¬²¢½«Æ临ÖƵ½²ÎÊýobjectInfoÖ¸ÏòµÄ¿Õ¼äÖУ¬¸Ã¿Õ¼äÓÉÓû§Ô¤·ÖÅä + * This function obtains TEE_ObjectInfo and copies the obtained information to the pre-allocated space + * pointed to by objectInfo. * - * @param object [IN]Ô´TEE_ObjectHandle - * @param objectInfo [OUT]ÓÃÓÚ´æ´¢TEE_ObjectInfoµÄ½á¹¹ÌåÖ¸Õë + * @param object Indicates the handle of the object. + * @param objectInfo Indicates the pointer to the TEE_ObjectInfo obtained. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_CORRUPT_OBJECT ÎļþË𻵣¬Îļþ¾ä±ú½«±»¹Ø±Õ - * @return TEE_ERROR_STORAGE_NOT_AVAILABLE ÎÞ·¨·ÃÎÊÎļþËùÔڵĴ洢ÇøÓò + * @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. * */ TEE_Result TEE_GetObjectInfo1(TEE_ObjectHandle object, TEE_ObjectInfo *objectInfo); /** - * @brief ʹÓóõʼ»¯¶ÔÏó½«TEE_Attribute¸³Öµ¸øδ³õʼ»¯µÄ¶ÔÏó + * @brief Assigns the TEE_Attribute of an initialized object to an uninitialized object. * - * ¸Ãº¯ÊýʹÓóõʼ»¯¶ÔÏó½«TEE_Attribute¸³Öµ¸øδ³õʼ»¯µÄ¶ÔÏó£¬Ï൱ÓÚ½«srcobjectµÄTEE_Attribute¸´ÖƵ½destobjectÖÐ\n - * Á½¸ö¶ÔÏóµÄTEE_AttributeÀàÐͺͱàºÅ±ØÐëÆ¥Åä + * 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 [IN]Òª·ÖÅäµÄδ³õʼ»¯µÄTEE_ObjectHandle - * @param srcObject [IN]³õʼ»¯µÄTEE_ObjectHandleÓÃÓÚ¸øÁíÒ»¸ö¶ÔÏó¸³Öµ + * @param destObject Indicates the uninitialized object. + * @param srcObject Indicates the initialized object. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_CORRUPT_OBJECT ÎļþË𻵣¬Îļþ¾ä±ú½«±»¹Ø±Õ - * @return TEE_ERROR_STORAGE_NOT_AVAILABLE ÎÞ·¨·ÃÎÊÎļþËùÔڵĴ洢ÇøÓò + * @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. * */ TEE_Result TEE_CopyObjectAttributes1(TEE_ObjectHandle destObject, TEE_ObjectHandle srcObject); /** - * @brief ÏÞÖƶÔÏóµÄobjectUseλ + * @brief Restricts the objectUse bit of an object. * - * ´Ëλ¾ö¶¨¶ÔÏóÖÐÃÜÔ¿µÄʹÓÃÇé¿ö¡£È¡Öµ·¶Î§Îª¡°Ê¹ÓÃÁ¿_³£Á¿¡±¡£¶ÔÓÚ²ÎÊýobjectUseµÄ±ê־λ£º\n - * Èç¹û´ËλÉèÖÃΪ1£¬Ôò¶ÔÏóµÄʹÓñêÖ¾²»»á¸Ä±ä\n - * µ±¸Ã²ÎÊýÉèÖÃΪ0ʱ£¬Çå³ý¸Ã¶ÔÏó¶ÔÓ¦µÄ¶ÔÏóʹÓñêÖ¾¡£\n - * д´½¨µÄ¶ÔÏ󽫰üº¬ËùÓеÄʹÓÃÁ¿_³£Á¿£¬²¢ÇÒʹÓÃÁ¿±êÖ¾Ö»ÄÜÇå³ý£¬²»ÄÜÉèÖà + * 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 [IN]ÐèÒªÏÞÖƵÄTEE_ObjectHandle - * @param objectUsage [IN]Óû§Ï£Íû¸ü¸ÄµÄobjectUsage + * @param object Indicates the TEE_ObjectHandle of the target object. + * @param objectUsage Indicates the new object usage. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_CORRUPT_OBJECT ÎļþË𻵣¬Îļþ¾ä±ú½«±»¹Ø±Õ - * @return TEE_ERROR_STORAGE_NOT_AVAILABLE ÎÞ·¨·ÃÎÊÎļþËùÔڵĴ洢ÇøÓò + * @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. * */ TEE_Result TEE_RestrictObjectUsage1(TEE_ObjectHandle object, uint32_t objectUsage); diff --git a/sdk/include/TA/tee_property_api.h b/sdk/include/TA/tee_property_api.h index 287b8f6..10e2f85 100644 --- a/sdk/include/TA/tee_property_api.h +++ b/sdk/include/TA/tee_property_api.h @@ -16,9 +16,9 @@ #include "tee_defines.h" /* - * below definitions are defined by Global Platform or Platform SDK released previously - * for compatibility: - * don't make any change to the content below + * The definitions below are defined by Global Platform or Platform SDK released previously + * for compatibility. + * Do not make any change to the content below. */ typedef enum { TEE_PROPSET_UNKNOW = 0, @@ -30,157 +30,158 @@ typedef enum { typedef uint32_t TEE_PropSetHandle; /* - * performs a lookup in a property set to retrieve an individual - * property and convert its value into a printable string + * @brief Obtains a property from a property set and converts its value into a printable string. * - * @param propsetOrEnumerator [IN] One of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator - * @param name [IN] Pointer to the zero-terminated string containing name of the property to retrieve - * @param valueBuffer [OUT] Output buffer for the property value - * @param valueBufferLen [IN/OUT] Output buffer length * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_ITEM_NOT_FOUND cannot find target property - * @return TEE_ERROR_SHORT_BUFFER the value buffer is not large enough to hold the whole property value + * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. + * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. + * @param valueBuffer Indicates the pointer to the buffer for holding the property value obtained. + * @param valueBufferLen Indicates the pointer to the buffer length. + * + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the target property cannot be obtained. + * @return Returns TEE_ERROR_SHORT_BUFFER if the value buffer is too small to hold the property value obtained. */ TEE_Result TEE_GetPropertyAsString(TEE_PropSetHandle propsetOrEnumerator, const char *name, char *valueBuffer, size_t *valueBufferLen); /* - * retrieves a single property in a property set and converts its value to a Boolean + * @brief Obtains a property from a property set and converts its value into a Boolean value. * - * @param propsetOrEnumerator [IN] One of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator - * @param name [IN] Pointer to the zero-terminated string containing name of the property to retrieve - * @param value [OUT] A pointer to the variable that will contain the value of the property + * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. + * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. + * @param value Indicates the pointer to the variable that holds the property value obtained. * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_ITEM_NOT_FOUND cannot find target property + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the target property cannot be obtained. */ TEE_Result TEE_GetPropertyAsBool(TEE_PropSetHandle propsetOrEnumerator, const char *name, bool *value); /* - * retrieves a single property in a property set and converts its value to a 32-bit unsigned integer + * @brief Obtains a property from a property set and converts its value into a 32-bit unsigned integer. * - * @param propsetOrEnumerator [IN] One of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator - * @param name [IN] Pointer to the zero-terminated string containing name of the property to retrieve - * @param value [OUT] A pointer to the variable that will contain the value of the property + * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. + * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. + * @param value Indicates the pointer to the variable that holds the property value obtained. * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_ITEM_NOT_FOUND cannot find target property + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the target property cannot be obtained. */ TEE_Result TEE_GetPropertyAsU32(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint32_t *value); #if defined(API_LEVEL) && (API_LEVEL >= API_LEVEL1_2) /* - * retrieves a single property in a property set and converts its value to a 64-bit unsigned integer + * @brief Obtains a property from a property set and converts its value into a 64-bit unsigned integer. * - * @param propsetOrEnumerator [IN] One of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator - * @param name [IN] Pointer to the zero-terminated string containing name of the property to retrieve - * @param value [IN/OUT] A pointer to the variable that will contain the value of the property + * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. + * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. + * @param value Indicates the pointer to the variable that holds the property value obtained. * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_ITEM_NOT_FOUND cannot find target property + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the target property cannot be obtained. */ TEE_Result TEE_GetPropertyAsU64(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint64_t *value); #endif // API_LEVEL /* - * retrieves an individual property and converts its value into a binary block + * @brief Obtains a property from a property set and converts its value into a binary block. * - * @param propsetOrEnumerator [IN] One of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator - * @param name [IN] Pointer to the zero-terminated string containing name of the property to retrieve - * @param valueBuffer [OUT] Output buffer for the property value - * @param valueBufferLen [IN/OUT] Output buffer length + * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. + * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. + * @param valueBuffer Indicates the pointer to the buffer for holding the property value obtained. + * @param valueBufferLen Indicates the pointer to the buffer length. * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_ITEM_NOT_FOUND cannot find target property + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the target property cannot be obtained. * @return TEE_ERROR_SHORT_BUFFER the value buffer is not large enough to hold the whole property value */ TEE_Result TEE_GetPropertyAsBinaryBlock(TEE_PropSetHandle propsetOrEnumerator, const char *name, void *valueBuffer, size_t *valueBufferLen); /* - * retrieves a single property in a property set and converts its value to TEE_UUID struct + * @brief Obtains a property from a property set and converts its value to the TEE_UUID struct. * - * @param propsetOrEnumerator [IN] One of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator - * @param name [IN] Pointer to the zero-terminated string containing name of the property to retrieve - * @param value [OUT] A pointer to the variable that will contain the value of the property + * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. + * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. + * @param value Indicates the pointer to the variable that holds the property value obtained. * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_ITEM_NOT_FOUND cannot find target property + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the target property cannot be obtained. */ TEE_Result TEE_GetPropertyAsUUID(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_UUID *value); /* - * retrieves a single property in a property set and converts its value to TEE_Identity struct + * @brief Obtains a property from a property set and converts its value to the TEE_Identity struct. * - * @param propsetOrEnumerator [IN] One of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator - * @param name [IN] Pointer to the zero-terminated string containing name of the property to retrieve - * @param value [OUT] A pointer to the variable that will contain the value of the property + * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator. + * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain. + * @param value Indicates the pointer to the variable that holds the property value obtained. * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_ITEM_NOT_FOUND cannot find target property + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the target property cannot be obtained. */ TEE_Result TEE_GetPropertyAsIdentity(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_Identity *value); /* - * allocates a property enumerator object + * @brief Allocates a property enumerator object. * - * @param enumerator [OUT] A pointer filled with an opaque handle on the property enumerator + * @param enumerator Indicates the pointer to the property enumerator filled with an opaque handle. * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_OUT_OF_MEMORY not enough resources to allocate the property enumerator + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if there is no enough resources to allocate the property enumerator. */ TEE_Result TEE_AllocatePropertyEnumerator(TEE_PropSetHandle *enumerator); /* - * deallocates a property enumerator object + * @brief Releases a property enumerator object. * - * @param enumerator [IN] A handle on the enumerator to free + * @param enumerator Indicates the handle on the property enumerator to release. * * @return void */ void TEE_FreePropertyEnumerator(TEE_PropSetHandle enumerator); /* - * starts to enumerate the properties in an enumerator + * @brief Starts to enumerate the properties in an enumerator. * - * @param enumerator [IN] A handle on the enumerator - * @param propSet [IN] A pseudo-handle on the property set to enumerate + * @param enumerator Indicates the handle on the enumerator. + * @param propSet Indicates the pseudo-handle on the property set to enumerate. * * @return void */ void TEE_StartPropertyEnumerator(TEE_PropSetHandle enumerator, TEE_PropSetHandle propSet); /* - * resets a property enumerator to its state immediately after allocation + * @brief Resets a property enumerator immediately after allocation. * - * @param enumerator A handle on the enumerator to reset + * @param enumerator Indicates the handle on the enumerator to reset. * * @return void */ void TEE_ResetPropertyEnumerator(TEE_PropSetHandle enumerator); /* - * gets the name of the current property in an enumerator + * @brief Obtains the name of this property in an enumerator. * - * @param enumerator [IN] A handle on the enumerator - * @param nameBuffer [OUT] The buffer to be filled with the name - * @param nameBufferLen [IN/OUT] The length of buffer to be filled + * @param enumerator Indicates the handle on the enumerator. + * @param nameBuffer Indicates the pointer to the buffer that stores the property name obtained. + * @param nameBufferLen Indicates the pointer to the buffer length. * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_ITEM_NOT_FOUND no current property either because the enumerator has not started - * or because it has reached the end of the property set - * @return TEE_ERROR_SHORT_BUFFER If the name buffer is not large enough to contain the property name + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the property is not found because the enumerator has not started + * or has reached the end of the property set. + * @return Returns TEE_ERROR_SHORT_BUFFER if the buffer is too small to hold the property name. */ TEE_Result TEE_GetPropertyName(TEE_PropSetHandle enumerator, void *nameBuffer, size_t *nameBufferLen); /* - * advances the enumerator to the next property + * @brief Obtains the next property in an enumerator. * - * @param enumerator [IN] A handle on the enumerator + * @param enumerator Indicates the handle on the enumerator. * - * @return TEE_SUCCESS operation success - * @return TEE_ERROR_ITEM_NOT_FOUND enumerator has reached the end of the property set or if it has not started + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the property is not found because the enumerator + * has not started or has reached the end of the property set. */ TEE_Result TEE_GetNextProperty(TEE_PropSetHandle enumerator); #endif diff --git a/sdk/include/TA/tee_time_api.h b/sdk/include/TA/tee_time_api.h index 2427e84..22ee844 100644 --- a/sdk/include/TA/tee_time_api.h +++ b/sdk/include/TA/tee_time_api.h @@ -13,9 +13,9 @@ /** * @file tee_time_api.h * - * @brief °²È«Ê±¼ä½Ó¿Ú + * @brief Provides APIs for managing the Trusted Execution Environment (TEE) time. * - * ¿ª·¢Õß¿ÉÒÔʹÓÃÕâЩ½Ó¿ÚʵÏÖ°²È«Ê±¼äÏà¹ØµÄ¹¦ÄÜ¡£ + * You can use these APIs to implement time-related features in a TEE. * * @since 1 */ @@ -32,55 +32,57 @@ */ /** - * @brief »ñÈ¡µ±Ç°TEEϵͳʱ¼ä + * @brief Obtains the current TEE system time. * - * @param time [OUT]µ±Ç°ÏµÍ³Ê±¼ä + * @param time Indicates the pointer to the current system time obtained. * */ void TEE_GetSystemTime(TEE_Time *time); /** - * @brief µÈ´ýÖ¸¶¨µÄºÁÃëÊý + * @brief Waits for the specified period of time, in milliseconds. * - * @param timeout [IN]Ö¸¶¨µÄºÁÃëÊý + * @param timeout Indicates the period of time to wait, in milliseconds. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_CANCEL µÈ´ýÒÑÈ¡Ïû - * @return TEE_ERROR_OUT_OF_MEMORY ûÓÐ×ã¹»µÄÄÚ´æÀ´Íê³É²Ù×÷ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_CANCEL if the wait is canceled. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if the memory is not sufficient to complete the operation. * */ TEE_Result TEE_Wait(uint32_t timeout); /** - * @brief ¼ìË÷ÊÜÐÅÈÎÓ¦ÓóÌÐòµÄ³Ö¾Ãʱ¼ä + * @brief Obtains the persistent time of this trusted application (TA). * - * @param time [IN]ÊÜÐÅÈÎÓ¦ÓóÌÐòµÄ³Ö¾Ãʱ¼ä + * @param time Indicates the pointer to the persistent time of the TA. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_TIME_NOT_SET ³Ö¾Ãʱ¼äÉÐδÉèÖà - * @return TEE_ERROR_TIME_NEEDS_RESET ÓÀ¾Ãʱ¼äÒÑÉèÖ㬵«¿ÉÄÜÒÑË𻵣¬²»µÃÔÙÐÅÈÎ - * @return TEE_ERROR_OVERFLOW TA³ÖÐøʱ¼äÖеÄÃëÊý³¬¹ýÁËuint32_tµÄ·¶Î§ - * @return TEE_ERROR_OUT_OF_MEMORY ûÓÐ×ã¹»µÄÄÚ´æÀ´Íê³É²Ù×÷ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_TIME_NOT_SET if the persistent time has not been set. + * @return Returns TEE_ERROR_TIME_NEEDS_RESET if the persistent time is corrupted and + * the application is not longer trusted. + * @return Returns TEE_ERROR_OVERFLOW if the number of seconds in the TA persistent time + * exceeds the range of uint32_t. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if the memory is not sufficient to complete the operation. * */ TEE_Result TEE_GetTAPersistentTime(TEE_Time *time); /** - * @brief ÉèÖõ±Ç°ÊÜÐÅÈÎÓ¦ÓóÌÐòµÄ³Ö¾Ã»¯Ê±¼ä + * @brief Sets the persistent time for this TA. * - * @param time [IN]ÊÜÐÅÈÎÓ¦ÓóÌÐòµÄ³Ö¾Ãʱ¼ä + * @param time Indicates the pointer to the persistent time of the TA. * - * @return TEE_SUCCESS ³É¹¦ - * @return TEE_ERROR_OUT_OF_MEMORY ûÓÐ×ã¹»µÄÄÚ´æÀ´Íê³É²Ù×÷ - * @return TEE_ERROR_STORAGE_NO_SPACE ûÓÐ×ã¹»µÄ´æ´¢¿Õ¼äÀ´Íê³É²Ù×÷ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if the memory is not sufficient to complete the operation. + * @return Returns TEE_ERROR_STORAGE_NO_SPACE if the storage space is not sufficient to complete the operation. * */ TEE_Result TEE_SetTAPersistentTime(TEE_Time *time); /** - * @brief »ñÈ¡µ±Ç°REEϵͳʱ¼ä + * @brief Obtains the current Rich Execution Environment (REE) system time. * - * @param time [OUT]µ±Ç°REEϵͳʱ¼ä + * @param time Indicates the pointer to the REE system time obtained. * */ void TEE_GetREETime(TEE_Time *time); diff --git a/sdk/include/TA/tee_trusted_storage_api.h b/sdk/include/TA/tee_trusted_storage_api.h index fcffa49..14ec62f 100644 --- a/sdk/include/TA/tee_trusted_storage_api.h +++ b/sdk/include/TA/tee_trusted_storage_api.h @@ -13,9 +13,9 @@ /** * @file tee_trusted_storage_api.h * - * @brief °²È«´æ´¢½Ó¿Ú + * @brief Provides trusted storage APIs. * - * ¿ª·¢Õß¿ÉÒÔµ÷ÓÃÕâЩ½Ó¿ÚʵÏÖ°²È«´æ´¢Ïà¹ØµÄ¹¦ÄÜ + * You can use these APIs to implement trusted storage features. * * @since 1 */ @@ -27,15 +27,14 @@ #include "tee_object_api.h" /** - * @brief Êý¾ÝÁ÷¶¨Î»ÆðʼλÖÃÑ¡ÏÓÃÓÚTEE_SeekObjectDataº¯Êý + * @brief Defines the start position in the data stream associated with an object. + * It is used in the TEE_SeekObjectData function. */ enum __TEE_Whence { - /** ½«ÆðʼλÖö¨Î»ÎªÊý¾ÝÁ÷µÄÆðʼλÖà */ - TEE_DATA_SEEK_SET = 0, /* Position the starting position as the beginning of the data stream */ - /** ½«ÆðʼλÖö¨Î»Îªµ±Ç°Êý¾ÝÁ÷λÖà */ - TEE_DATA_SEEK_CUR, /* Position the starting position as the current data stream position */ - /** ½«ÆðʼλÖö¨Î»ÔÚÊý¾ÝÁ÷µÄĩβ */ - TEE_DATA_SEEK_END /* Position the starting position at the end of the data stream */ + + TEE_DATA_SEEK_SET = 0, /* Set the start position to the beginning of the data stream. */ + TEE_DATA_SEEK_CUR, /* Set the start position to the current data stream position. */ + TEE_DATA_SEEK_END /* Set the start position to the end of the data stream. */ }; struct __TEE_ObjectEnumHandle; @@ -44,82 +43,89 @@ typedef struct __TEE_ObjectEnumHandle *TEE_ObjectEnumHandle; typedef uint32_t TEE_Whence; /** - * @brief ´æ´¢ID£¬¶¨Òå¶ÔÓ¦Ó¦ÓõĴ洢¿Õ¼ä + * @brief Defines the storage ID, which identifies the storage space of the application. */ enum Object_Storage_Constants { - /** Ϊÿ¸öÓ¦ÓóÌÐòµ¥¶ÀʹÓÃ˽Óд洢¿Õ¼ä */ - TEE_OBJECT_STORAGE_PRIVATE = 0x00000001, /* Separate private storage space for each application */ - /** ÓÃÓÚÓ¦ÓóÌÐòµÄµ¥¶À¸öÈË´æ´¢¿Õ¼ä */ - TEE_OBJECT_STORAGE_PERSO = 0x00000002, /* Separate perso storage space for application */ - /** Ìí¼ÓÒÔʵÏÖ°²È«ÉÁ´æ´æ´¢ */ - TEE_OBJECT_SEC_FLASH = 0x80000000, /* Add for secure flash storage */ - /** Ìí¼ÓÓÃÓÚ´æ´¢ce */ - TEE_OBJECT_STORAGE_CE = 0x80000002, /* Add for storage ce */ + + TEE_OBJECT_STORAGE_PRIVATE = 0x00000001, /* Separate private storage space for each application. */ + TEE_OBJECT_STORAGE_PERSO = 0x00000002, /* Separate personal storage space for application. */ + TEE_OBJECT_SEC_FLASH = 0x80000000, /* Space for secure flash storage. */ + TEE_OBJECT_STORAGE_CE = 0x80000002, /* Credential encrypted storage space. */ }; /** - * @brief ϵͳ×ÊÔ´Ô¼Êø£¬ÈçÊý¾ÝÁ÷λÖÃָʾ¿ÉÒÔ²ÉÈ¡µÄ×î´óÖµ + * @brief Defines the system resource constraints, such as the maximum value for the data stream position indicator. */ enum Miscellaneous_Constants { - /** Êý¾ÝÁ÷µÄλÖÃָʾ·û¿ÉÒÔÕ¼ÓõÄ×î´ó³¤¶È */ - TEE_DATA_MAX_POSITION = 0xFFFFFFFF, /* The maximum length that the position indicator of the data stream can take */ - /** objectIDµÄ×î´ó³¤¶È£¬Êµ¼ÊÀ©Õ¹µ½128×Ö½Ú */ - TEE_OBJECT_ID_MAX_LEN = 64, /* The maximum length of objectID, which actually extends to 128 bytes */ + + TEE_DATA_MAX_POSITION = 0xFFFFFFFF, /* Maximum length that the position indicator of the data stream can take. */ + TEE_OBJECT_ID_MAX_LEN = 64, /* Maximum length of the object ID, which can extend to 128 bytes. */ }; /** - * @brief Êý¾ÝÁ÷¿É´æ´¢µÄ×î´óÊý¾Ý×Ö½ÚÊý + * @brief Defines the maximum number of bytes that can be held in a data stream. */ enum TEE_DATA_Size { - /** ¶ÔÏóÊý¾ÝÁ÷¿É´æ´¢µÄ×î´óÊý¾Ý×Ö½ÚÊý */ - TEE_DATA_OBJECT_MAX_SIZE = 0xFFFFFFFF /* The maximum bytes of data that the object data stream can store */ + + TEE_DATA_OBJECT_MAX_SIZE = 0xFFFFFFFF }; /** - * @brief TEE_ObjectHandleµÄhandleFlags¾ö¶¨ÁËTEE_ObjectHandle¶Ô¶ÔÏóÊý¾ÝÁ÷µÄ·ÃÎÊȨÏÞ + * @brief Defines the handleFlags of a TEE_ObjectHandle. + * The handleFlags determines the access permissions to the data stream associated with the object. */ enum Data_Flag_Constants { - /** ¶ÔÊý¾ÝÁ÷¾ßÓжÁȨÏÞ£¬¿ÉÒÔ¶Á */ + /** The data stream can be read. */ TEE_DATA_FLAG_ACCESS_READ = 0x00000001, - /** ¶ÔÊý¾ÝÁ÷¾ßÓÐдȨÏÞ£¬¿ÉÒÔдºÍ½Ø¶Ï */ + /** The data stream can be written or truncated. */ TEE_DATA_FLAG_ACCESS_WRITE = 0x00000002, - /** ¶ÔÊý¾ÝÁ÷¾ßÓÐдÈë_METAȨÏÞ£¬¿ÉÒÔɾ³ýºÍÖØÃüÃû²Ù×÷ */ + /** The data stream can be deleted or renamed. */ TEE_DATA_FLAG_ACCESS_WRITE_META = 0x00000004, - /** ¶ÔÊý¾ÝÁ÷¾ßÓй²Ïí¶ÁȨÏÞ£¬Äú¿ÉÒÔ´ò¿ª¶à¸öTEE_ObjectHandles½øÐв¢·¢¶Á */ + /** Multiple TEE_ObjectHandles can be opened for concurrent read. */ TEE_DATA_FLAG_SHARE_READ = 0x00000010, - /** ¶ÔÊý¾ÝÁ÷¾ßÓй²ÏíдÈëȨÏÞ£¬¿ÉÒÔ´ò¿ª¶à¸öTEE_ObjectHandles²¢·¢Ð´Èë */ + /** Multiple TEE_ObjectHandles can be opened for concurrent write. */ TEE_DATA_FLAG_SHARE_WRITE = 0x00000020, - /** δʹÓà */ + /** Reserved. */ TEE_DATA_FLAG_CREATE = 0x00000200, - /** ±£»¤Í¬ÃûµÄÏÖÓÐÎļþ¡£Èç¹ûͬÃûÎļþ²»´æÔÚ£¬Ôò´´½¨ÐµÄÊý¾ÝÎļþ£»Èç¹ûͬÃûÎļþ´æÔÚ£¬Ôò±¨´í */ + /** + * Protect the existing file with the same name. Throw an error if the file with the same name exists; + * create a data file otherwise. + */ TEE_DATA_FLAG_EXCLUSIVE = 0x00000400, - /** ±£»¤Í¬ÃûµÄÏÖÓÐÎļþ¡£Èç¹ûͬÃûÎļþ²»´æÔÚ£¬Ôò´´½¨ÐµÄÊý¾ÝÎļþ£»Èç¹ûͬÃûÎļþ´æÔÚ£¬Ôò±¨´í */ + /** + * Protect the existing file with the same name. Throw an error if the file with the same name exists; + * create a data file otherwise. + */ TEE_DATA_FLAG_OVERWRITE = 0x00000400, - /** Èç¹ûbit28ÉèÖÃΪ1£¬±íʾAES256£¬Èç¹ûΪ0£¬±íʾAES128 */ + /** Use AES256 if bit 28 is 1; use AES128 if bit 28 is 0. */ TEE_DATA_FLAG_AES256 = 0x10000000, - /** Èç¹ûbit29ÉèÖÃΪ1£¬Ôò±íʾÏÈ´ò¿ªµÍ°æ±¾ */ + /** If bit 29 is set to 1, open the earlier version preferentially. */ TEE_DATA_FLAG_OPEN_AESC = 0x20000000, }; /** - * @brief ´´½¨Ò»¸öеij־û¯¶ÔÏó + * @brief Creates a persistent object. * - * ´´½¨Ò»¸öеij־û¯¶ÔÏ󣬿ÉÒÔÖ±½Ó³õʼ»¯Êý¾ÝÁ÷ºÍTEE_Attribute£¬Óû§¿ÉÒÔʹÓ÷µ»ØµÄ¾ä±ú·ÃÎʶÔÏóµÄTEE_AttributeºÍÊý¾ÝÁ÷ + * This function creates a persistent object with initialized TEE_Attribute and data stream. + * You can use the returned handle to access the TEE_Attribute and data stream of the object. * - * @param storageID [IN]¶ÔÓ¦ÓÚÿ¸öÓ¦ÓóÌÐòµÄµ¥¶À´æ´¢¿Õ¼ä£¬ÖµÎªObject_Storage_Constants - * @param ojbectID [IN]¶ÔÏó±êʶ·û£¬Òª´´½¨µÄ¶ÔÏóµÄÃû³Æ - * @param objectIDLen [IN]¶ÔÏó±êʶ·ûµÄ³¤¶È£¨°´×Ö½Ú£©£¬²»³¬¹ý128×Ö½Ú - * @param flags [IN]¶ÔÏó´´½¨ºóµÄ±êÖ¾£¬Öµ¿ÉÒÔÊÇData_Flag_Constant»òHandle_Flag_ConstantÖеÄÒ»¸ö»ò¶à¸ö - * @param attributes [IN]ÁÙʱ¶ÔÏóµÄTEE_ObjectHandleÓÃÓÚ³õʼ»¯¶ÔÏóµÄTEE_Attribute£¬¿ÉÒÔÊÇTEE_HANDLE_NULL - * @param initialData [IN]³õʼ»¯Êý¾Ý£¬ÓÃÓÚ³õʼ»¯Êý¾ÝÁ÷Êý¾Ý - * @param initialDataLen [IN]³õʼÊý¾Ý³¤¶È£¨ÒÔ×Ö½ÚΪµ¥Î»£© - * @param object [OUT]º¯ÊýÖ´Ðгɹ¦ºó·µ»ØµÄTEE_ObjectHandle + * @param storageID Indicates the storage to use. The value is specified by Object_Storage_Constants. + * @param ojbectID Indicates the pointer to the object identifier, that is, the name of the object to create. + * @param objectIDLen Indicates the length of the object identifier, in bytes. It cannot exceed 128 bytes. + * @param flags Indicates the flags of the object created. The value can be + * one or more of Data_Flag_Constants or Handle_Flag_Constants. + * @param attributes Indicates the TEE_ObjectHandle of a transient object from which to take + * TEE_Attribute. It can be TEE_HANDLE_NULL if the persistent object contains no attribute. + * @param initialData Indicates the pointer to the initial data used to initialize the data stream data. + * @param initialDataLen Indicates the length of the initial data, in bytes. + * @param object Indicates the pointer to the TEE_ObjectHandle returned + * after the function is successfully executed. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_ITEM_NOT_FOUND storageID²»´æÔÚ - * @return TEE_ERROR_ACCESS_CONFLICT ·ÃÎʳåÍ» - * @return TEE_ERROR_OUT_OF_MEMORY ÄÚ´æ²»×㣬ÎÞ·¨Íê³É²Ù×÷ - * @return TEE_ERROR_STORAGE_NO_SPACE ûÓÐ×ã¹»µÄ¿Õ¼äÀ´´´½¨¶ÔÏó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the storage specified by storageID does not exist. + * @return Returns TEE_ERROR_ACCESS_CONFLICT if an access conflict occurs. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if the memory is not sufficient to complete the operation. + * @return Returns TEE_ERROR_STORAGE_NO_SPACE if there is no enough space to create the object. * */ TEE_Result TEE_CreatePersistentObject(uint32_t storageID, const void *ojbectID, size_t objectIDLen, uint32_t flags, @@ -127,186 +133,199 @@ TEE_Result TEE_CreatePersistentObject(uint32_t storageID, const void *ojbectID, TEE_ObjectHandle *object); /** - * @brief ´ò¿ªÏÖÓеÄÓÀ¾Ã¶ÔÏó + * @brief Opens an existing persistent object. * - * ´ò¿ªÏÖÓеÄÓÀ¾Ã¶ÔÏó£¬Óû§¿ÉÒÔʹÓ÷µ»ØµÄ¾ä±ú·ÃÎʶÔÏóµÄTEE_AttributeºÍÊý¾ÝÁ÷ + * The handle returned can be used to access the TEE_Attribute and data stream of the object. * - * @param storageID [IN]¶ÔÓ¦ÓÚÿ¸öÓ¦ÓóÌÐòµÄµ¥¶À´æ´¢¿Õ¼ä£¬ÖµÎªObject_Storage_Constants - * @param ojbectID [IN]¶ÔÏó±êʶ·û£¬Òª´ò¿ªµÄ¶ÔÏóµÄÃû³Æ - * @param objectIDLen [IN]¶ÔÏó±êʶ·ûµÄ³¤¶È£¨°´×Ö½Ú£©£¬²»³¬¹ý128×Ö½Ú - * @param flags [IN]¶ÔÏó´ò¿ªºóµÄ±êÖ¾£¬Öµ¿ÉÒÔÊÇData_Flag_Constants»òHandle_Flag_ConstantsÖеÄÒ»¸ö»ò¶à¸ö - * @param object[OUT]º¯ÊýÖ´Ðгɹ¦ºó·µ»ØµÄTEE_ObjectHandle + * @param storageID Indicates the storage to use. The value is specified by Object_Storage_Constants. + * @param ojbectID Indicates the pointer to the object identifier, that is, the name of the object to open. + * @param objectIDLen Indicates the length of the object identifier, in bytes. It cannot exceed 128 bytes. + * @param flags Indicates the flags of the object opened. + * The value can be one or more of Data_Flag_Constants or Handle_Flag_Constants. + * @param object Indicates the pointer to the TEE_ObjectHandle returned + * after the function is successfully executed. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_ITEM_NOT_FOUND storageID²»´æÔÚ»òÕÒ²»µ½¶ÔÏó±êʶ·û - * @return TEE_ERROR_ACCESS_CONFLICT ·ÃÎʳåÍ» - * @return TEE_ERROR_OUT_OF_MEMORY ÄÚ´æ²»×㣬ÎÞ·¨Íê³É²Ù×÷ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_ITEM_NOT_FOUND if the storage specified by storageID does not exist + * or the object identifier cannot be found in the storage. + * @return Returns TEE_ERROR_ACCESS_CONFLICT if an access conflict occurs. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if the memory is not sufficient to complete the operation. * */ TEE_Result TEE_OpenPersistentObject(uint32_t storageID, const void *ojbectID, size_t objectIDLen, uint32_t flags, TEE_ObjectHandle *object); /** - * @brief ´Ó¶ÔÏóµÄÊý¾ÝÁ÷¶ÁÈ¡Êý¾ÝµÄ´óС×Ö½Úµ½»º³åÇø + * @brief Reads data from the data stream associated with an object into the buffer. * - * ´Ó¶ÔÏóµÄÊý¾ÝÁ÷¶ÁÈ¡Êý¾ÝµÄ´óС×Ö½Úµ½»º³åÇø£¬TEE_ObjectHandleÐèҪʹÓÃTEE_DATA_FLAG_ACCESS_READȨÏÞ´ò¿ª + * The TEE_ObjectHandle of the object must have been opened with the TEE_DATA_FLAG_ACCESS_READ permission. * - * @param ojbect [IN]Òª¶ÁÈ¡µÄTEE_ObjectHandle - * @param buffer [OUT]´æ´¢¶ÁÊý¾ÝµÄ»º³åÇø - * @param size [IN]°´×Ö½Ú¶ÁÈ¡µÄÊý¾Ý´óС - * @param count [OUT]°´×Ö½Úʵ¼Ê¶ÁÈ¡µÄÊý¾Ý´óС + * @param ojbect Indicates the TEE_ObjectHandle of the object to read. + * @param buffer Indicates the pointer to the buffer used to store the data read. + * @param size Indicates the number of bytes to read. + * @param count Indicates the pointer to the variable that contains the number of bytes read. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_OUT_OF_MEMORY ÄÚ´æ²»×㣬ÎÞ·¨Íê³É²Ù×÷ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if the memory is not sufficient to complete the operation. * */ TEE_Result TEE_ReadObjectData(TEE_ObjectHandle ojbect, void *buffer, size_t size, uint32_t *count); /** - * @brief ½«Êý¾Ý´Ó»º³åÇøдÈë¶ÔÏóµÄÊý¾ÝÁ÷µÄ´óС×Ö½Ú + * @brief Writes bytes from the buffer to the data stream associated with an object. * - * ½«Êý¾Ý´Ó»º³åÇøдÈë¶ÔÏóµÄÊý¾ÝÁ÷µÄ´óС×Ö½Ú,TEE_ObjectHandleÐèҪʹÓÃTEE_DATA_FLAG_ACCESS_WRITEȨÏÞ´ò¿ª + * The TEE_ObjectHandle must have been opened with the TEE_DATA_FLAG_ACCESS_WRITE permission. * - * @param ojbect [IN]ҪдÈëµÄTEE_ObjectHandle - * @param buffer [IN]´æ´¢ÒªÐ´ÈëµÄÊý¾Ý - * @param size [IN]ҪдÈëµÄÊý¾Ý³¤¶È£¬´óС²»³¬¹ý4096×Ö½Ú + * @param ojbect Indicates the TEE_ObjectHandle of the object. + * @param buffer Indicates the pointer to the buffer that stores the data to be written. + * @param size Indicates the number of bytes to be written. It cannot exceed 4096 bytes. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_OUT_OF_MEMORY ÄÚ´æ²»×㣬ÎÞ·¨Íê³É²Ù×÷ - * @return TEE_ERROR_STORAGE_NO_SPACE ûÓÐ×ã¹»µÄ¿Õ¼äÀ´Ö´ÐвÙ×÷ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if the memory is not sufficient to complete the operation. + * @return Returns TEE_ERROR_STORAGE_NO_SPACE if the storage space is not sufficient to complete the operation. * */ TEE_Result TEE_WriteObjectData(TEE_ObjectHandle ojbect, const void *buffer, size_t size); /** - * @brief ¸ü¸ÄÊý¾ÝÁ÷µÄ´óС + * @brief Changes the size of a data stream. * - * Èç¹û´óССÓÚµ±Ç°Êý¾ÝÁ÷µÄ´óС£¬Ôòɾ³ýËùÓжàÓàµÄ×Ö½Ú¡£Èç¹û´óС´óÓÚµ±Ç°Êý¾ÝÁ÷µÄ´óС£¬ÔòʹÓá°0¡±À©Õ¹TEE_ObjectHandle\n - * ÐèÒª¾ßÓÐTEE_DATA_FLAG_ACCESS_WRITEȨÏÞ´ò¿ª + * If the size is less than the current size of the data stream, all bytes beyond size are deleted. If the size + * is greater than the current size of the data stream, add 0s at the end of the stream to extend the stream. + * The object handle must be opened with the TEE_DATA_FLAG_ACCESS_WRITE permission. * - * @param object [IN]Òª½Ø¶ÏµÄTEE_ObjectHandle - * @param size [IN]Êý¾ÝÁ÷µÄг¤¶È£¬´óС²»³¬¹ý4096×Ö½Ú + * @param object Indicates the TEE_ObjectHandle of the object. + * @param size Indicates the new size of the data stream. It cannot exceed 4096 bytes. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_STORAGE_NO_SPACE ûÓÐ×ã¹»µÄ¿Õ¼äÀ´Ö´ÐвÙ×÷ + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_STORAGE_NO_SPACE if the storage space is not sufficient to complete the operation. * */ TEE_Result TEE_TruncateObjectData(TEE_ObjectHandle object, size_t size); /** - * @brief - * ÉèÖÃTEE_ObjectHandleÖ¸ÏòµÄÊý¾ÝÁ÷λÖà + * @brief Sets the position of the data stream to which TEE_ObjectHandle points. * - * ÉèÖÃTEE_ObjectHandleÖ¸ÏòµÄÊý¾ÝÁ÷λÖ㬽«Êý¾ÝÁ÷λÖÃÉèÖÃΪ£ºÆðʼλÖÃ+Æ«ÒÆÁ¿²ÎÊýwherece¿ØÖÆÆ«ÒÆÁ¿µÄÆðʼλÖã¬\n - * ¸ÃÖµ¿ÉÒÔÔÚTEE_WhenceÖÐÑ¡Ôñ£¬º¬ÒåÈçÏ£º\n - * TEE_DATA_SEEK_SET£¬Êý¾ÝÁ÷Æ«ÒÆÁ¿µÄÆðʼλÖÃΪÎļþÍ·£¬Îª0\n - * TEE_DATA_SEEK_CUR£¬Êý¾ÝÁ÷Æ«ÒƵÄÆðʼλÖÃΪµ±Ç°Î»ÖÃ\n - * TEE_DATA_SEEK_END£¬Êý¾ÝÁ÷Æ«ÒÆÁ¿µÄÆðʼλÖÃÊÇÎļþµÄĩβµ±²ÎÊýÆ«ÒÆÁ¿ÎªÕýÊýʱ£¬ËüÏòºóÆ«ÒÆ£¬µ±²ÎÊýÆ«ÒÆÁ¿Îª¸ºÊýʱ£¬ËüÏòÇ°Æ«ÒÆ¡£ + * The data position indicator is determined by the start position and an offset together. + * The whence parameter determines the start position. Its value is set in TEE_Whence as follows: + * TEE_DATA_SEEK_SET = 0: The start position is the beginning of the data stream. + * TEE_DATA_SEEK_CUR: The start position is the current position of the data stream. + * TEE_DATA_SEEK_END: The start position is the end of the data stream. + * If the parameter offset is a positive number, the data position is moved forward. + * If offset is a negative number, the data position is moved backward. * - * @param object [IN]ÐèÒªÉèÖõÄTEE_ObjectHandle - * @param offset [IN]Êý¾ÝÁ÷λÖÃÒƶ¯µÄ´óС£¬´óС²»³¬¹ý4096×Ö½Ú - * @param whence [IN]Êý¾ÝÁ÷Æ«ÒÆÁ¿µÄ³õʼλÖà + * @param object Indicates the TEE_ObjectHandle of the object. + * @param offset Indicates the number of bytes to move the data position. It cannot exceed 4096 bytes. + * @param whence Indicates the start position in the data stream to calculate the new position. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_OVERFLOW ¸Ã²Ù×÷µ¼ÖÂλÖÃָʾÆ÷µÄÖµ³¬¹ýÆäϵͳÏÞÖÆTEE_DATA_MAX_POSIT + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OVERFLOW if the position indicator resulting from this operation + * is greater than TEE_DATA_MAX_POSIT. * */ TEE_Result TEE_SeekObjectData(TEE_ObjectHandle object, int32_t offset, TEE_Whence whence); /** - * @brief ͬ²½´ò¿ªµÄTEE_ObjectHandle²¢Í¬²½ÏàÓ¦µÄ°²È«ÊôÐÔÎļþµ½´ÅÅÌ + * @brief Synchronizes the opened TEE_ObjectHandle and the corresponding security attribute file to the disk. * - * @param object [IN]ÐèҪͬ²½µÄTEE_ObjectHandle + * @param object Indicates the TEE_ObjectHandle of the object. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ + * @return Returns TEE_SUCCESS if the operation is successful. * */ TEE_Result TEE_SyncPersistentObject(TEE_ObjectHandle object); /** - * @brief ¸ü¸Ä¶ÔÏó±êʶ·û + * @brief Changes the object identifier. * - * ÐèҪʹÓÃTEE_DATA_FLAG_ACCESS_WRITE_METAȨÏÞ´ò¿ªTEE_ObjectHandle + * The TEE_ObjectHandle must have been opened with the TEE_DATA_FLAG_ACCESS_WRITE_META permission. * - * @param object [IN/OUT]ÒªÐ޸ĵĶÔÏó¾ä±ú - * @param newObjectID [IN]жÔÏó±êʶ·û - * @param newObjectIDLen [IN]жÔÏó±êʶ·û³¤¶È + * @param object Indicates the handle of the target object. + * @param newObjectID Indicates the pointer to the new object identifier. + * @param newObjectIDLen Indicates the length of the new object identifier. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ + * @return Returns TEE_SUCCESS if the operation is successful. * */ TEE_Result TEE_RenamePersistentObject(TEE_ObjectHandle object, void *newObjectID, size_t newObjectIDLen); /** - * @brief ·ÖÅäδ³õʼ»¯¶ÔÏóö¾ÙÆ÷µÄ¾ä±ú + * @brief Allocates a handle on an uninitialized object enumerator. * - * @param obj_enumerator [OUT]Ö¸Ïòд´½¨µÄ¶ÔÏóö¾ÙÆ÷¾ä±úµÄÖ¸Õë + * @param obj_enumerator Indicates the pointer to the handle of the newly created object enumerator. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_OUT_OF_MEMORY ûÓÐ×ã¹»µÄÄÚ´æÀ´·ÖÅä + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_OUT_OF_MEMORY if the memory is not sufficient to complete the operation. * */ TEE_Result TEE_AllocatePersistentObjectEnumerator(TEE_ObjectEnumHandle *obj_enumerator); /** - * @brief ÊÍ·ÅÒÑ·ÖÅäµÄ¶ÔÏóö¾ÙÆ÷¾ä±ú¡£ + * @brief Releases all resources associated with an object enumerator handle. * - * º¯Êýµ÷Óúó¾ä±úʧЧ£¬ËùÓзÖÅäµÄ¾ä±ú¶¼±»ÊÍ·Å£¬ÓëTEE_AllocatePersistentObjectEnumeratorÅä¶ÔʹÓà + * After this function is called, the object handle is no longer valid and all resources associated with + * the object enumerator handle will be reclaimed. + * TEE_FreePersistentObjectEnumerator and TEE_AllocatePersistentObjectEnumeratorare used in pairs. * - * @param obj_enumerator [IN]´ý·¢²¼µÄTEE_ObjectEnumHandle + * @param obj_enumerator Indicates the TEE_ObjectEnumHandle to release. * */ void TEE_FreePersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator); /** - * @brief ½«ÁÙʱ¶ÔÏóö¾ÙÆ÷ÖØÖÃΪÆä³õʼ״̬£¬¼´·ÖÅäºóµÄ״̬ + * @brief Resets an object enumerator handle to its initial state after allocation. * - * @param obj_enumerator [IN]ÐèÒªÖØÖõĶÔÏóö¾ÙÆ÷µÄTEE_ObjectEnumHandle + * @param obj_enumerator Indicates the TEE_ObjectEnumHandle of the object enumerator to reset. * */ void TEE_ResetPersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator); /** - * @brief ¿ªÊ¼Ã¶¾Ù¸ø¶¨´æ´¢¿Õ¼äÖеÄËùÓжÔÏó + * @brief Starts the enumeration of all the objects in the given trusted storage. * - * ¶ÔÏóµÄÐÅÏ¢¿ÉÒÔͨ¹ýTEE_GetNextPersistentObjectº¯Êý»ñÈ¡ + * The object information can be obtained by using TEE_GetNextPersistentObject. * - * @param obj_enumerator [IN]·ÖÅäµÄ¶ÔÏóö¾ÙÆ÷TEE_ObjectEnumHandle - * @param storage_id [IN]¶ÔÓ¦ÓÚÿ¸öÓ¦ÓóÌÐòµÄµ¥¶À´æ´¢¿Õ¼ä£¬ÖµÎªObject_Storage_Constants£¬\n - * Ä¿Ç°½öÖ§³ÖTEE_STORAGE_PRIVATE + * @param obj_enumerator Indicates the TEE_ObjectEnumHandle of the object enumerator. + * @param storage_id Indicates the storage, in which the objects are enumerated. + * The value is specified by Object_Storage_Constants. + * Currently, only TEE_STORAGE_PRIVATE is supported. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ITEM_NOT_FOUND storageID²»ÊÇTEE_STORAGE_PRIVATE»òÕß´æ´¢¿Õ¼äÖÐûÓжÔÏó + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ITEM_NOT_FOUND if storageID is not TEE_STORAGE_PRIVATE + * or there is no object in the specified storage. * */ TEE_Result TEE_StartPersistentObjectEnumerator(TEE_ObjectEnumHandle obj_enumerator, uint32_t storage_id); /** - * @brief »ñÈ¡¶ÔÏóö¾ÙÆ÷ÖеÄÏÂÒ»¸ö¶ÔÏó + * @brief Obtains the next object in the object enumerator. * - * ·µ»Ø¶ÔÏóµÄTEE_ObjectInfo¡¢objectID¡¢objectIDLenÐÅÏ¢ + * Information such as TEE_ObjectInfo, objectID, and objectIDLen will be obtained. * - * @param obj_enumerator [IN]³õʼ»¯¶ÔÏóö¾ÙÆ÷TEE_ObjectEnumHandle - * @param object_info [IN]´æ´¢»ñÈ¡µ½µÄTEE_ObjectInfo½á¹¹ÌåÖ¸Õë - * @param object_id [IN]»º³åÇøÖ¸Õ룬ÓÃÓÚ´æ´¢»ñÈ¡µÄobjectID - * @param object_id_len[IN]ÓÃÓÚ´æ´¢»ñÈ¡µ½µÄ¶ÔÏóIDLen + * @param obj_enumerator Indicates the TEE_ObjectEnumHandle of the object enumerator. + * @param object_info Indicates the pointer to the obtainedTEE_ObjectInfo. + * @param object_id Indicates the pointer to the buffer used to store the obtained objectID. + * @param object_id_len Indicates the pointer to the objectIDLen. * - * @param TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @param TEE_ITEM_NOT_FOUND ö¾ÙÆ÷ûÓжÔÏó»òö¾ÙÆ÷ÉÐδ³õʼ»¯ + * @return Returns TEE_SUCCESS if the operation is successful. + * @param Returns TEE_ITEM_NOT_FOUND if the object enumerator has no element + * or the enumerator has not been initialized. * */ TEE_Result TEE_GetNextPersistentObject(TEE_ObjectEnumHandle obj_enumerator, TEE_ObjectInfo *object_info, void *object_id, size_t *object_id_len); /** - * @brief ¹Ø±Õ´ò¿ªµÄTEE_ObjectHandle²¢É¾³ý¶ÔÏó + * @brief Closes a TEE_ObjectHandle and deletes the object. * - * ¸Ã¶ÔÏóÊdz־öÔÏ󣬲¢ÇÒÐèҪʹÓÃTEE_DATA_FLAG_ACCESS_WRITE_METAȨÏÞ´ò¿ª + * The object must be a persistent object, and the object handle must have been opened with + * the TEE_DATA_FLAG_ACCESS_WRITE_META permission. * - * @param object [IN]ÐèÒª¹Ø±ÕºÍɾ³ýµÄTEE_ObjectHandle + * @param object Indicates the object handle to close. * - * @return TEE_SUCCESS ָʾº¯ÊýÒѳɹ¦Ö´ÐÐ - * @return TEE_ERROR_STORAGE_NOT_AVAILABLE ÎÞ·¨·ÃÎÊÎļþËùÔڵĴ洢ÇøÓò + * @return Returns TEE_SUCCESS if the operation is successful. + * @return Returns TEE_ERROR_STORAGE_NOT_AVAILABLE if the object is stored + * in a storage area that is inaccessible currently. * */ TEE_Result TEE_CloseAndDeletePersistentObject1(TEE_ObjectHandle object);