shellmatta/doc/shellmatta_auth.dox

/**

    @page shellmatta_auth Shellmatta Authentication

    The shellmatta comes with a simple authentication mechanism.
    It can be used to hide certain (or all) commands from users without
    permission.

    The permissions can be set per command.

    To enable the shellmatta auth module you have to include the file
    shellmatta_auth.c into your build and set the define
    ``SHELLMATTA_AUTHENTICATION``.

    Unfortunately the structure of each command has to be altered to include
    the additional information required by the auth module.
    Please add another NULL to the initializers of every command of type
    #shellmatta_cmd_t.


        shellmatta_cmd_t exampleCmd = { "example",
                                        "e",
                                        "example command",
                                        "example [options]\n"
                                        "\t-v, --version - print the version of the command",
                                        exampleCmdFct,
                                        NULL,
                                        NULL};

    After initializing the shellmatta instance you have to setup users with
    username and password.
    By enabling the user to be superuser you grant this user access to all
    commands without the need of setting a permission list.

        shellmatta_auth_user_t userList[] = {
            {1, true, "root", "rootpw"},
            {2, false, "shimatta", "12345678"},
            {3, false, "not_shimatta", "87654321"}
        };

    Every command can get a permission matrix - the perm lists can be reused for
    multiple users with the same permissions.
    When no entry is found for a command in the permission list the command
    defaults to be public.

    It is also possible to use the userID 0 to hide a command when logged in.

        uint32_t exampleCmdPerms[] = {2};
        shellmatta_auth_perm_t permList[] = {
            {"exampleCmd", exampleCmdPerms, sizeof(exampleCmdPerms)/sizeof(exampleCmdPerms[0])}
        };

    Now call the #shellmatta_auth_init method and pass the user and permissions
    lists.
    It is possible to register optional callbacks for a custom password check
    and a log function which is called on every authentication event.

        shellmatta_auth_init(handle, userList, 3, permList, 1, false, NULL, NULL);


    @section shellmatta_auth_custom_login Custom login

    By default the shellmatta uses plain text passwords.
    This of course is not state of the art and usually highly insecure.

    As most of the fancy password hashing methods are platform dependant none of
    those is included to keep up the compatibility with as many platforms as
    possible (sacrificing security).

    To overcome this limitation you can register your own function to check the
    credentials.

    Just implement a function of type #shellmatta_auth_check_t and pass it to
    the #shellmatta_auth_init method during initialization.

        shellmatta_retCode_t custom_auth_check(const uint32_t userId, const char* password) {
            /‌/ Check if the passed userID matches the passed password.
            if (password_matches()) {
                return SHELLMATTA_OK;
            }
            return SHELLMATTA_ERROR;
        }

*/