Skip to end of metadata
Go to start of metadata

Create a User Profile 

To create a user profile, call the Auth_CreateUser() function with a user name and password combination. The new user profile has no rights by default, but you can add them later using the Auth_GrantRight()function. The following example shows how to create a user profile.

void  Ex_AuthCreate (void)
{
    AUTH_USER_HANDLE  new_user_handle;
    RTOS_ERR          err;


    new_user_handle = Auth_CreateUser("UserA", "PwdA", &err);
    APP_RTOS_ASSERT_CRITICAL(err.Code == RTOS_ERR_NONE, ;);

    PP_UNUSED_PARAM(new_user_handle);
}
Listing - Ex_AuthCreate

 

Validate a User Name/Password Combination

To obtain a user's handle and confirm that the credentials are valid, use the Auth_ValidateCredentials() function. This function compares the submitted credentials against the list of existing user profiles to find a match. Once the match is found, the function returns the associated user handle.

If the user handle has the rights, use this user handle to grant or revoke a right for another user. You can also use it to proceed with the next action the user was trying to take.

void  Ex_AuthValidate (void)
{
    AUTH_USER_HANDLE  user_handle;
    RTOS_ERR          err;


    (void)Auth_CreateUser("UserB", "PwdB", &err);
    APP_RTOS_ASSERT_CRITICAL(err.Code == RTOS_ERR_NONE, ;);


    user_handle = Auth_ValidateCredentials("UserB", "Pwd0", &err);
    if (err.Code == RTOS_ERR_INVALID_CREDENTIALS) {
        /* Invalid user name/password combination. */
        /* At this point, we would normally return or indicate an error. */
    } else if (err.Code != RTOS_ERR_NONE) {
        /* Handle error. */
    }

    user_handle = Auth_ValidateCredentials("UserB", "PwdB", &err);
    if (err.Code == RTOS_ERR_INVALID_CREDENTIALS) {
        /* Invalid user name/password combination. */
    } else if (err.Code != RTOS_ERR_NONE) {
        /* Handle error. */
    }
    /* If credentials were good, we may continue and use the 'user_handle' obtained. */

    PP_UNUSED_PARAM(user_handle);
}
Listing - Ex_AuthValidate

 

Get a User Without Validating Its Credentials

You can obtain a user's handle without validating the credentials by using the Auth_GetUser() function instead of Auth_ValidateCredentials(). Once you recover the user handle, it only indicates that the user exists, but does not display any associated rights.

void  Ex_AuthGet (void)
{
    AUTH_USER_HANDLE  user_a_unvalidated_handle;
    RTOS_ERR          err;


                                                                /* The user must have been created before,  */
    user_a_unvalidated_handle = Auth_GetUser("UserA", &err);    /* for this call to be successful.          */
    APP_RTOS_ASSERT_CRITICAL(err.Code == RTOS_ERR_NONE, ;);

                                                                /* If obtained, this merely means           */
    PP_UNUSED_PARAM(user_a_unvalidated_handle);                 /* that the user exists.                    */
}
Listing - Ex_AuthGet

 

Rights

To grant or revoke rights to a user handle, use the Auth_GrantRight() and Auth_RevokeRight() functions respectively. Before you can call these two functions, you need to retrieve two user handles.

  • The first user handle is for the user to which you want to grant or revoke a right. In this case, you do not normally need to have that user's password. 
  • The second user handle is for the user that wishes to grant or revoke the right. This user handle must either be a root user, have admin rights, or have granting/revoking rights. Verify this second user's credentials to prevent anyone from knowing only that user's name to grant rights to another user.

To check if a given user has a particular right, use the Auth_GetUserRight() function.

The following example shows how to grant rights to a user handle as an Admin. Typically, the user name and password come from an external source (such as typing it in or from a shell), but to simplify this example, the user name/password are directly included. The example also checks if the user has the right before the operation (no rights given) and after the operation (rights now given).

void  Ex_AuthRights (void)
{
    AUTH_USER_HANDLE  user_a_unvalidated_handle;
    AUTH_USER_HANDLE  admin_validated_handle;
    AUTH_RIGHT        right;
    RTOS_ERR          err;


                                                                /* The user must have been created before,  */
    user_a_unvalidated_handle = Auth_GetUser("UserA", &err);    /* for this call to be successful.          */
    APP_RTOS_ASSERT_CRITICAL(err.Code == RTOS_ERR_NONE, ;);
    /* If obtained, this only means that the user exists. */


    admin_validated_handle = Auth_ValidateCredentials("admin", "admin", &err);
    if (err.Code == RTOS_ERR_INVALID_CREDENTIALS) {
        /* Invalid user name/password combination. */
        /* At this point, we would normally return or indicate an error. */
    } else if (err.Code != RTOS_ERR_NONE) {
        /* Handle error. */
    }
    /* If credentials were good, we may continue and use the 'user_handle' obtained. */


    right = Auth_GetUserRight(user_a_unvalidated_handle, &err);
    APP_RTOS_ASSERT_CRITICAL(err.Code == RTOS_ERR_NONE, ;);
    /* At this point, 'right' does not contain any bit set, since no right has been granted to that user. */


    Auth_GrantRight((AUTH_RIGHT_6 | AUTH_RIGHT_8), user_a_unvalidated_handle, admin_validated_handle, &err);
    if (err.Code == RTOS_ERR_PERMISSION) {
        /* This would mean that the 'as_user_handle' does not have the right to add. */
        /* At this point, we would normally return or indicate an error. */
    } else if (err.Code != RTOS_ERR_NONE) {
        /* Handle error. */
    }
    /* If no error, rights 6 and 8 were added, let's confirm. */


    right = Auth_GetUserRight(user_a_unvalidated_handle, &err);
    APP_RTOS_ASSERT_CRITICAL(err.Code == RTOS_ERR_NONE, ;);
    /* At this point, 'right' has the AUTH_RIGHT_6 and AUTH_RIGHT_8 set,   */
    /* since they have been granted to that user.                          */


    Auth_RevokeRight(AUTH_RIGHT_6, user_a_unvalidated_handle, admin_validated_handle, &err);
    if (err.Code == RTOS_ERR_PERMISSION) {
        /* This would mean that the 'as_user_handle' does not have the right to revoke. */
        /* At this point, we would normally return or indicate an error.                */
    } else if (err.Code != RTOS_ERR_NONE) {
        /* Handle error. */
    }
    /* If no error, right 6 was revoked. */


    right = Auth_GetUserRight(user_a_unvalidated_handle, &err);
    APP_RTOS_ASSERT_CRITICAL(err.Code == RTOS_ERR_NONE, ;);

    /* At this point, 'right' has ONLY the AUTH_RIGHT_8 set, since AUTH_RIGHT_6 has been revoked. */

    PP_UNUSED_PARAM(right);
}
Listing - Ex_AuthRights

 

Rights Definition

An application may define its own rights as follows:

#include  <rtos/include/common/auth.h>                                        (1)


#define  APP_FILE_READ_RIGHT     AUTH_RIGHT_0                                 (2)
#define  APP_FILE_WRITE_RIGHT   (AUTH_RIGHT_1 | APP_FILE_READ_RIGHT)          (3)
#define  APP_FILE_DELETE_RIGHT  (AUTH_RIGHT_2 | APP_FILE_WRITE_RIGHT)         (4)
Listing - Defining authentication right

(1) Include the auth.h file.

(2) The READ right can only read and is defined as Right 0.

(3) The WRITE right can write and read, it is defined as Right 0 and Right 1.

(3) The DELETE right can delete, write and read, it is defined as Right 0, Right 1 and Right 2.

If two distinct modules use the same right numbers (AUTH_RIGHT_xx), this can cause a conflict. If a user does not have the right to execute an operation, but has an "equivalent" right from another module, the authentication module will not be able to distinguish between both rights. However, this may mean that the module may allow the user to have this right if they share the same right's value. To prevent this from happening, each module should have its own AUTH_RIGHT_xx fields, without sharing them with another module.

  • No labels