/* * @copyright Copyright (c) 2017-2020 TOYOTA MOTOR CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef HAL_API_SECURITY_HAL_H_ #define HAL_API_SECURITY_HAL_H_ #include #include /** * @file security_hal.h */ /** @addtogroup update_service * @{ */ /** @addtogroup security_hal * @ingroup update_service * @{ */ /** * \~english The max size of RSA modulus */ #define RSA_MODULUS_MAX_SIZE 2048 /** * \~english The max size of RSA public exponent */ #define RSA_PUBLIC_EXPONENT_MAX_SIZE 2048 /** * \~english The max size of RSA private exponent */ #define RSA_PRIVATE_EXPONENT_MAX_SIZE 2048 /** * \~english The minimum size of RSA padding */ #define RSA_PADDING_MINIMUM_SIZE 11 /** * \~english Cipher type */ enum CipherType { /** * \~english AES symmetric cipher */ SYMMETRIC_CIPHER_AES = 1, /** * \~english BLOWFISH symmetric cipher */ SYMMETRIC_CIPHER_BLOWFISH, /** * \~english CAST5 symmetric cipher */ SYMMETRIC_CIPHER_CAST5, /** * \~english DES symmetric cipher */ SYMMETRIC_CIPHER_DES, /** * \~english DESEDA symmetric cipher */ SYMMETRIC_CIPHER_DESEDA, /** * \~english DESEDA3 symmetric cipher */ SYMMETRIC_CIPHER_DESEDA3, /** * \~english IDEA symmetric cipher */ SYMMETRIC_CIPHER_IDEA, /** * \~english RC2 symmetric cipher */ SYMMETRIC_CIPHER_RC2, /** * \~english RC4 symmetric cipher */ SYMMETRIC_CIPHER_RC4, /** * \~english RC5 symmetric cipher */ SYMMETRIC_CIPHER_RC5, /** * \~english RSA asymmetric cipher */ ASYMMETRIC_CIPHER_RSA, /** * \~english DSA asymmetric cipher */ ASYMMETRIC_CIPHER_DSA, /** * \~english ECDSA asymmetric cipher */ ASYMMETRIC_CIPHER_ECDSA }; /** * \~english Symmetric Cipher Mode */ enum SymmetricCipherMode { /** * \~english Stream symmetric cipher mode */ SYMMETRIC_CIPHER_MODE_STREAM = 0x00000001, /** * \~english ECB symmetric cipher mode */ SYMMETRIC_CIPHER_MODE_BLOCK_ECB = 0x00000002, /** * \~english CBC symmetric cipher mode */ SYMMETRIC_CIPHER_MODE_BLOCK_CBC = 0x00000004, /** * \~english CFB symmetric cipher mode */ SYMMETRIC_CIPHER_MODE_BLOCK_CFB = 0x00000008, /** * \~english OFB symmetric cipher mode */ SYMMETRIC_CIPHER_MODE_BLOCK_OFB = 0x00000010 }; /** * \~english Symmetric cipher Block Size */ enum SymmetricCipherBlockSize { /** * \~english Symmetric cipher block size is 4 bytes */ SYMMETRIC_CIPHER_BLOCK_SIZE_4 = 0x00000001, /** * \~english Symmetric cipher block size is 8 bytes */ SYMMETRIC_CIPHER_BLOCK_SIZE_8 = 0x00000002, /** * \~english Symmetric cipher block size is 16 bytes */ SYMMETRIC_CIPHER_BLOCK_SIZE_16 = 0x00000004, /** * \~english Symmetric cipher block size is 32 bytes */ SYMMETRIC_CIPHER_BLOCK_SIZE_32 = 0x00000008 }; /** * \~english Symmetric Cipher Round */ enum SymmetricCipherRound { /** * \~english Symmetric cipher round is 1 */ SYMMETRIC_CIPHER_ROUND_1 = 0x00000001, /** * \~english Symmetric cipher round is 2 */ SYMMETRIC_CIPHER_ROUND_2 = 0x00000002, /** * \~english Symmetric cipher round is 8.5 */ SYMMETRIC_CIPHER_ROUND_8_5 = 0x00000004, /** * \~english Symmetric cipher round is 10 */ SYMMETRIC_CIPHER_ROUND_10 = 0x00000008, /** * \~english Symmetric cipher round is 12 */ SYMMETRIC_CIPHER_ROUND_12 = 0x00000010, /** * \~english Symmetric cipher round is 14 */ SYMMETRIC_CIPHER_ROUND_14 = 0x00000020, /** * \~english Symmetric cipher round is 16 */ SYMMETRIC_CIPHER_ROUND_16 = 0x00000040 }; /** * \~english Asymmetric Padding Mode */ enum AsymmetricPaddingMode { /** * \~english RSA PKCS1 asymmetric padding mode */ ASYMMETRIC_PADDING_MODE_RSA_PKCS1 = 1, /** * \~english RSA SSLV23 asymmetric padding mode */ ASYMMETRIC_PADDING_MODE_RSA_SSLV23, /** * \~english RSA NOPADDING asymmetric padding mode */ ASYMMETRIC_PADDING_MODE_RSA_NOPADDING, /** * \~english RSA OAEP asymmetric padding mode */ ASYMMETRIC_PADDING_MODE_RSA_OAEP, /** * \~english RSA PSS asymmetric padding mode */ ASYMMETRIC_PADDING_MODE_RSA_PSS }; /** * @union CipherParameter * \~english @par Brief * Union of cipher parameter */ union CipherParameter { /** * \~english Struct of symmetric cipher parameter */ struct SymmetricCipherParameter { /** * \~english Symmetric cipher mode */ enum SymmetricCipherMode mode; /** * \~english Symmetric cipher block size */ enum SymmetricCipherBlockSize block_size; /** * \~english Symmetric cipher round */ enum SymmetricCipherRound round; /** * \~english Padding ON/OFF. Only used in CBC mode and ECB mode. * Padding ON : * Encrypt: * 1.If plaintext length isn't aligned with block size, the * ciphertext length is aligned with block size. * 2.If plaintext length is aligned with block size, the * ciphertext length is equal to plaintext length + 1 block size. * Decrypt: * 1.If ciphertext length isn't aligned with block size, return error. * 2.If ciphertext length is aligned with block size, plaintext length * is equal to ciphertext length minus padding length. Padding length * is greater than 0 and not greater than block size. * Padding OFF: * Encrypt: * 1.If plaintext length isn't aligned with block size, return error. * 2.If plaintext length is aligned with block size, the * ciphertext length is equal to plaintext length. * Decrypt: * 1.If ciphertext length isn't aligned with block size, return error. * 2.If ciphertext length is aligned with block size, the * plaintext length is equal to ciphertext length. */ bool to_pad; } symmetric; /** * \~english Struct of asymmetric cipher parameter */ struct AsymmetricCipherParameter { /** * \~english Asymmetric padding mode */ enum AsymmetricPaddingMode mode; } asymmetric; }; /** * \~english Symmetric cipher key type */ enum SymmetricCipherKeyType { /** * \~english Key is managed by hardware/chip */ SYMMETRIC_CIPHER_KEY_TYPE_MANAGED, /** * \~english Key is provided by user */ SYMMETRIC_CIPHER_KEY_TYPE_USER }; /** * @struct RsaPrivateKey * \~english @par Brief * Struct of RSA private key */ struct RsaPrivateKey { /** * \~english Private exponent */ uint8_t d[RSA_PRIVATE_EXPONENT_MAX_SIZE]; /** * \~english Modulus */ uint8_t n[RSA_MODULUS_MAX_SIZE]; /** * \~english The length of private exponent */ uint32_t d_length; /** * \~english The length of modulus */ uint32_t n_length; }; /** * @union PrivateKey * \~english @par Brief * Union of private key */ union PrivateKey { /** * \~english Rsa private key */ struct RsaPrivateKey rsa; }; /** * @struct RsaPublicKey * \~english @par Brief * Union of RSA public key */ struct RsaPublicKey { /** * \~english Public exponent */ uint8_t e[RSA_PUBLIC_EXPONENT_MAX_SIZE]; /** * \~english Modulus */ uint8_t n[RSA_MODULUS_MAX_SIZE]; /** * \~english The length of public exponent */ uint32_t e_length; /** * \~english The length of modulus */ uint32_t n_length; }; /** * @union PublicKey * \~english @par Brief * Union of public key */ union PublicKey { /** * \~english Struct of rsa public key */ struct RsaPublicKey rsa; }; /** * \~english Asymmetric cipher key type */ enum AsymmetricCipherKeyType { /** * \~english Key is managed by hardware/chip */ ASYMMETRIC_CIPHER_KEY_TYPE_MANAGED, /** * \~english Public key is provided by user */ ASYMMETRIC_CIPHER_KEY_TYPE_USER_PUBLIC, /** * \~english Private key is provided by user */ ASYMMETRIC_CIPHER_KEY_TYPE_USER_PRIVATE }; /** * @union KeyParam * \~english @par Brief * Union of key parameter */ union KeyParam { /** * \~english Struct of symmetric key paramater */ struct SymmetricKeyParam { /** * \~english Symmetric cipher key type */ enum SymmetricCipherKeyType key_type; /** * \~english Union of symmetric key parameter */ union { /** * \~english The symmetric key index */ uint32_t managed_key_index; /** * \~english Struct of user key */ struct { /** * \~english Key source */ uint8_t* key; /** * \~english Key length */ uint32_t key_len; /** * \~english Key Initialization vector. */ uint8_t* iv; /** * \~english Initialization vector length.The length should be * equal to block size, otherwise return error. */ uint32_t iv_len; } user_key; } key_param; } symmetric; /** * \~english Struct of asymmetric key parameter */ struct AsymmetricKeyParam { /** * \~english Asymmetric cipher key type */ enum AsymmetricCipherKeyType key_type; /** * \~english Union of asymmetric key parameter */ union { /** * \~english The asymmetric key index */ uint32_t managed_key_index; /** * \~english Union of user key */ union { /** * \~english Public key */ union PublicKey* public_key; /** * \~english Private key */ union PrivateKey* private_key; } user_key; } key_param; } asymmetric; }; /** * \~english hash type */ enum HashType { /** * \~english hash type is md5 */ HASH_TYPE_MD5 = 1, /** * \~english hash type is sha1 */ HASH_TYPE_SHA1, /** * \~english hash type is sha224 */ HASH_TYPE_SHA224, /** * \~english hash type is sha256 */ HASH_TYPE_SHA256, /** * \~english hash type is sha384 */ HASH_TYPE_SHA384, /** * \~english hash type is sha512 */ HASH_TYPE_SHA512 }; /** * \ingroup EncryptStart * \~english @par Brief * Initialize the encrypt context information. * \~english @param [in] cipher_type * enum CipherType - Cipher type. * \~english @param [in] param * union CipherParameter* - Cipher parameter * \~english @param [in] key * union KeyParam* - Key parameter * \~english @param [out] ctx * void** - The encrypt information context handle. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize * fail or hardware I/O operation fail or * hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - None. * \~english @par Change of internal state * - Change of internal state according to the API does not occur. * \~english @par Conditions of processing failure * - If the parameter "cipher_type" is less than SYMMETRIC_CIPHER_AES * or greater than ASYMMETRIC_CIPHER_ECDSA [eFrameworkunifiedStatusInvldParam] * - If the parameter "param" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "key" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle initialize failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Initialize the encrypt context information according to cipher type, * cipher parameter and key parameter. * - If EncryptStart() was called successfully, EncryptCleanup() should * be called to clean up encrypt context information. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * EncryptUpdate, EncryptFinish, EncryptCleanup */ EFrameworkunifiedStatus EncryptStart(enum CipherType cipher_type, union CipherParameter* param, union KeyParam* key, void** ctx); /** * \ingroup EncryptUpdate * \~english @par Brief * Encrypt plaintext information. * \~english @param [in] ctx * void* - The encrypt information context handle. * \~english @param [in] in * const uint8_t* - The plaintext to be encrypted. * \~english @param [in] in_len * uint32_t - The input buffer length * in_len shall be greater than 0 for symmetric encrypt. * in_len shall be greater than 0 and not greater than * RSA_PRIVATE_EXPONENT_MAX_SIZE/8 - RSA_PADDING_MINIMUM_SIZE * for RSA asymmetric encrypt. * \~english @param [out] out * uint8_t* - The ciphertext after plaintext had been encrypted. * \~english @param [in] out_len * uint32_t - The output buffer length. * out_len shall not be less than in_len + 1 block size for symmetric encrypt. * out_len shall not be less than RSA_PRIVATE_EXPONENT_MAX_SIZE/8 for RSA asymmetric encrypt. * \~english @param [out] true_length * uint32_t* - The ciphertext length. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail, hardware I/O operation fail, * hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - EncryptStart() was called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "in" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "in_len" is 0 for symmetric encrypt[eFrameworkunifiedStatusInvldParam] * - If the parameter "in_len" is 0 or greater than * RSA_PRIVATE_EXPONENT_MAX_SIZE/8 - RSA_PADDING_MINIMUM_SIZE for RSA asymmetric encrypt[eFrameworkunifiedStatusInvldParam] * - If the parameter "out is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out_len" is less than in_len + 1 block size * for symmetric encrypt [eFrameworkunifiedStatusInvldParam] * - If the parameter "out_len" is less than RSA_PRIVATE_EXPONENT_MAX_SIZE/8 * for RSA asymmetric encrypt [eFrameworkunifiedStatusInvldParam] * - If the parameter "true_length" is NULL [eFrameworkunifiedStatusFail] * - If the hardware/handle init failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Update the plaintext to ciphertext by symmetric or asymmetric encrypt algorithm. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * EncryptStart, EncryptFinish, EncryptCleanup */ EFrameworkunifiedStatus EncryptUpdate(void* ctx, const uint8_t* in, uint32_t in_len, uint8_t* out, uint32_t out_len, uint32_t* true_length); /** * \ingroup EncryptFinish * \~english @par Brief * Encrypt the final plaintext information. * \~english @param [in] ctx * void* - The encrypt information context handle. * \~english @param [out] out * uint8_t* - The ciphertext after plaintext had been encrypted. * out is useless for RSA asymmetric encrypt. * \~english @param [in] out_len * uint32_t - The final output buffer length. * out_len shall not be less than 1 block size for symmetric encrypt. * out_len is useless for RSA asymmetric encrypt. * \~english @param [out] true_length * uint32_t* - The ciphertext length. * true_length is useless for RSA asymmetric encrypt. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail, hardware I/O operation fail, * hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - EncryptStart() and EncryptUpdate() were called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out_len" is less than 1 block size * for symmetric encrypt [eFrameworkunifiedStatusInvldParam] * - If the parameter "true_length" is NULL [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle init failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Update the final plaintext to ciphertext for symmetric encrypt and do nothing for asymmetric encrypt. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * EncryptStart, EncryptUpdate, EncryptCleanup */ EFrameworkunifiedStatus EncryptFinish(void* ctx, uint8_t* out, uint32_t out_len, uint32_t* true_length); /** * \ingroup EncryptCleanup * \~english @par Brief * Clean up encrypt context information. * \~english @param [in] ctx * void* - The encrypt information context handle. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - EncryptStart() was called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * \~english @par Detail * - Clean up encrypt context information. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * EncryptStart, EncryptUpdate, EncryptFinish */ EFrameworkunifiedStatus EncryptCleanup(void* ctx); /** * \ingroup DecryptStart * \~english @par Brief * Initialize the decrypt context information. * \~english @param [in] cipher_type * enum CipherType - Cipher type. * \~english @param [in] param * union CipherParameter* - Cipher parameter * \~english @param [in] key * union KeyParam* - Key parameter * \~english @param [out] ctx * void** - The decrypt information context handle. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail or hardware I/O * operation fail or hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - None. * \~english @par Change of internal state * - Change of internal state according to the API does not occur. * \~english @par Conditions of processing failure * - If the parameter "cipher_type" is less than SYMMETRIC_CIPHER_AES * or greater than ASYMMETRIC_CIPHER_ECDSA [eFrameworkunifiedStatusInvldParam] * - If the parameter "param" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "key" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle initialize failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Initialize the decrypt context information according to cipher type, cipher parameter and key parameter. * - If DecryptStart() was called successfully, DecryptCleanup() should be called * to clean up decrypt context information. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * DecryptUpdate, DecryptFinish, DecryptCleanup */ EFrameworkunifiedStatus DecryptStart(enum CipherType cipher_type, union CipherParameter* param, union KeyParam *key, void** ctx); /** * \ingroup DecryptUpdate * \~english @par Brief * Decrypt ciphertext information. * \~english @param [in] ctx * void* - The decrypt information context handle. * \~english @param [in] in * const uint8_t* - The ciphertext to be decrypted. * \~english @param [in] in_len * uint32_t - The input buffer length * in_len shall be greater than 0 for symmetric decrypt. * in_len shall be equal to RSA_PRIVATE_EXPONENT_MAX_SIZE/8 * for RSA asymmetric decrypt. * \~english @param [out] out * uint8_t* - The plaintext after ciphertext had been decrypted. * \~english @param [in] out_len * uint32_t - The output buffer length. * out_len shall not be less than in_len + 1 block size for symmetric decrypt. * out_len shall not be less than RSA_PRIVATE_EXPONENT_MAX_SIZE/8 - RSA_PADDING_MINIMUM_SIZE * for RSA asymmetric decrypt. * \~english @param [out] true_length * uint32_t* - The plaintext length. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail, hardware I/O operation fail, * hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - DecryptStart() was called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "in" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "in_len" is 0 for symmetric decrypt [eFrameworkunifiedStatusInvldParam] * - If the parameter "in_len" isn't equal to * RSA_PRIVATE_EXPONENT_MAX_SIZE/8 for RSA asymmetric decrypt [eFrameworkunifiedStatusInvldParam] * - If the parameter "out is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out_len" is less than in_len * for symmetric decrypt [eFrameworkunifiedStatusInvldParam] * - If the parameter "out_len" is less than RSA_PRIVATE_EXPONENT_MAX_SIZE/8 - RSA_PADDING_MINIMUM_SIZE * for RSA asymmetric decrypt [eFrameworkunifiedStatusInvldParam] * - If the parameter "true_length" is NULL [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle init failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Update the ciphertext to plaintext by symmetric or asymmetric decrypt algorithm. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * DecryptStart, DecryptFinish, DecryptCleanup */ EFrameworkunifiedStatus DecryptUpdate(void* ctx, const uint8_t* in, uint32_t in_len, uint8_t* out, uint32_t out_len, uint32_t* true_length); /** * \ingroup DecryptFinish * \~english @par Brief * Decrypt the final ciphertext information. * \~english @param [in] ctx * void* - The decrypt information context handle. * \~english @param [out] out * uint8_t* - The plaintext after ciphertext had been decrypted. * out is useless for RSA asymmetric decrypt. * \~english @param [in] out_len * uint32_t - The final output buffer length. * out_len shall not be less than 1 block size for symmetric decrypt. * out_len is useless for RSA asymmetric decrypt. * \~english @param [out] true_length * uint32_t* - The plaintext length. * true_length is useless for RSA asymmetric decrypt. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail, hardware I/O operation fail, * hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - DecryptStart() and DecryptUpdate() were called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out_len" is less than 1 block size * for symmetric decrypt [eFrameworkunifiedStatusInvldParam] * - If the parameter "true_length" is NULL [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle init failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Update the final ciphertext to plaintext for symmetric decrypt and do nothing for asymmetric decrypt. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * DecryptStart, DecryptUpdate, DecryptCleanup */ EFrameworkunifiedStatus DecryptFinish(void* ctx, uint8_t* out, uint32_t out_len, uint32_t* true_length); /** * \ingroup DecryptCleanup * \~english @par Brief * Clean up decrypt context information. * \~english @param [in] ctx * void* - The decrypt information context handle. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - DecryptStart() was called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * \~english @par Detail * - Clean up decrypt context information. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * DecryptStart, DecryptUpdate, DecryptFinish */ EFrameworkunifiedStatus DecryptCleanup(void* ctx); /** * \ingroup HashStart * \~english @par Brief * Initialize hash context information. * \~english @param [in] hash_type * enum HashType - Hash type. * \~english @param [out] ctx * void** - The hash information context handle. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail or hardware I/O operation * fail or hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - None. * \~english @par Change of internal state * - Change of internal state according to the API does not occur. * \~english @par Conditions of processing failure * - If the parameter "hash_type" less than HASH_TYPE_MD5 * or greater than HASH_TYPE_SHA512 [eFrameworkunifiedStatusInvldParam] * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle initialize failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Initialize hash context information according to hash type. * - If HashStart() was called successfully, HashCleanup() should be called * to clean up hash context information. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * HashUpdate, HashFinish, HashCleanup */ EFrameworkunifiedStatus HashStart(enum HashType hash_type, void** ctx); /** * \ingroup HashUpdate * \~english @par Brief * Caculate hash value of input data. * \~english @param [in] ctx * void* - The hash information context handle. * \~english @param [in] in * const uint8_t* - The input data to be hashed. * \~english @param [in] in_len * uint32_t - The input buffer length * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail, hardware I/O operation fail, * hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - HashStart() was called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "in" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "in_len" is 0 [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle init failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Caculate hash value of input data. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * HashStart, HashFinish, HashCleanup */ EFrameworkunifiedStatus HashUpdate(void* ctx, const uint8_t* in, uint32_t in_len); /** * \ingroup HashFinish * \~english @par Brief * Caculate final message digest. * \~english @param [in] ctx * void* - The hash information context handle. * \~english @param [out] out * uint8_t* - The message digest after all input data had been hashed. * \~english @param [in] out_len * uint32_t - The output buffer length. * \~english @param [out] true_length * uint32_t* - The message digest length. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail, hardware I/O operation fail, * hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - HashStart() and HashUpdate() were called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out_len" is 0 [eFrameworkunifiedStatusInvldParam] * - If the parameter "true_length" is NULL [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle init failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Caculate final message digest. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * HashStart, HashUpdate, HashCleanup */ EFrameworkunifiedStatus HashFinish(void* ctx, uint8_t* out, uint32_t out_len, uint32_t* true_length); /** * \ingroup HashCleanup * \~english @par Brief * Clean up hash context information. * \~english @param [in] ctx * void* - The hash information context handle. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - HashStart() was called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * \~english @par Detail * - Clean up hash context information. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * HashStart, HashUpdate, HashFinish */ EFrameworkunifiedStatus HashCleanup(void* ctx); /** * \ingroup RandomInit * \~english @par Brief * Initialize random number context information. * \~english @param [out] ctx * void** - The random number information context handle. * \~english @param [in] seed_buffer * uint8_t* - The random number seed buffer. * \~english @param [in] buffer_len * uint32_t - The random number seed buffer length. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail or hardware I/O operation * fail or hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - None. * \~english @par Change of internal state * - Change of internal state according to the API does not occur. * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "seed_buffer" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "buffer_len" is 0 [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle initialize failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Initialize random number context information according to random number seed. * - If RandomInit() was called successfully, RandomCleanup() should be called to * clean up random number context information. If RandomInit() was called faild, * RandomCleanup() must not be called. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * RandomGet, RandomCleanup */ EFrameworkunifiedStatus RandomInit(void** ctx, uint8_t* seed_buffer, uint32_t buffer_len); /** * \ingroup RandomGet * \~english @par Brief * Get random number. * \~english @param [in] ctx * void* - The random number information context handle. * \~english @param [out] out * uint8_t* - The random number that caculated by random number seed. * \~english @param [in] out_len * uint32_t - The output buffer length. * \~english @param [out] true_length * uint32_t* - The random number length. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware/handle initialize fail, hardware I/O operation fail, * hardware device busy or allocate context handle fail. * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - RandomInit() was called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out" is NULL [eFrameworkunifiedStatusInvldParam] * - If the parameter "out_len" is 0 [eFrameworkunifiedStatusInvldParam] * - If the parameter "true_length" is NULL [eFrameworkunifiedStatusInvldParam] * - If the hardware/handle init failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * - If ctx can not be allocated [eFrameworkunifiedStatusFail] * \~english @par Detail * - Get random number. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * RandomInit, RandomCleanup */ EFrameworkunifiedStatus RandomGet(void* ctx, uint8_t* out, uint32_t out_len, uint32_t* true_length); /** * \ingroup RandomCleanup * \~english @par Brief * Clean up random number context information. * \~english @param [in] ctx * void* - The random number information context handle. * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusInvldParam : indicates parameter error. * \~english @par Prerequisite * - RandomInit() was called successfully. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the parameter "ctx" is NULL [eFrameworkunifiedStatusInvldParam] * \~english @par Detail * - Clean up random number context information. * - The API can be used by multiple processes. * \~english @par Classification * Public * \~english @par Type * Sync * \~english @see * RandomInit, RandomGet */ EFrameworkunifiedStatus RandomCleanup(void* ctx); /** * \ingroup ResetSecurityIC * \~english @par Brief * Security IC Reset. * \~english @param none * \~english @retval eFrameworkunifiedStatusOK : indicates success * \~english @retval eFrameworkunifiedStatusFail : indicates the hardware initialize fail, hardware I/O operation fail, * hardware device busy. * \~english @par Prerequisite * - None. * \~english @par Change of internal state * - Change of internal state according to the API does not occur * \~english @par Conditions of processing failure * - If the hardware initialize failed [eFrameworkunifiedStatusFail] * - If the hardware I/O operation failed [eFrameworkunifiedStatusFail] * - If the hardware device is busy [eFrameworkunifiedStatusFail] * \~english @par Classification * Public * \~english @par Type * Sync * \~english @par Detail * - Security IC Reset. * - The API can be used by multiple processes. * - This API does not cleanup context information when EncryptStart(), DecryptStart() or HashStart() is successfull. * Use EncryptCleanup(), DecryptCleanup() or RandomCleanup() to cleanup context information. * \~english @see * None */ EFrameworkunifiedStatus ResetSecurityIC(void); /** @}*/ // end of security_hal /** @}*/ // end of update_service #endif // HAL_API_SECURITY_HAL_H_