Home > Articles > Operating Systems, Server > Solaris

  • Print
  • + Share This
Like this article? We recommend

Writing a PAM Service Module

The easiest way to gain experience writing PAM service modules is to code one. The following example, pam_compare.so.1, is a stand-alone module for the PAM password stack. It enables a system administrator to prevent users from choosing a new password string that resembles their old password string.

The concept for this module is as follows: Each character in the users new password is checked against a particular character that may have been present in the users old password string. The module is based on the logic that there can only be a configurable number of matching characters between the old and new passwords. If the limit is exceeded, the new password is rejected.

The configuration of the pam_compare module is accomplished by adding the following entries to the /etc/pam.conf(4)file. These entries need to be placed before the pam_authtok_store.so.1 definition.

Here is an example of such an entry:

other   password required   pam_authtok_get.so.1
other   password requisite pam_authtok_check.so.1
other   password requisite pam_compare.so.1         maxequal=4
other   password required   pam_authtok_store.so.1

The pam_compare module accepts two flags:

  • debug: Turns on debugging messages through the syslog level LOG_DEBUG value.

  • maxequal=n: Configures the maximum number of allowable shared characters.

If the maxequal flag is not specified, old and new passwords will not be allowed to contain any shared characters.

Source Code

The source code (available on http://www.sun.com/solutions/blueprints/tools/index.html) consists of a number of files. These files are several makefiles, the C-source pam_compare.c, and the associated man page. Prerequisites are an ANSI C compiler and the make utility found in the /usr/ccs/bin/make utility. All work is performed in the Solaris 9 OE.

Note – The supplied makefiles create both 32-bit and 64-bit versions of the module. Deployable modules should be compiled for both 32- and 64-bit operation because you cannot make assumptions about whether the application using these modules is a 32-bit or 64-bit application.


A combination of makefiles that have been tested on the Solaris 9 OE are provided. You should not need to modify these files. Included in the makefiles are comments that explain what options are required to compile the PAM module. The following code box is the top-level makefile.

SUBDIRS=        sparc sparcv9

all     :=      TARGET= all
clean   :=      TARGET=clean

all clean:      $(SUBDIRS)

        @cd $@; pwd; $(MAKE) $(TARGET)


It contains the various implemented make-targets and a list of subdirectories (conveniently named after the architectures that the modules are being built for). This makefile descends into the architecture subdirectories in order to build the given target.

Each of the architecture subdirectories contain a makefile with declarations that are specific to the target architecture together with an include statement that includes the makefile with declarations common for all architectures, named Makefile.common.

The contents of the sparc/Makefile file are:

include ../Makefile.common

The contents of the sparcv9/Makefile file are:

include ../Makefile.common

CFLAGS  += -xarch=v9
LDFLAGS += -xarch=v9

These extra flags instruct the compiler to generate a 64-bit code.

The makefile containing the architecture-independent declarations (Makefile.common) contains the actual target definitions.

# -D_REENTRANT is used when writing multi-threaded code. It enables
# multi-thread-safe declarations from the system header files.
# -Kpic causes the compiler to generate code that is suitable for
# dynamic loading into an applications address space.

CFLAGS=         -D_REENTRANT -Kpic

# The -G option tells the linker to generate a shared object.
# The -z defs option forces a fatal error if any undefined
# symbols remain at the end of the link-phase (see ld(1))

LDFLAGS=        -G -z defs
LDLIBS=         -lpam -lc

VPATH=  ..
SRC=    pam_compare.c
OBJ=    $(SRC:.c=.o)

all: pam_compare.so.1

pam_compare.so.1: $(OBJ)
        $(CC) $(LDFLAGS) -o $@ $(OBJ) $(LDLIBS)

        $(RM) $(OBJ) pam_compare.so.1

There are four Makefiles:


The actual compile commands are executed in the architecture-specific directory, so remember to instruct make to look for sources in the parent directory (VPATH). The object- and resulting the library command files are placed in the architecture-specific directory.

pam_compare Source File

This section details the pam_compare.c source file, including information on how this specific PAM module is built. Examples present the best way to explain how to write your own PAM service modules, such as the following:

1  /*
2   * Copyright 2002 Sun Microsystems, Inc.  All rights reserved.
3   * Use is subject to license terms.
4   */
6  #pragma ident   "@(#)pam_compare.c      1.1     02/09/03 SMI"
8  #include <stdarg.h>
9  #include <syslog.h>
10  #include <stdio.h>
11  #include <stdlib.h>
12  #include <string.h>
13  #include <security/pam_appl.h>
14  #include <security/pam_modules.h>

In order to write a PAM module, you need to include the security/pam_appl.h file, which contains PAM error codes and structures used by the PAM API, and the security/pam_modules.h file, which contains the PAM SPI prototypes.

Because PAM service modules can't assume that the interaction with the user is based on a simple terminal-like interface (for example, compare the telnet interface and dtlogin interface)—the command printf or the function puts cannot be used to communicate with the user. Therefore, the PAM framework introduces the concept of a conversation function.

This function is supplied to the module, by the application. For any interaction with the user, the application's conversation function is called. It is up to the application to make sure that the correct interface is used to communicate with the user. For example, the dtlogin interface draws an alert box to display messages to the user, while the telnetd interface might simply perform a write command on a socket.

The following example module introduces a simple routine (pam_display()) that is used to display a one-line message to the user, using the conversation function present in the PAM handle.

16  /*
17   * Display a one-line message to the user
18   */
19  static void
20  pam_display(pam_handle_t *pamh, int style, char *fmt, ...)
21  {
22          struct pam_conv *pam_convp;
23          char buf[512];
24          va_list ap;
25          struct pam_message *msg;
26          struct pam_response *response = NULL;
28          va_start(ap, fmt);
29          (void)vsnprintf(buf, sizeof (buf), fmt, ap);
30          va_end(ap);
32          if (pam_get_item(pamh, PAM_CONV, (void **)&pam_convp)
                != PAM_SUCCESS) {
33                  syslog(LOG_ERR, "pam_compare: Can't get PAM_CONV
34                  return;
35 }
37          if ((pam_convp == NULL) || (pam_convp->conv == NULL)) {
38                  syslog(LOG_ERR, "pam_compare: no conversation
                           function defined");
39                  return;
40          }
42          msg = (struct pam_message *)calloc(1, size of (struct
43          if (msg == NULL) {
44                  syslog(LOG_ERR, "pam_compare: out of memory");
45                  return;
46 }
48          msg->msg_style = style;
49          msg->msg = buf;
51 (pam_convp->conv)(1, &msg, &response, pam_convp->appdata_ptr);
53          if (response)
54                  free(response);
56          free(msg);
57  }

In Line 25, the pam_message is the structure used to pass a prompt, an error message, or an informational message from the PAM service modules to the application. The application displays the message to the user. Note that it is the responsibility of the PAM service modules to localize the messages. The memory used by the pam_message must be allocated and freed by the PAM service modules.

In Line 26, the pam_response is a structure used to receive information back from the user. The storage used by the pam_response is allocated by the application, and should be freed by the PAM service modules.

Line 32 obtains the conversation structure, pam_conv, to retrieve the address of the function needed to call and display the information to the user. The pam_conv structure contains two members as illustrated in the following:

struct pam_conv {
   int (*conv)(int, struct pam_message **, struct pam_response **,    void *);
   void *appdata_ptr;

In Line 48, PAM defines several message styles: PAM_PROMPT_ECHO_ON, PAM_PROMPT_ECHO_OFF, PAM_ERROR_MSG, and PAM_TEXT_INFO. Even though this basic routine only deals with displaying messages (it doesn't deal with input from the user), the style attribute is parameterized as an example.

In Line 49, the application conversation function receives an array of pam_message structures. The function pointer conv contains the address of the input/output function that the service module uses to interact with the user. The extra appdata_ptr element is private to the application. The service module is supposed to supply this pointer when calling the conversation function. Because only a single message is displayed, only one element initializes and passes its address to the conversation function.

Line 51 transfers control to the application conversation function. An array of messages containing just one element are passed. Although the application should not collect any responses (this function only displays information), you should still check for responses and free any memory allocated by the application's conversation function (see line 53—54).

Line 56 frees the space allocated to pass the message to the conversation function.

59  /*
60   * int compare(old, new, max)
61   *
62   * compare the strings old and new. If more than "max"
       characters of new
63   * also appear in old, return 1 (error). Otherwise return 0.
64   */
65  static
66  int compare(unsigned char *old, unsigned char *new, int max)
67  {
68          unsigned char in_old[256];
69          int equal = 0;
71          (void)memset(in_old, 0, sizeof (in_old));
73          while (*old)
74                  in_old[*(old++)]++;
76          while (*new) {
77                  if (in_old[*new])
78                          equal++;
79                  new++;
80          }
82          if (equal > max)
83                  return (1);
85          return (0);
86  }

Lines 65—86 define a function used to compare the strings old and new. If more than "max" characters of the old string also appear in the new string, return 1 (error). Otherwise, return 0. Use this function in the PAM module to determine whether the new password chosen by the user is acceptable.

88  /*
89   * int pam_sm_chauthtok(pamh, flags, argc, argv)
90   *
91   * Make sure the old and the new password don't share too many
92   * characters.
93   */
94  int
95  pam_sm_chauthtok(pam_handle_t *pamh, int flags, int argc,
    const char **argv)
96  {
97          int i;
98          int debug = 0;
99          int maxequal = 0;
100          int pam_err;
101          char *service;
102          char *user;
103          char *passwd;   /* the newly typed password */
104          char *opasswd;  /* the user's old password */
106          for (i = 0; i < argc; i++) {
107                  if (strcmp(argv[i], "debug") == 0)
108                          debug = 1;
109                  else if (strncmp(argv[i], "maxequal=", 9) == 0)
110                          maxequal = atoi(&argv[i][9]);
111          }
113          if (debug)
114                  syslog(LOG_DEBUG, "pam_compare: entering

Line 95 defines the pam_sm_chauthtok() function, part of the PAM SPI definition. Once the module is configured in the /etc/pam.conf(4) file, the PAM framework calls this routine when the application calls the pam_chauthtok() function. This function is the entry point of the module, but it is always through the PAM framework.

Start the module by interpreting the arguments that have been specified in the /etc/pam.conf(4) file. Then accept the two different arguments, or flags in PAM terminology, debug and maxequal. Any arguments specified in the configuration file are handed over by the PAM framework. This is just like the command-line arguments presented to an application's main() function receiving an argument count (argc), and an array of character pointers (argv).

Lines 113—114 log some extra messages if the debug flag is specified.

The PAM password management stack is different from the other PAM stacks in that it invokes each of the service modules twice. The first time a service module is invoked, the PAM framework sets the PAM_PRELIM_CHECK bit in the flags, the second time the service module is invoked, the framework sets the PAM_UPDATE_AUTHTOK bit in the flags file.

The PAM_PRELIM_CHECK flag indicates to the service module that the module should not start updating any passwords, but should make sure that all the module's prerequisites for password updates are met.

The module, in this example, is quite simple because it does not depend on any other services. Be aware that more complex modules might differ in this regard. For example, a module that updates a password in an LDAP server needs to check that the LDAP server is up and running before trying to update any information. This preliminary checking avoids the chance of one module updating the password in a Network Information Service (NIS) server, while the next module fails to update the password in an unavailable LDAP server. Such a scenario would leave one module with two different passwords, and complicates future logins.

Because the PAM framework invokes each of the service modules twice, when should you perform a check? You do have three options:

  1. At the time you are called with the PAM_PRELIM_CHECK flag.

  2. At the time you are called with the PAM_UPDATE_AUTHTOK flag.

  3. Both times

Because nothing that is important to the module (old and new passwords) has changed between the first and the second time around, option 3 is not useful.

In option 1, using the PAM_PRELIM_CHECK flag, the password service only performs preliminary checks. No passwords should be updated. In option 2, using the PAM_UPDATE_AUTHTOK flag, the password service updates passwords.


PAM_PRELIM_CHECK and PAM_UPDATE_AUTHTOK cannot be set at the same time.

Performing your checks during the preliminary round makes sure that no module updates any passwords without your consent, for example, without this module returning the PAM_SUCCESS value.

The PAM_IGNORE value is returned during the second round of calls (the PAM_PRELIM_CHECK flag is not set) because you do not actually contribute to the updating process. For example:

116          if ((flags & PAM_PRELIM_CHECK) == 0)
117                  return (PAM_IGNORE);

It is important to note the difference between returning the PAM_SUCCESS value and the PAM_IGNORE value. In this case, if the PAM_SUCCESS value is returned, it might cause the complete PAM stack to succeed, even if all other modules returned the PAM_IGNORE value. You do not want the password management stack to succeed without performing any work, so you want to return the PAM_IGNORE value.

119 pam_err = pam_get_item(pamh, PAM_SERVICE, (void **)&service);
120 if (pam_err != PAM_SUCCESS) {
121 syslog(LOG_ERR, "pam_compare: error getting service item");
122 return (pam_err);
123 }
125 pam_err = pam_get_item(pamh, PAM_USER, (void **)&user);
126 if (pam_err != PAM_SUCCESS) {
127 syslog(LOG_ERR, "pam_compare: can't get user item");
128 return (pam_err);
129 }
131 /*
132 * Make sure "user" and "service" are set. Otherwise it might
133 * be misconfigured and dump core when these items are for used
134 * for error reporting.
135 */
136 if (user == NULL || service == NULL) {
137 syslog(LOG_ERR, "pam_compare: %s is NULL",
138 user == NULL ? "PAM_USER" : "PAM_SERVICE");
139 return (PAM_SYSTEM_ERR);
140 }

Although you are only interested in the old and the new passwords (the PAM items PAM_OLDAUTHTOK and PAM_AUTHTOK), you must also obtain the two other PAM items: PAM_SERVICE (the name of the application) and PAM_USER (the login name of the user whose password that is about to be updated). This information is used to create error messages.

Note that there is a distinction between the pam_get_item() function returning a value other than PAM_SUCCESS, and the item not being set by the application (for example, user == NULL). The first error indicates a problem with the PAM stack (probably a misconfiguration), while the second condition indicates a malfunctioning application because the user's password can not be changed without setting the PAM_USER item.

142          pam_err = pam_get_item(pamh, PAM_AUTHTOK, (void
143          if (pam_err != PAM_SUCCESS) {
144                  syslog(LOG_ERR, "pam_compare: can't get password
145                  return (pam_err);
146          }
148          pam_err = pam_get_item(pamh, PAM_OLDAUTHTOK, (void
149          if (pam_err != PAM_SUCCESS) {
150                  syslog(LOG_ERR, "pam_compare: can't get old
                             password item");
151                  return (pam_err);
152          }
154          /*
155           * PAM_AUTHTOK should be set. If it is NULL, the check
                   can't be performed
156           * so this module should be ignored (another module
                   will probably fail)
157           */
158          if (passwd == NULL) {
159                  if (debug)
160                          syslog(LOG_DEBUG, "pam_compare:
                             PAM_AUTHTOK = NULL.");
161                  return (PAM_IGNORE);
162          }
164          /*
165           * If PAM_OLDAUTHTOK is NULL (possible i.e. when root
                                           executes passwd)
166           * there isn't an old password to compare the new
                with. return
167           * PAM_SUCCESS since there is no reason to reject the
                new password.
168           */
170          if (opasswd == NULL)
171                  return (PAM_SUCCESS);

Lines 142 and 148, respectively, retrieve the old and new password so you can compare them. Before invoking the compare() routine, make sure that both passwords are actually set, because there might be valid reasons for these passwords to not be set.

Line 158 checks the new password. If, for whatever reason, the password is not set, you cannot perform the check. If you cannot perform the check, the result of the module should not contribute to the overall result of the password stack, as configured in /etc/pam.conf(4)file, so the PAM_IGNORE value must be returned.

You can choose to return the PAM_AUTHTOK_ERR value to force an error of the overall stack, but, in general, you should return a PAM_IGNORE value if your module somehow results in a nonoperation. This is the case for this module, if you cannot perform a check.


Please remember this about return values; besides the PAM_SUCCESS value being returned on a successful completion, error return values as described in the pam(3PAM) function may also be returned. For example, PAM_AUTHTOK_ERR indicates an authentication token manipulation error.

Also check the old password to see if it is set. There is only one valid reason why the old password might be not set, and that is if the system administrator sets the password for an ordinary user. If that is the case, then the password program doesn't always ask for the old password. So if the old password is not set, accept the new password and return the PAM_SUCCESS value.

173          if (compare((unsigned char *)opasswd, (unsigned char
174              maxequal)) {
175                  pam_display(pamh, PAM_ERROR_MSG,
176                      "%s: Your old and new password can't share
                               more than %d "
177                      "characters.", service, maxequal);
178                  syslog(LOG_WARNING, "%s: pam_compare: "
179                      "rejected new password for %s", service,
181                  return (PAM_AUTHTOK_ERR);
182          }
184          return (PAM_SUCCESS);
185  }

Now that both passwords have been retrieved, and you have made sure they are both set, call the compare() function to see if the new password should be accepted. If the compare() function reports success (returns 0), return the PAM_SUCCESS value to the PAM framework (see line 184).

If however, the compare routine reports failure (the old and new password share more than maxequal characters), inform the user of the problem (using the simple one-line-message-display-routine, pam_display()), and log a system message to record this failure (see lines 178—179). Exit the PAM module by returning the PAM_AUTHTOK_ERROR value which causes the PAM password stack to fail.

Remember that all these checks are done in the PRELIMINARY phase of the password stack traversal. Because any failure detected in this phase prevents the actual update of the password (which should happen in the next traversal), no password is changed if the PAM_AUTHTOK_ERR value is returned.

This concludes the code walkthrough of the example module, pam_compare.

  • + Share This
  • 🔖 Save To Your Account

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information

To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.


Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.


If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information

Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.


This site is not directed to children under the age of 13.


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information

If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information

Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents

California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure

Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact

Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice

We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020