Linux Shadow Password HOWTO: Adding shadow support to a C program

Next Previous Contents

## 8. Adding shadow support to a C program

Adding shadow support to a program is actually fairly straightforward. The only problem is that the program must be run by root (or SUID root) in order for the the program to be able to access the `/etc/shadow` file.

This presents one big problem: very careful programming practices must be followed when creating SUID programs. For instance, if a program has a shell escape, this must not occur as root if the program is SUID root.

For adding shadow support to a program so that it can check passwords, but otherwise does need to run as root, it's a lot safer to run the program SUID shadow instead. The `xlock` program is an example of this.

In the example given below, `pppd-1.2.1d` already runs SUID as root, so adding shadow support should not make the program any more vulnerable.

## 8.1 Header files

The header files should reside in `/usr/include/shadow`. There should also be a `/usr/include/shadow.h`, but it will be a symbolic link to `/usr/include/shadow/shadow.h`.

To add shadow support to a program, you need to include the header files:

    #include <shadow/shadow.h>
    #include <shadow/pwauth.h>

It might be a good idea to use compiler directives to conditionally compile the shadow code (I do in the example below).

## 8.2 libshadow.a library

When you installed the Shadow Suite the `libshadow.a` file was created and installed in `/usr/lib`.

When compiling shadow support into a program, the linker needs to be told to include the `libshadow.a` library into the link.

This is done by:

> `

>     gcc program.c -o program -lshadow

> `

However, as we will see in the example below, most large programs use a `Makefile`, and usually have a variable called `LIBS=...` that we will modify.

## 8.3 Shadow Structure

The `libshadow.a` library uses a structure called `spwd` for the information it retrieves from the `/etc/shadow` file. This is the definition of the `spwd` structure from the `/usr/include/shadow/shadow.h` header file:

    struct spwd
    {
      char *sp_namp;                /* login name */
      char *sp_pwdp;                /* encrypted password */
      sptime sp_lstchg;             /* date of last change */
      sptime sp_min;                /* minimum number of days between changes */
      sptime sp_max;                /* maximum number of days between changes */
      sptime sp_warn;               /* number of days of warning before password
                                       expires */
      sptime sp_inact;              /* number of days after password expires
                                       until the account becomes unusable. */
      sptime sp_expire;             /* days since 1/1/70 until account expires
    */
      unsigned long sp_flag;        /* reserved for future use */
    };

The Shadow Suite can put things into the `sp_pwdp` field besides just the encoded passwd. The password field could contain:

> `

>     username:Npge08pfz4wuk;@/sbin/extra:9479:0:10000::::

> `

This means that in addition to the password, the program `/sbin/extra` should be called for further authentication. The program called will get passed the username and a switch that indicates why it's being called. See the file `/usr/include/shadow/pwauth.h` and the source code for `pwauth.c` for more information.

What this means is that we should use the function `pwauth` to perform the actual authentication, as it will take care of the secondary authentication as well. The example below does this.

The author of the Shadow Suite indicates that since most programs in existence don't do this, and that it may be removed or changed in future versions of the Shadow Suite.

## 8.4 Shadow Functions

The `shadow.h` file also contains the function prototypes for the functions contained in the `libshadow.a` library:

    extern void setspent __P ((void));
    extern void endspent __P ((void));
    extern struct spwd *sgetspent __P ((__const char *__string));
    extern struct spwd *fgetspent __P ((FILE *__fp));
    extern struct spwd *getspent __P ((void));
    extern struct spwd *getspnam __P ((__const char *__name));
    extern int putspent __P ((__const struct spwd *__sp, FILE *__fp));

The function that we are going to use in the example is: `getspnam` which will retrieve for us a `spwd` structure for the supplied name.

## 8.5 Example

This is an example of adding shadow support to a program that needs it, but does not have it by default.

This example uses the Point-to-Point Protocol Server (pppd-1.2.1d), which has a mode in which it performs PAP authentication using user names and passwords from the `/etc/passwd` file instead of the PAP or CHAP files. You would not need to add this code to `pppd-2.2.0` because it's already there.

This feature of pppd probably isn't used very much, but if you installed the Shadow Suite, it won't work anymore because the passwords are no longer stored in `/etc/passwd`.

The code for authenticating users under `pppd-1.2.1d` is located in the `/usr/src/pppd-1.2.1d/pppd/auth.c` file.

The following code needs to be added to the top of the file where all the other `#include` directives are. We have surrounded the `#includes` with conditional directives (i.e. only include if we are compiling for shadow support).

    #ifdef HAS_SHADOW
    #include <shadow.h>
    #include <shadow/pwauth.h>
    #endif

The next thing to do is to modify the actual code. We are still making changes to the `auth.c` file.

Function `auth.c` before modifications:

    /*
     * login - Check the user name and password against the system
     * password database, and login the user if OK.
     *
     * returns:
     *      UPAP_AUTHNAK: Login failed.
     *      UPAP_AUTHACK: Login succeeded.
     * In either case, msg points to an appropriate message.
     */
    static int
    login(user, passwd, msg, msglen)
        char *user;
        char *passwd;
        char **msg;
        int *msglen;
    {
        struct passwd *pw;
        char *epasswd;
        char *tty;

        if ((pw = getpwnam(user)) == NULL) {
            return (UPAP_AUTHNAK);
        }
         /*
         * XXX If no passwd, let them login without one.
         */
        if (pw->pw_passwd == '\0') {
            return (UPAP_AUTHACK);
        }

        epasswd = crypt(passwd, pw->pw_passwd);
        if (strcmp(epasswd, pw->pw_passwd)) {
            return (UPAP_AUTHNAK);
        }

        syslog(LOG_INFO, "user %s logged in", user);

        /*
         * Write a wtmp entry for this user.
         */
        tty = strrchr(devname, '/');
        if (tty == NULL)
            tty = devname;
        else
            tty++;
        logwtmp(tty, user, "");             /* Add wtmp login entry */
        logged_in = TRUE;

        return (UPAP_AUTHACK);
    }

The user's password is placed into `pw->pw_passwd`, so all we really need to do is add the function `getspnam`. This will put the password into `spwd->sp_pwdp`.

We will add the function `pwauth` to perform the actual authentication. This will automatically perform secondary authentication if the shadow file is setup for it.

Function `auth.c` after modifications to support shadow:

    /*
     * login - Check the user name and password against the system
     * password database, and login the user if OK.
     *
     * This function has been modified to support the Linux Shadow Password
     * Suite if USE_SHADOW is defined.
     *
     * returns:
     *      UPAP_AUTHNAK: Login failed.
     *      UPAP_AUTHACK: Login succeeded.
     * In either case, msg points to an appropriate message.
     */
    static int
    login(user, passwd, msg, msglen)
        char *user;
        char *passwd;
        char **msg;
        int *msglen;
    {
        struct passwd *pw;
        char *epasswd;
        char *tty;

    #ifdef USE_SHADOW
        struct spwd *spwd;
        struct spwd *getspnam();
    #endif

        if ((pw = getpwnam(user)) == NULL) {
            return (UPAP_AUTHNAK);
        }

    #ifdef USE_SHADOW
            spwd = getspnam(user);
            if (spwd)
                    pw->pw_passwd = spwd->sp-pwdp;
    #endif

         /*
         * XXX If no passwd, let NOT them login without one.
         */
        if (pw->pw_passwd == '\0') {
            return (UPAP_AUTHNAK);
        }
    #ifdef HAS_SHADOW
        if ((pw->pw_passwd && pw->pw_passwd[0] == '@'
             && pw_auth (pw->pw_passwd+1, pw->pw_name, PW_LOGIN, NULL))
            || !valid (passwd, pw)) {
            return (UPAP_AUTHNAK);
        }
    #else
        epasswd = crypt(passwd, pw->pw_passwd);
        if (strcmp(epasswd, pw->pw_passwd)) {
            return (UPAP_AUTHNAK);
        }
    #endif

        syslog(LOG_INFO, "user %s logged in", user);

        /*
         * Write a wtmp entry for this user.
         */
        tty = strrchr(devname, '/');
        if (tty == NULL)
            tty = devname;
        else
            tty++;
        logwtmp(tty, user, "");             /* Add wtmp login entry */
        logged_in = TRUE;

        return (UPAP_AUTHACK);
    }

Careful examination will reveal that we made another change as well. The original version allowed access (returned `UPAP_AUTHACK` if there was NO password in the `/etc/passwd` file. This is not good, because a common use of this login feature is to use one account to allow access to the PPP process and then check the username and password supplied by PAP with the username in the `/etc/passwd` file and the password in the `/etc/shadow` file.

So if we had set the original version up to run as the shell for a user i.e. `ppp`, then anyone could get a ppp connection by setting their PAP to user `ppp` and a password of null.

We fixed this also by returning `UPAP_AUTHNAK` instead of `UPAP_AUTHACK` if the password field was empty.

Interestingly enough, `pppd-2.2.0` has the same problem.

Next we need to modify the Makefile so that two things occur: `USE_SHADOW` must be defined, and `libshadow.a` needs to be added to the linking process.

Edit the Makefile, and add:

> `

>     LIBS = -lshadow

> `

Then we find the line:

> `

>     COMPILE_FLAGS = -I.. -D_linux_=1 -DGIDSET_TYPE=gid_t

> `

And change it to:

> `

>     COMPILE_FLAGS = -I.. -D_linux_=1 -DGIDSET_TYPE=gid_t -DUSE_SHADOW

> `

Now make and install.

Next Previous Contents