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 c1a8ee9b34657e8e4b03c2ab9c19b7294f568129..ed1e70e25c5ea2e1f64bbebf94225f4592ffd153 100644 (file)
--- 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:
  * 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
  * - 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 1eeb8c685c7bc067cd874856301f04ae706bdd51..3b4f982c945f9ef8d528d936b91bb783d082d2be 100644 (file)
--- 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);
 
     /** 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);
 
     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 7d600bd102b4347ed3e8f4053562c207a6ad6f53..2c74193c7ecf402b5d8aee77645d57f0f476082f 100644 (file)
--- 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 */
  */
 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;
 
 /**
 } hal_security_keys_password_iv_s;
 
 /**


@@ -68,7 +68,7 @@ typedef struct {
  */
 typedef struct {
     hal_security_keys_data_s password;    /**< Password buffer */
  */
 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;
 
     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 170fc555f7c27cd34a85b8a7089c0d6bd84be0fa..74be5ed630c97f58daf10d20a16247a770bfa6c9 100644 (file)
--- a/include/hal-security-keys.h
+++ b/include/hal-security-keys.h
@@ -26,21 +26,114 @@
 extern "C" {
 #endif
 
 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);
 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);
 
 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);
 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);
 
 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);
 
 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);
 
 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,
 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);
 
                                           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,
 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);
 
                                           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,
 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);
 
                                             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,
 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);
 
                                           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,
 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);
 
                                          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,
 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);
 
                                          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,
 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);
 
                                       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,
 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);
 
                                       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);
 
 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,
 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);
 
                                   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);
 
 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,
 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);
 
                                              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,
 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);
 
                                                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,
 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);
 
                                         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,
 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);
 
                                         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,
 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);
 
                                    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,
 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);
 
                                    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);
 
 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,
 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);
 
                                         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);
 
 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);
 
 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);
 
 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);
 
 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,
 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);
 
                                        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,
 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);
 
                                        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,
 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);
 
                                   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,
 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);
 
                                    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,
 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);
 
                                           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);
 
 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);
 
 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);
 
 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
 #ifdef __cplusplus
 }
 #endif