From bb913c8471722f79e4fceae198edbd53342c2438 Mon Sep 17 00:00:00 2001 From: Dongik Lee Date: Mon, 26 May 2025 17:32:15 +0900 Subject: [PATCH] Update security-auth API comments Change-Id: I76fe8eb67595162b76f5133f97879d95168e9543 --- include/hal-security-auth.h | 214 ++++++++++++++++++++++++++++++++++++ src/hal-api-security-auth.c | 6 +- 2 files changed, 217 insertions(+), 3 deletions(-) diff --git a/include/hal-security-auth.h b/include/hal-security-auth.h index 8b6ba0c..c6e1620 100644 --- a/include/hal-security-auth.h +++ b/include/hal-security-auth.h @@ -23,66 +23,280 @@ extern "C" { #endif +/** + * @addtogroup HALAPI_HAL_SECURITY_AUTH_MODULE + * @{ + */ + +/** + * @brief Gets the security auth backend + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_OUT_OF_MEMORY running out of memory state + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @see hal_security_auth_put_backend() + */ int hal_security_auth_get_backend(void); + +/** + * @brief Puts the security auth backend + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @see hal_security_auth_get_backend() + */ int hal_security_auth_put_backend(void); +/** + * @brief Create a authentication password file for the given user ID and password type + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_UNKNOWN a error with unknown reason + */ int hal_security_auth_create_password_file(uid_t user_id, hal_security_auth_password_type_e password_type); +/** + * @brief Write all the authentication information of the given user ID into a authentication password file + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the given user ID + */ int hal_security_auth_write_memory_to_file(uid_t user_id); +/** + * @brief Write the authentication attempt of the given user ID into a authentication password file + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization +* @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the given user ID + */ int hal_security_auth_write_attempt_to_file(uid_t user_id); +/** + * @brief Set a new authentication password for the given user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the given user ID + */ int hal_security_auth_set_password(uid_t user_id, const char* password); +/** + * @brief Check if the provided password matches the authentication password associated with the given user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_PASSWORD_MISMATCH password mismatch occured + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the given user ID + */ int hal_security_auth_check_password(uid_t user_id, const char* password); +/** + * @brief Set the maximum size of the authentication history for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_set_max_history_size(uid_t user_id, unsigned int history_size); +/** + * @brief Get the maximum size of the authentication history for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_get_max_history_size(uid_t user_id, unsigned int *history_size); +/** + * @brief Get the expiration day of the authentication password for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_get_expire_time(uid_t user_id, unsigned int *expire_time); +/** + * @brief Set the expiration day of the authentication password for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_set_expire_time(uid_t user_id, unsigned int expire_time); +/** + * @brief Get the left seconds to the expiration date time of the authentication password for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_get_expire_time_left(uid_t user_id, unsigned int *expire_time_left); +/** + * @brief Set the left expiration date time of the authentication password for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_set_expire_time_left(uid_t user_id, unsigned int expire_time_left); +/** + * @brief Get the number of authentication attempts for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_get_attempt(uid_t user_id, unsigned int *attempt); +/** + * @brief Reset the number of authentication attempts for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_reset_attempt(uid_t user_id); +/** + * @brief Increment the number of authentication attempts by 1 for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_increment_attempt(uid_t user_id); +/** + * @brief Get the maximum allowed number of authentication attempts for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_get_max_attempt(uid_t user_id, unsigned int *max_attempt); +/** + * @brief Set the maximum allowed number of authentication attempts for the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_set_max_attempt(uid_t user_id, unsigned int max_attempt); +/** + * @brief Check if the authentication password for the specified user ID is active or not + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE password active flag is true + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_STATUS password active flag is false + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_is_password_active(uid_t user_id); +/** + * @brief Check if the authentication password for the specified user ID has been reused or not + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE the authentication password was not reused + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_STATUS the authentication password was reused + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_is_password_reused(uid_t user_id, const char* password); +/** + * @brief Check if the authentication password for the specified user ID has expired + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE the current system time did not exceed the expiration time of the authentication password + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_PASSWORD_EXPIRED the current system time exceeded the expiration time of the authentication password + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_check_expiration(uid_t user_id); +/** + * @brief Check if the number of authentication attempts for the specified user ID has exceeded + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE the number of attempts did not exceed the number of max attempts + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_PASSWORD_MAX_ATTEMPTS_EXCEEDED the number of attempts exceeded the number of max attempts + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_check_attempt_exceeded(uid_t user_id); +/** + * @brief Check if the current authentication attempt for the specified user ID has exceeded the retry timeout + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE a retry timeout did not occur + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_PASSWORD_RETRY_TIMER a retry timeout occured + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_is_ignore_period(uid_t user_id); +/** + * @brief Check if the authentication attempt history for the specified user ID is active or not + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE max history size is not equal to 0 + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_STATUS max history size is equal to 0 + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + */ int hal_security_auth_is_history_active(uid_t user_id); +/** + * @brief Get the password type associated with the specified user ID + * @since HAL_MODULE_SECURITY_AUTH 1.0 + * @return @c 0 on success, otherwise a negative error value + * @retval HAL_SECURITY_AUTH_ERROR_NONE successful + * @retval HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL a failure during HAL initialization + * @retval HAL_SECURITY_AUTH_ERROR_INPUT_PARAM there is no relevent instance for the specified user ID + * @see hal_security_auth_password_type_e type for password type + */ int hal_security_auth_get_password_type(uid_t user_id, hal_security_auth_password_type_e *password_type); diff --git a/src/hal-api-security-auth.c b/src/hal-api-security-auth.c index dcdf6f9..bbecb0d 100644 --- a/src/hal-api-security-auth.c +++ b/src/hal-api-security-auth.c @@ -47,20 +47,20 @@ EXPORT int hal_security_auth_get_backend(void) return HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL; } - return 0; + return HAL_SECURITY_AUTH_ERROR_NONE; } EXPORT int hal_security_auth_put_backend(void) { if (!g_security_auth_funcs) - return HAL_SECURITY_AUTH_ERROR_INPUT_PARAM; + return HAL_SECURITY_AUTH_ERROR_HAL_INIT_FAIL; hal_common_put_backend(HAL_MODULE_SECURITY_AUTH, (void *)g_security_auth_funcs); free(g_security_auth_funcs); g_security_auth_funcs = NULL; - return 0; + return HAL_SECURITY_AUTH_ERROR_NONE; } EXPORT int hal_security_auth_create_password_file(uid_t user_id, hal_security_auth_password_type_e password_type) -- 2.34.1