Authentication API#

Auth_ConfigureRootUser()#

Description#

Configure the properties of the root user, in the Auth sub-module.

Files#

auth.h/auth.c

Prototype#

void  Auth_ConfigureRootUser (AUTH_CFG_ROOT_USER  *p_cfg)

Arguments#

p_cfg

Pointer to the structure containing the new root user parameters.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before Auth_Init(). If it is not called, default values will be used to initialize the module.

Auth_ConfigureResource()#

Description#

Configure the properties of the resources used by the Auth sub-module.

Files#

auth.h/auth.c

Prototype#

void  Auth_ConfigureResource (AUTH_CFG_RESOURCE  *p_cfg)

Arguments#

p_cfg

Pointer to the structure containing the new resource usage parameters.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before Auth_Init(). If it is not called, default values will be used to initialize the module.

Auth_ConfigureMemSeg()#

Description#

Configure the memory segment that will be used to allocate internal data needed by Auth instead of the default memory segment.

Files#

auth.h/auth.c

Prototype#

void  Auth_ConfigureMemSeg (MEM_SEG  *p_mem_seg)

Arguments#

p_mem_seg

Pointer to the memory segment from which the internal data will be allocated. If DEF_NULL, the internal data will be allocated from the global Heap.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before Auth_Init(). If it is not called, default values will be used to initialize the module.

Auth_Init()#

Description#

Initializes authentication module.

Files#

auth.h/auth.c

Prototype#

void  Auth_Init (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

  1. The functions Auth_Configure...() can be used to configure more specific properties of the Auth sub-module, when RTOS_CFG_EXTERNALIZE_OPTIONAL_CFG_EN is set to DEF_DISABLED. If set to DEF_ENABLED, the structure Auth_InitCfg needs to be declared and filled by the application to configure these specific properties for the module.

Auth_CreateUser()#

Description#

Creates a user profile and fills the properties of the user profile structure provided.

Files#

auth.h/auth.c

Prototype#

AUTH_USER_HANDLE  Auth_CreateUser (const  CPU_CHAR    *p_name,
                                   const  CPU_CHAR    *p_pwd,
                                   RTOS_ERR           *p_err)

Arguments#

p_name

Pointer to the user name string.

p_pwd

Pointer to the password string.

p_err

Pointer to the variable that receives the following return error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_NO_MORE_RSRC

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

Handle of the created user profile.

Notes / Warnings#

None.

Auth_GetUser()#

Description#

Gets the specific user profile structure according to the name provided.

Files#

auth.h/auth.c

Prototype#

AUTH_USER_HANDLE  Auth_GetUser (const  CPU_CHAR    *p_name,
                                RTOS_ERR           *p_err)

Arguments#

p_name

Pointer to the user name string to retrieve.

p_err

Pointer to the variable that receives the following return error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

Handle of the user associated with the name provided.

Notes / Warnings#

None.

Auth_GetUserRight()#

Description#

Gets the rights of the user associated with the specified user handle.

Files#

auth.h/auth.c

Prototype#

AUTH_RIGHT  Auth_GetUserRight (AUTH_USER_HANDLE    user_handle,
                               RTOS_ERR           *p_err)

Arguments#

user_handle

Handle name of the user profile from which to retrieve the rights.

p_err

Pointer to the variable that receives the following return error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

User's rights, if no errors.

AUTH_RIGHT_NONE, if any errors are returned.

Notes / Warnings#

None.

Auth_ValidateCredentials()#

Description#

Validates the user and password tuple with known users.

Files#

auth.h/auth.c

Prototype#

AUTH_USER_HANDLE  Auth_ValidateCredentials (const  CPU_CHAR    *p_name,
                                            const  CPU_CHAR    *p_pwd,
                                            RTOS_ERR           *p_err)

Arguments#

p_name

Pointer to the user name string.

p_pwd

Pointer to the password string.

p_err

Pointer to the variable that receives the following return error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_CREDENTIALS

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

Handle of the user associated with the provided name and password, if no errors are returned.

Notes / Warnings#

None.

Auth_GrantRight()#

Description#

Grants a specific right to a user as another user (limits the rights granted).

Files#

auth.h/auth.c

Prototype#

void  Auth_GrantRight (AUTH_RIGHT          right,
                       AUTH_USER_HANDLE    user_handle,
                       AUTH_USER_HANDLE    as_user_handle,
                       RTOS_ERR           *p_err)

Arguments#

right

The new right to grant.

user_handle

User handle of the user that will receive the new right.

as_user_handle

User handle of the user with the permission level to perform this task.

p_err

Pointer to the variable that receives the following return error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_PERMISSION

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.

Auth_RevokeRight()#

Description#

Revokes a specific right of a specified user.

Files#

auth.h/auth.c

Prototype#

void  Auth_RevokeRight (AUTH_RIGHT          right,
                        AUTH_USER_HANDLE    user_handle,
                        AUTH_USER_HANDLE    as_user_handle,
                        RTOS_ERR           *p_err)

Arguments#

right

Right to revoke.

user_handle

User handle of the user that will have right revoked.

as_user_handle

User handle of the user with the permission level to perform this task.

p_err

Pointer to variable that receives the following return error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_PERMISSION

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.