Password


Overview

The Password module models the interface to a generic credential storage device which is password based. An u_pwd_t object is the handler through which all authentication and retrieval operations are performed over a given password DB. A password storage collects a number of identical records which carry at least an username and related password, plus an optional opaque blob which is intended to transport application specific information. Each of such records is mediated by the u_pwd_rec_t object. The storage is abstracted by means of a brigade of callbacks that the programmer is supposed to supply to the u_pwd_init function. A specialization of such function is provided for file based password files as u_pwd_init_file.

A simple authenticator based on the Password module follows:

    int main (int argc, char *argv[])
    {
        char c;
        int i, rc, in_memory = 0;
        u_pwd_t *pwd = NULL;
        char prompt[128];

        while ((c = getopt(argc, argv, "m")) != -1)
        {
            switch (c)
            {
                case 'm':
                    ++in_memory;
                    break;
                default:
                    con_err("usage: pwd [-m] user ...");
            }
        }

        argc -= optind;
        argv += optind;

        con_err_if (u_pwd_init_file("./passwd", NULL, 0, in_memory, &pwd));

        for (i = 0; i < argc; i++)
        {
            (void) u_snprintf(prompt, sizeof prompt, "%s: ", argv[i]);
            rc = u_pwd_auth_user(pwd, argv[i], getpass(prompt));
            u_con("auth %s", rc ? "failed" : "ok");
        }

        u_pwd_term(pwd);

        return EXIT_SUCCESS;
    err:
        return EXIT_FAILURE;
    }

Where the passwd file structure can be as simple as:

    # "name":"password"[:"hint"]
    jake:joliet:blues
    steve:colonel:cropper
    donald:duck:dunn

Note that the password field is in clear-text: in fact there was no hash callback supplied to the u_pwd_init_file function.

Typedefs

typedef struct u_pwd_s u_pwd_t
 default length of a password file line (can be changed at compile time via -DU_PWD_LINE_MAX=nnn flag)
typedef struct u_pwd_rec_s u_pwd_rec_t
 Carry information about a single password DB record.
typedef int(* u_pwd_hash_cb_t )(const char *, size_t, char[])
 Password hashing callback prototype: accept a string and its lenght, return the hashed string.
typedef char *(* u_pwd_load_cb_t )(char *, int, void *)
 Record load callback prototype: has fgets(3)-like prototype with generic storage resource handler.
typedef int(* u_pwd_open_cb_t )(const char *, void **)
 Master password DB open callback prototype: accepts an uri, return the (opaque) resource handler - the same that will be supplied to the u_pwd_load_cb_t.
typedef int(* u_pwd_notify_cb_t )(const char *, time_t, time_t *)
 Update notification callback prototype: return true if supplied timestamp is older than last modification time (this will force a reload for in-memory password DBs).

Functions

int u_pwd_init (const char *res_uri, u_pwd_open_cb_t cb_open, u_pwd_load_cb_t cb_load, u_pwd_close_cb_t cb_close, u_pwd_notify_cb_t cb_notify, u_pwd_hash_cb_t cb_hash, size_t hash_len, int in_memory, u_pwd_t **ppwd)
 Initialize a pwd instance.
int u_pwd_retr (u_pwd_t *pwd, const char *user, u_pwd_rec_t **prec)
 Retrieve a pwd record.
int u_pwd_auth_user (u_pwd_t *pwd, const char *user, const char *password)
 Check if user has presented the right credential.
void u_pwd_term (u_pwd_t *pwd)
 Dispose the supplied pwd instance.
int u_pwd_init_file (const char *res_uri, u_pwd_hash_cb_t cb_hash, size_t hash_len, int in_memory, u_pwd_t **ppwd)
 Init specialization for file-based password db.
void u_pwd_rec_free (u_pwd_t *pwd, u_pwd_rec_t *rec)
 Dispose a u_pwd_rec_t object.
const char * u_pwd_rec_get_user (u_pwd_rec_t *rec)
 Return the user field of the supplied pwd record.
const char * u_pwd_rec_get_password (u_pwd_rec_t *rec)
 Return the password field of the supplied pwd record.
const char * u_pwd_rec_get_opaque (u_pwd_rec_t *rec)
 Return the opaque field of the supplied pwd record.
int u_pwd_in_memory (u_pwd_t *pwd)
 Return the in_memory attribute from the supplied pwd instance.

Typedef Documentation

typedef struct u_pwd_s u_pwd_t

Base pwd object, mediates all operations over the password DB

Definition at line 31 of file pwd.h.


Function Documentation

int u_pwd_auth_user ( u_pwd_t pwd,
const char *  user,
const char *  password 
)

Check if user has presented the right password to access the u_pwd_t object pwd

Parameters:
pwd an already initialized pwd instance
user user whose credential has to be checked
password the supplied credential
Return values:
0 if authentication is ok
~0 if authentication fails

Definition at line 246 of file srcs/toolbox/pwd.c.

References u_free(), u_pwd_rec_free(), u_pwd_retr(), u_strlcpy(), and u_zalloc().

int u_pwd_in_memory ( u_pwd_t pwd  ) 

Get the in_memory attribute from the supplied u_pwd_t object, i.e. the fact that the password DB is memory cached or not.

Parameters:
pwd the u_pwd_t object to be inquired
Returns:
return 0 in case it is not an in-memory pwd instance

Definition at line 417 of file srcs/toolbox/pwd.c.

int u_pwd_init ( const char *  res_uri,
u_pwd_open_cb_t  cb_open,
u_pwd_load_cb_t  cb_load,
u_pwd_close_cb_t  cb_close,
u_pwd_notify_cb_t  cb_notify,
u_pwd_hash_cb_t  cb_hash,
size_t  hash_len,
int  in_memory,
u_pwd_t **  ppwd 
)

Get a new u_pwd_t object using the supplied attributes

Parameters:
res_uri name of the master db resource
cb_open method to open res_uri (get its handler)
cb_load method to load res_uri lines one by one
cb_close method to dispose res_uri handler (OPTIONAL)
cb_notify method to notify changes in the master resource (OPTIONAL)
cb_hash method to hash passwords (OPTIONAL)
hash_len hashed password string length (needed if cb_hash has been set)
in_memory if true, keep an hash-map'd version of the master db into memory (useful for huge and static db's)
ppwd the pwd instance handler as a result value
Return values:
0 on success
~0 on failure

Definition at line 161 of file srcs/toolbox/pwd.c.

References u_pwd_term(), u_strlcpy(), and u_zalloc().

Referenced by u_pwd_init_file().

int u_pwd_init_file ( const char *  res_uri,
u_pwd_hash_cb_t  cb_hash,
size_t  hash_len,
int  in_memory,
u_pwd_t **  ppwd 
)

An u_pwd_init specialization for file-based password DBs

Parameters:
res_uri name of the master db resource
cb_hash method to hash passwords (OPTIONAL)
hash_len hashed password string lenght (needed if cb_hash has been set)
in_memory if true, keep an hash-map'd version of the master db into memory (useful for huge and static db's)
ppwd the pwd instance handler as a result value
Return values:
0 on success
~0 on failure

Definition at line 327 of file srcs/toolbox/pwd.c.

References u_pwd_init().

void u_pwd_rec_free ( u_pwd_t pwd,
u_pwd_rec_t rec 
)

Dispose the supplied u_pwd_rec_t object rec. It MUST be called on u_pwd_rec_t records returned from u_pwd_retr when using "in memory" pwd instances (for non "in memory" pwd's the function is a NOP)

Parameters:
pwd the pwd instance which owns rec
rec the pwd_rec record to be disposed
Returns:
nothing

Definition at line 346 of file srcs/toolbox/pwd.c.

References u_free().

Referenced by u_pwd_auth_user().

const char* u_pwd_rec_get_opaque ( u_pwd_rec_t rec  ) 

Get the user opaque attribute from the supplied u_pwd_rec_t object

Parameters:
rec an u_pwd_rec_t object returned by u_pwd_retr
Returns:
the opaque string (which can be NULL even if successful)

Definition at line 401 of file srcs/toolbox/pwd.c.

const char* u_pwd_rec_get_password ( u_pwd_rec_t rec  ) 

Get the user password attribute from the supplied u_pwd_rec_t object

Parameters:
rec an u_pwd_rec_t object returned by u_pwd_retr
Returns:
a NUL-terminated string carrying the user password, or NULL on error

Definition at line 386 of file srcs/toolbox/pwd.c.

const char* u_pwd_rec_get_user ( u_pwd_rec_t rec  ) 

Get the user name attribute from the supplied u_pwd_rec_t object

Parameters:
rec an u_pwd_rec_t object returned by u_pwd_retr
Returns:
a NUL-terminated string carrying the user name, or NULL on error

Definition at line 370 of file srcs/toolbox/pwd.c.

int u_pwd_retr ( u_pwd_t pwd,
const char *  user,
u_pwd_rec_t **  prec 
)

Retrieve the u_pwd_rec_t object (if any) corresponding to the supplied user from the u_pwd_t instance pwd

Parameters:
pwd an already initialized pwd instance
user user whose info shall be retrieved
prec retrieved user record as a result argument (the record must be free'd using u_pwd_rec_free API).
Return values:
0 on success
~0 on failure

Definition at line 219 of file srcs/toolbox/pwd.c.

Referenced by u_pwd_auth_user().

void u_pwd_term ( u_pwd_t pwd  ) 

Dispose the supplied u_pwd_t object pwd

Parameters:
pwd the pwd instance that shall be disposed
Returns:
nothing

Definition at line 300 of file srcs/toolbox/pwd.c.

Referenced by u_pwd_init().


←Products
© 2005-2012 - KoanLogic S.r.l. - All rights reserved