File:  [NetBSD Developer Wiki] / wikisrc / guide / pam.mdwn
Revision 1.1: download - view: text, annotated - select for diffs
Sat Mar 9 00:00:15 2013 UTC (9 years, 10 months ago) by jdf
Branches: MAIN
CVS tags: HEAD
Add PAM section from the guide.
Note that there is missing content!

# Pluggable Authentication Modules (PAM)

## About

This article describes the underlying principles and mechanisms of the 
*Pluggable Authentication Modules (PAM)* library, and explains how to configure 
PAM, how to integrate PAM into applications, and how to write PAM modules.

See below for the license of this text.

## Introduction

The Pluggable Authentication Modules (PAM) library is a generalized API for 
authentication-related services which allows a system administrator to add new 
authentication methods simply by installing new PAM modules, and to modify 
authentication policies by editing configuration files.

PAM was defined and developed in 1995 by Vipin Samar and Charlie Lai of Sun 
Microsystems, and has not changed much since. In 1997, the Open Group published 
the X/Open Single Sign-on (XSSO) preliminary specification, which standardized 
the PAM API and added extensions for single (or rather integrated) sign-on. At 
the time of this writing, this specification has not yet been adopted as a 

Although this article focuses primarily on FreeBSD 5.x and NetBSD 3.x, which 
both use OpenPAM, it should be equally applicable to FreeBSD 4.x, which uses 
Linux-PAM, and other operating systems such as Linux and Solaris.

## Terms and conventions

### Definitions

The terminology surrounding PAM is rather confused. Neither Samar and Lai's 
original paper nor the XSSO specification made any attempt at formally defining 
terms for the various actors and entities involved in PAM, and the terms that 
they do use (but do not define) are sometimes misleading and ambiguous. The 
first attempt at establishing a consistent and unambiguous terminology was a 
whitepaper written by Andrew G. Morgan (author of Linux-PAM) in 1999. While 
Morgan's choice of terminology was a huge leap forward, it is in this author's 
opinion by no means perfect. What follows is an attempt, heavily inspired by 
Morgan, to define precise and unambiguous terms for all actors and entities 
involved in PAM.

 * *account* -- The set of credentials the applicant is requesting from the 

 * *applicant* -- The user or entity requesting authentication.

 * *arbitrator* -- The user or entity who has the privileges necessary to verify 
   the applicant's credentials and the authority to grant or deny the request.

 * *chain* -- A sequence of modules that will be invoked in response to a PAM 
   request. The chain includes information about the order in which to invoke 
   the modules, what arguments to pass to them, and how to interpret the 

 * *client* -- The application responsible for initiating an authentication 
   request on behalf of the applicant and for obtaining the necessary 
   authentication information from him.

 * *facility* -- One of the four basic groups of functionality provided by PAM: 
   authentication, account management, session management and authentication 
   token update.

 * *module* -- A collection of one or more related functions implementing a 
   particular authentication facility, gathered into a single (normally 
   dynamically loadable) binary file and identified by a single name.

 * *policy* -- The complete set of configuration statements describing how to 
   handle PAM requests for a particular service. A policy normally consists of 
   four chains, one for each facility, though some services do not use all four 

 * *server* -- The application acting on behalf of the arbitrator to converse 
   with the client, retrieve authentication information, verify the applicant's 
   credentials and grant or deny requests.

 * *service* -- A class of servers providing similar or related functionality 
   and requiring similar authentication. PAM policies are defined on a 
   per-service basis, so all servers that claim the same service name will be 
   subject to the same policy.

 * *session* -- The context within which service is rendered to the applicant by 
   the server. One of PAM's four facilities, session management, is concerned 
   exclusively with setting up and tearing down this context.

 * *token* -- A chunk of information associated with the account, such as a 
   password or passphrase, which the applicant must provide to prove his 

 * *transaction* -- A sequence of requests from the same applicant to the same 
   instance of the same server, beginning with authentication and session set-up 
   and ending with session tear-down.

### Usage examples

This section aims to illustrate the meanings of some of the terms defined above by way of a handful of simple examples.

#### Client and server are one

This simple example shows `alice` [su(1)]('ing to `root`.

    $ whoami
    $ ls -l `which su`
    -r-sr-xr-x  1 root  wheel  10744 Dec  6 19:06 /usr/bin/su
    $ su -
    Password: xi3kiune
    # whoami

 * The applicant is `alice`.
 * The account is `root`.
 * The [su(1)]( process is both client and server.
 * The authentication token is `xi3kiune`.
 * The arbitrator is `root`, which is why [su(1)]( is setuid `root`.

#### Client and server are separate

The example below shows `eve` try to initiate an 
connection to ``, ask to log in as `bob`, and succeed. Bob 
should have chosen a better password!

    $ whoami
    $ ssh's password: god
    Last login: Thu Oct 11 09:52:57 2001 from
    NetBSD 3.0 (LOGIN) #1: Thu Mar 10 18:22:36 WET 2005
    Welcome to NetBSD!

 * The applicant is `eve`.
 * The client is Eve's [ssh(1)]( process.
 * The server is the [sshd(8)]( process on ``
 * The account is `bob`.
 * The authentication token is `god`.
 * Although this is not shown in this example, the arbitrator is `root`.

#### Sample policy

The following is FreeBSD's default policy for `sshd`:

    sshd    auth        required  no_warn
    sshd    auth        required no_warn try_first_pass
    sshd    account     required
    sshd    account     required
    sshd    session     required  no_fail
    sshd    password    required

 * This policy applies to the `sshd` service (which is not necessarily 
   restricted to the 

 * `auth`, `account`, `session` and `password` are facilities.

 * ``, ``, ``, `` and 
   `` are modules. It is clear from this example that `` 
   provides at least two facilities (authentication and account management.)

There are some differences between FreeBSD and NetBSD PAM policies:

 * By default, every configuration is done under `/etc/pam.d`.

 * If configuration is non-existent, you will not have access to the system, in 
   contrast with FreeBSD that has a default policy of allowing authentication.

 * For authentication, NetBSD forces at least one `required`, `requisite` or 
   `binding` module to be present.

## PAM Essentials

### Facilities and primitives

The PAM API offers six different authentication primitives grouped in four 
facilities, which are described below.

 * `auth` -- *Authentication.* This facility concerns itself with authenticating 
   the applicant and establishing the account credentials. It provides two 

	* [pam\_authenticate(3)]( 
	  authenticates the applicant, usually by requesting an authentication token 
	  and comparing it with a value stored in a database or obtained from an 
	  authentication server.

	* [pam\_setcred(3)]( 
	  establishes account credentials such as user ID, group membership and 
	  resource limits.

 * `account` -- *Account management.* This facility handles 
   non-authentication-related issues of account availability, such as access 
   restrictions based on the time of day or the server's work load. It provides 
   a single primitive:

	* [pam\_acct\_mgmt(3)]( 
	  verifies that the requested account is available.

 * `session` -- *Session management.* This facility handles tasks associated 
   with session set-up and tear-down, such as login accounting. It provides two 

	* [pam\_open\_session(3)]( 
	  performs tasks associated with session set-up: add an entry in the `utmp` 
	  and `wtmp` databases, start an SSH agent, etc.

	* [pam\_close\_session(3)]( 
	  performs tasks associated with session tear-down: add an entry in the 
	  `utmp` and `wtmp` databases, stop the SSH agent, etc.

 * `password` -- *Password management.* This facility is used to change the 
   authentication token associated with an account, either because it has 
   expired or because the user wishes to change it. It provides a single 

	* [pam\_chauthtok(3)]( 
	  changes the authentication token, optionally verifying that it is 
	  sufficiently hard to guess, has not been used previously, etc.

### Modules

Modules are a very central concept in PAM; after all, they are the *M* in *PAM*. 
A PAM module is a self-contained piece of program code that implements the 
primitives in one or more facilities for one particular mechanism; possible 
mechanisms for the authentication facility, for instance, include the UNIX® 
password database, NIS, LDAP and Radius.

#### Module Naming

FreeBSD and NetBSD implement each mechanism in a single module, named 
`pam_mechanism`.so (for instance, `` for the UNIX mechanism.) Other 
implementations sometimes have separate modules for separate facilities, and 
include the facility name as well as the mechanism name in the module name. To 
name one example, Solaris has a `` module which is commonly 
used to authenticate dialup users. Also, almost every module has a man page with 
the same name, i.e.: 
explains how the `` module works.

#### Module Versioning

FreeBSD's original PAM implementation, based on Linux-PAM, did not use version 
numbers for PAM modules. This would commonly cause problems with legacy 
applications, which might be linked against older versions of the system 
libraries, as there was no way to load a matching version of the required 

OpenPAM, on the other hand, looks for modules that have the same version number 
as the PAM library (currently 2 in FreeBSD and 0 in NetBSD), and only falls back 
to an unversioned module if no versioned module could be loaded. Thus legacy 
modules can be provided for legacy applications, while allowing new (or newly 
built) applications to take advantage of the most recent modules.

Although Solaris PAM modules commonly have a version number, they're not truly 
versioned, because the number is a part of the module name and must be included 
in the configuration.

#### Module Path

There isn't a common directory for storing PAM modules. Under FreeBSD, they are 
located at `/usr/lib` and, under NetBSD, you can find them in 

### Chains and policies

When a server initiates a PAM transaction, the PAM library tries to load a 
policy for the service specified in the 
call. The policy specifies how authentication requests should be processed, and 
is defined in a configuration file. This is the other central concept in PAM: 
the possibility for the admin to tune the system security policy (in the wider 
sense of the word) simply by editing a text file.

A policy consists of four chains, one for each of the four PAM facilities. Each 
chain is a sequence of configuration statements, each specifying a module to 
invoke, some (optional) parameters to pass to the module, and a control flag 
that describes how to interpret the return code from the module.

Understanding the control flags is essential to understanding PAM configuration 
files. There are a number of different control flags:

 * `binding` -- If the module succeeds and no earlier module in the chain has 
   failed, the chain is immediately terminated and the request is granted. If 
   the module fails, the rest of the chain is executed, but the request is 
   ultimately denied.

   This control flag was introduced by Sun in Solaris 9 (SunOS 5.9), and is also supported by OpenPAM.

 * `required` -- If the module succeeds, the rest of the chain is executed, and 
   the request is granted unless some other module fails. If the module fails, 
   the rest of the chain is also executed, but the request is ultimately denied.

 * `requisite` -- If the module succeeds, the rest of the chain is executed, and 
   the request is granted unless some other module fails. If the module fails, 
   the chain is immediately terminated and the request is denied.

 * `sufficient` -- If the module succeeds and no earlier module in the chain has 
   failed, the chain is immediately terminated and the request is granted. If 
   the module fails, the module is ignored and the rest of the chain is 

   As the semantics of this flag may be somewhat confusing, especially when it is used for the last module in a chain, it is recommended that the `binding` control flag be used instead if the implementation supports it.

 * `optional` -- The module is executed, but its result is ignored. If all 
   modules in a chain are marked `optional`, all requests will always be 

When a server invokes one of the six PAM primitives, PAM retrieves the chain for 
the facility the primitive belongs to, and invokes each of the modules listed in 
the chain, in the order they are listed, until it reaches the end, or determines 
that no further processing is necessary (either because a `binding` or 
`sufficient` module succeeded, or because a `requisite` module failed.) The 
request is granted if and only if at least one module was invoked, and all 
non-optional modules succeeded.

Note that it is possible, though not very common, to have the same module listed 
several times in the same chain. For instance, a module that looks up user names 
and passwords in a directory server could be invoked multiple times with 
different parameters specifying different directory servers to contact. PAM 
treat different occurrences of the same module in the same chain as different, 
unrelated modules.

### Transactions

The lifecycle of a typical PAM transaction is described below. Note that if any 
of these steps fails, the server should report a suitable error message to the 
client and abort the transaction.

 1. If necessary, the server obtains arbitrator credentials through a mechanism 
    independent of PAM -- most commonly by virtue of having been started by `root`, 
    or of being setuid `root`.

 2. The server calls 
    to initialize the PAM library and specify its service name and the target 
    account, and register a suitable conversation function.

 3. The server obtains various information relating to the transaction (such as 
    the applicant's user name and the name of the host the client runs on) and 
    submits it to PAM using 

 4. The server calls 
    to authenticate the applicant.

 5. The server calls 
    to verify that the requested account is available and valid. If the password is 
    correct but has expired, 
    will return `PAM_NEW_AUTHTOK_REQD` instead of `PAM_SUCCESS`.

 6. If the previous step returned `PAM_NEW_AUTHTOK_REQD`, the server now calls 
    to force the client to change the authentication token for the requested 

 7. Now that the applicant has been properly authenticated, the server calls 
    to establish the credentials of the requested account. It is able to do this 
    because it acts on behalf of the arbitrator, and holds the arbitrator's 

 8. Once the correct credentials have been established, the server calls 
    to set up the session.

 9. The server now performs whatever service the client requested -- for 
    instance, provide the applicant with a shell.

10. Once the server is done serving the client, it calls 
    to tear down the session.

11. Finally, the server calls 
    to notify the PAM library that it is done and that it can release whatever 
    resources it has allocated in the course of the transaction.

## PAM Configuration

### PAM policy files

#### The `/etc/pam.conf` file

The traditional PAM policy file is `/etc/pam.conf`. This file contains all the 
PAM policies for your system. Each line of the file describes one step in a 
chain, as shown below:

    login   auth    required  no_warn

The fields are, in order: service name, facility name, control flag, module 
name, and module arguments. Any additional fields are interpreted as additional 
module arguments.

A separate chain is constructed for each service / facility pair, so while the 
order in which lines for the same service and facility appear is significant, 
the order in which the individual services and facilities are listed is not. The 
examples in the original PAM paper grouped configuration lines by facility, and 
the Solaris stock `pam.conf` still does that, but FreeBSD's stock configuration 
groups configuration lines by service. Either way is fine; either way makes 
equal sense.

#### The `/etc/pam.d` directory

OpenPAM and Linux-PAM support an alternate configuration mechanism, which is the 
preferred mechanism in FreeBSD and NetBSD. In this scheme, each policy is 
contained in a separate file bearing the name of the service it applies to. 
These files are stored in `/etc/pam.d/`.

These per-service policy files have only four fields instead of `pam.conf`'s 
five: the service name field is omitted. Thus, instead of the sample `pam.conf` 
line from the previous section, one would have the following line in 

    auth    required  no_warn

As a consequence of this simplified syntax, it is possible to use the same 
policy for multiple services by linking each service name to a same policy file. 
For instance, to use the same policy for the `su` and `sudo` services, one could 
do as follows:

    # cd /etc/pam.d
    # ln -s su sudo

This works because the service name is determined from the file name rather than 
specified in the policy file, so the same file can be used for multiple 
differently-named services.

Since each service's policy is stored in a separate file, the `pam.d` mechanism 
also makes it very easy to install additional policies for third-party software 

#### The policy search order

As we have seen above, PAM policies can be found in a number of places. If no 
configuration file is found for a particular service, the `/etc/pam.d/other` is 
used instead. If that file does not exist, `/etc/pam.conf` is searched for 
entries matching he specified service or, failing that, the "other" service.

It is essential to understand that PAM's configuration system is centered on 

### Breakdown of a configuration line

As explained in the [PAM policy files](chap-pam.html#pam-config-file "18.5.1. 
PAM policy files") section, each line in `/etc/pam.conf` consists of four or 
more fields: the service name, the facility name, the control flag, the module 
name, and zero or more module arguments.

The service name is generally (though not always) the name of the application 
the statement applies to. If you are unsure, refer to the individual 
application's documentation to determine what service name it uses.

Note that if you use `/etc/pam.d/` instead of `/etc/pam.conf`, the service name 
is specified by the name of the policy file, and omitted from the actual 
configuration lines, which then start with the facility name.

The facility is one of the four facility keywords described in the
[[Facilities and primitives|guide/pam#facilities-primitives]]] section.

Likewise, the control flag is one of the four keywords described in the [[Chains 
and policies|guide/pam#chains-policies]] section, describing how to interpret 
the return code from the module. Linux-PAM supports an alternate syntax that 
lets you specify the action to associate with each possible return code, but 
this should be avoided as it is non-standard and closely tied in with the way 
Linux-PAM dispatches service calls (which differs greatly from the way Solaris 
and OpenPAM do it.) Unsurprisingly, OpenPAM does not support this syntax.

### Policies

To configure PAM correctly, it is essential to understand how policies are 

When an application calls 
the PAM library loads the policy for the specified service and constructs four 
module chains (one for each facility.) If one or more of these chains are empty, 
the corresponding chains from the policy for the `other` service are 

When the application later calls one of the six PAM primitives, the PAM library 
retrieves the chain for the corresponding facility and calls the appropriate 
service function in each module listed in the chain, in the order in which they 
were listed in the configuration. After each call to a service function, the 
module type and the error code returned by the service function are used to 
determine what happens next. With a few exceptions, which we discuss below, the 
following table applies:

[[!table data="""
           |   `PAM_SUCCESS`   | `PAM_IGNORE` |       `other`
binding    | if (!fail) break; |      -       |     fail = true;
required   |         -         |      -       |     fail = true;
requisite  |         -         |      -       | fail = true; break;
sufficient | if (!fail) break; |      -       |          -
optional   |         -         |      -       |          -

If `fail` is true at the end of a chain, or when a `break` is reached, the 
dispatcher returns the error code returned by the first module that failed. 
Otherwise, it returns `PAM_SUCCESS`.

The first exception of note is that the error code `PAM_NEW_AUTHTOK_REQD` is 
treated like a success, except that if no module failed, and at least one module 
returned `PAM_NEW_AUTHTOK_REQD`, the dispatcher will return 

The second exception is that 
treats `binding` and `sufficient` modules as if they were `required`.

The third and final exception is that 
runs the entire chain twice (once for preliminary checks and once to actually 
set the password), and in the preliminary phase it treats `binding` and 
`sufficient` modules as if they were `required`.

## PAM modules

### Common Modules

#### pam\_deny(8)

module is one of the simplest modules available; it responds to any request with 
`PAM_AUTH_ERR`. It is useful for quickly disabling a service (add it to the top 
of every chain), or for terminating chains of `sufficient` modules.

#### pam\_echo(8)

module simply passes its arguments to the conversation function as a 
`PAM_TEXT_INFO` message. It is mostly useful for debugging, but can also serve 
to display messages such as `Unauthorized access will be prosecuted` before 
starting the authentication procedure.

#### pam\_exec(8)

module takes its first argument to be the name of a program to execute, and the 
remaining arguments are passed to that program as command-line arguments. One 
possible application is to use it to run a program at login time which mounts 
the user's home directory.

#### pam\_ftpusers(8)

module successes if and only if the user is listed in `/etc/ftpusers`. 
Currently, in NetBSD, this module doesn't understand the extended syntax of 
[ftpd(8)](, but 
this will be fixed in the future.

#### pam\_group(8)

module accepts or rejects applicants on the basis of their membership in a 
particular file group (normally `wheel` for 
[su(1)]( It is 
primarily intended for maintaining the traditional behaviour of BSD 
[su(1)](, but has 
many other uses, such as excluding certain groups of users from a particular 

In NetBSD, there is an argument called `authenticate` in which the user is asked 
to authenticate using his own password.

#### pam\_guest(8)

module allows guest logins using fixed login names. Various requirements can be 
placed on the password, but the default behaviour is to allow any password as 
long as the login name is that of a guest account. The 
module can easily be used to implement anonymous FTP logins.

#### pam\_krb5(8)

module provides functions to verify the identity of a user and to set user 
specific credentials using Kerberos 5. It prompts the user for a password and 
obtains a new Kerberos TGT for the principal. The TGT is verified by obtaining a 
service ticket for the local host. The newly acquired credentials are stored in 
a credential cache and the environment variable KRB5CCNAME is set appropriately. 
The credentials cache should be destroyed by the user at logout with 

#### pam\_ksu(8)

module provides only authentication services for Kerberos 5 to determine whether 
or not the applicant is authorized to obtain the privileges of the target 

#### pam\_lastlog(8)

module provides only session management services. It records the session in 

#### pam\_login\_access(8)

module provides an implementation of the account management primitive which 
enforces the login restrictions specified in the 

#### pam\_nologin(8)

module refuses non-root logins when `/var/run/nologin` exists. This file is 
normally created by 
when less than five minutes remain until the scheduled shutdown time.

#### pam\_permit(8)

module is one of the simplest modules available; it responds to any request with 
`PAM_SUCCESS`. It is useful as a placeholder for services where one or more 
chains would otherwise be empty.

#### pam\_radius(8)

module provides authentication services based upon the RADIUS (Remote 
Authentication Dial In User Service) protocol.

#### pam\_rhosts(8)

module provides only authentication services. It reports success if and only if 
the target user's ID is not 0 and the remote host and user are listed in 
`/etc/hosts.equiv` or in the target user's `~/.rhosts`.

#### pam\_rootok(8)

module reports success if and only if the real user id of the process calling it 
(which is assumed to be run by the applicant) is 0. This is useful for 
non-networked services such as 
[su(1)]( or 
[passwd(1)](, to 
which the `root` should have automatic access.

#### pam\_securetty(8)

module provides only account services. It is used when the applicant is 
attempting to authenticate as superuser, and the process is attached to an 
insecure TTY.

#### pam\_self(8)

module reports success if and only if the names of the applicant matches that of 
the target account. It is most useful for non-networked services such as 
[su(1)](, where the 
identity of the applicant can be easily verified.

#### pam\_ssh(8)

module provides both authentication and session services. The authentication 
service allows users who have passphrase-protected SSH secret keys in their 
`~/.ssh` directory to authenticate themselves by typing their passphrase. The 
session service starts 
and preloads it with the keys that were decrypted in the authentication phase. 
This feature is particularly useful for local logins, whether in X (using 
[xdm(1)]( or 
another PAM-aware X login manager) or at the console.

This module implements what is fundamentally a password authentication scheme. 
Care should be taken to only use this module over a secure session (secure TTY, 
encrypted session, etc.), otherwise the user's SSH passphrase could be 

Additional consideration should be given to the use of 
Users often assume that file permissions are sufficient to protect their SSH 
keys, and thus use weak or no passphrases. Since the system administrator has no 
effective means of enforcing SSH passphrase quality, this has the potential to 
expose the system to security risks.

#### pam\_unix(8)

module implements traditional UNIX® password authentication, using 
under FreeBSD or 
under NetBSD to obtain the target account's password and compare it with the one 
provided by the applicant. It also provides account management services 
(enforcing account and password expiration times) and password-changing 
services. This is probably the single most useful module, as the great majority 
of admins will want to maintain historical behaviour for at least some services.

### NetBSD-specific PAM Modules

#### pam\_skey(8)

module implements S/Key One Time Password (OTP) authentication methods, using 
the `/etc/skeykeys` database.

## PAM Application Programming

This section has not yet been written.

## PAM Module Programming

This section has not yet been written.

## Sample PAM Application

The following is a minimal implementation of 
[su(1)]( using PAM. 
Note that it uses the OpenPAM-specific 
conversation function, which is prototyped in `security/openpam.h`. If you wish 
build this application on a system with a different PAM library, you will have 
to provide your own conversation function. A robust conversation function is 
surprisingly difficult to implement; the one presented in the [Sample PAM 
Conversation Function](chap-pam.html#pam-sample-conv "18.11. Sample PAM 
Conversation Function") sub-chapter is a good starting point, but should not be 
used in real-world applications.

    #include <sys/param.h>
    #include <sys/wait.h>
    #include <err.h>
    #include <pwd.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <syslog.h>
    #include <unistd.h>
    #include <security/pam_appl.h>
    #include <security/openpam.h> /* for openpam_ttyconv() */
    extern char **environ;
    static pam_handle_t *pamh;
    static struct pam_conv pamc;
    static void
        fprintf(stderr, "Usage: su [login [args]]\n");
    main(int argc, char *argv[])
        char hostname[MAXHOSTNAMELEN];
        const char *user, *tty;
        char **args, **pam_envlist, **pam_env;
        struct passwd *pwd;
        int o, pam_err, status;
        pid_t pid;
        while ((o = getopt(argc, argv, "h")) != -1)
            switch (o) {
            case 'h':
        argc -= optind;
        argv += optind;
        if (argc > 0) {
            user = *argv;
        } else {
            user = "root";
        /* initialize PAM */
        pamc.conv = &openpam_ttyconv;
        pam_start("su", user, &pamc, &pamh);
        /* set some items */
        gethostname(hostname, sizeof(hostname));
        if ((pam_err = pam_set_item(pamh, PAM_RHOST, hostname)) != PAM_SUCCESS)
            goto pamerr;
        user = getlogin();
        if ((pam_err = pam_set_item(pamh, PAM_RUSER, user)) != PAM_SUCCESS)
            goto pamerr;
        tty = ttyname(STDERR_FILENO);
        if ((pam_err = pam_set_item(pamh, PAM_TTY, tty)) != PAM_SUCCESS)
            goto pamerr;
        /* authenticate the applicant */
        if ((pam_err = pam_authenticate(pamh, 0)) != PAM_SUCCESS)
            goto pamerr;
        if ((pam_err = pam_acct_mgmt(pamh, 0)) == PAM_NEW_AUTHTOK_REQD)
            pam_err = pam_chauthtok(pamh, PAM_CHANGE_EXPIRED_AUTHTOK);
        if (pam_err != PAM_SUCCESS)
            goto pamerr;
        /* establish the requested credentials */
        if ((pam_err = pam_setcred(pamh, PAM_ESTABLISH_CRED)) != PAM_SUCCESS)
            goto pamerr;
        /* authentication succeeded; open a session */
        if ((pam_err = pam_open_session(pamh, 0)) != PAM_SUCCESS)
            goto pamerr;
        /* get mapped user name; PAM may have changed it */
        pam_err = pam_get_item(pamh, PAM_USER, (const void **)&user);
        if (pam_err != PAM_SUCCESS || (pwd = getpwnam(user)) == NULL)
            goto pamerr;
        /* export PAM environment */
        if ((pam_envlist = pam_getenvlist(pamh)) != NULL) {
            for (pam_env = pam_envlist; *pam_env != NULL; ++pam_env) {
        /* build argument list */
        if ((args = calloc(argc + 2, sizeof *args)) == NULL) {
            goto err;
        *args = pwd->pw_shell;
        memcpy(args + 1, argv, argc * sizeof *args);
        /* fork and exec */
        switch ((pid = fork())) {
        case -1:
            goto err;
        case 0:
            /* child: give up privs and start a shell */
            /* set uid and groups */
            if (initgroups(pwd->pw_name, pwd->pw_gid) == -1) {
            if (setgid(pwd->pw_gid) == -1) {
            if (setuid(pwd->pw_uid) == -1) {
            execve(*args, args, environ);
            /* parent: wait for child to exit */
            waitpid(pid, &status, 0);
            /* close the session and release PAM resources */
            pam_err = pam_close_session(pamh, 0);
            pam_end(pamh, pam_err);
        fprintf(stderr, "Sorry\n");
        pam_end(pamh, pam_err);

## Sample PAM Module

The following is a minimal implementation of 
offering only authentication services. It should build and run with most PAM 
implementations, but takes advantage of OpenPAM extensions if available: note 
the use of 
which enormously simplifies prompting the user for a password.

    #include <sys/param.h>
    #include <pwd.h>
    #include <stdlib.h>
    #include <stdio.h>
    #include <string.h>
    #include <unistd.h>
    #include <security/pam_modules.h>
    #include <security/pam_appl.h>
    #ifndef _OPENPAM
    static char password_prompt[] = "Password:";
    #ifndef PAM_EXTERN
    #define PAM_EXTERN
    PAM_EXTERN int
    pam_sm_authenticate(pam_handle_t *pamh, int flags,
        int argc, const char *argv[])
    #ifndef _OPENPAM
        const void *ptr;
        const struct pam_conv *conv;
        struct pam_message msg;
        const struct pam_message *msgp;
        struct pam_response *resp;
        struct passwd *pwd;
        const char *user;
        char *crypt_password, *password;
        int pam_err, retry;
        /* identify user */
        if ((pam_err = pam_get_user(pamh, &user, NULL)) != PAM_SUCCESS)
            return (pam_err);
        if ((pwd = getpwnam(user)) == NULL)
            return (PAM_USER_UNKNOWN);
        /* get password */
    #ifndef _OPENPAM
        pam_err = pam_get_item(pamh, PAM_CONV, &ptr);
        if (pam_err != PAM_SUCCESS)
            return (PAM_SYSTEM_ERR);
        conv = ptr;
        msg.msg_style = PAM_PROMPT_ECHO_OFF;
        msg.msg = password_prompt;
        msgp = &msg;
        password = NULL;
        for (retry = 0; retry < 3; ++retry) {
    #ifdef _OPENPAM
            pam_err = pam_get_authtok(pamh, PAM_AUTHTOK,
                (const char **)&password, NULL);
            resp = NULL;
            pam_err = (*conv->conv)(1, &msgp, &resp, conv->appdata_ptr);
            if (resp != NULL) {
                if (pam_err == PAM_SUCCESS)
                    password = resp->resp;
            if (pam_err == PAM_SUCCESS)
        if (pam_err == PAM_CONV_ERR)
            return (pam_err);
        if (pam_err != PAM_SUCCESS)
            return (PAM_AUTH_ERR);
        /* compare passwords */
        if ((!pwd->pw_passwd[0] && (flags & PAM_DISALLOW_NULL_AUTHTOK)) ||
            (crypt_password = crypt(password, pwd->pw_passwd)) == NULL ||
            strcmp(crypt_password, pwd->pw_passwd) != 0)
            pam_err = PAM_AUTH_ERR;
            pam_err = PAM_SUCCESS;
    #ifndef _OPENPAM
        return (pam_err);
    PAM_EXTERN int
    pam_sm_setcred(pam_handle_t *pamh, int flags,
        int argc, const char *argv[])
        return (PAM_SUCCESS);
    PAM_EXTERN int
    pam_sm_acct_mgmt(pam_handle_t *pamh, int flags,
        int argc, const char *argv[])
        return (PAM_SUCCESS);
    PAM_EXTERN int
    pam_sm_open_session(pam_handle_t *pamh, int flags,
        int argc, const char *argv[])
        return (PAM_SUCCESS);
    PAM_EXTERN int
    pam_sm_close_session(pam_handle_t *pamh, int flags,
        int argc, const char *argv[])
        return (PAM_SUCCESS);
    PAM_EXTERN int
    pam_sm_chauthtok(pam_handle_t *pamh, int flags,
        int argc, const char *argv[])
        return (PAM_SERVICE_ERR);

## Sample PAM Conversation Function

The conversation function presented below is a greatly simplified version of 
It is fully functional, and should give the reader a good idea of how a 
conversation function should behave, but it is far too simple for real-world 
use. Even if you're not using OpenPAM, feel free to download the source code and 
to your uses; we believe it to be as robust as a tty-oriented conversation 
function can reasonably get.

    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <unistd.h>
    #include <security/pam_appl.h>
    converse(int n, const struct pam_message **msg,
        struct pam_response **resp, void *data)
        struct pam_response *aresp;
        char buf[PAM_MAX_RESP_SIZE];
        int i;
        data = data;
        if (n <= 0 || n > PAM_MAX_NUM_MSG)
            return (PAM_CONV_ERR);
        if ((aresp = calloc(n, sizeof *aresp)) == NULL)
            return (PAM_BUF_ERR);
        for (i = 0; i < n; ++i) {
            aresp[i].resp_retcode = 0;
            aresp[i].resp = NULL;
            switch (msg[i]->msg_style) {
            case PAM_PROMPT_ECHO_OFF:
                aresp[i].resp = strdup(getpass(msg[i]->msg));
                if (aresp[i].resp == NULL)
                    goto fail;
            case PAM_PROMPT_ECHO_ON:
                fputs(msg[i]->msg, stderr);
                if (fgets(buf, sizeof buf, stdin) == NULL)
                    goto fail;
                aresp[i].resp = strdup(buf);
                if (aresp[i].resp == NULL)
                    goto fail;
            case PAM_ERROR_MSG:
                fputs(msg[i]->msg, stderr);
                if (strlen(msg[i]->msg) > 0 &&
                    msg[i]->msg[strlen(msg[i]->msg) - 1] != '\n')
                    fputc('\n', stderr);
            case PAM_TEXT_INFO:
                fputs(msg[i]->msg, stdout);
                if (strlen(msg[i]->msg) > 0 &&
                    msg[i]->msg[strlen(msg[i]->msg) - 1] != '\n')
                    fputc('\n', stdout);
                goto fail;
        *resp = aresp;
        return (PAM_SUCCESS);
            for (i = 0; i < n; ++i) {
                    if (aresp[i].resp != NULL) {
                            memset(aresp[i].resp, 0, strlen(aresp[i].resp));
            memset(aresp, 0, n * sizeof *aresp);
        *resp = NULL;
        return (PAM_CONV_ERR);

## Further Reading

### Papers

 * *[sun-pam]: [Making Login Services Independent of Authentication Technologies](*. Vipin Samar and Charlie Lai. Sun Microsystems.
 * *[opengroup-singlesignon]: [X/Open Single Sign-on Preliminary Specification](*. The Open Group. 1-85912-144-6. June 1997.
 * *[kernelorg-pamdraft]: [Pluggable Authentication Modules](*. Andrew G. Morgan. October 6, 1999.

### User Manuals

 * *[sun-pamadmin]: [PAM Administration](*. Sun Microsystems.

### Related Web pages

 * *[openpam-website]: [OpenPAM homepage](*. Dag-Erling Smørgrav. ThinkSec AS.
 * *[linuxpam-website]: [Linux-PAM homepage](*. Andrew G. Morgan.
 * *[solarispam-website]: [Solaris PAM homepage](*. Sun Microsystems.

CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb