From 2127a67ef9cb303d4f37e9ff4150875f530fe43e Mon Sep 17 00:00:00 2001 From: Jakub Wlostowski Date: Thu, 22 May 2025 13:19:55 +0200 Subject: [PATCH] Update security-certs API comments Change-Id: I2e55e45a9a8b5e6a98449078022e40fcaf0430de --- include/hal-security-certs.h | 117 +++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/include/hal-security-certs.h b/include/hal-security-certs.h index ac79917..24c853b 100644 --- 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 -- 2.34.1