- The PAM API
- The PAM SPI
- Writing a PAM Service Module
- Testing the PAM Module
- Conclusion
Like this article? We recommend
Like this article? We recommend
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.
Makefiles
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)
$(SUBDIRS): FRC
@cd $@; pwd; $(MAKE) $(TARGET)
FRC:
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)
clean:
$(RM) $(OBJ) pam_compare.so.1
There are four Makefiles:
./Makefile ./Makefile.common ./sparc/Makefile ./sparcv9/Makefile
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 */ 5 6 #pragma ident "@(#)pam_compare.c 1.1 02/09/03 SMI" 7 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> 15
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;
27
28 va_start(ap, fmt);
29 (void)vsnprintf(buf, sizeof (buf), fmt, ap);
30 va_end(ap);
31
32 if (pam_get_item(pamh, PAM_CONV, (void **)&pam_convp)
!= PAM_SUCCESS) {
33 syslog(LOG_ERR, "pam_compare: Can't get PAM_CONV
item");
34 return;
35 }
36
37 if ((pam_convp == NULL) || (pam_convp->conv == NULL)) {
38 syslog(LOG_ERR, "pam_compare: no conversation
function defined");
39 return;
40 }
41
42 msg = (struct pam_message *)calloc(1, size of (struct
pam_message));
43 if (msg == NULL) {
44 syslog(LOG_ERR, "pam_compare: out of memory");
45 return;
46 }
47
48 msg->msg_style = style;
49 msg->msg = buf;
50
51 (pam_convp->conv)(1, &msg, &response, pam_convp->appdata_ptr);
52
53 if (response)
54 free(response);
55
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.
58
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;
70
71 (void)memset(in_old, 0, sizeof (in_old));
72
73 while (*old)
74 in_old[*(old++)]++;
75
76 while (*new) {
77 if (in_old[*new])
78 equal++;
79 new++;
80 }
81
82 if (equal > max)
83 return (1);
84
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 */
105
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 }
112
113 if (debug)
114 syslog(LOG_DEBUG, "pam_compare: entering
pam_sm_chauthtok");
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:
At the time you are called with the PAM_PRELIM_CHECK flag.
At the time you are called with the PAM_UPDATE_AUTHTOK flag.
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.
Note
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 }
124
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 }
130
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
**)&passwd);
143 if (pam_err != PAM_SUCCESS) {
144 syslog(LOG_ERR, "pam_compare: can't get password
item");
145 return (pam_err);
146 }
147
148 pam_err = pam_get_item(pamh, PAM_OLDAUTHTOK, (void
**)&opasswd);
149 if (pam_err != PAM_SUCCESS) {
150 syslog(LOG_ERR, "pam_compare: can't get old
password item");
151 return (pam_err);
152 }
153
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 }
163
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 */
169
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.
Note
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
*)passwd,
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,
user);
180
181 return (PAM_AUTHTOK_ERR);
182 }
183
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.