Update security-auth API comments

Change-Id: I76fe8eb67595162b76f5133f97879d95168e9543

diff --git a/include/hal-security-auth.h b/include/hal-security-auth.h
index 8b6ba0c2b9453cd377004c6213a9e92e3053ffbc..c6e1620d8b0d72c468ffbc66c58a2733624f6f0b 100644 (file)
--- 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 dcdf6f9c8fd97dbf801caa80cf4a49275c574d8b..bbecb0dff11ea361a2191564a15a298bac8aa0b9 100644 (file)
--- 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)