<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.20">
<TITLE>The PWDB Library Guide: Implementation</TITLE>
<LINK HREF="pwdb-4.html" REL=next>
<LINK HREF="pwdb-2.html" REL=previous>
<LINK HREF="pwdb.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="pwdb-4.html">Next</A>
<A HREF="pwdb-2.html">Previous</A>
<A HREF="pwdb.html#toc3">Contents</A>
<HR>
<H2><A NAME="s3">3.</A> <A HREF="pwdb.html#toc3">Implementation</A></H2>
<P><EM>This will get completed as we develop the library</EM></P>
<H2><A NAME="ss3.1">3.1</A> <A HREF="pwdb.html#toc3.1">The core (public) functions</A>
</H2>
<P><CODE>libpwdb</CODE> offers the following generic interface:</P>
<H3>Initialization and termination</H3>
<P>
<UL>
<LI><CODE>int pwdb_start(void)</CODE>
<P>Initialize the library for use by the current application Will read
the configuration file and publicize the database policies (as they are
listed in <CODE>/etc/pwdb.conf</CODE>) in <CODE>const int *pwdb_policy</CODE>
and <CODE>const int *pwdb_group_policy</CODE>. The library maintains a
count of the number of times it has been <CODE>pwdb_start()</CODE>ed.</P>
</LI>
<LI><CODE>int pwdb_end(void)</CODE>
<P>Once the <CODE>pwdb_start()</CODE>ed count returns to zero, this function
closes down the library and free()'s all memory allocated by it. Any
attempt to <CODE>pwdb_end()</CODE> the library more times than it has been
<CODE>pwdb_start()</CODE>ed will cause <CODE>PWDB_ABORT</CODE> to be
returned. <EM>This feature can be used by an application to guarantee
the library is shutdown..</EM>
<BLOCKQUOTE><CODE>
<PRE>
while (pwdb_end() == PWDB_SUCCESS);
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
</UL>
</P>
<H3>Structure management</H3>
<P>
<UL>
<LI><CODE>int pwdb_entry_delete(const struct pwdb_entry **e)</CODE>
<P><CODE>free()</CODE> the memory associated with the pointer
<CODE>*e</CODE>. Its value will be overwritten with <CODE>'\\0'</CODE>s before
the memory is <CODE>free()</CODE>d. This is reassuring from the point of
view of minimizing security problems. This function should be used to
liberate a <CODE>pwdb_entry</CODE> returned by <CODE>pwdb_get_entry()</CODE>.</P>
</LI>
<LI><CODE>int pwdb_get_entry(const struct pwdb *p, const char *entry, const
struct pwdb_entry **e);</CODE>
<P>Read (and duplicate) an entry from the argument pwdb structure. Should
the requested entry not prove to be present, <CODE>PWDB_NOT_FOUND</CODE> is
returned.</P>
</LI>
<LI><CODE>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))</CODE>
<P>Set an entry in the argument pwdb structure. One can delete an
entry from a struct pwdb by calling this function with <CODE>NULL</CODE> for
<CODE>datum</CODE> and <CODE>-1</CODE> for <CODE>length</CODE>.</P>
<P>The two functions passed as arguments in this call are as follows:</P>
<P>
<DL>
<DT><B><CODE>int compare(const void *value1, const void *value2, int length)</CODE></B><DD><P>compare the two entry <CODE>value</CODE>s. They are both of given <CODE>length</CODE>
in <CODE>char</CODE>s.</P>
<DT><B><CODE>int strvalue(const void *value, char *buffer, int length)</CODE></B><DD><P>Produce a text version of the given entry <CODE>value</CODE>. The <CODE>buffer</CODE>
is the destination of the output text and the <CODE>length</CODE> is that of
the <CODE>*value</CODE> in bytes. Note, the buffer is guaranteed by the
calling process to be long enough for the output text.</P>
</DL>
</P>
</LI>
<LI><CODE>int pwdb_delete(const struct pwdb **old)</CODE>
<P>Applications use this to liberate the memory associated with a
<CODE>pwdb</CODE> structure. Following a successful <CODE>free()</CODE>,
<CODE>*old</CODE> is set to <CODE>NULL</CODE>.</P>
</LI>
<LI><CODE>int pwdb_new(const struct pwdb **new, int life_sec)</CODE>
<P>Applications can request a new (blank) <CODE>pwdb</CODE> structure with this
call. Note that it is returned as a <CODE>const</CODE> structure. This is to
prevent the application from altering the structure directly. An
application should use the library functions to modify this structure.
The <CODE>life_sec</CODE> 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 <CODE>life_sec</CODE> is non-zero, the <CODE>pwdb</CODE> structure will
expire in that many seconds. Zero indicates the <CODE>pwdb</CODE> structure
will non expire.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
int pwdb_merge(const struct pwdb *target, const struct pwdb *source,
int overwrite)
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>this function copies the elements of <CODE>source</CODE> to <CODE>target</CODE>. If
<CODE>overwrite</CODE> is <CODE>PWDB_TRUE</CODE> then all elements of <CODE>source</CODE> that
are also in <CODE>target</CODE> will be overwritten by this call.</P>
</LI>
<LI><CODE>int pwdb_expire(const struct pwdb *p, int life_sec)</CODE>
This function can shorten the lifetime of a the referenced <CODE>struct
pwdb</CODE>. It computes the expiry time from the present with respect to
<CODE>life_sec</CODE> and if this is <EM>before</EM> the expiration time currently
associated with the <CODE>*p</CODE> structure, it shortens the life of the
structure accordingly.
<P>Note, it is not possible to extend the life of a <CODE>pwdb</CODE> structure,
only to <EM>shorten</EM> it. An argument of <CODE>0</CODE> or less will result in
the immediate expiry of the <CODE>pwdb</CODE> structure.</P>
</LI>
<LI><CODE>int pwdb_source(const struct pwdb *old, const pwdb_type *src,
const char *class, const char *name, const int id)</CODE>
This function is used to set the source of the indicate <CODE>pwdb</CODE>
structure. The argument <CODE>src</CODE> is a pointer to a list of
<CODE>pwdb_type</CODE> entries. This list is terminated with a
<CODE>_PWDB_MAX_TYPES</CODE> item. Valid types are listed in the
<CODE><security/pwdb_public.h></CODE> file. The remaining arguments
are used to initialize the caching facilities.
</LI>
</UL>
</P>
<H3>Database query functions</H3>
<P>
<UL>
<LI><CODE>int pwdb_locate(const char *class, const pwdb_type *src, const char
*name, const int id, struct pwdb **p)</CODE>
<P>Obtain the entry for a given name and/or id in the indicated
database. If <CODE>*p</CODE> is not <CODE>NULL</CODE> 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
<CODE>*p</CODE> structure. If <CODE>*p</CODE> is <CODE>NULL</CODE>, then a struct pwdb is
allocated by the <CODE>pwdb_locate()</CODE> function in the first module used
(and eventually merged with the subsequent modules, depending on the
local setup). The <CODE>class</CODE> is the kind of database we are searching,
examples include <CODE>user</CODE> and <CODE>group</CODE>.</P>
</LI>
<LI><CODE>int pwdb_request(const char *class, const pwdb_type *src, const char *entry, struct pwdb **p)</CODE>
<P>This function will further query the database, for an entry
that may depend on the entries already present in the <CODE>*p</CODE>
structure. The <CODE>entry</CODE>s that can be appended to the existing
<CODE>*p</CODE> structure are defined for the <CODE>class</CODE> of database.
For example, one may request the <EM>"groupids"</EM> <CODE>entry</CODE> from
<CODE>"group"</CODE> 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 <CODE>pwdb</CODE> structure.</P>
</LI>
<LI><CODE>int pwdb_replace(const char *class, const pwdb_type *src,
const char *name, const int id, struct pwdb **p)</CODE>
<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
<CODE>p</CODE> argument. The <CODE>src</CODE> argument is the list of entries that
will be updated.</P>
</LI>
<LI><CODE>int pwdb_remove(const char *class, const pwdb_type *src,
const char *name, const int id, struct pwdb **p)</CODE>
<P>Remove the entry for the indicated <CODE>name</CODE> and/or <CODE>id</CODE> in the
indicated database. If not <CODE>NULL</CODE> the remove function may obtain
access information from the <CODE>p</CODE> argument.</P>
<P>Note, this function only acts on the specified <CODE>class</CODE> of
database. If reference to a <CODE>name</CODE> or <CODE>id</CODE> is present in another
<CODE>class</CODE> of database, then it is the responsibility of the
application to purge these databases too. The <CODE>pwdb_remove()</CODE>
function is not sufficiently powerful to follow up on
cross-references.</P>
<P>As an example of the above concern, consider the removal of <CODE>name</CODE>
``joe'' from the <CODE>"user"</CODE> database. The <CODE>"group"</CODE> database
entries that refer to ``joe'' as a group-member are unaffected by this
<CODE>pwdb_remove()</CODE> request. Instead, it is the responsibility of the
calling application to search for such entries and systematically
<CODE>pwdb_remove()</CODE>
them.</P>
</LI>
<LI><CODE>int pwdb_support(const char *class, const pwdb_type *src,
const char *entry_name)</CODE>
<P>Indicate whether the given entry name is supported by the given
database(s). <CODE>PWDB_SUCCESS</CODE> indicates yes. Anything else is NO (or
something more specific, could be ``yes, if you supply a pass_phrase''
for example).</P>
</LI>
<LI><CODE>int pwdb_flags(const char *class, const pwdb_type *db, pwdb_flag *flag_p)</CODE>
<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 <CODE>class</CODE> of database (<CODE>user</CODE>,
<CODE>group</CODE> etc.), <CODE>db</CODE> (the database(s) we are going to use)
and some storage space for the returned flags.</P>
<P>Valid return flags which can be logically OR'd together are:</P>
<P>
<DL>
<DT><B><CODE>PWDB_F_NOACCESS</CODE></B><DD><P>insufficient privilege to access database</P>
<DT><B><CODE>PWDB_F_NOUPDATE</CODE></B><DD><P>insufficient privilege to alter an entry</P>
<DT><B><CODE>PWDB_F_PASS_PHRASE</CODE></B><DD><P>to access the database, the process must supply a "pass_phrase" entry
with a preallocated pwdb structure (use pwdb_new() call)</P>
<DT><B><EM>..and..</EM></B><DD><P><EM>more flags are likely to be added</EM></P>
</DL>
</P>
<P>To establish if a given flag is set the following macro is
supplied:</P>
</LI>
<LI><CODE>pwdb_on(flag, PWDB_F_XXX)</CODE>
<P>it returns TRUE(<CODE>1</CODE>) or FALSE(<CODE>0</CODE>).</P>
</LI>
</UL>
</P>
<H3>Diagnostics</H3>
<P>
<UL>
<LI><CODE>const char *pwdb_strerror(int pwdb_error)</CODE>
<P>return a textual description of the indicated return value.</P>
<P>Valid return codes are:</P>
<P>
<DL>
<DT><B><CODE>PWDB_SUCCESS</CODE></B><DD><P>task completed successfully</P>
<DT><B><CODE>PWDB_BAD_REQUEST</CODE></B><DD><P>request not recognized</P>
<DT><B><CODE>PWDB_TOO_WEAK</CODE></B><DD><P>insufficient privilege for operation</P>
<DT><B><CODE>PWDB_ABORT</CODE></B><DD><P>internal failure - seek help</P>
<DT><B><CODE>PWDB_BLOCKED</CODE></B><DD><P>another process has locked resource</P>
<DT><B><CODE>PWDB_MALLOC</CODE></B><DD><P>insufficient memory for operation</P>
<DT><B><CODE>PWDB_NOT_FOUND</CODE></B><DD><P>requested item was not found</P>
<DT><B><CODE>PWDB_PASS_PHRASE_REQD</CODE></B><DD><P>pass_phrase needed to satisfy request <EM>here the application should
supply a pwdb structure with a "pass_phrase" entry and call the
function again</EM></P>
<DT><B><CODE>PWDB_CONF_ERR</CODE></B><DD><P>there is a problem with the PWDB_CONF file.</P>
<DT><B><CODE>PWDB_EXPIRED</CODE></B><DD><P>the referenced pwdb structure has expired it is no longer valid and
should be deleted.</P>
<DT><B><CODE>PWDB_UNSUPPORTED</CODE></B><DD><P>this function is not supported by some module (not supported means
also unimplemented, for a while...)</P>
<DT><B><CODE>PWDB_TIMEOUT</CODE></B><DD><P>a timeout occured while performing the function. Presently could show up
only when using RADIUS interface.</P>
</DL>
</P>
</LI>
</UL>
</P>
<H3>Types of database</H3>
<P>The pwdb_type of database a request is associated with is
given by one of the following values:</P>
<P>
<DL>
<DT><B><CODE>PWDB_DEFAULT</CODE></B><DD><P>no database indicated, use configured list</P>
<DT><B><CODE>PWDB_UNIX</CODE></B><DD><P>generic /etc/passwd and /etc/group files</P>
<DT><B><CODE>PWDB_SHADOW</CODE></B><DD><P>/etc/shadow and /etc/gshadow <EM>Intended to supplement other databases</EM></P>
<DT><B><CODE>PWDB_NIS</CODE></B><DD><P>Use NIS server</P>
<DT><B><CODE>PWDB_RADIUS</CODE></B><DD><P>Use RADIUS server</P>
<DT><B><CODE>PWDB_DECNIS</CODE></B><DD><P>Use a NIS server configured for Digital Equipment Corp Enhanced Security,
or a Solaris server with an adjunct NIS password file.</P>
</DL>
</P>
<P>
<UL>
<LI><CODE>const char *pwdb_db_name(pwdb_type src)</CODE>
<P>return a character representation of the database functions</P>
</LI>
</UL>
</P>
<H2><A NAME="ss3.2">3.2</A> <A HREF="pwdb.html#toc3.2">Functions supplied by database modules</A>
</H2>
<P>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:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
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);
};
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>For the functions above taking a <CODE>name</CODE> and an <CODE>id</CODE> entry, the
application may choose to leave one unspecified with the following
defaults:</P>
<P>
<DL>
<DT><B><CODE>PWDB_NAME_UNKNOWN</CODE></B><DD><P>just look at the id field</P>
<DT><B><CODE>PWDB_ID_UNKNOWN</CODE></B><DD><P>just look at the name field</P>
</DL>
</P>
<P>In the case that the application supplies neither the <CODE>name</CODE> or the
<CODE>id</CODE>, the module functions will try to obtain the relevant
information from the argument <CODE>pwdb</CODE> structure.</P>
<P>It is legal for both the <CODE>name</CODE> and <CODE>id</CODE> 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, <CODE>PWDB_BAD_REQUEST</CODE>
is returned.</P>
<P>The structure is registered via an entry in the modules list (see
pwdb_module.c).</P>
<H2><A NAME="ss3.3">3.3</A> <A HREF="pwdb.html#toc3.3">Standard entries in pwdb structures</A>
</H2>
<P>The following are standard entries in the pwdb structure. They can be
read/written with calls to <CODE>pwdb_g/set_entry</CODE>.</P>
<P>First, we consider the <CODE>"user"</CODE> class of databases. For these, two
entries are mandatory. They correspond to the name of the user and the
user's uid.</P>
<P>
<DL>
<DT><B><CODE>user</CODE></B><DD><P>character string; the user's login id.</P>
<DT><B><CODE>uid</CODE></B><DD><P>uid_t; the user's <EM>user-id</EM>.</P>
</DL>
</P>
<P>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 <CODE>/etc/passwd</CODE>
file.</P>
<P>
<DL>
<DT><B><CODE>passwd</CODE></B><DD><P>character string; the <EM>encrypted</EM> password for the user.</P>
<DT><B><CODE>defer_pass</CODE></B><DD><P>This entry is intended to take care of situations that the normal
<CODE>passwd</CODE> field is not used for the password. The <CODE>defer_pass</CODE>
entry contains a character string that has typically two functions:
<UL>
<LI> it indicates that the password is to be stored in the database
that sets this entry.</LI>
<LI> it serves as a substitution string for databases that would
normally contain the password entry.</LI>
</UL>
</P>
<P>For example, for a <CODE>unix+shadow</CODE> setup, <CODE>defer_pass</CODE> would have
the value ``<CODE>x</CODE>''. The <CODE>unix</CODE> (no <CODE>shadow</CODE>) value for this
entry is ``U'' which implies that the <CODE>passwd</CODE> field came from the
user's entry in the <CODE>/etc/passwd</CODE> file.</P>
<DT><B><CODE>gid</CODE></B><DD><P>gid_t; the user's principal <EM>group-id</EM>.</P>
<DT><B><CODE>group</CODE></B><DD><P>character string; naming the user's principal group.</P>
<DT><B><CODE>gecos</CODE></B><DD><P>character 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.</P>
<DT><B><CODE>dir</CODE></B><DD><P>character string; the home directory of the user.</P>
<DT><B><CODE>shell</CODE></B><DD><P>character string; the shell that the user prefers to use.</P>
</DL>
</P>
<P>These entries correspond to the entries in the <CODE>/etc/group</CODE> file
<EM>in addition to the user and gid entries above</EM>. They can be
<CODE>pwdb_request()</CODE>d from the "group" class of databases.</P>
<P>
<DL>
<DT><B><CODE>groups</CODE></B><DD><P>character string; listing the group memberships of the user. The field
separators are commas -- no spaces.</P>
<DT><B><CODE>groupids</CODE></B><DD><P>array of <CODE>gid_t</CODE>; an array containing the group id's of the user in
numerical form.</P>
</DL>
</P>
<P>The following are intended to correspond to <CODE>/etc/shadow</CODE>
entries.</P>
<P>
<DL>
<DT><B><CODE>last_change</CODE></B><DD><P>long integer; day of last change of password</P>
<DT><B><CODE>min_change</CODE></B><DD><P>long integer; minimum number of days between password changes</P>
<DT><B><CODE>max_change</CODE></B><DD><P>integer; maximum number of days between password changes</P>
<DT><B><CODE>warn_change</CODE></B><DD><P>long integer; number of days to warn user to change their password
before it expires</P>
<DT><B><CODE>defer_change</CODE></B><DD><P>long integer; number of days after a user's password has expired
before the user is denied access</P>
<DT><B><CODE>expire</CODE></B><DD><P>long integer; day the user's account expires</P>
<DT><B><CODE>shadow_flags</CODE></B><DD><P>long integer; reserved for use by underlying shadow implementation</P>
</DL>
</P>
<P>The following is the entry used to supply a <EM>clear-text</EM> password
for access to the database.</P>
<P>
<DL>
<DT><B><CODE>pass_phrase</CODE></B><DD><P>character string; this is the password required to access the user's
record in a database</P>
</DL>
</P>
<P>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.</P>
<H2><A NAME="ss3.4">3.4</A> <A HREF="pwdb.html#toc3.4">Helper functions</A>
</H2>
<H3>Public functions</H3>
<P>
<UL>
<LI><CODE>char *_pwdb_delete_string(char *s)</CODE>
<P>overwrite the string '<CODE>s</CODE>' and return <CODE>NULL</CODE>. usage:</P>
<P><CODE>old_ptr = _pwdb_delete(old_ptr);</CODE></P>
</LI>
<LI><CODE>char *_pwdb_dup_string(const char *s)</CODE>
<P><CODE>malloc()</CODE> a copy of the string '<CODE>s</CODE>'. Return its address or
<CODE>NULL</CODE> if <CODE>s == NULL</CODE> or on error.</P>
<P>this memory will <EM>not</EM> be <CODE>free()</CODE>'d by a call to
<CODE>pwdb_end()</CODE>.</P>
</LI>
<LI><CODE>void pwdb_print_pwdb_struct(const struct pwdb *p)</CODE>
<P>Dump the contents of <CODE>*p</CODE> to the <CODE>stderr</CODE>. Useful for debugging.</P>
</LI>
</UL>
</P>
<H3>Private functions</H3>
<P>
<UL>
<LI><CODE>static struct pwdb *_pwd_check(const struct pwdb *p)</CODE>
<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.</P>
<P>this function is strictly designed for the use of the
generic code. Both modules and applications should never
need to call it.</P>
</LI>
</UL>
</P>
<H2><A NAME="ss3.5">3.5</A> <A HREF="pwdb.html#toc3.5">Typical usage</A>
</H2>
<P>Here is a skeleton usage for a login type program.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
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();
</PRE>
</CODE></BLOCKQUOTE>
</P>
<HR>
<A HREF="pwdb-4.html">Next</A>
<A HREF="pwdb-2.html">Previous</A>
<A HREF="pwdb.html#toc3">Contents</A>
</BODY>
</HTML>
distrib
>
Mageia
>
6
>
i586
>
media
>
core-release
>
by-pkgid
>
361aec75ca848765d8dc12993cdb4cd6
>
files
>
7
