Unix Password Management

Putting and Getting a record from a custom file

Name: ex2-3.c Covers: fgetpwent, putpwent

#include <stdio.h>
#include <pwd.h>
#include <sys/types.h>

#include <errno.h> /* for perror() */

int main ()
{
FILE *mypasswd;

Getting a record by name, then by user id.

Name: ex2-4.c Covers: getpwnam, getpwuid

#include <stdio.h>
#include <pwd.h>
#include <sys/types.h>
#include <errno.h>

int main()
{
struct passwd *p_entry1, *p_entry2;

/* We are getting the password entry for OUR own user id,

/etc/group

In addition to functions for manipulation of the password database, there are also a set of functions to manipulate the group database's group and group membership. Again, I won't go over the details of the /etc/group file, but suffice it to say that it's similar to the /etc/passwd file. It has four fields: group name, group password, group id number, and a list of members of the group.

The group struct

The group struct is defined in <grp.h> as follows:
char *gr_name; /* group name */
char *gr_passwd; /* group password */
gid_t gr_gid; /* group id */
char **gr_mem; /* group members */
}

Big surprise, just as in the file, the struct has a member for group name, group password, group id (which is of type gid_t - remember that?) and a two-dimensional array of strings (user names of group members.)
What's interesting about the group structure, is its last member. As I pointed out a second ago, it's a two-dimensional array. This makes scanning through the member list a bit tricky (not difficult, but interesting.) The key to know is that the last pointer at the end of the list of strings, is a null pointer. You want to check for this when cycling through the member list. The following is a snippet of code that does just that:

231struct group *g_entry;
g_entry = getgrent();

for (i=0;g_entry->gr_mem[i]!=0;++i) {
printf("%s ",g_entry->gr_mem[i]);
}

Getting Groups

The group system calls for manipulating the group database are as follows:

#include <grp.h>
#include <sys/types.h>

struct group *getgrent(void);
void setgrent(void);
void endgrent(void);

Getting group records from the group database is very similar to getting user names from the password database. The function getgrent automagically opens the group database and retrieves the first group. Each time getgrent is called it will retrieve the next record in the group database. Hence, if you want to scan the group database, you can just call getgrent until a null pointer is fetched. This null pointer tells you that you have reached the end of the file.

Starting Over

You can rewind the database and start over (from the first record) by calling setgrent. This function makes the internal cursor go to the beginning of the group database file and start with the first one without closing the file.

Cleaning up after yourself

If you are done scanning the group database file, then you should close the file. Call endgrent. This is good practice as it frees up the file from possible corruption through other processes attempts to access the file at the same time. However, it's not good programming practice to call endgrent, if you want to start searching the group database from the beginning. Yeah, it'll work, but it needlessly uses up file descriptors.

Does it have to be the group database?

No! In fact, there's a function similar to the fgetpwent, it's called the fgetgrent ... as if you couldn't already guess! The function is defined as follows:

#include <grp.h>
#include <stdio.h>
#include <sys/types.h>

struct group *fgetgrent(FILE *stream);

The function fgetgrent works exactly the same as fgetpwent, in that it takes an open and valid pointer to the file stream as an argument. Then, like getgrent, it cycles through the custom group database file returning a pointer to a group struct.

No looping required!

You can also use two functions to get the group data directly, either by name or by group id. These functions are provided to make all of our lives much easier! The following are the functions defined:

#include <grp.h>
#include <sys/types.h>

struct group *getgrnam(const char *name);
struct group *getgrgid(gid_t gid);

Get it by group name

Locating the group record by name is a cinch when you use getgrnam and send it, as an argument, the C string consisting of the group's name. It returns a pointer to the group structure filled with group data if it can find the group you asked it to look for. Otherwise, the function returns a null pointer, which basically means that you're out of luck.

Get it by group id

Additionally, locating the group by id is just as easy when you use getgrid. This function takes as one argument the group id number and based on that will return you the record with that group id number associated with it. If it cannot find that group then it returns a null pointer. Pretty simple huh?

Adding an entry

Unfortunately, they don't have any convenient functions to put entries into the group database. However, you can easily use sprintf to format your group struct data and write the string to the file. You can even make your own putgrent function! We have supplied such a function (identical to the putpwent function) for you! Consider the following code:

#include <stdio.h>
#include <grp.h>
#include <sys/types.h>
#include <errno.h>

int putgrent(const struct group *g, FILE *stream)
/* This function mimics the behaviour demonstrated by
putpwent() except that it operates on groups instead */
{
int temp_length=0; /* length of string to calloc() */
int i=0; /* our member iterator */
char temp_double[27]; /* holds the string of gid */
char *temp_holder; /* create a temporary holder
for our output data */

/* This should never be the case! */
if (g==NULL || stream==NULL) return -1;

/* first thing we want to do is calculate
how long our line's going to be. We do
this by getting the strlen() of each of
the group struct's members */
temp_length=strlen(g->gr_name);
temp_length+=strlen(g->gr_passwd);

/* now in order to get the length of the string
version of the group ID, we have to convert it
then count the characters */
sprintf(temp_double, "%ld", g->gr_gid);
temp_length+=strlen(temp_double);

/* now we have to iterate through the loop to
get our group members' lengths. */
for(i=0;g->gr_mem[i]!=0;++i)
temp_length+=strlen(g->gr_mem[i]);

/* Cool! We got the length of the line, let's
add `i' to it because we are going to need
to put coma's in there between the names,
and add 10 for extra colons, and padding! */
temp_length+=(10+i);

/* allocate the number of chars necessary for line */
temp_holder = (char *)calloc(temp_length,sizeof(char));
if ( temp_holder == NULL ) return -1;

/* Format the name and password and group id's */
sprintf(temp_holder,"%s:%s:%ld:",
g->gr_name, g->gr_passwd, g->gr_gid);

for(i=0;g->gr_mem[i]!=0;++i) {
strcat(temp_holder,g->gr_mem[i]);
strcat(temp_holder,",");
}

/* And finally replace extra coma with a newline! */
temp_holder[strlen(temp_holder)-1] = '
/* write the line to a file stream given to you */
if ( fputs(temp_holder, stream) < 0 )

Shadow Passwords

If you are using shadowed passwords, most modern UNIX systems are now doing so, then you will have to concurrently use various other functions when accessing the password database. Using the getpwent function doesn't search the /etc/shadow file for the person's password. For manipulating shadowed passwords you will have to use getspent family of functions instead.
From the manual pages:

#include <shadow.h>

struct spwd *getspent();
struct spwd *getspnam(char *name);

void setspent();
void endspent();

struct spwd *fgetspent(FILE *fp);
struct spwd *sgetspent(char *cp);

int putspent(struct spwd *p, FILE *fp);

As you have probably guessed, the functions above operate on the shadowed password database file almost identically as they do on the regular password database file. Note the similarity in the spelling to the normal functions (easy enough to remember which one does what since s stands for shadowed.) The one difference you have noticed however, is that these functions return a struct of type spwd.
The spwd struct differs from the standard password database file in the following ways:

#include <shadow.h>

struct spwd {
char sp_namp; /* user login name */
char sp_pwdp; /* encrypted password */
long sp_lstchg; /* last password change */
int sp_min; /* days until change allowed */
int sp_max; /* days before change required */
int sp_warn; /* days warning before expiration */
int sp_inact; /* days before account becomes inactive*/
int sp_expire; /* _date_ when account expires */
int sp_flag; /* reserved for future use */
}

These fields, like the password database file are delimited by colons in the /etc/shadow file. A sample entry in the /etc/shadow file would look something like this:

barry:$1$0ZWTtM5U$yN5VxD9$j1ndsyQ:11112:0:99999:7::11322:

The first field is, of course, the user's login name, a null terminated character string. The second field is a standard crypt'd password, a null terminated character string. The third field, sp_lastchg, is the number of days since January 1, 1970 that the password has changed.

The sp_lastchg is a long integer and is a bit tricky in that to get the actual date that the person changed their password you would have to pass it through the C-time and date functions. Otherwise you can calculate it yourself (not recommended.) In the above example, the user changed his password 11112 days after January 1, 1970.

A practically useless field, sp_min, holds the number of days before which a password may not be changed. I say practically, because the user ought to be encouraged to change their password as often as is reasonably possible (for security reasons.) To help you to encourage users to change their password there's the sp_max field. This field sets the number of days before users must change their password. Some users, however, may not heed your encouragements, or may forget that their password is to expire. To help remind users, we have the sp_warn field; it contains the number of days before the password expires that the users are warned of this.

On large UNIX systems, universities for example, it may be difficult to track which users leave permanently from the organisation. For automatic account disabling, we have the sp_inact field. This field contains the number of days after the password expires that the account is considered expired and is diabled. However, if the administrator knows beforehand that users are to have an account for a particular period of time, they can set sp_expire. This field contains the number of days before an account is disabled.

As you can see, this shadowed password struct allows for a more comprehensive and complex control over the the user's account versus the older password database file. It increases security and makes the system administrator's life a lot easier. And now that you have been introduced to the shadowed password struct, you can write small custom programs to manipulate the shadowed password database, augmenting your homebrew administration toolkit.

Locking and Unlocking Shadowed Password Database

Before we end the shadowed password section, there are two additional functions that may be used for shadowed passwords. They are as follows:

#include <shadow.h>

int lckpwdf();
int ulckpwdf();

It's good practice to lock files (exclusively) when using them in public areas. For example, if the file is located in /tmp or in our case /etc. There may be an open administration tool somewhere working on these system critical files, and the last thing you need is a race condition or corrupted file. The shadow password suite gives us two functions lckpwdf, and ulckpwdf. These functions attempt to lock and unlock, respectively, the shadowed password database, and the password database.

After issuing the command, the lckpwdf function will try to lock /etc/shadow and /etc/password for up to 15 seconds. If lckpwdf fails to attain an exclusive lock on either one of these files, then the function returns a negative number. You should programmatically take care of this error to inform you of this fact. When you are done updating the shadow password file, it is good practice to unlock the files by issuing ulckpwdf.

Sample Programs

Listing all groups

Name: ex2-5.c Covers: getgrent

#include <stdio.h>
#include <grp.h>
#include <sys/types.h>

int main()
{
struct group *g_entry;
int i;

while( (g_entry=getgrent()) != 0 ) {
printf("%sPasswd: %s
"Group Id: %ld Members:
g_entry->gr_name,