Update security-certs API comments

Change-Id: I2e55e45a9a8b5e6a98449078022e40fcaf0430de

diff --git a/include/hal-security-certs.h b/include/hal-security-certs.h
index ac79917b76bdee8176304ecfcde3e92e97d7bcfa..24c853b732e18ea87f06bcacd3ec29a0002e1ce0 100644 (file)
--- a/include/hal-security-certs.h
+++ b/include/hal-security-certs.h
@@ -23,35 +23,152 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup HALAPI_HAL_SECURITY_CERTS_MODULE
+ * @{
+ */
+
+/**
+ * @brief Gets the security certs backend
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -ENOMEM Out of memory
+ * @retval -ENOTSUP The feature is not supported
+ * @see hal_security_certs_put_backend()
+ */
 int hal_security_certs_get_backend(void);
+
+/**
+ * @brief Puts the security certs backend
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -EINVAL Invalid parameter
+ * @see hal_security_certs_get_backend()
+ */
 int hal_security_certs_put_backend(void);
 
+/**
+ * @brief Creates security certs key context
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @param[out] context The handle to security certs context
+ * @param[in] key_type The key type
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -ENOMEM Out of memory
+ * @retval -ENODATA Unsupported key type
+ * @retval -ENOTSUP The feature is not supported
+ * @see hal_security_certs_free_key_context()
+ */
 int hal_security_certs_create_key_context(hal_security_certs_context_s* context,
                                           hal_security_certs_data_s key_type);
 
+/**
+ * @brief Frees security certs key context
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @param[in] context The handle to security certs context
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -EINVAL Invalid parameter
+ * @retval -ENOTSUP The feature is not supported
+ * @see hal_security_certs_create_key_context()
+ */
 int hal_security_certs_free_key_context(hal_security_certs_context_s* context);
 
+/**
+ * @brief Requests the certificate chain
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @param[in] context The handle to security certs context
+ * @param[out] cert_chain The certificate chain
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -ENOMEM Out of memory
+ * @retval -EINVAL Invalid parameter
+ * @retval -ENOTSUP The feature is not supported
+ */
 int hal_security_certs_request_certificate_chain(hal_security_certs_context_s* context,
                                                  hal_security_certs_data_s* cert_chain);
 
+/**
+ * @brief Signs crypto data
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @param[in] context The handle to security certs context
+ * @param[in] digest_type The digest type
+ * @param[in] message The message to be signed
+ * @param[out] signature The resulting signature
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -ENOMEM Out of memory
+ * @retval -EINVAL Invalid parameter
+ * @retval -ENODATA Unsupported digest type
+ * @retval -ENOTSUP The feature is not supported
+ */
 int hal_security_certs_sign_crypto_data(hal_security_certs_context_s* context,
                                         hal_security_certs_digest_type_e digest_type,
                                         hal_security_certs_data_s message,
                                         hal_security_certs_data_s* signature);
 
+/**
+ * @brief Gets key type
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @param[in] context The handle to security certs context
+ * @param[out] key_type The resulting key type
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -EINVAL Invalid parameter
+ * @retval -ENOTSUP The feature is not supported
+ */
 int hal_security_certs_get_key_type(hal_security_certs_context_s* context,
                                     hal_security_certs_crypto_key_type_e* key_type);
 
+/**
+ * @brief Gets key length in bits
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @param[in] context The handle to security certs context
+ * @param[out] key_length The resulting key length in bits
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -EINVAL Invalid parameter
+ * @retval -ENOTSUP The feature is not supported
+ */
 int hal_security_certs_get_key_bit_length(hal_security_certs_context_s* context,
                                           unsigned int* key_length);
 
+/**
+ * @brief Calls extended API
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @param[in] method_name The method name to call
+ * @param[in] input_data The input data
+ * @param[out] output_data The output data
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -ENOMEM Out of memory
+ * @retval -EINVAL Invalid parameter
+ * @retval -ENOTSUP The feature is not supported
+ */
 int hal_security_certs_ext_call_api(hal_security_certs_data_s method_name,
                                     hal_security_certs_data_s input_data,
                                     hal_security_certs_data_s* output_data);
 
+/**
+ * @brief Gets extended API privilege
+ * @since HAL_MODULE_SECURITY_CERTS 1.0
+ * @param[in] method_name The method name
+ * @param[out] privilege The resulting privilege
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval 0 Successful
+ * @retval -ENOMEM Out of memory
+ * @retval -EINVAL Invalid parameter
+ * @retval -ENOTSUP The feature is not supported
+ */
 int hal_security_certs_ext_get_api_privilege(hal_security_certs_data_s method_name,
                                              hal_security_certs_data_s* privilege);
 
+/**
+ * @}
+ */
+
 #ifdef __cplusplus
 }
 #endif