Previous Next Table of Contents

3. Implementation

This will get completed as we develop the library

3.1 The core (public) functions

libpwdb offers the following generic interface:

Initialization and termination

Structure management

Database query functions

Diagnostics

Types of database

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

3.2 Functions supplied by database modules

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_UNKNOWN

just look at the id field

PWDB_ID_UNKNOWN

just 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).

3.3 Standard entries in pwdb structures

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.

user

character string; the user's login id.

uid

uid_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.

passwd

character string; the encrypted password for the user.

defer_pass

This 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.

gid

gid_t; the user's principal group-id.

group

character string; naming the user's principal group.

gecos

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.

dir

character string; the home directory of the user.

shell

character 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.

groups

character string; listing the group memberships of the user. The field separators are commas -- no spaces.

groupids

array 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_change

long integer; day of last change of password

min_change

long integer; minimum number of days between password changes

max_change

integer; maximum number of days between password changes

warn_change

long integer; number of days to warn user to change their password before it expires

defer_change

long integer; number of days after a user's password has expired before the user is denied access

expire

long integer; day the user's account expires

The following is the entry used to supply a clear-text password for access to the database.

pass_phrase

character 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.

3.4 Helper functions

Public functions

Private functions

3.5 Typical usage

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();


Previous Next Table of Contents