1 <!doctype linuxdoc system>
7 Copyright (c) Andrew G. Morgan 1996-9. All rights reserved.
9 ** some sections, in this document, were contributed by other
10 ** authors. They carry individual copyrights.
12 Redistribution and use in source and binary forms, with or without
13 modification, are permitted provided that the following conditions are
16 1. Redistributions of source code must retain the above copyright
17 notice, and the entire permission notice in its entirety,
18 including the disclaimer of warranties.
20 2. Redistributions in binary form must reproduce the above copyright
21 notice, this list of conditions and the following disclaimer in the
22 documentation and/or other materials provided with the distribution.
24 3. The name of the author may not be used to endorse or promote
25 products derived from this software without specific prior
28 ALTERNATIVELY, this product may be distributed under the terms of the
29 GNU General Public License, in which case the provisions of the GNU
30 GPL are required INSTEAD OF the above restrictions. (This clause is
31 necessary due to a potential bad interaction between the GNU GPL and
32 the restrictions contained in a BSD-style copyright.)
34 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
35 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
36 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
37 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
38 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
39 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
40 OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
41 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
42 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
43 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
50 <title>The Linux-PAM Module Writers' Guide
51 <author>Andrew G. Morgan, <tt>morgan@linux.kernel.org</tt>
52 <date>DRAFT v0.71 1999/11/8
54 This manual documents what a programmer needs to know in order to
55 write a module that conforms to the <bf/Linux-PAM/ standard. It also
56 discusses some security issues from the point of view of the module
68 #include <security/pam_modules.h>
70 gcc -fPIC -c pam_module-name.c
71 ld -x --shared -o pam_module-name.so pam_module-name.o -lpam
78 <bf/Linux-PAM/ (Pluggable Authentication Modules for Linux) is a
79 library that enables the local system administrator to choose how
80 individual applications authenticate users. For an overview of the
81 <bf/Linux-PAM/ library see the <bf/Linux-PAM/ System Administrators'
85 A <bf/Linux-PAM/ module is a single executable binary file that can be
86 loaded by the <bf/Linux-PAM/ interface library. This PAM library is
87 configured locally with a system file, <tt>/etc/pam.conf</tt>, to
88 authenticate a user request via the locally available authentication
89 modules. The modules themselves will usually be located in the
90 directory <tt>/usr/lib/security</tt> and take the form of dynamically
91 loadable object files (see dlopen(3)). Alternatively, the modules can
92 be statically linked into the <bf/Linux-PAM/ library; this is mostly to
93 allow <bf/Linux-PAM/ to be used on platforms without dynamic linking
94 available, but the two forms can be used together. It is the
95 <bf/Linux-PAM/ interface that is called by an application and it is
96 the responsibility of the library to locate, load and call the
97 appropriate functions in a <bf/Linux-PAM/-module.
100 Except for the immediate purpose of interacting with the user
101 (entering a password etc..) the module should never call the
102 application directly. This exception requires a "conversation
103 mechanism" which is documented below.
105 <sect>What can be expected by the module
108 Here we list the interface that the conventions that all
109 <bf/Linux-PAM/ modules must adhere to.
111 <sect1>Getting and setting <tt/PAM_ITEM/s and <em/data/
114 First, we cover what the module should expect from the <bf/Linux-PAM/
115 library and a <bf/Linux-PAM/ <em/aware/ application. Essesntially this
116 is the <tt/libpam.*/ library.
125 extern int pam_set_data(pam_handle_t *pamh,
126 const char *module_data_name,
128 void (*cleanup)(pam_handle_t *pamh,
129 void *data, int error_status) );
134 The modules may be dynamically loadable objects. In general such files
135 should not contain <tt/static/ variables. This and the subsequent
136 function provide a mechanism for a module to associate some data with
137 the handle <tt/pamh/. Typically a module will call the
138 <tt/pam_set_data()/ function to register some data under a (hopefully)
139 unique <tt/module_data_name/. The data is available for use by other
140 modules too but <em/not/ by an application.
143 The function <tt/cleanup()/ is associated with the <tt/data/ and, if
144 non-<tt/NULL/, it is called when this data is over-written or
145 following a call to <tt/pam_end()/ (see the Linux-PAM Application
149 The <tt/error_status/ argument is used to indicate to the module the
150 sort of action it is to take in cleaning this data item. As an
151 example, Kerberos creates a ticket file during the authentication
152 phase, this file might be associated with a data item. When
153 <tt/pam_end()/ is called by the module, the <tt/error_status/
154 carries the return value of the <tt/pam_authenticate()/ or other
155 <tt/libpam/ function as appropriate. Based on this value the Kerberos
156 module may choose to delete the ticket file (<em/authentication
157 failure/) or leave it in place.
160 The <tt/error_status/ may have been logically OR'd with either of the
161 following two values:
165 <tag><tt/PAM_DATA_REPLACE/</tag>
166 When a data item is being replaced (through a second call to
167 <tt/pam_set_data()/) this mask is used. Otherwise, the call is assumed
168 to be from <tt/pam_end()/.
170 <tag><tt/PAM_DATA_SILENT/</tag>
171 Which indicates that the process would prefer to perform the
172 <tt/cleanup()/ quietly. That is, discourages logging/messages to the
185 extern int pam_get_data(const pam_handle_t *pamh,
186 const char *module_data_name,
192 This function together with the previous one provides a method of
193 associating module-specific data with the handle <tt/pamh/. A
194 successful call to <tt/pam_get_data/ will result in <tt/*data/
195 pointing to the data associated with the <tt/module_data_name/. Note,
196 this data is <em/not/ a copy and should be treated as <em/constant/
200 Note, if there is an entry but it has the value <tt/NULL/, then this
201 call returns <tt/PAM_NO_MODULE_DATA/.
210 extern int pam_set_item(pam_handle_t *pamh
218 This function is used to (re)set the value of one of the
219 <tt/item_type/s. The reader is urged to read the entry for this
220 function in the <bf/Linux-PAM/ application developers' manual.
223 In addition to the <tt/item/s listed there, the module can set the
224 following two <tt/item_type/s:
228 <tag><tt/PAM_AUTHTOK/</tag>
230 The authentication token (password). This token should be ignored by
231 all module functions besides <tt/pam_sm_authenticate()/ and
232 <tt/pam_sm_chauthtok()/. In the former function it is used to pass the
233 most recent authentication token from one stacked module to
234 another. In the latter function the token is used for another
235 purpose. It contains the currently active authentication token.
237 <tag><tt/PAM_OLDAUTHTOK/</tag>
239 The old authentication token. This token should be ignored by all
240 module functions except <tt/pam_sm_chauthtok()/.
245 Both of these items are reset before returning to the application.
246 When resetting these items, the <bf/Linux-PAM/ library first writes
247 <tt/0/'s to the current tokens and then <tt/free()/'s the associated
251 The return values for this function are listed in the
252 <bf>Linux-PAM</bf> Application Developers' Guide.
261 extern int pam_get_item(const pam_handle_t *pamh
269 This function is used to obtain the value of the specified
270 <tt/item_type/. It is better documented in the <bf/Linux-PAM/
271 Application Developers' Guide. However, there are three things worth
276 Generally, if the module wishes to obtain the name of the user, it
277 should not use this function, but instead perform a call to
278 <tt/pam_get_user()/ (see section <ref id="pam-get-user"
282 The module is additionally privileged to read the authentication
283 tokens, <tt/PAM_AUTHTOK/ and <tt/PAM_OLDAUTHTOK/ (see the section
284 above on <tt/pam_set_data()/).
287 The module should <em/not/ <tt/free()/ or alter the data pointed to by
288 <tt/*item/ after a successful return from <tt/pam_get_item()/. This
289 pointer points directly at the data contained within the <tt/*pamh/
290 structure. Should a module require that a change is made to the this
291 <tt/ITEM/ it should make the appropriate call to <tt/pam_set_item()/.
294 <sect2>The <em/conversation/ mechanism
297 Following the call <tt>pam_get_item(pamh,PAM_CONV,&item)</tt>, the
298 pointer <tt/item/ points to a <em/conversation/-function that provides
299 limited but direct access to the application. The purpose of this
300 function is to allow the module to prompt the user for their password
301 and pass other information in a manner consistent with the
302 application. For example, an X-windows based program might pop up a
303 dialog box to report a login failure. Just as the application should
304 not be concerned with the method of authentication, so the module
305 should not dictate the manner in which input (output) is
306 obtained from (presented to) to the user.
309 The reader is strongly urged to read the more complete description of
310 the <tt/pam_conv/ structure, written from the perspective of the
311 application developer, in the <bf/Linux-PAM/ Application Developers'
315 The <tt/pam_response/ structure returned after a call to the
316 <tt/pam_conv/ function must be <tt/free()/'d by the module. Since the
317 call to the conversation function originates from the module, it is
318 clear that either this <tt/pam_response/ structure could be either
319 statically or dynamically (using <tt/malloc()/ etc.) allocated within
320 the application. Repeated calls to the conversation function would
321 likely overwrite static memory, so it is required that for a
322 successful return from the conversation function the memory for the
323 response structure is dynamically allocated by the application with
324 one of the <tt/malloc()/ family of commands and <em/must/ be
325 <tt/free()/'d by the module.
328 If the <tt/pam_conv/ mechanism is used to enter authentication tokens,
329 the module should either pass the result to the <tt/pam_set_item()/
330 library function, or copy it itself. In such a case, once the token
331 has been stored (by one of these methods or another one), the memory
332 returned by the application should be overwritten with <tt/0/'s, and
336 The return values for this function are listed in the
337 <bf>Linux-PAM</bf> Application Developers' Guide.
339 <sect2>Getting the name of a user<label id="pam-get-user">
345 extern int pam_get_user(pam_handle_t *pamh,
352 This is a <bf/Linux-PAM/ library function that returns the
353 (prospective) name of the user. To determine the username it does the
354 following things, in this order:
357 <item> checks what <tt/pam_get_item(pamh, PAM_USER, ... );/ would have
358 returned. If this is not <tt/NULL/ this is what it returns. Otherwise,
360 <item> obtains a username from the application via the <tt/pam_conv/
361 mechanism, it prompts the user with the first non-<tt/NULL/ string in
365 <item> The <tt/prompt/ argument passed to the function
366 <item> What is returned by <tt/pam_get_item(pamh,PAM_USER_PROMPT, ... );/
367 <item> The default prompt: ``Please enter username: ''
373 By whatever means the username is obtained, a pointer to it is
374 returned as the contents of <tt/*user/. Note, this memory should
375 <em/not/ be <tt/free()/'d by the module. Instead, it will be liberated
376 on the next call to <tt/pam_get_user()/, or by <tt/pam_end()/ when the
377 application ends its interaction with <bf/Linux-PAM/.
380 Also, in addition, it should be noted that this function sets the
381 <tt/PAM_USER/ item that is associated with the <tt/pam_[gs]et_item()/
385 The return value of this function is one of the following:
388 <item> <tt/PAM_SUCCESS/ - username obtained.
390 <item> <tt/PAM_CONV_AGAIN/ - converstation did not complete and the
391 caller is required to return control to the application, until such
392 time as the application has completed the conversation process. A
393 module calling <tt/pam_get_user()/ that obtains this return code,
394 should return <tt/PAM_INCOMPLETE/ and be prepared (when invoked the
395 next time) to recall <tt/pam_get_user()/ to fill in the user's name,
396 and then pick up where it left off as if nothing had happened. This
397 procedure is needed to support an event-driven application programming
400 <item> <tt/PAM_CONV_ERR/ - the conversation method supplied by the
401 application failed to obtain the username.
405 <sect2>Setting a Linux-PAM environment variable
411 extern int pam_putenv(pam_handle_t *pamh, const char *name_value);
416 <bf/Linux-PAM/ (0.54+) comes equipped with a series of functions for
417 maintaining a set of <em/environment/ variables. The environment is
418 initialized by the call to <tt/pam_start()/ and is <bf/erased/ with a
419 call to <tt/pam_end()/. This <em/environment/ is associated with the
420 <tt/pam_handle_t/ pointer returned by the former call.
423 The default environment is all but empty. It contains a single
424 <tt/NULL/ pointer, which is always required to terminate the
425 variable-list. The <tt/pam_putenv()/ function can be used to add a
426 new environment variable, replace an existing one, or delete an old
431 <item>Adding/replacing a variable<newline>
433 To add or overwrite a <bf/Linux-PAM/ environment variable the value of
434 the argument <tt/name_value/, should be of the following form:
437 name_value="VARIABLE=VALUE OF VARIABLE"
440 Here, <tt/VARIABLE/ is the environment variable's name and what
441 follows the `<tt/=/' is its (new) value. (Note, that <tt/"VARIABLE="/
442 is a valid value for <tt/name_value/, indicating that the variable is
445 <item> Deleting a variable<newline>
447 To delete a <bf/Linux-PAM/ environment variable the value of
448 the argument <tt/name_value/, should be of the following form:
451 name_value="VARIABLE"
454 Here, <tt/VARIABLE/ is the environment variable's name and the absence
455 of an `<tt/=/' indicates that the variable should be removed.
460 In all cases <tt/PAM_SUCCESS/ indicates success.
462 <sect2>Getting a Linux-PAM environment variable
468 extern const char *pam_getenv(pam_handle_t *pamh, const char *name);
473 This function can be used to return the value of the given
474 variable. If the returned value is <tt/NULL/, the variable is not
477 <sect2>Listing the Linux-PAM environment
483 extern char * const *pam_getenvlist(pam_handle_t *pamh);
488 This function returns a pointer to the entire <bf/Linux-PAM/
489 environment array. At first sight the <em/type/ of the returned data
490 may appear a little confusing. It is basically a <em/read-only/ array
491 of character pointers, that lists the <tt/NULL/ terminated list of
492 environment variables set so far.
495 Although, this is not a concern for the module programmer, we mention
496 here that an application should be careful to copy this entire array
497 before executing <tt/pam_end()/ otherwise all the variable information
498 will be lost. (There are functions in <tt/libpam_misc/ for this
499 purpose: <tt/pam_misc_copy_env()/ and <tt/pam_misc_drop_env()/.)
501 <sect1>Other functions provided by <tt/libpam/
503 <sect2>Understanding errors
509 <tt>extern const char *pam_strerror(pam_handle_t *pamh, int errnum);</tt>
512 This function returns some text describing the <bf/Linux-PAM/ error
513 associated with the argument <tt/errnum/. If the error is not
514 recognized <tt/``Unknown Linux-PAM error''/ is returned.
518 <sect2>Planning for delays
524 <tt>extern int pam_fail_delay(pam_handle_t *pamh, unsigned int
528 This function is offered by <bf/Linux-PAM/ to facilitate time delays
529 following a failed call to <tt/pam_authenticate()/ and before control
530 is returned to the application. When using this function the module
531 programmer should check if it is available with,
534 #ifdef HAVE_PAM_FAIL_DELAY
536 #endif /* HAVE_PAM_FAIL_DELAY */
541 Generally, an application requests that a user is authenticated by
542 <bf/Linux-PAM/ through a call to <tt/pam_authenticate()/ or
543 <tt/pam_chauthtok()/. These functions call each of the <em/stacked/
544 authentication modules listed in the <bf/Linux-PAM/ configuration
545 file. As directed by this file, one of more of the modules may fail
546 causing the <tt/pam_...()/ call to return an error. It is desirable
547 for there to also be a pause before the application continues. The
548 principal reason for such a delay is security: a delay acts to
549 discourage <em/brute force/ dictionary attacks primarily, but also
550 helps hinder <em/timed/ (cf. covert channel) attacks.
553 The <tt/pam_fail_delay()/ function provides the mechanism by which an
554 application or module can suggest a minimum delay (of <tt/micro_sec/
555 <em/micro-seconds/). <bf/Linux-PAM/ keeps a record of the longest time
556 requested with this function. Should <tt/pam_authenticate()/ fail,
557 the failing return to the application is delayed by an amount of time
558 randomly distributed (by up to 25%) about this longest value.
561 Independent of success, the delay time is reset to its zero default
562 value when <bf/Linux-PAM/ returns control to the application.
566 <sect>What is expected of a module
569 The module must supply a sub-set of the six functions listed
570 below. Together they define the function of a <bf/Linux-PAM
571 module/. Module developers are strongly urged to read the comments on
572 security that follow this list.
577 The six module functions are grouped into four independent management
578 groups. These groups are as follows: <em/authentication/,
579 <em/account/, <em/session/ and <em/password/. To be properly defined,
580 a module must define all functions within at least one of these
581 groups. A single module may contain the necessary functions for
582 <em/all/ four groups.
584 <sect2> Functional independence
587 The independence of the four groups of service a module can offer
588 means that the module should allow for the possibility that any one of
589 these four services may legitimately be called in any order. Thus, the
590 module writer should consider the appropriateness of performing a
591 service without the prior success of some other part of the module.
594 As an informative example, consider the possibility that an
595 application applies to change a user's authentication token, without
596 having first requested that <bf/Linux-PAM/ authenticate the user. In
597 some cases this may be deemed appropriate: when <tt/root/ wants to
598 change the authentication token of some lesser user. In other cases it
599 may not be appropriate: when <tt/joe/ maliciously wants to reset
600 <tt/alice/'s password; or when anyone other than the user themself
601 wishes to reset their <em/KERBEROS/ authentication token. A policy for
602 this action should be defined by any reasonable authentication scheme,
603 the module writer should consider this when implementing a given
606 <sect2> Minimizing administration problems
609 To avoid system administration problems and the poor construction of a
610 <tt>/etc/pam.conf</tt> file, the module developer may define all
611 six of the following functions. For those functions that would not be
612 called, the module should return <tt/PAM_SERVICE_ERR/ and write an
613 appropriate message to the system log. When this action is deemed
614 inappropriate, the function would simply return <tt/PAM_IGNORE/.
616 <sect2> Arguments supplied to the module
619 The <tt/flags/ argument of each of the following functions can be
620 logically OR'd with <tt/PAM_SILENT/, which is used to inform the
621 module to not pass any <em/text/ (errors or warnings) to the
625 The <tt/argc/ and <tt/argv/ arguments are taken from the line
626 appropriate to this module---that is, with the <em/service_name/
627 matching that of the application---in the configuration file (see the
628 <bf/Linux-PAM/ System Administrators' Guide). Together these two
629 parameters provide the number of arguments and an array of pointers to
630 the individual argument tokens. This will be familiar to C programmers
631 as the ubiquitous method of passing command arguments to the function
632 <tt/main()/. Note, however, that the first argument (<tt/argv[0]/) is
633 a true argument and <bf/not/ the name of the module.
635 <sect1> Authentication management
638 To be correctly initialized, <tt/PAM_SM_AUTH/ must be <tt/#define/'d
639 prior to including <tt><security/pam_modules.h></tt>. This will
640 ensure that the prototypes for static modules are properly declared.
646 <tt>PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags,
647 int argc, const char **argv);</tt>
650 This function performs the task of authenticating the user.
653 The <tt/flags/ argument can be a logically OR'd with <tt/PAM_SILENT/
654 and optionally take the following value:
657 <tag><tt/PAM_DISALLOW_NULL_AUTHTOK/</tag>
658 return <tt/PAM_AUTH_ERR/ if the database of authentication
659 tokens for this authentication mechanism has a <tt/NULL/ entry for the
660 user. Without this flag, such a <tt/NULL/ token will lead to a success
661 without the user being prompted.
665 Besides <tt/PAM_SUCCESS/ return values that can be sent by this
666 function are one of the following:
670 <tag><tt/PAM_AUTH_ERR/</tag>
671 The user was not authenticated
672 <tag><tt/PAM_CRED_INSUFFICIENT/</tag>
673 For some reason the application does not have sufficient
674 credentials to authenticate the user.
675 <tag><tt/PAM_AUTHINFO_UNAVAIL/</tag>
676 The modules were not able to access the authentication
677 information. This might be due to a network or hardware failure etc.
678 <tag><tt/PAM_USER_UNKNOWN/</tag>
679 The supplied username is not known to the authentication
681 <tag><tt/PAM_MAXTRIES/</tag>
682 One or more of the authentication modules has reached its
683 limit of tries authenticating the user. Do not try again.
688 <tt>PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags, int
689 argc, const char **argv);</tt>
692 This function performs the task of altering the credentials of the
693 user with respect to the corresponding authorization
694 scheme. Generally, an authentication module may have access to more
695 information about a user than their authentication token. This
696 function is used to make such information available to the
697 application. It should only be called <em/after/ the user has been
698 authenticated and after a session has been established.
701 Permitted flags, one of which, may be logically OR'd with
705 <tag><tt/PAM_ESTABLISH_CRED/</tag>
706 Set the credentials for the authentication service,
707 <tag><tt/PAM_DELETE_CRED/</tag>
708 Delete the credentials associated with the authentication service,
709 <tag><tt/PAM_REINITIALIZE_CRED/</tag>
710 Reinitialize the user credentials, and
711 <tag><tt/PAM_REFRESH_CRED/</tag>
712 Extend the lifetime of the user credentials.
716 Generally, the module should attempt to return the same error code as
717 <tt/pam_sm_authenticate/ did. This will preserve the logic followed
718 by libpam as it executes the stack of <em/authentication/ modules,
719 when the application calls <tt/pam_authenticate()/ and
720 <tt/pam_setcred()/. Failing to do this, will lead to much confudion
721 on the part of the System administrator.
724 <bf>The following text is depreciated. Some thought needs to be given to
725 how the credential setting modules are supposed to be stacked...</bf>
728 Besides <tt/PAM_SUCCESS/, the module may return one of the following
732 <tag><tt/PAM_CRED_UNAVAIL/</tag>
733 This module cannot retrieve the user's credentials.
734 <tag><tt/PAM_CRED_EXPIRED/</tag>
735 The user's credentials have expired.
736 <tag><tt/PAM_USER_UNKNOWN/</tag>
737 The user is not known to this authentication module.
738 <tag><tt/PAM_CRED_ERR/</tag>
739 This module was unable to set the credentials of the user.
744 <sect1> Account management
747 To be correctly initialized, <tt/PAM_SM_ACCOUNT/ must be
748 <tt/#define/'d prior to including <tt><security/pam_modules.h></tt>.
749 This will ensure that the prototype for a static module is properly
756 <tt>PAM_EXTERN int pam_sm_acct_mgmt(pam_handle_t *pamh, int flags, int
757 argc, const char **argv);</tt>
760 This function performs the task of establishing whether the user is
761 permitted to gain access at this time. It should be understood that
762 the user has previously been validated by an authentication
763 module. This function checks for other things. Such things might be:
764 the time of day or the date, the terminal line, remote
768 This function may also determine things like the expiration on
769 passwords, and respond that the user change it before continuing.
772 Valid flags, which may be logically OR'd with <tt/PAM_SILENT/, are the
773 same as those applicable to the <tt/flags/ argument of
774 <tt/pam_sm_authenticate/.
777 This function may return one of the following errors,
781 <tag><tt/PAM_ACCT_EXPIRED/</tag>
782 The user is no longer permitted access to the system.
783 <tag><tt/PAM_AUTH_ERR/</tag>
784 There was an authentication error.
785 <tag><tt/PAM_AUTHTOKEN_REQD/</tag>
786 The user's authentication token has expired. Before calling
787 this function again the application will arrange for a new one to be
788 given. This will likely result in a call to <tt/pam_sm_chauthtok()/.
789 <tag><tt/PAM_USER_UNKNOWN/</tag>
790 The user is not known to the module's account management
797 <sect1> Session management
800 To be correctly initialized, <tt/PAM_SM_SESSION/ must be
801 <tt/#define/'d prior to including
802 <tt><security/pam_modules.h></tt>. This will ensure that the
803 prototypes for static modules are properly declared.
806 The following two functions are defined to handle the
807 initialization/termination of a session. For example, at the beginning
808 of a session the module may wish to log a message with the system
809 regarding the user. Similarly, at the end of the session the module
810 would inform the system that the user's session has ended.
813 It should be possible for sessions to be opened by one application and
814 closed by another. This either requires that the module uses only
815 information obtained from <tt/pam_get_item()/, or that information
816 regarding the session is stored in some way by the operating system
817 (in a file for example).
823 <tt>PAM_EXTERN int pam_sm_open_session(pam_handle_t *pamh, int flags, int
824 argc, const char **argv);</tt>
827 This function is called to commence a session. The only valid, but
828 optional, flag is <tt/PAM_SILENT/.
831 As a return value, <tt/PAM_SUCCESS/ signals success and
832 <tt/PAM_SESSION_ERR/ failure.
835 <tt>PAM_EXTERN int pam_sm_close_session(pam_handle_t *pamh, int flags, int
836 argc, const char **argv);</tt>
839 This function is called to terminate a session. The only valid, but
840 optional, flag is <tt/PAM_SILENT/.
843 As a return value, <tt/PAM_SUCCESS/ signals success and
844 <tt/PAM_SESSION_ERR/ failure.
848 <sect1> Password management
851 To be correctly initialized, <tt/PAM_SM_PASSWORD/ must be
852 <tt/#define/'d prior to including <tt><security/pam_modules.h></tt>.
853 This will ensure that the prototype for a static module is properly
860 <tt>PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int
861 argc, const char **argv);</tt>
864 This function is used to (re-)set the authentication token of the
865 user. A valid flag, which may be logically OR'd with <tt/PAM_SILENT/,
866 can be built from the following list,
869 <tag><tt/PAM_CHANGE_EXPIRED_AUTHTOK/</tag>
870 This argument indicates to the module that the users
871 authentication token (password) should only be changed if it has
872 expired. This flag is optional and <em/must/ be combined with one of
873 the following two flags. Note, however, the following two options are
874 <em/mutually exclusive/.
876 <tag><tt/PAM_PRELIM_CHECK/</tag>
877 This indicates that the modules are being probed as to their
878 ready status for altering the user's authentication token. If the
879 module requires access to another system over some network it should
880 attempt to verify it can connect to this system on receiving this
881 flag. If a module cannot establish it is ready to update the user's
882 authentication token it should return <tt/PAM_TRY_AGAIN/, this
883 information will be passed back to the application.
885 <tag><tt/PAM_UPDATE_AUTHTOK/</tag>
886 This informs the module that this is the call it should change
887 the authorization tokens. If the flag is logically OR'd with
888 <tt/PAM_CHANGE_EXPIRED_AUTHTOK/, the token is only changed if it has
894 Note, the <bf/Linux-PAM/ library calls this function twice in
895 succession. The first time with <tt/PAM_PRELIM_CHECK/ and then, if the
896 module does not return <tt/PAM_TRY_AGAIN/, subsequently with
897 <tt/PAM_UPDATE_AUTHTOK/. It is only on the second call that the
898 authorization token is (possibly) changed.
901 <tt/PAM_SUCCESS/ is the only successful return value, valid
905 <tag><tt/PAM_AUTHTOK_ERR/</tag>
906 The module was unable to obtain the new authentication token.
908 <tag><tt/PAM_AUTHTOK_RECOVERY_ERR/</tag>
909 The module was unable to obtain the old authentication token.
911 <tag><tt/PAM_AUTHTOK_LOCK_BUSY/</tag>
912 Cannot change the authentication token since it is currently
915 <tag><tt/PAM_AUTHTOK_DISABLE_AGING/</tag>
916 Authentication token aging has been disabled.
918 <tag><tt/PAM_PERM_DENIED/</tag>
921 <tag><tt/PAM_TRY_AGAIN/</tag>
922 Preliminary check was unsuccessful. Signals an immediate return
923 to the application is desired.
925 <tag><tt/PAM_USER_UNKNOWN/</tag>
926 The user is not known to the authentication token changing
933 <sect>Generic optional arguments
936 Here we list the generic arguments that all modules can expect to
937 be passed. They are not mandatory, and their absence should be
938 accepted without comment by the module.
942 <tag><tt/debug/</tag>
944 Use the <tt/syslog(3)/ call to log debugging information to the system
947 <tag><tt/no_warn/</tag>
949 Instruct module to not give warning messages to the application.
951 <tag><tt/use_first_pass/</tag>
953 The module should not prompt the user for a password. Instead, it
954 should obtain the previously typed password (by a call to
955 <tt/pam_get_item()/ for the <tt/PAM_AUTHTOK/ item), and use that. If
956 that doesn't work, then the user will not be authenticated. (This
957 option is intended for <tt/auth/ and <tt/passwd/ modules only).
959 <tag><tt/try_first_pass/</tag>
961 The module should attempt authentication with the previously typed
962 password (by a call to <tt/pam_get_item()/ for the <tt/PAM_AUTHTOK/
963 item). If that doesn't work, then the user is prompted for a
964 password. (This option is intended for <tt/auth/ modules only).
966 <tag><tt/use_mapped_pass/</tag>
968 <bf/WARNING:/ coding this functionality may cause the module writer to
969 break <em/local/ encryption laws. For example, in the U.S. there are
970 restrictions on the export computer code that is capable of strong
971 encryption. It has not been established whether this option is
972 affected by this law, but one might reasonably assume that it does
973 until told otherwise. For this reason, this option is not supported
974 by any of the modules distributed with <bf/Linux-PAM/.
976 The intended function of this argument, however, is that the module
977 should take the existing authentication token from a previously
978 invoked module and use it as a key to retrieve the authentication
979 token for this module. For example, the module might create a strong
980 hash of the <tt/PAM_AUTHTOK/ item (established by a previously
981 executed module). Then, with logical-exclusive-or, use the result as a
982 <em/key/ to safely store/retrieve the authentication token for this
983 module in/from a local file <em/etc/. .
985 <tag><tt/expose_account/</tag>
988 In general the leakage of some information about user accounts is not
989 a secure policy for modules to adopt. Sometimes information such as
990 users names or home directories, or preferred shell, can be used to
991 attack a user's account. In some circumstances, however, this sort of
992 information is not deemed a threat: displaying a user's full name when
993 asking them for a password in a secured environment could also be
994 called being 'friendly'. The <tt/expose_account/ argument is a
995 standard module argument to encourage a module to be less discrete
996 about account information as it is deemed appropriate by the local
1001 <sect>Programming notes
1004 Here we collect some pointers for the module writer to bear in mind
1005 when writing/developing a <bf/Linux-PAM/ compatible module.
1007 <sect1>Security issues for module creation
1009 <sect2>Sufficient resources
1012 Care should be taken to ensure that the proper execution of a module
1013 is not compromised by a lack of system resources. If a module is
1014 unable to open sufficient files to perform its task, it should fail
1015 gracefully, or request additional resources. Specifically, the
1016 quantities manipulated by the <tt/setrlimit(2)/ family of commands
1017 should be taken into consideration.
1022 Generally, the module may wish to establish the identity of the user
1023 requesting a service. This may not be the same as the username
1024 returned by <tt/pam_get_user()/. Indeed, that is only going to be the
1025 name of the user under whose identity the service will be given. This
1026 is not necessarily the user that requests the service.
1029 In other words, user X runs a program that is setuid-Y, it grants the
1030 user to have the permissions of Z. A specific example of this sort of
1031 service request is the <em/su/ program: user <tt/joe/ executes
1032 <em/su/ to become the user <em/jane/. In this situation X=<tt/joe/,
1033 Y=<tt/root/ and Z=<tt/jane/. Clearly, it is important that the module
1034 does not confuse these different users and grant an inappropriate
1038 The following is the convention to be adhered to when juggling
1043 <item>X, the identity of the user invoking the service request.
1044 This is the user identifier; returned by the function <tt/getuid(2)/.
1046 <item>Y, the privileged identity of the application used to grant the
1047 requested service. This is the <em/effective/ user identifier;
1048 returned by the function <tt/geteuid(2)/.
1050 <item>Z, the user under whose identity the service will be granted.
1051 This is the username returned by <tt/pam_get_user(2)/ and also stored
1052 in the <bf/Linux-PAM/ item, <tt/PAM_USER/.
1054 <item><bf/Linux-PAM/ has a place for an additional user identity that
1055 a module may care to make use of. This is the <tt/PAM_RUSER/ item.
1056 Generally, network sensitive modules/applications may wish to set/read
1057 this item to establish the identity of the user requesting a service
1058 from a remote location.
1063 Note, if a module wishes to modify the identity of either the <tt/uid/
1064 or <tt/euid/ of the running process, it should take care to restore
1065 the original values prior to returning control to the <bf/Linux-PAM/
1068 <sect2>Using the conversation function
1070 Prior to calling the conversation function, the module should reset
1071 the contents of the pointer that will return the applications
1072 response. This is a good idea since the application may fail to fill
1073 the pointer and the module should be in a position to notice!
1076 The module should be prepared for a failure from the conversation. The
1077 generic error would be <tt/PAM_CONV_ERR/, but anything other than
1078 <tt/PAM_SUCCESS/ should be treated as indicating failure.
1080 <sect2>Authentication tokens
1083 To ensure that the authentication tokens are not left lying around the
1084 items, <tt/PAM_AUTHTOK/ and <tt/PAM_OLDAUTHTOK/, are not available to
1085 the application: they are defined in
1086 <tt><security/pam_modules.h></tt>. This is ostensibly for
1087 security reasons, but a maliciously programmed application will always
1088 have access to all memory of the process, so it is only superficially
1089 enforced. As a general rule the module should overwrite
1090 authentication tokens as soon as they are no longer needed.
1091 Especially before <tt/free()/'ing them. The <bf/Linux-PAM/ library is
1092 required to do this when either of these authentication token items
1096 Not to dwell too little on this concern; should the module store the
1097 authentication tokens either as (automatic) function variables or
1098 using <tt/pam_[gs]et_data()/ the associated memory should be
1099 over-written explicitly before it is released. In the case of the
1100 latter storage mechanism, the associated <tt/cleanup()/ function
1101 should explicitly overwrite the <tt/*data/ before <tt/free()/'ing it:
1107 * An example cleanup() function for releasing memory that was used to
1111 int cleanup(pam_handle_t *pamh, void *data, int error_status)
1125 <sect1>Use of <tt/syslog(3)/
1128 Only rarely should error information be directed to the user. Usually,
1129 this is to be limited to ``<em/sorry you cannot login now/'' type
1130 messages. Information concerning errors in the configuration file,
1131 <tt>/etc/pam.conf</tt>, or due to some system failure encountered by
1132 the module, should be written to <tt/syslog(3)/ with
1133 <em/facility-type/ <tt/LOG_AUTHPRIV/.
1136 With a few exceptions, the level of logging is, at the discretion of
1137 the module developer. Here is the recommended usage of different
1144 As a general rule, errors encountered by a module should be logged at
1145 the <tt/LOG_ERR/ level. However, information regarding an unrecognized
1146 argument, passed to a module from an entry in the
1147 <tt>/etc/pam.conf</tt> file, is <bf/required/ to be logged at the
1151 Debugging information, as activated by the <tt/debug/ argument to the
1152 module in <tt>/etc/pam.conf</tt>, should be logged at the
1153 <tt/LOG_DEBUG/ level.
1156 If a module discovers that its personal configuration file or some
1157 system file it uses for information is corrupted or somehow unusable,
1158 it should indicate this by logging messages at level, <tt/LOG_ALERT/.
1161 Shortages of system resources, such as a failure to manipulate a file
1162 or <tt/malloc()/ failures should be logged at level <tt/LOG_CRIT/.
1165 Authentication failures, associated with an incorrectly typed password
1166 should be logged at level, <tt/LOG_NOTICE/.
1170 <sect1> Modules that require system libraries
1173 Writing a module is much like writing an application. You have to
1174 provide the "conventional hooks" for it to work correctly, like
1175 <tt>pam_sm_authenticate()</tt> etc., which would correspond to the
1176 <tt/main()/ function in a normal function.
1179 Typically, the author may want to link against some standard system
1180 libraries. As when one compiles a normal program, this can be done for
1181 modules too: you simply append the <tt>-l</tt><em>XXX</em> arguments
1182 for the desired libraries when you create the shared module object. To
1183 make sure a module is linked to the <tt>lib<em>whatever</em>.so</tt>
1184 library when it is <tt>dlopen()</tt>ed, try:
1187 % gcc -shared -Xlinker -x -o pam_module.so pam_module.o -lwhatever
1191 <sect1> Added requirements for <em/statically/ loaded modules.
1194 Copyright (C) Michael K. Johnson 1996.
1195 Last modified: AGM 1996/5/31.
1199 Modules may be statically linked into libpam. This should be true of
1200 all the modules distributed with the basic <bf/Linux-PAM/
1201 distribution. To be statically linked, a module needs to export
1202 information about the functions it contains in a manner that does not
1203 clash with other modules.
1205 The extra code necessary to build a static module should be delimited
1206 with <tt/#ifdef PAM_STATIC/ and <tt/#endif/. The static code should do
1209 <item> Define a single structure, <tt/struct pam_module/, called
1210 <tt>_pam_<it>modname</it>_modstruct</tt>, where
1211 <tt><it>modname</it></tt> is the name of the module <bf/as used in the
1212 filesystem/ but without the leading directory name (generally
1213 <tt>/usr/lib/security/</tt> or the suffix (generally <tt/.so/).
1218 As a simple example, consider the following module code which defines
1219 a module that can be compiled to be <em/static/ or <em/dynamic/:
1224 #include <stdio.h> /* for NULL define */
1226 #define PAM_SM_PASSWORD /* the only pam_sm_... function declared */
1227 #include <security/pam_modules.h>
1229 PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags,
1230 int argc, const char **argv)
1235 #ifdef PAM_STATIC /* for the case that this module is static */
1237 struct pam_module _pam_modname_modstruct = { /* static module data */
1247 #endif /* end PAM_STATIC */
1252 To be linked with <em/libpam/, staticly-linked modules must be built
1253 from within the <tt>Linux-PAM-X.YY/modules/</tt> subdirectory of the
1254 <bf/Linux-PAM/ source directory as part of a normal build of the
1255 <bf/Linux-PAM/ system.
1257 The <em/Makefile/, for the module in question, must execute the
1258 <tt/register_static/ shell script that is located in the
1259 <tt>Linux-PAM-X.YY/modules/</tt> subdirectory. This is to ensure that
1260 the module is properly registered with <em/libpam/.
1262 The <bf/two/ manditory arguments to <tt/register_static/ are the
1263 title, and the pathname of the object file containing the module's
1264 code. The pathname is specified relative to the
1265 <tt>Linux-PAM-X.YY/modules</tt> directory. The pathname may be an
1266 empty string---this is for the case that a single object file needs to
1267 register more than one <tt/struct pam_module/. In such a case, exactly
1268 one call to <tt/register_static/ must indicate the object file.
1271 Here is an example; a line in the <em/Makefile/ might look like this:
1276 (cd ..; ./register_static pam_modname pam_modname/pam_modname.o)
1281 For some further examples, see the <tt>modules</tt> subdirectory of
1282 the current <bf/Linux-PAM/ distribution.
1285 <sect>An example module file
1289 perhaps this should point to a place in the file structure!?
1296 <tag><tt>/usr/lib/libpam.so.*</tt></tag>
1298 the shared library providing applications with access to
1301 <tag><tt>/etc/pam.conf</tt></tag>
1303 the <bf/Linux-PAM/ configuration file.
1305 <tag><tt>/usr/lib/security/pam_*.so</tt></tag>
1307 the primary location for <bf/Linux-PAM/ dynamically loadable object
1315 <item>The <bf/Linux-PAM/ System Administrators' Guide.
1316 <item>The <bf/Linux-PAM/ Application Writers' Guide.
1318 V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH PLUGGABLE
1319 AUTHENTICATION MODULES'', Open Software Foundation Request For
1320 Comments 86.0, October 1995.
1326 I intend to put development comments here... like ``at the moment
1327 this isn't actually supported''. At release time what ever is in
1328 this section will be placed in the Bugs section below! :)
1333 Perhaps we should keep a registry of data-names as used by
1334 <tt/pam_[gs]et_data()/ so there are no unintentional problems due to
1338 <tt/pam_strerror()/ should be internationalized....
1341 There has been some debate about whether <tt/initgroups()/ should be
1342 in an application or in a module. It was settled by Sun who stated
1343 that initgroups is an action of the <em/application/. The modules are
1344 permitted to add additional groups, however.
1347 Refinements/futher suggestions to <tt/syslog(3)/ usage by modules are
1352 <sect>Author/acknowledgments
1355 This document was written by Andrew G. Morgan
1356 (<tt/morgan@transmeta.com/) with many contributions from
1357 <!-- insert credits here -->
1359 an sgml list of people to credit for their contributions to Linux-PAM
1367 Derrick J. Brashear,
1386 Luke Kenneth Casson Leighton,
1389 Marek Michalkiewicz,
1399 Savochkin Andrey Vladimirovich,
1408 Thanks are also due to Sun Microsystems, especially to Vipin Samar and
1409 Charlie Lai for their advice. At an early stage in the development of
1410 <bf/Linux-PAM/, Sun graciously made the documentation for their
1411 implementation of PAM available. This act greatly accelerated the
1412 development of <bf/Linux-PAM/.
1414 <sect>Bugs/omissions
1417 Few PAM modules currently exist. Few PAM-aware applications exist.
1418 This document is hopelessly unfinished. Only a partial list of people is
1419 credited for all the good work they have done.
1421 <sect>Copyright information for this document
1424 Copyright (c) Andrew G. Morgan 1996, 1997. All rights reserved.
1426 Email: <tt><morgan@transmeta.com></tt>
1429 Redistribution and use in source and binary forms, with or without
1430 modification, are permitted provided that the following conditions are
1437 1. Redistributions of source code must retain the above copyright
1438 notice, and the entire permission notice in its entirety,
1439 including the disclaimer of warranties.
1442 2. Redistributions in binary form must reproduce the above copyright
1443 notice, this list of conditions and the following disclaimer in the
1444 documentation and/or other materials provided with the distribution.
1447 3. The name of the author may not be used to endorse or promote
1448 products derived from this software without specific prior
1454 <bf/Alternatively/, this product may be distributed under the terms of
1455 the GNU General Public License (GPL), in which case the provisions of
1456 the GNU GPL are required <bf/instead of/ the above restrictions.
1457 (This clause is necessary due to a potential bad interaction between
1458 the GNU GPL and the restrictions contained in a BSD-style copyright.)
1461 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
1462 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1463 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1464 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
1465 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
1466 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
1467 OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1468 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
1469 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
1470 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH