From: Jakub Wlostowski Date: Fri, 23 May 2025 08:31:38 +0000 (+0200) Subject: Update security-keys API comments X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;ds=sidebyside;p=platform%2Fhal%2Fapi%2Fsecurity.git Update security-keys API comments Change-Id: I267cabe16a86d99241c5b24f95d61cacec97e57b --- diff --git a/doc/hal_security_keys_doc.h b/doc/hal_security_keys_doc.h index c1a8ee9..ed1e70e 100644 --- a/doc/hal_security_keys_doc.h +++ b/doc/hal_security_keys_doc.h @@ -36,7 +36,7 @@ * The Security Keys provides functions to handle keys and data related operations * * The Security Keys functions provide methods to: - * - Create IV + * - Create initialization vector * - Create/Destroy keys (AES, RSA, DSA, ECDSA, KEM) * - Import/Export wrapped keys * - Encapsulate/Decapsulate KEM keys diff --git a/include/hal-security-keys-interface-1.h b/include/hal-security-keys-interface-1.h index 1eeb8c6..3b4f982 100644 --- a/include/hal-security-keys-interface-1.h +++ b/include/hal-security-keys-interface-1.h @@ -43,7 +43,7 @@ typedef struct _hal_backend_security_keys_funcs { /** Free HAL backend context */ int (*context_free)(hal_security_keys_context_s* context); - /** Create IV */ + /** Create initialization vector */ int (*create_iv)(const hal_security_keys_context_s context, hal_security_keys_data_s* iv); diff --git a/include/hal-security-keys-types.h b/include/hal-security-keys-types.h index 7d600bd..2c74193 100644 --- a/include/hal-security-keys-types.h +++ b/include/hal-security-keys-types.h @@ -59,7 +59,7 @@ typedef struct { */ typedef struct { hal_security_keys_data_s password; /**< Password buffer */ - hal_security_keys_data_s iv; /**< IV buffer */ + hal_security_keys_data_s iv; /**< Initialization vector buffer */ } hal_security_keys_password_iv_s; /** @@ -68,7 +68,7 @@ typedef struct { */ typedef struct { hal_security_keys_data_s password; /**< Password buffer */ - hal_security_keys_data_s iv; /**< IV buffer */ + hal_security_keys_data_s iv; /**< Initialization vector buffer */ hal_security_keys_data_s tag; /**< Tag buffer */ } hal_security_keys_password_iv_tag_s; diff --git a/include/hal-security-keys.h b/include/hal-security-keys.h index 170fc55..74be5ed 100644 --- a/include/hal-security-keys.h +++ b/include/hal-security-keys.h @@ -26,21 +26,114 @@ extern "C" { #endif +/** + * @addtogroup HALAPI_HAL_SECURITY_KEYS_MODULE + * @{ + */ + +/** + * @brief Gets the security keys backend + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @see hal_security_keys_put_backend() + */ int hal_security_keys_get_backend(void); + +/** + * @brief Puts the security keys backend + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @see hal_security_keys_get_backend() + */ int hal_security_keys_put_backend(void); +/** + * @brief Initializes the security keys context + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[out] context Security keys context handle + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @see hal_security_keys_context_free() + */ int hal_security_keys_context_initialize(hal_security_keys_context_s* context); + +/** + * @brief Frees the security keys context + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @see hal_security_keys_context_initialize() + */ int hal_security_keys_context_free(hal_security_keys_context_s* context); +/** + * @brief Creates new initialization vector + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[out] iv Initialization vector + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_create_iv(const hal_security_keys_context_s context, hal_security_keys_data_s* iv); +/** + * @brief Creates new AES key + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] key_size_bits Key size in bits + * @param[in] key_id Key id + * @param[in] key_pwd Key password and initialization vector + * @param[out] key_tag Key tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_create_key_aes(const hal_security_keys_context_s context, const size_t key_size_bits, const hal_security_keys_data_s key_id, const hal_security_keys_password_iv_s key_pwd, hal_security_keys_data_s* key_tag); +/** + * @brief Creates new RSA key pair + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] key_size_bits Key size in bits + * @param[in] priv_key_id Private key id + * @param[in] priv_key_pwd Private key password and initialization vector + * @param[in] pub_key_id Public key id + * @param[in] pub_key_pwd Public key password and initialization vector + * @param[out] priv_key_tag Private key tag + * @param[out] pub_key_tag Public key tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_create_key_pair_rsa(const hal_security_keys_context_s context, const size_t key_size_bits, const hal_security_keys_data_s priv_key_id, @@ -50,6 +143,28 @@ int hal_security_keys_create_key_pair_rsa(const hal_security_keys_context_s cont hal_security_keys_data_s* priv_key_tag, hal_security_keys_data_s* pub_key_tag); +/** + * @brief Creates new DSA key pair + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] key_size_bits Key size in bits + * @param[in] prime Prime attribute + * @param[in] subprime Subprime attribute + * @param[in] base Base attribute + * @param[in] priv_key_id Private key id + * @param[in] priv_key_pwd Private key password and initialization vector + * @param[in] pub_key_id Public key id + * @param[in] pub_key_pwd Public key password and initialization vector + * @param[out] priv_key_tag Private key tag + * @param[out] pub_key_tag Public key tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_create_key_pair_dsa(const hal_security_keys_context_s context, const size_t key_size_bits, const hal_security_keys_data_s prime, @@ -62,6 +177,25 @@ int hal_security_keys_create_key_pair_dsa(const hal_security_keys_context_s cont hal_security_keys_data_s* priv_key_tag, hal_security_keys_data_s* pub_key_tag); +/** + * @brief Creates new ECDSA key pair + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] ec_type Elliptic curve type + * @param[in] priv_key_id Private key id + * @param[in] priv_key_pwd Private key password and initialization vector + * @param[in] pub_key_id Public key id + * @param[in] pub_key_pwd Public key password and initialization vector + * @param[out] priv_key_tag Private key tag + * @param[out] pub_key_tag Public key tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_create_key_pair_ecdsa(const hal_security_keys_context_s context, const hal_security_keys_ec_type_e ec_type, const hal_security_keys_data_s priv_key_id, @@ -71,6 +205,25 @@ int hal_security_keys_create_key_pair_ecdsa(const hal_security_keys_context_s co hal_security_keys_data_s* priv_key_tag, hal_security_keys_data_s* pub_key_tag); +/** + * @brief Creates new KEM key pair + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] kem_type KEM type + * @param[in] priv_key_id Private key id + * @param[in] priv_key_pwd Private key password and initialization vector + * @param[in] pub_key_id Public key id + * @param[in] pub_key_pwd Public key password and initialization vector + * @param[out] priv_key_tag Private key tag + * @param[out] pub_key_tag Public key tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_create_key_pair_kem(const hal_security_keys_context_s context, const hal_security_keys_kem_type_e kem_type, const hal_security_keys_data_s priv_key_id, @@ -80,6 +233,30 @@ int hal_security_keys_create_key_pair_kem(const hal_security_keys_context_s cont hal_security_keys_data_s* priv_key_tag, hal_security_keys_data_s* pub_key_tag); +/** + * @brief Imports wrapped key + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] algo Algorithm type + * @param[in] hash Hash type + * @param[in] iv Initialization vector + * @param[in] aad Additional authentication data + * @param[in] ctr_len_or_tag_size_bits Counter length or tag size in bits + * @param[in] wrapping_key_id Wrapping key id + * @param[in] wrapping_key_pwd Wrapping key password, initialization vector and tag + * @param[in] wrapped_key Wrapped key + * @param[in] key_id Key id + * @param[in] key_pwd Key password and initialization vector + * @param[in] key_type Key type + * @param[out] key_tag Key tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_import_wrapped_key(const hal_security_keys_context_s context, const hal_security_keys_algo_type_e algo, const hal_security_keys_hash_algorithm_e hash, @@ -94,6 +271,29 @@ int hal_security_keys_import_wrapped_key(const hal_security_keys_context_s conte const hal_security_keys_data_type_e key_type, hal_security_keys_data_s* key_tag); +/** + * @brief Exports wrapped key + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] algo Algorithm type + * @param[in] hash Hash type + * @param[in] iv Initialization vector + * @param[in] aad Additional authentication data + * @param[in] ctr_len_or_tag_size_bits Counter length or tag size in bits + * @param[in] wrapping_key_id Wrapping key id + * @param[in] wrapping_key_pwd Wrapping key password, initialization vector and tag + * @param[in] key_id Key id + * @param[in] key_pwd Key password, initialization vector and tag + * @param[in] key_type Key type + * @param[out] wrapped_key Wrapped key + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_export_wrapped_key(const hal_security_keys_context_s context, const hal_security_keys_algo_type_e algo, const hal_security_keys_hash_algorithm_e hash, @@ -107,6 +307,27 @@ int hal_security_keys_export_wrapped_key(const hal_security_keys_context_s conte const hal_security_keys_data_type_e key_type, hal_security_keys_data_s* wrapped_key); +/** + * @brief Encapsulates key + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] kem_type KEM algorithm type + * @param[in] pub_key_id Public key id + * @param[in] pub_key_pwd Public key password, initialization vector and tag + * @param[in] shared_secret_id Shared secret id + * @param[in] shared_secret_pwd Shared secret password and initialization vector + * @param[out] ciphertext Ciphertext + * @param[out] shared_secret_tag Shared secret tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_create_key_pair_kem() + * @see hal_security_keys_decapsulate_key() + */ int hal_security_keys_encapsulate_key(const hal_security_keys_context_s context, const hal_security_keys_kem_type_e kem_type, const hal_security_keys_data_s pub_key_id, @@ -116,6 +337,27 @@ int hal_security_keys_encapsulate_key(const hal_security_keys_context_s context, hal_security_keys_data_s* ciphertext, hal_security_keys_data_s* shared_secret_tag); +/** + * @brief Decapsulates key + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] kem_type KEM algorithm type + * @param[in] priv_key_id Private key id + * @param[in] priv_key_pwd Private key password, initialization vector and tag + * @param[in] shared_secret_id Shared secret id + * @param[in] shared_secret_pwd Shared secret password and initialization vector + * @param[in] ciphertext Ciphertext + * @param[out] shared_secret_tag Shared secret tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_create_key_pair_kem() + * @see hal_security_keys_encapsulate_key() + */ int hal_security_keys_decapsulate_key(const hal_security_keys_context_s context, const hal_security_keys_kem_type_e kem_type, const hal_security_keys_data_s priv_key_id, @@ -125,9 +367,42 @@ int hal_security_keys_decapsulate_key(const hal_security_keys_context_s context, const hal_security_keys_data_s ciphertext, hal_security_keys_data_s* shared_secret_tag); +/** + * @brief Destroys key + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] key_id Key id + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_destroy_key(const hal_security_keys_context_s context, const hal_security_keys_data_s key_id); +/** + * @brief Imports data + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] data_id Data id + * @param[in] data_pwd Data password and initialization vector + * @param[in] data_type Data type + * @param[in] data Data + * @param[in] data_encryption_iv Data encryption initialization vector + * @param[in] data_encryption_tag Data encryption tag + * @param[out] data_tag Data tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_export_data() + */ int hal_security_keys_import_data(const hal_security_keys_context_s context, const hal_security_keys_data_s data_id, const hal_security_keys_password_iv_s data_pwd, @@ -137,12 +412,50 @@ int hal_security_keys_import_data(const hal_security_keys_context_s context, const hal_security_keys_data_s data_encryption_tag, hal_security_keys_data_s* data_tag); +/** + * @brief Exports data + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] data_id Data id + * @param[in] data_pwd Data password, initialization vector and tag + * @param[in] data_type Data type + * @param[out] data Data + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_import_data() + */ int hal_security_keys_export_data(const hal_security_keys_context_s context, const hal_security_keys_data_s data_id, const hal_security_keys_password_iv_tag_s data_pwd, const hal_security_keys_data_type_e data_type, hal_security_keys_data_s* data); +/** + * @brief Wraps concatenated data + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] algo Algorithm type + * @param[in] hash Hash type + * @param[in] wrapping_key_id Wrapping key id + * @param[in] wrapping_key_pwd Wrapping key password, initialization vector and tag + * @param[in] key_id Key id + * @param[in] key_pwd Key password, initialization vector and tag + * @param[in] data Data + * @param[out] wrapped_key Wrapped key + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_unwrap_concatenated_data() + */ int hal_security_keys_wrap_concatenated_data(const hal_security_keys_context_s context, const hal_security_keys_algo_type_e algo, const hal_security_keys_hash_algorithm_e hash, @@ -153,6 +466,30 @@ int hal_security_keys_wrap_concatenated_data(const hal_security_keys_context_s c const hal_security_keys_data_s data, hal_security_keys_data_s* wrapped_key); +/** + * @brief Unwraps concatenated data + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] algo Algorithm type + * @param[in] hash Hash type + * @param[in] wrapping_key_id Wrapping key id + * @param[in] wrapping_key_pwd Wrapping key password, initialization vector and tag + * @param[in] wrapped_key Wrapped key + * @param[in] key_id Key id + * @param[in] key_pwd Key password and initialization vector + * @param[in] key_type Key type + * @param[in] key_size_bits Key size in bits + * @param[out] data Data + * @param[out] key_tag Key tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_wrap_concatenated_data() + */ int hal_security_keys_unwrap_concatenated_data(const hal_security_keys_context_s context, const hal_security_keys_algo_type_e algo, const hal_security_keys_hash_algorithm_e hash, @@ -166,6 +503,27 @@ int hal_security_keys_unwrap_concatenated_data(const hal_security_keys_context_s hal_security_keys_data_s* data, hal_security_keys_data_s* key_tag); +/** + * @brief Encrypts data with authentication + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] key_id Key id + * @param[in] key_pwd Key password, initialization vector and tag + * @param[in] data Data to encrypt + * @param[in] iv Initialization vector + * @param[in] aad Additional authentication data + * @param[in] tag_size_bits Tag size in bits + * @param[out] tag Tag + * @param[out] out Encrypted data + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_decrypt_data_auth() + */ int hal_security_keys_encrypt_data_auth(const hal_security_keys_context_s context, const hal_security_keys_data_s key_id, const hal_security_keys_password_iv_tag_s key_pwd, @@ -176,6 +534,27 @@ int hal_security_keys_encrypt_data_auth(const hal_security_keys_context_s contex hal_security_keys_data_s* tag, hal_security_keys_data_s* out); +/** + * @brief Decrypts data with authentication + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] key_id Key id + * @param[in] key_pwd Key password, initialization vector and tag + * @param[in] data Data to decrypt + * @param[in] iv Initialization vector + * @param[in] aad Additional authentication data + * @param[in] tag_size_bits Tag size in bits + * @param[in] tag Tag + * @param[out] out Decrypted data + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_encrypt_data_auth() + */ int hal_security_keys_decrypt_data_auth(const hal_security_keys_context_s context, const hal_security_keys_data_s key_id, const hal_security_keys_password_iv_tag_s key_pwd, @@ -186,6 +565,27 @@ int hal_security_keys_decrypt_data_auth(const hal_security_keys_context_s contex const hal_security_keys_data_s tag, hal_security_keys_data_s* out); +/** + * @brief Encrypts data + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] algo Algorithm type + * @param[in] hash Hash type + * @param[in] padding Padding type + * @param[in] key_id Key id + * @param[in] key_pwd Key password, initialization vector and tag + * @param[in] data Data to encrypt + * @param[in] iv Initialization vector + * @param[out] out Encrypted data + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_decrypt_data() + */ int hal_security_keys_encrypt_data(const hal_security_keys_context_s context, const hal_security_keys_algo_type_e algo, const hal_security_keys_hash_algorithm_e hash, @@ -196,6 +596,27 @@ int hal_security_keys_encrypt_data(const hal_security_keys_context_s context, const hal_security_keys_data_s iv, hal_security_keys_data_s* out); +/** + * @brief Decrypts data + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] algo Algorithm type + * @param[in] hash Hash type + * @param[in] padding Padding type + * @param[in] key_id Key id + * @param[in] key_pwd Key password, initialization vector and tag + * @param[in] data Data to decrypt + * @param[in] iv Initialization vector + * @param[out] out Decrypted data + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_encrypt_data() + */ int hal_security_keys_decrypt_data(const hal_security_keys_context_s context, const hal_security_keys_algo_type_e algo, const hal_security_keys_hash_algorithm_e hash, @@ -206,9 +627,41 @@ int hal_security_keys_decrypt_data(const hal_security_keys_context_s context, const hal_security_keys_data_s iv, hal_security_keys_data_s* out); +/** + * @brief Destroys data + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] data_id Data id + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_destroy_data(const hal_security_keys_context_s context, const hal_security_keys_data_s data_id); +/** + * @brief Initializes cipher + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] encrypt Cipher for encryption = true / decryption = false + * @param[in] key_id Key id + * @param[in] key_pwd Key password, initialization vector and tag + * @param[in] iv Initialization vector + * @param[in] aad Additional authentication data + * @param[in] tag_size_bits Tag size in bits + * @param[out] cipher_context Initialized cipher context + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_cipher_initialize(const hal_security_keys_context_s context, const bool encrypt, const hal_security_keys_data_s key_id, @@ -218,23 +671,95 @@ int hal_security_keys_cipher_initialize(const hal_security_keys_context_s contex const size_t tag_size_bits, hal_security_keys_cipher_context_t* cipher_context); +/** + * @brief Adds AAD to cipher + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] cipher_context Cipher context + * @param[in] aad Additional authentication data + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_cipher_add_aad(const hal_security_keys_context_s context, const hal_security_keys_cipher_context_t cipher_context, const hal_security_keys_data_s aad); +/** + * @brief Updates cipher with data + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] cipher_context Cipher context + * @param[in] data Data + * @param[out] out Output data + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_cipher_update(const hal_security_keys_context_s context, const hal_security_keys_cipher_context_t cipher_context, const hal_security_keys_data_s data, hal_security_keys_data_s* out); +/** + * @brief Finalizes cipher + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] cipher_context Cipher context + * @param[in] data Data + * @param[out] out Output data + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_cipher_finalize(const hal_security_keys_context_s context, const hal_security_keys_cipher_context_t cipher_context, const hal_security_keys_data_s data, hal_security_keys_data_s* out); +/** + * @brief Frees cipher context + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] cipher_context Cipher context + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + */ int hal_security_keys_cipher_free(const hal_security_keys_context_s context, const hal_security_keys_cipher_context_t cipher_context); +/** + * @brief Creates signature + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] algo Algorithm type + * @param[in] hash Hash type + * @param[in] priv_key_id Private key id + * @param[in] priv_key_pwd Private key password, initialization vector and tag + * @param[in] message Message to sign + * @param[out] signature Output signature + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_verify_signature() + */ int hal_security_keys_create_signature(const hal_security_keys_context_s context, const hal_security_keys_algo_type_e algo, const hal_security_keys_hash_algorithm_e hash, @@ -243,6 +768,26 @@ int hal_security_keys_create_signature(const hal_security_keys_context_s context const hal_security_keys_data_s message, hal_security_keys_data_s* signature); +/** + * @brief Verifies signature + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] algo Algorithm type + * @param[in] hash Hash type + * @param[in] pub_key_id Public key id + * @param[in] pub_key_pwd Public key password, initialization vector and tag + * @param[in] message Message to verify + * @param[in] signature Signature + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_VERIFICATION_FAILED Signature verification failed + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + * @see hal_security_keys_create_signature() + */ int hal_security_keys_verify_signature(const hal_security_keys_context_s context, const hal_security_keys_algo_type_e algo, const hal_security_keys_hash_algorithm_e hash, @@ -251,6 +796,26 @@ int hal_security_keys_verify_signature(const hal_security_keys_context_s context const hal_security_keys_data_s message, const hal_security_keys_data_s signature); +/** + * @brief Derives ECDH + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] ec_type Elliptic curve type + * @param[in] pub_key_x Public key X point + * @param[in] pub_key_y Public key Y point + * @param[in] priv_key_id Private key id + * @param[in] priv_key_pwd Private key password, initialization vector and tag + * @param[in] secret_id Secret id + * @param[in] secret_pwd Secret password and initialization vector + * @param[out] secret_tag Secret tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_derive_ecdh(const hal_security_keys_context_s context, const hal_security_keys_ec_type_e ec_type, const hal_security_keys_data_s pub_key_x, @@ -261,6 +826,24 @@ int hal_security_keys_derive_ecdh(const hal_security_keys_context_s context, const hal_security_keys_password_iv_s secret_pwd, hal_security_keys_data_s* secret_tag); +/** + * @brief Derives KBKDF + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] params KBKDF parameters + * @param[in] secret_id Secret id + * @param[in] secret_pwd Secret password, initialization vector and tag + * @param[in] key_id Key id + * @param[in] key_pwd Key password and initialization vector + * @param[out] key_tag Key tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_derive_kbkdf(const hal_security_keys_context_s context, const hal_security_keys_kbkdf_params_s params, const hal_security_keys_data_s secret_id, @@ -269,6 +852,26 @@ int hal_security_keys_derive_kbkdf(const hal_security_keys_context_s context, const hal_security_keys_password_iv_s key_pwd, hal_security_keys_data_s* key_tag); +/** + * @brief Derives hybrid KBKDF + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[in] params KBKDF parameters + * @param[in] first_secret_id First secret id + * @param[in] first_secret_pwd First secret password, initialization vector and tag + * @param[in] second_secret_id Second secret id + * @param[in] second_secret_pwd Second secret password, initialization vector and tag + * @param[in] key_id Key id + * @param[in] key_pwd Key password and initialization vector + * @param[out] key_tag Key tag + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_TARGET_DEAD Target dead + */ int hal_security_keys_derive_hybrid_kbkdf(const hal_security_keys_context_s context, const hal_security_keys_kbkdf_params_s params, const hal_security_keys_data_s first_secret_id, @@ -279,16 +882,56 @@ int hal_security_keys_derive_hybrid_kbkdf(const hal_security_keys_context_s cont const hal_security_keys_password_iv_s key_pwd, hal_security_keys_data_s* key_tag); +/** + * @brief Gets max chunk size + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] context Security keys context handle + * @param[out] chunk_size Chunk size + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + */ int hal_security_keys_get_max_chunk_size(const hal_security_keys_context_s context, size_t* chunk_size); +/** + * @brief Creates DBP key + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] destroy_old Destroy old DBP key if exists + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_PERMITTED Operation not permitted + */ int hal_security_keys_create_key_dbp(const bool destroy_old); +/** + * @brief Encrypts data with DBP key + * @since HAL_MODULE_SECURITY_KEYS 1.0 + * @param[in] dbp_scheme_version DBP scheme version + * @param[in] data Data to encrypt + * @param[in] iv Initialization vector + * @param[out] out Encrypted data + * @return @c 0 on success, otherwise an error value + * @retval #HAL_SECURITY_KEYS_ERROR_NONE Successful + * @retval #HAL_SECURITY_KEYS_ERROR_NOT_SUPPORTED Feature not supported + * @retval #HAL_SECURITY_KEYS_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #HAL_SECURITY_KEYS_ERROR_OUT_OF_MEMORY Out of memory + * @retval #HAL_SECURITY_KEYS_ERROR_INTERNAL_ERROR Internal error + * @retval #HAL_SECURITY_KEYS_ERROR_NO_KEY Key doesn't exist + * @see hal_security_keys_create_key_dbp() + */ int hal_security_keys_encrypt_data_dbp(const hal_security_keys_dbp_scheme_version_e dbp_scheme_version, const hal_security_keys_data_s data, const hal_security_keys_data_s iv, hal_security_keys_data_s* out); +/** + * @} + */ + #ifdef __cplusplus } #endif