This will get completed as we develop the library
libpwdb offers the following generic interface:
int pwdb_start(void)
Initialize the library for use by the current application Will read
the configuration file and publicize the database policies (as they are
listed in /etc/pwdb.conf) in const int *pwdb_policy
and const int *pwdb_group_policy. The library maintains a
count of the number of times it has been pwdb_start()ed.
int pwdb_end(void)
Once the pwdb_start()ed count returns to zero, this function
closes down the library and free()'s all memory allocated by it. Any
attempt to pwdb_end() the library more times than it has been
pwdb_start()ed will cause PWDB_ABORT to be
returned. This feature can be used by an application to guarantee
the library is shutdown..
while (pwdb_end() == PWDB_SUCCESS);
int pwdb_entry_delete(const struct pwdb_entry **e)
free() the memory associated with the pointer
*e. Its value will be overwritten with '\\0's before
the memory is free()d. This is reassuring from the point of
view of minimizing security problems. This function should be used to
liberate a pwdb_entry returned by pwdb_get_entry().
int pwdb_get_entry(const struct pwdb *p, const char *entry, const
struct pwdb_entry **e);
Read (and duplicate) an entry from the argument pwdb structure. Should
the requested entry not prove to be present, PWDB_NOT_FOUND is
returned.
int pwdb_set_entry(const struct pwdb *p, const char *entry, const void
*datum, const int length,
int (*compare)(const void *, const void *, int),
int (*strvalue)(const void *, char *, int),
int max_strval_size))
Set an entry in the argument pwdb structure. One can delete an
entry from a struct pwdb by calling this function with NULL for
datum and -1 for length.
The two functions passed as arguments in this call are as follows:
int compare(const void *value1, const void *value2, int length)compare the two entry values. They are both of given length
in chars.
int strvalue(const void *value, char *buffer, int length)Produce a text version of the given entry value. The buffer
is the destination of the output text and the length is that of
the *value in bytes. Note, the buffer is guaranteed by the
calling process to be long enough for the output text.
int pwdb_delete(const struct pwdb **old)
Applications use this to liberate the memory associated with a
pwdb structure. Following a successful free(),
*old is set to NULL.
int pwdb_new(const struct pwdb **new, int life_sec)
Applications can request a new (blank) pwdb structure with this
call. Note that it is returned as a const structure. This is to
prevent the application from altering the structure directly. An
application should use the library functions to modify this structure.
The life_sec time is used to limit the length of time this pwdb
structure will be valid for. It is some number of seconds from the
present. If life_sec is non-zero, the pwdb structure will
expire in that many seconds. Zero indicates the pwdb structure
will non expire.
int pwdb_merge(const struct pwdb *target, const struct pwdb *source,
int overwrite)
this function copies the elements of source to target. If
overwrite is PWDB_TRUE then all elements of source that
are also in target will be overwritten by this call.
int pwdb_expire(const struct pwdb *p, int life_sec)
This function can shorten the lifetime of a the referenced struct
pwdb. It computes the expiry time from the present with respect to
life_sec and if this is before the expiration time currently
associated with the *p structure, it shortens the life of the
structure accordingly.
Note, it is not possible to extend the life of a pwdb structure,
only to shorten it. An argument of 0 or less will result in
the immediate expiry of the pwdb structure.
int pwdb_source(const struct pwdb *old, const pwdb_type *src,
const char *class, const char *name, const int id)
This function is used to set the source of the indicate pwdb
structure. The argument src is a pointer to a list of
pwdb_type entries. This list is terminated with a
_PWDB_MAX_TYPES item. Valid types are listed in the
<security/pwdb_public.h> file. The remaining arguments
are used to initialize the caching facilities.
int pwdb_locate(const char *class, const pwdb_type *src, const char
*name, const int id, struct pwdb **p)
Obtain the entry for a given name and/or id in the indicated
database. If *p is not NULL the database-module may choose
to use the information it contains. It is intended that information
obtained with this function is merged with that of the original
*p structure. If *p is NULL, then a struct pwdb is
allocated by the pwdb_locate() function in the first module used
(and eventually merged with the subsequent modules, depending on the
local setup). The class is the kind of database we are searching,
examples include user and group.
int pwdb_request(const char *class, const pwdb_type *src, const char *entry, struct pwdb **p)
This function will further query the database, for an entry
that may depend on the entries already present in the *p
structure. The entrys that can be appended to the existing
*p structure are defined for the class of database.
For example, one may request the "groupids" entry from
"group" class, which will search the group database for the list
of groups to which a given user belongs. The name of the user is
passed as an entry in the preexisting pwdb structure.
int pwdb_replace(const char *class, const pwdb_type *src,
const char *name, const int id, struct pwdb **p)
Add/replace the entry for a name and/or id in the indicated list of
databases. The fields for the new database entries are taken from the
p argument. The src argument is the list of entries that
will be updated.
int pwdb_remove(const char *class, const pwdb_type *src,
const char *name, const int id, struct pwdb **p)
Remove the entry for the indicated name and/or id in the
indicated database. If not NULL the remove function may obtain
access information from the p argument.
Note, this function only acts on the specified class of
database. If reference to a name or id is present in another
class of database, then it is the responsibility of the
application to purge these databases too. The pwdb_remove()
function is not sufficiently powerful to follow up on
cross-references.
As an example of the above concern, consider the removal of name
``joe'' from the "user" database. The "group" database
entries that refer to ``joe'' as a group-member are unaffected by this
pwdb_remove() request. Instead, it is the responsibility of the
calling application to search for such entries and systematically
pwdb_remove()
them.
int pwdb_support(const char *class, const pwdb_type *src,
const char *entry_name)
Indicate whether the given entry name is supported by the given
database(s). PWDB_SUCCESS indicates yes. Anything else is NO (or
something more specific, could be ``yes, if you supply a pass_phrase''
for example).
int pwdb_flags(const char *class, const pwdb_type *db, pwdb_flag *flag_p)
In order to know in advance whether a process is able to read/modify a
specified database, this command is provided by each module.
The input arguments are the class of database (user,
group etc.), db (the database(s) we are going to use)
and some storage space for the returned flags.
Valid return flags which can be logically OR'd together are:
PWDB_F_NOACCESSinsufficient privilege to access database
PWDB_F_NOUPDATEinsufficient privilege to alter an entry
PWDB_F_PASS_PHRASEto access the database, the process must supply a "pass_phrase" entry with a preallocated pwdb structure (use pwdb_new() call)
more flags are likely to be added
To establish if a given flag is set the following macro is supplied:
pwdb_on(flag, PWDB_F_XXX)
it returns TRUE(1) or FALSE(0).
const char *pwdb_strerror(int pwdb_error)
return a textual description of the indicated return value.
Valid return codes are:
PWDB_SUCCESStask completed successfully
PWDB_BAD_REQUESTrequest not recognized
PWDB_TOO_WEAKinsufficient privilege for operation
PWDB_ABORTinternal failure - seek help
PWDB_BLOCKEDanother process has locked resource
PWDB_MALLOCinsufficient memory for operation
PWDB_NOT_FOUNDrequested item was not found
PWDB_PASS_PHRASE_REQDpass_phrase needed to satisfy request here the application should supply a pwdb structure with a "pass_phrase" entry and call the function again
PWDB_CONF_ERRthere is a problem with the PWDB_CONF file.
PWDB_EXPIREDthe referenced pwdb structure has expired it is no longer valid and should be deleted.
PWDB_UNSUPPORTEDthis function is not supported by some module (not supported means also unimplemented, for a while...)
PWDB_TIMEOUTa timeout occured while performing the function. Presently could show up only when using RADIUS interface.
The pwdb_type of database a request is associated with is given by one of the following values:
PWDB_DEFAULTno database indicated, use configured list
PWDB_UNIXgeneric /etc/passwd and /etc/group files
PWDB_SHADOW/etc/shadow and /etc/gshadow Intended to supplement other databases
PWDB_NISUse NIS server
PWDB_RADIUSUse RADIUS server
PWDB_DECNISUse a NIS server configured for Digital Equipment Corp Enhanced Security, or a Solaris server with an adjunct NIS password file.
const char *pwdb_db_name(pwdb_type src)
return a character representation of the database functions
Each module must provide 7 functions to the generic pwdb interface. They are registered with the generic interface via a structure of the following form:
struct _pwdb_module {
pwdb_type type; /* type of database (code) */
const char *name; /* type of database (text) */
const char *class; /* class of database (user/group) */
/* FUNCTIONS: used to access the relevant database */
int (*locate)(const char *name, const int id, const struct pwdb **p);
int (*request)(const char *entry_name, const struct pwdb **p);
int (*replace)(const char *name, const int id, const struct pwdb **p);
int (*delete)(const char *name, const int id, const struct pwdb **p);
int (*support)(const char *entry_name);
int (*flags)(pwdb_flag *flags);
int (*cleanup)(int code);
};
For the functions above taking a name and an id entry, the
application may choose to leave one unspecified with the following
defaults:
PWDB_NAME_UNKNOWNjust look at the id field
PWDB_ID_UNKNOWNjust look at the name field
In the case that the application supplies neither the name or the
id, the module functions will try to obtain the relevant
information from the argument pwdb structure.
It is legal for both the name and id to be specified. In
this case they must both match an entry in the database to satisfy one
of the above function calls. If both values are supplied and there is
no entry in the database which matches them, PWDB_BAD_REQUEST
is returned.
The structure is registered via an entry in the modules list (see pwdb_module.c).
The following are standard entries in the pwdb structure. They can be
read/written with calls to pwdb_g/set_entry.
First, we consider the "user" class of databases. For these, two
entries are mandatory. They correspond to the name of the user and the
user's uid.
usercharacter string; the user's login id.
uiduid_t; the user's user-id.
The next entries are named by convention. Where possible new database
functions should map these entries into their corresponding fields.
These entries correspond to the entries in the /etc/passwd
file.
passwdcharacter string; the encrypted password for the user.
defer_passThis entry is intended to take care of situations that the normal
passwd field is not used for the password. The defer_pass
entry contains a character string that has typically two functions:
For example, for a unix+shadow setup, defer_pass would have
the value ``x''. The unix (no shadow) value for this
entry is ``U'' which implies that the passwd field came from the
user's entry in the /etc/passwd file.
gidgid_t; the user's principal group-id.
groupcharacter string; naming the user's principal group.
gecoscharacter string; giving a more complete name for the user. It is conventional for this field to contain office and other information concerning the real-world identity of the user.
dircharacter string; the home directory of the user.
shellcharacter string; the shell that the user prefers to use.
These entries correspond to the entries in the /etc/group file
in addition to the user and gid entries above. They can be
pwdb_request()d from the "group" class of databases.
groupscharacter string; listing the group memberships of the user. The field separators are commas -- no spaces.
groupidsarray of gid_t; an array containing the group id's of the user in
numerical form.
The following are intended to correspond to /etc/shadow
entries.
last_changelong integer; day of last change of password
min_changelong integer; minimum number of days between password changes
max_changeinteger; maximum number of days between password changes
warn_changelong integer; number of days to warn user to change their password before it expires
defer_changelong integer; number of days after a user's password has expired before the user is denied access
expirelong integer; day the user's account expires
shadow_flagslong integer; reserved for use by underlying shadow implementation
The following is the entry used to supply a clear-text password for access to the database.
pass_phrasecharacter string; this is the password required to access the user's record in a database
When integrating another database format the implementor is strongly encouraged to try to reuse the entries above to the extent they are appropriate. Should there be an absent entry in any database, the database management functions should be able to supply a reasonable default but only when updating its database.
char *_pwdb_delete_string(char *s)
overwrite the string 's' and return NULL. usage:
old_ptr = _pwdb_delete(old_ptr);
char *_pwdb_dup_string(const char *s)
malloc() a copy of the string 's'. Return its address or
NULL if s == NULL or on error.
this memory will not be free()'d by a call to
pwdb_end().
void pwdb_print_pwdb_struct(const struct pwdb *p)
Dump the contents of *p to the stderr. Useful for debugging.
static struct pwdb *_pwd_check(const struct pwdb *p)
Establish if the pwdb structure was allocated by the library This library should not honor requests from elsewhere. return the local version (non-const) of this structure or NULL on error.
this function is strictly designed for the use of the generic code. Both modules and applications should never need to call it.
Here is a skeleton usage for a login type program.
pwdb_start();
pwdb_locate("user", PWDB_DEFAULT, username, PWDB_ID_UNKNOWN, &pw);
pwdb_request_group("group", PWDB_DEFAULT, "groupids", &pw);
pwdb_get_entry(pw, "uid", &e1);
pwdb_get_entry(pw, "gid", &e2);
pwdb_get_entry(pw, "groupids", &e3);
pwdb_end();