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 value
s. They are both of given length
in char
s.
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 entry
s 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_NOACCESS
insufficient privilege to access database
PWDB_F_NOUPDATE
insufficient privilege to alter an entry
PWDB_F_PASS_PHRASE
to 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_SUCCESS
task completed successfully
PWDB_BAD_REQUEST
request not recognized
PWDB_TOO_WEAK
insufficient privilege for operation
PWDB_ABORT
internal failure - seek help
PWDB_BLOCKED
another process has locked resource
PWDB_MALLOC
insufficient memory for operation
PWDB_NOT_FOUND
requested item was not found
PWDB_PASS_PHRASE_REQD
pass_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_ERR
there is a problem with the PWDB_CONF file.
PWDB_EXPIRED
the referenced pwdb structure has expired it is no longer valid and should be deleted.
PWDB_UNSUPPORTED
this function is not supported by some module (not supported means also unimplemented, for a while...)
PWDB_TIMEOUT
a 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_DEFAULT
no database indicated, use configured list
PWDB_UNIX
generic /etc/passwd and /etc/group files
PWDB_SHADOW
/etc/shadow and /etc/gshadow Intended to supplement other databases
PWDB_NIS
Use NIS server
PWDB_RADIUS
Use RADIUS server
const char *pwdb_db_name(pwdb_type src)
return a character representation of the database functions