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 struct u_pwd_s u_pwd_t |
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
pwd | an already initialized pwd instance | |
user | user whose credential has to be checked | |
password | the supplied credential |
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.
pwd | the u_pwd_t object to be inquired |
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
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 |
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
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 |
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)
pwd | the pwd instance which owns rec | |
rec | the pwd_rec record to be disposed |
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
rec | an u_pwd_rec_t object returned by u_pwd_retr |
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
rec | an u_pwd_rec_t object returned by u_pwd_retr |
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
rec | an u_pwd_rec_t object returned by u_pwd_retr |
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
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). |
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
pwd | the pwd instance that shall be disposed |
Definition at line 300 of file srcs/toolbox/pwd.c.
Referenced by u_pwd_init().