9 Open Software Foundation V. Samar (SunSoft)
10 Request For Comments: 86.0 R. Schemers (SunSoft)
16 PLUGGABLE AUTHENTICATION MODULES (PAM)
21 Since low-level authentication mechanisms constantly evolve, it is
22 important to shield the high-level consumers of these mechanisms
23 (system-entry services and users) from such low-level changes. With
24 the Pluggable Authentication Module (PAM) framework, we can provide
25 pluggability for a variety of system-entry services -- not just
26 system authentication _per se_, but also for account, session and
27 password management. PAM's ability to _stack_ authentication modules
28 can be used to integrate `login' with different authentication
29 mechanisms such as RSA, DCE, and Kerberos, and thus unify login
30 mechanisms. The PAM framework can also provide easy integration of
31 smart cards into the system.
33 Modular design and pluggability have become important for users who
34 want ease of use. In the PC hardware arena, no one wants to set the
35 interrupt vector numbers or resolve the addressing conflict between
36 various devices. In the software arena, people also want to be able
37 to replace components easily for easy customization, maintenance, and
40 Authentication software deserves special attention because
41 authentication forms a very critical component of any secure computer
42 system. The authentication infrastructure and its components may
43 have to be modified or replaced either because some deficiencies have
44 been found in the current algorithms, or because sites want to
45 enforce a different security policy than what was provided by the
46 system vendor. The replacement and modification should be done in
47 such a way that the user is not affected by these changes.
49 The solution has to address not just how the applications use the new
50 authentication mechanisms in a generic fashion, but also how the user
51 will be authenticated to these mechanisms in a generic way. The
52 former is addressed by GSS-API [Linn 93], while this RFC addresses
53 the later; these two efforts are complementary to each other.
55 Since most system-entry services (for example, `login', `dtlogin',
56 `rlogin', `ftp', `rsh') may want to be independent of the specific
57 authentication mechanisms used by the machine, it is important that
58 there be a framework for _plugging_ in various mechanisms. This
59 requires that the system applications use a standard API to interact
63 Samar, Schemers Page 1
71 OSF-RFC 86.0 PAM October 1995
75 with the authentication services. If these system-entry services
76 remain independent of the actual mechanism used on that machine, the
77 system administrator can install suitable authentication modules
78 without requiring changes to these applications.
80 For any security system to be successful, it has to be easy to use.
81 In the case of authentication, the single most important ease-of-use
82 characteristic is that the user should not be required to learn about
83 various ways of authentication and remember multiple passwords.
84 Ideally, there should be one all-encompassing authentication system
85 where there is only one password, but for heterogeneous sites,
86 multiple authentication mechanisms have to co-exist. The problem of
87 integrating multiple authentication mechanisms such as Kerberos
88 [Steiner 88], RSA [Rivest 78], and Diffie-Hellman [Diffie 76, Taylor
89 88], is also referred to as _integrated login_, or _unified login_
90 problem. Even if the user has to use multiple authentication
91 mechanisms, the user should not be forced to type multiple passwords.
92 Furthermore, the user should be able to use the new network identity
93 without taking any further actions. The key here is in modular
94 integration of the network authentication technologies with `login'
95 and other system-entry services.
97 In this RFC we discuss the architecture and design of pluggable
98 authentication modules. This design gives the capability to use
99 field-replaceable authentication modules along with unified login
100 capability. It thus provides for both _pluggability_ and _ease-of-
103 The RFC is organized as follows. We first motivate the need for a
104 generic way to authenticate the user by various system-entry services
105 within the operating system. We describe the goals and constraints
106 of the design. This leads to the architecture, description of the
107 interfaces, and _stacking_ of modules to get unified login
108 functionality. We then describe our experience with the design, and
109 end with a description of future work.
112 2. OVERVIEW OF IDENTIFICATION AND AUTHENTICATION MECHANISMS
114 An identification and authentication ("I&A") mechanism is used to
115 establish a user's identity the system (i.e., to a local machine's
116 operating system) and to other principals on the network. On a
117 typical UNIX system, there are various ports of entry into the
118 system, such as `login', `dtlogin', `rlogin', `ftp', `rsh', `su', and
119 `telnet'. In all cases, the user has to be identified and
120 authenticated before granting appropriate access rights to the user.
121 The user identification and authentication for all these entry points
122 needs to be coordinated to ensure a secure system.
124 In most of the current UNIX systems, the login mechanism is based
125 upon verification of the password using the modified DES algorithm.
129 Samar, Schemers Page 2
137 OSF-RFC 86.0 PAM October 1995
141 The security of the implementation assumes that the password cannot
142 be guessed, and that the password does not go over the wire in the
143 clear. These assumptions, however, are not universally valid.
144 Various programs are now available freely on the Internet that can
145 run dictionary attack against the encrypted password. Further, some
146 of the network services (for example, `rlogin', `ftp', `telnet') send
147 the password over in clear, and there are "sniffer" programs freely
148 available to steal these passwords. The classical assumptions may be
149 acceptable on a trusted network, but in an open environment there is
150 a need to use more restrictive and stronger authentication
151 mechanisms. Examples of such mechanisms include Kerberos, RSA,
152 Diffie-Hellman, one-time password [Skey 94], and challenge-response
153 based smart card authentication systems. Since this list will
154 continue to evolve, it is important that the system-entry services do
155 not have hard-coded dependencies on any of these authentication
161 The goals of the PAM framework are as follows:
163 (a) The system administrator should be able to choose the default
164 authentication mechanism for the machine. This can range from
165 a simple password-based mechanism to a biometric or a smart
168 (b) It should be possible to configure the user authentication
169 mechanism on a per application basis. For example, a site may
170 require S/Key password authentication for `telnet' access,
171 while allowing machine `login' sessions with just UNIX password
174 (c) The framework should support the display requirements of the
175 applications. For example, for a graphical login session such
176 as `dtlogin', the user name and the password may have to be
177 entered in a new window. For networking system-entry
178 applications such as `ftp' and `telnet', the user name and
179 password has to be transmitted over the network to the client
182 (d) It should be possible to configure multiple authentication
183 protocols for each of those applications. For example, one may
184 want the users to get authenticated by both Kerberos and RSA
185 authentication systems.
187 (e) The system administrator should be able to _stack_ multiple
188 user authentication mechanisms such that the user is
189 authenticated with all authentication protocols without
190 retyping the password.
195 Samar, Schemers Page 3
203 OSF-RFC 86.0 PAM October 1995
207 (f) The architecture should allow for multiple passwords if
208 necessary to achieve higher security for users with specific
209 security requirements.
211 (g) The system-entry services should not be required to change when
212 the underlying mechanism changes. This can be very useful for
213 third-party developers because they often do not have the
214 source code for these services.
216 (h) The architecture should provide for a _pluggable_ model for
217 system authentication, as well as for other related tasks such
218 as password, account, and session management.
220 (i) For backward-compatibility reasons, the PAM API should support
221 the authentication requirements of the current system-entry
224 There are certain issues that the PAM framework does not specifically
227 (a) We focus only on providing a generic scheme through which users
228 use passwords to establish their identities to the machine.
229 Once the identity is established, how the identity is
230 communicated to other interested parties is outside the scope
231 of this design. There are efforts underway at IETF [Linn 93]
232 to develop a Generic Security Services Application Interface
233 (GSSAPI) that can be used by applications for secure and
234 authenticated communication without knowing the underlying
237 (b) The _single-signon_ problem of securely transferring the
238 identity of the caller to a remote site is not addressed. For
239 example, the problem of delegating credentials from the
240 `rlogin' client to the other machine without typing the
241 password is not addressed by our work. We also do not address
242 the problem of sending the passwords over the network in the
245 (c) We do not address the source of information obtained from the
246 "`getXbyY()'" family of calls (e.g., `getpwnam()'). Different
247 operating systems address this problem differently. For
248 example, Solaris uses the name service switch (NSS) to
249 determine the source of information for the "`getXbyY()'"
250 calls. It is expected that data which is stored in multiple
251 sources (such as passwd entries in NIS+ and the DCE registry)
252 is kept in sync using the appropriate commands (such as
261 Samar, Schemers Page 4
269 OSF-RFC 86.0 PAM October 1995
273 4. OVERVIEW OF THE PAM FRAMEWORK
275 We propose that the goals listed above can be met through a framework
276 in which authentication modules can be _plugged_ independently of the
277 application. We call this the _Pluggable Authentication Modules_
280 The core components of the PAM framework are the authentication
281 library API (the front end) and the authentication mechanism-specific
282 modules (the back end), connected through the Service Provider
283 Interface (SPI). Applications write to the PAM API, while the
284 authentication-system providers write to the PAM SPI and supply the
285 back end modules that are independent of the application.
287 ftp telnet login (Applications)
293 | PAM API | <-- pam.conf file
297 UNIX Kerberos Smart Cards (Mechanisms)
299 Figure 1: The Basic PAM Architecture
301 Figure 1 illustrates the relationship between the application, the
302 PAM library, and the authentication modules. Three applications
303 (`login', `telnet' and `ftp') are shown which use the PAM
304 authentication interfaces. When an application makes a call to the
305 PAM API, it loads the appropriate authentication module as determined
306 by the configuration file, `pam.conf'. The request is forwarded to
307 the underlying authentication module (for example, UNIX password,
308 Kerberos, smart cards) to perform the specified operation. The PAM
309 layer then returns the response from the authentication module to the
312 PAM unifies system authentication and access control for the system,
313 and allows plugging of associated authentication modules through well
314 defined interfaces. The plugging can be defined through various
315 means, one of which uses a configuration file, such as the one in
316 Table 1. For each of the system applications, the file specifies the
317 authentication module that should be loaded. In the example below,
318 `login' uses the UNIX password module, while `ftp' and `telnet' use
327 Samar, Schemers Page 5
335 OSF-RFC 86.0 PAM October 1995
339 Table 1: A Simplified View of a Sample PAM Configuration File.
347 Authentication configuration is only one aspect of this interface.
348 Other critical components include account management, session
349 management, and password management. For example, the `login'
350 program may want to verify not only the password but also whether the
351 account has aged or expired. Generic interfaces also need to be
352 provided so that the password can be changed according to the
353 requirements of the module. Furthermore, the application may want to
354 log information about the current session as determined by the
357 Not all applications or services may need all of the above
358 components, and not each authentication module may need to provide
359 support for all of the interfaces. For example, while `login' may
360 need access to all four components, `su' may need access to just the
361 authentication component. Some applications may use some specific
362 authentication and password management modules but share the account
363 and session management modules with others.
365 This reasoning leads to a partitioning of the entire set of
366 interfaces into four areas of functionality: (1) authentication, (2)
367 account, (3) session, and (4) password. The concept of PAM was
368 extended to these functional areas by implementing each of them as a
369 separate pluggable module.
371 Breaking the functionality into four modules helps the module
372 providers because they can use the system-provided libraries for the
373 modules that they are not changing. For example, if a supplier wants
374 to provide a better version of Kerberos, they can just provide that
375 new authentication and password module, and reuse the existing ones
376 for account and session.
378 4.1. Module Description
380 More details on specific API's are described in Appendix A. A brief
381 description of four modules follows:
383 (a) Authentication management: This set includes the
384 `pam_authenticate()' function to authenticate the user, and the
385 `pam_setcred()' interface to set, refresh or destroy the user
388 (b) Account management: This set includes the `pam_acct_mgmt()'
389 function to check whether the authenticated user should be
393 Samar, Schemers Page 6
401 OSF-RFC 86.0 PAM October 1995
405 given access to his/her account. This function can implement
406 account expiration and access hour restrictions.
408 (c) Session management: This set includes the `pam_open_session()'
409 and `pam_close_session()' functions for session management and
410 accounting. For example, the system may want to store the
411 total time for the session.
413 (d) Password management: This set includes a function,
414 `pam_chauthtok()', to change the password.
417 5. FRAMEWORK INTERFACES
419 The PAM framework further provides a set of administrative interfaces
420 to support the above modules and to provide for application-module
421 communication. There is no corresponding service provider interface
422 (SPI) for such functions.
424 5.1. Administrative Interfaces
426 Each set of PAM transactions starts with `pam_start()' and ends with
427 the `pam_end()' function. The interfaces `pam_get_item()' and
428 `pam_set_item()' are used to read and write the state information
429 associated with the PAM transaction.
431 If there is any error with any of the PAM interfaces, the error
432 message can be printed with `pam_strerror()'.
434 5.2. Application-Module Communication
436 During application initialization, certain data such as the user name
437 is saved in the PAM framework layer through `pam_start()' so that it
438 can be used by the underlying modules. The application can also pass
439 opaque data to the module which the modules will pass back while
440 communicating with the user.
442 5.3. User-Module Communication
444 The `pam_start()' function also passes conversation function that has
445 to be used by the underlying modules to read and write module
446 specific authentication information. For example, these functions
447 can be used to prompt the user for the password in a way determined
448 by the application. PAM can thus be used by graphical, non-
449 graphical, or networked applications.
459 Samar, Schemers Page 7
467 OSF-RFC 86.0 PAM October 1995
471 5.4. Inter-Module Communication
473 Though the modules are independent, they can share certain common
474 information about the authentication session such as user name,
475 service name, password, and conversation function through the
476 `pam_get_item()' and `pam_set_item()' interfaces. These API's can
477 also be used by the application to change the state information after
478 having called `pam_start()' once.
480 5.5. Module State Information
482 The PAM service modules may want to keep certain module-specific
483 state information about the session. The interfaces `pam_get_data()'
484 and `pam_set_data()' can be used by the service modules to access and
485 update module-specific information as needed from the PAM handle.
486 The modules can also attach a cleanup function with the data. The
487 cleanup function is executed when `pam_end()' is called to indicate
488 the end of the current authentication activity.
490 Since the PAM modules are loaded upon demand, there is no direct
491 module initialization support in the PAM framework. If there are
492 certain initialization tasks that the PAM service modules have to do,
493 they should be done upon the first invocation. However, if there are
494 certain clean-up tasks to be done when the authentication session
495 ends, the modules should use `pam_set_data()' to specify the clean-up
496 functions, which would be called when `pam_end()' is called by the
500 6. MODULE CONFIGURATION MANAGEMENT
502 Table 2 shows an example of a configuration file `pam.conf' with
503 support for authentication, session, account, and password management
504 modules. `login' has three entries: one each for authentication
505 processing, session management and account management. Each entry
506 specifies the module name that should be loaded for the given module
507 type. In this example, the `ftp' service uses the authentication and
508 session modules. Note that all services here share the same session
509 management module, while having different authentication modules.
525 Samar, Schemers Page 8
533 OSF-RFC 86.0 PAM October 1995
537 Table 2: Configuration File (pam.conf) with Different Modules
540 service module_type control_flag module_path options
541 ------- ----------- ------------ ----------- -------
542 login auth required pam_unix_auth.so nowarn
543 login session required pam_unix_session.so
544 login account required pam_unix_account.so
545 ftp auth required pam_skey_auth.so debug
546 ftp session required pam_unix_session.so
547 telnet session required pam_unix_session.so
548 login password required pam_unix_passwd.so
549 passwd password required pam_unix_passwd.so
550 OTHER auth required pam_unix_auth.so
551 OTHER session required pam_unix_session.so
552 OTHER account required pam_unix_account.so
554 The first field, _service_, denotes the service (for example,
555 `login', `passwd', `rlogin'). The name `OTHER' indicates the module
556 used by all other applications that have not been specified in this
557 file. This name can also be used if all services have the same
558 requirements. In the example, since all the services use the same
559 session module, we could have replaced those lines with a single
562 The second field, _module_type_, indicates the type of the PAM
563 functional module. It can be one of `auth', `account', `session', or
566 The third field, _control_flag_ determines the behavior of stacking
567 multiple modules by specifying whether any particular module is
568 _required_, _sufficient_, or _optional_. The next section describes
569 stacking in more detail.
571 The fourth field, _module_path_, specifies the location of the
572 module. The PAM framework loads this module upon demand to invoke
573 the required function.
575 The fifth field, _options_, is used by the PAM framework layer to
576 pass module specific options to the modules. It is up to the module
577 to parse and interpret the options. This field can be used by the
578 modules to turn on debugging or to pass any module specific
579 parameters such as a timeout value. It is also used to support
580 unified login as described below. The options field can be used by
581 the system administrator to fine-tune the PAM modules.
583 If any of the fields are invalid, or if a module is not found, that
584 line is ignored and the error is logged as a critical error via
585 `syslog(3)'. If no entries are found for the given module type, then
586 the PAM framework returns an error to the application.
591 Samar, Schemers Page 9
599 OSF-RFC 86.0 PAM October 1995
603 7. INTEGRATING MULTIPLE AUTHENTICATION SERVICES WITH STACKING
605 In the world of heterogeneous systems, the system administrator often
606 has to deal with the problem of integrating multiple authentication
607 mechanisms. The user is often required to know about the
608 authentication command of the new authentication module (for example,
609 `kinit', `dce_login') after logging into the system. This is not
610 user-friendly because it forces people to remember to type the new
611 command and enter the new password. This functionality should be
612 invisible instead of burdening the user with it.
614 There are two problems to be addressed here:
616 (a) Supporting multiple authentication mechanisms.
618 (b) Providing unified login in the presence of multiple mechanisms.
620 In the previous section, we described how one could replace the
621 default authentication module with any other module of choice. Now
622 we demonstrate how the same model can be extended to provide support
623 for multiple modules.
625 7.1. Design for Stacked Modules
627 One possibility was to provide hard-coded rules in `login' or other
628 applications requiring authentication services [Adamson 95]. But
629 this becomes very specific to the particular combination of
630 authentication protocols, and also requires the source code of the
631 application. Digital's Security Integration Architecture [SIA 95]
632 addresses this problem by specifying the same list of authentication
633 modules for all applications. Since requirements for various
634 applications can vary, it is essential that the configuration be on a
635 per-application basis.
637 To support multiple authentication mechanisms, the PAM framework was
638 extended to support _stacking_. When any API is called, the back
639 ends for the stacked modules are invoked in the order listed, and the
640 result returned to the caller. In Figure 2, the authentication
641 service of `login' is stacked and the user is authenticated by UNIX,
642 Kerberos, and RSA authentication mechanisms. Note that in this
643 example, there is no stacking for session or account management
657 Samar, Schemers Page 10
665 OSF-RFC 86.0 PAM October 1995
675 +--+--+ +--+--+ +--+--+
676 | PAM | | PAM | | PAM |
677 +--+--+ +--+--+ +--+--+
688 Figure 2: Stacking With the PAM Architecture
690 Stacking is specified through additional entries in the configuration
691 file shown earlier. As shown in Table 2, for each application (such
692 as `login') the configuration file can specify multiple mechanisms
693 that have to be invoked in the specified order. When mechanisms
694 fail, the _control_flag_ decides which error should be returned to
695 the application. Since the user should not know which authentication
696 module failed when a bad password was typed, the PAM framework
697 continues to call other authentication modules on the stack even on
698 failure. The semantics of the control flag are as follows:
700 (a) `required': With this flag, the module failure results in the
701 PAM framework returning the error to the caller _after_
702 executing all other modules on the stack. For the function to
703 be able to return success to the application all `required'
704 modules have to report success. This flag is normally set when
705 authentication by this module is a _must_.
707 (b) `optional': With this flag, the PAM framework ignores the
708 module failure and continues with the processing of the next
709 module in sequence. This flag is used when the user is allowed
710 to login even if that particular module has failed.
712 (c) `sufficient': With this flag, if the module succeeds the PAM
713 framework returns success to the application immediately
714 without trying any other modules. For failure cases, the
715 _sufficient_ modules are treated as `optional'.
717 Table 3 shows a sample configuration file that stacks the `login'
718 command. Here the user is authenticated by UNIX, Kerberos, and RSA
719 authentication services. The `required' key word for _control_flag_
723 Samar, Schemers Page 11
731 OSF-RFC 86.0 PAM October 1995
735 enforces that the user is allowed to login only if he/she is
736 authenticated by _both_ UNIX and Kerberos services. RSA
737 authentication is optional by virtue of the `optional' key word in
738 the _control_flag_ field. The user can still log in even if RSA
739 authentication fails.
741 Table 3: PAM Configuration File with Support for Stacking
743 service module_type control_flag module_path options
744 ------- ----------- ------------ ----------- -------
745 login auth required pam_unix.so debug
746 login auth required pam_kerb.so use_mapped_pass
747 login auth optional pam_rsa.so use_first_pass
749 Table 4 illustrates the use of the sufficient flag for the `rlogin'
750 service. The Berkeley `rlogin' protocol specifies that if the remote
751 host is trusted (as specified in the `/etc/hosts.equiv' file or in
752 the `.rhosts' file in the home directory of the user), then the
753 `rlogin' daemon should not require the user to type the password. If
754 this is not the case, then the user is required to type the password.
755 Instead of hard coding this policy in the `rlogin' daemon, this can
756 be expressed with the `pam.conf' file in Table 4. The PAM module
757 `pam_rhosts_auth.so.1' implements the `.rhosts' policy described
758 above. If a site administrator wants to enable remote login with
759 only passwords, then the first line should be deleted.
761 Table 4: PAM Configuration File for the rlogin service
763 service module_type control_flag module_path options
764 ------- ----------- ------------ ----------- -------
765 rlogin auth sufficient pam_rhosts_auth.so
766 rlogin auth required pam_unix.so
768 7.2. Password-Mapping
770 Multiple authentication mechanisms on a machine can lead to multiple
771 passwords that users have to remember. One attractive solution from
772 the ease-of-use viewpoint is to use the same password for all
773 mechanisms. This, however, can also weaken the security because if
774 that password were to be compromised in any of the multiple
775 mechanisms, all mechanisms would be compromised at the same time.
776 Furthermore, different authentication mechanisms may have their own
777 distinctive password requirements in regards to its length, allowed
778 characters, time interval between updates, aging, locking, and so
779 forth. These requirements make it problematic to use the same
780 password for multiple authentication mechanisms.
782 The solution we propose, while not precluding use of the same
783 password for every mechanism, allows for a different password for
784 each mechanism through what we call _password-mapping_. This
785 basically means using the user's _primary_ password to encrypt the
789 Samar, Schemers Page 12
797 OSF-RFC 86.0 PAM October 1995
801 user's other (_secondary_) passwords, and storing these encrypted
802 passwords in a place where they are available to the user. Once the
803 primary password is verified, the authentication modules would obtain
804 the other passwords for their own mechanisms by decrypting the
805 mechanism-specific encrypted password with the primary password, and
806 passing it to the authentication service. The security of this
807 design for password-mapping assumes that the primary password is the
808 user's strongest password, in terms of its unguessability (length,
809 type and mix of characters used, etc.).
811 If there is any error in password-mapping, or if the mapping does not
812 exist, the user will be prompted for the password by each
813 authentication module.
815 To support password-mapping, the PAM framework saves the primary
816 password and provides it to stacked authentication modules. The
817 password is cleared out before the `pam_authenticate' function
820 How the password is encrypted depends completely on the module
821 implementation. The encrypted secondary password (also called a
822 "mapped password") can be stored in a trusted or untrusted place,
823 such as a smart card, a local file, or a directory service. If the
824 encrypted passwords are stored in an untrusted publicly accessible
825 place, this does provide an intruder with opportunities for potential
828 Though password-mapping is voluntary, it is recommended that all
829 module providers add support for the following four mapping options:
831 (a) `use_first_pass': Use the same password used by the first
832 mechanism that asked for a password. The module should not ask
833 for the password if the user cannot be authenticated by the
834 first password. This option is normally used when the system
835 administrator wants to enforce the same password across
838 (b) `try_first_pass': This is the same as `use_first_pass', except
839 that if the primary password is not valid, it should prompt the
840 user for the password.
842 (c) `use_mapped_pass': Use the password-mapping scheme to get the
843 actual password for this module. One possible implementation
844 is to get the mapped-password using the XFN API [XFN 94], and
845 decrypt it with the primary password to get the module-specific
846 password. The module should not ask for the password if the
847 user cannot be authenticated by the first password. The XFN
848 API allows user-defined attributes (such as _mapped-password_)
849 to be stored in the _user-context_. Using the XFN API is
850 particularly attractive because support for the XFN may be
851 found on many systems in the future.
855 Samar, Schemers Page 13
863 OSF-RFC 86.0 PAM October 1995
867 (d) `try_mapped_pass': This is the same as `use_mapped_pass',
868 except that if the primary password is not valid, it should
869 prompt the user for the password.
871 When passwords get updated, the PAM framework stores both the old as
872 well as the new password to be able to inform other dependent
873 authentication modules about the change. Other modules can use this
874 information to update the encrypted password without forcing the user
875 to type the sequence of passwords again. The PAM framework clears
876 out the passwords before returning to the application.
878 Table 3 illustrates how the same password can be used by `login' for
879 authenticating to the standard UNIX login, Kerberos and RSA services.
880 Once the user has been authenticated to the primary authentication
881 service (UNIX `login' in this example) with the primary password, the
882 option `use_mapped_pass' indicates to the Kerberos module that it
883 should use the primary password to decrypt the stored Kerberos
884 password and then use the Kerberos password to get the ticket for the
885 ticket-granting-service. After that succeeds, the option
886 `use_first_pass' indicates to the RSA module that instead of
887 prompting the user for a password, it should use the primary password
888 typed earlier for authenticating the user. Note that in this
889 scenario, the user has to enter the password just once.
891 Note that if a one-time password scheme (e.g., S/Key) is used,
892 password mapping cannot apply.
894 7.3. Implications of Stacking on the PAM Design
896 Because of the stacking capability of PAM, we have designed the PAM
897 API's to not return any data to the application, except status. If
898 this were not the case, it would be difficult for the PAM framework
899 to decide which module should return data to the application. When
900 there is any error, the application does not know which of the
901 modules failed. This behavior enables (even requires) the
902 application to be completely independent from the modules.
904 Another design decision we have made is that PAM gives only the user
905 name to all the underlying PAM modules, hence it is the
906 responsibility of the PAM modules to convert the name to their own
907 internal format. For example, the Kerberos module may have to
908 convert the UNIX user name to a Kerberos principal name.
910 Stacking also forces the modules to be designed such that they can
911 occur anywhere in the stack without any side-effects.
913 Since modules such as the authentication and the password module are
914 very closely related, it is important they be configured in the same
915 order and with compatible options.
921 Samar, Schemers Page 14
929 OSF-RFC 86.0 PAM October 1995
933 8. INTEGRATION WITH SMART CARDS
935 Many networking authentication protocols require possession of a long
936 key to establish the user identity. For ease-of-use reasons, that
937 long key is normally encrypted with the user's password so that the
938 user is not required to memorize it. However, weak passwords can be
939 compromised through a dictionary attack and thus undermine the
940 stronger network authentication mechanism. Furthermore, the
941 encrypted data is normally stored in a centrally accessible service
942 whose availability depends upon the reliability of the associated
943 service. Solutions have been proposed to use a pass-phrase or one-
944 time-password, but those are much longer than the regular eight
945 character passwords traditionally used with UNIX `login'. This makes
946 the solution user-unfriendly because it requires longer strings to be
947 remembered and typed.
949 For most authentication protocol implementations, the trust boundary
950 is the local machine. This assumption may not be valid in cases
951 where the user is mobile and has to use publicly available networked
952 computers. In such cases, it is required that the clear text of the
953 key or the password never be made available to the machine.
955 Smart cards solve the above problems by reducing password exposure by
956 supporting a _two factor_ authentication mechanism: the first with
957 the possession of the card, and the second with the knowledge of the
958 PIN associated with the card. Not only can the smart cards be a
959 secure repository of multiple passwords, they can also provide the
960 encryption and authentication functions such that the long (private)
961 key is never exposed outside the card.
963 The PAM framework allows for integrating smart cards to the system by
964 providing a smart card specific module for authentication.
965 Furthermore, the unified login problem is simplified because the
966 multiple passwords for various authentication mechanisms can be
967 stored on the smart card itself. This can be enabled by adding a
968 suitable key-word such as `use_smart_card' in the _options_ field.
973 It is important to understand the impact of PAM on the security of
974 any system so that the site-administrator can make an informed
977 (a) Sharing of passwords with multiple authentication mechanisms.
979 If there are multiple authentication modules, one possibility
980 is to use the same password for all of them. If the password
981 for any of the multiple authentication system is compromised,
982 the user's password in all systems would be compromised. If
983 this is a concern, then multiple passwords might be considered
987 Samar, Schemers Page 15
995 OSF-RFC 86.0 PAM October 1995
999 at the cost of ease-of-use.
1001 (b) Password-mapping.
1003 This technique of encrypting all other passwords with the
1004 primary password assumes that it is lot more difficult to crack
1005 the primary password and that reasonable steps have been taken
1006 to ensure limited availability of the encrypted primary
1007 password. If this is not done, an intruder could target the
1008 primary password as the first point of dictionary attack. If
1009 one of the other modules provide stronger security than the
1010 password based security, the site would be negating the strong
1011 security by using password-mapping. If this is a concern, then
1012 multiple passwords might be considered at the cost of ease-of-
1013 use. If smart cards are used, they obviate the need for
1014 password-mapping completely.
1016 (c) Security of the configuration file.
1018 Since the policy file dictates how the user is authenticated,
1019 this file should be protected from unauthorized modifications.
1021 (d) Stacking various PAM modules.
1023 The system administrator should fully understand the
1024 implications of stacking various modules that will be installed
1025 on the system and their respective orders and interactions.
1026 The composition of various authentication modules should be
1027 carefully examined. The trusted computing base of the machine
1028 now includes the PAM modules.
1031 10. EXPERIENCE WITH PAM
1033 The PAM framework was first added in Solaris 2.3 release as a private
1034 internal interface. PAM is currently being used by several system
1035 entry applications such as `login', `passwd', `su', `dtlogin',
1036 `rlogind', `rshd', `telnetd', `ftpd', `in.rexecd', `uucpd', `init',
1037 `sac', and `ttymon'. We have found that PAM provides an excellent
1038 framework to encapsulate the authentication-related tasks for the
1039 entire system. The Solaris 2.3 PAM API's were hence enhanced and
1040 simplified to support stacking.
1042 PAM modules have been developed for UNIX, DCE, Kerberos, S/Key,
1043 remote user authentication, and dialpass authentication. Other PAM
1044 modules are under development, and integration with smart cards is
1047 Some third parties have used the PAM interface to extend the security
1048 mechanisms offered by the Solaris environment.
1053 Samar, Schemers Page 16
1061 OSF-RFC 86.0 PAM October 1995
1065 The PAM API has been accepted by Common Desktop Environment (CDE)
1066 vendors as the API to be used for integrating the graphical interface
1067 for login, `dtlogin' with multiple authentication mechanisms.
1072 Amongst the various components of PAM, the password component needs
1073 to be carefully examined to see whether the stacking semantics are
1074 particularly applicable, and how PAM should deal with partial
1075 failures when changing passwords.
1077 The _control_flag_ of the configuration file can be extended to
1078 include other semantics. For example, if the error is "name service
1079 not available", one may want to retry. It is also possible to offer
1080 semantics of "return success if any of the modules return success".
1082 In an earlier section, we had mentioned integration of smart cards
1083 with PAM. Though we feel that integration should be straight forward
1084 from the PAM architecture point of view, there may be some issues
1085 with implementation because the interfaces to the smart cards have
1086 not yet been standardized.
1088 One possible extension to PAM is to allow the passing of module-
1089 specific data between applications and PAM modules. For example, the
1090 `login' program likes to build its new environment from a select list
1091 of variables, yet the DCE module needs the `KRB5CCNAME' variable to
1092 be exported to the child process. For now we have modified the
1093 `login' program to explicitly export the `KRB5CCNAME' variable.
1095 Administrative tools are needed to help system administrators modify
1096 `pam.conf', and perform sanity checks on it (i.e., a `pam_check'
1102 The PAM framework and the module interfaces provide pluggability for
1103 user authentication, as well as for account, session and password
1104 management. The PAM architecture can be used by `login' and by all
1105 other system-entry services, and thus ensure that all entry points
1106 for the system have been secured. This architecture enables
1107 replacement and modification of authentication modules in the field
1108 to secure the system against the newly found weaknesses without
1109 changing any of the system services.
1111 The PAM framework can be used to integrate `login' and `dtlogin' with
1112 different authentication mechanisms such as RSA and Kerberos.
1113 Multiple authentication systems can be accessed with the same
1114 password. The PAM framework also provides easy integration of smart
1115 cards into the system.
1119 Samar, Schemers Page 17
1127 OSF-RFC 86.0 PAM October 1995
1131 PAM provides complementary functionality to GSS-API, in that it
1132 provides mechanisms through which the user gets authenticated to any
1133 new system-level authentication service on the machine. GSS-API then
1134 uses the credentials for authenticated and secure communications with
1135 other application-level service entities on the network.
1138 13. ACKNOWLEDGEMENTS
1140 PAM development has spanned several release cycles at SunSoft.
1141 Shau-Ping Lo, Chuck Hickey, and Alex Choy did the first design and
1142 implementation. Bill Shannon and Don Stephenson helped with the PAM
1143 architecture. Rocky Wu prototyped stacking of multiple modules.
1144 Paul Fronberg, Charlie Lai, and Roland Schemers made very significant
1145 enhancements to the PAM interfaces and took the project to completion
1146 within a very short time. Kathy Slattery wrote the PAM
1147 documentation. John Perry integrated PAM within the CDE framework.
1150 APPENDIX A. PAM API'S
1152 This appendix gives an informal description of the various interfaces
1153 of PAM. Since the goal here is just for the reader to get a working
1154 knowledge about the PAM interfaces, not all flags and options have
1155 been fully defined and explained. The API's described here are
1158 The PAM Service Provider Interface is very similar to the PAM API,
1159 except for one extra parameter to pass module-specific options to the
1162 A.1. Framework Layer API's
1168 struct pam_conv *pam_conversation,
1172 `pam_start()' is called to initiate an authentication transaction.
1173 `pam_start()' takes as arguments the name of the service, the name of
1174 the user to be authenticated, the address of the conversation
1175 structure. `pamh' is later used as a handle for subsequent calls to
1178 The PAM modules do not communicate directly with the user; instead
1179 they rely on the application to perform all such interaction. The
1180 application needs to provide the conversation functions, `conv()',
1181 and associated application data pointers through a `pam_conv'
1185 Samar, Schemers Page 18
1193 OSF-RFC 86.0 PAM October 1995
1197 structure when it initiates an authentication transaction. The
1198 module uses the `conv()' function to prompt the user for data,
1199 display error messages, or text information.
1207 `pam_end()' is called to terminate the PAM transaction as specified
1208 by `pamh', and to free any storage area allocated by the PAM modules
1209 with `pam_set_item()'.
1224 `pam_get_item()' and `pam_set_item()' allow the parameters specified
1225 in the initial call to `pam_start()' to be read and updated. This is
1226 useful when a particular parameter is not available when
1227 `pam_start()' is called or must be modified after the initial call to
1228 `pam_start()'. `pam_set_item()' is passed a pointer to the object,
1229 `item', and its type, `item_type'. `pam_get_item()' is passed the
1230 address of the pointer, `item', which is assigned the address of the
1233 The `item_type' is one of the following:
1235 Table 5: Possible Values for Item_type
1237 Item Name Description
1238 --------- -----------
1239 PAM_SERVICE The service name
1240 PAM_USER The user name
1241 PAM_TTY The tty name
1242 PAM_RHOST The remote host name
1243 PAM_CONV The pam_conv structure
1244 PAM_AUTHTOK The authentication token (password)
1245 PAM_OLDAUTHTOK The old authentication token
1246 PAM_RUSER The remote user name
1251 Samar, Schemers Page 19
1259 OSF-RFC 86.0 PAM October 1995
1263 Note that the values of `PAM_AUTHTOK' and `PAM_OLDAUTHTOK' are only
1264 available to PAM modules and not to the applications. They are
1265 explicitly cleared out by the framework before returning to the
1273 `pam_strerror()' maps the error number to a PAM error message string,
1274 and returns a pointer to that string.
1279 char *module_data_name,
1281 (*cleanup)(pam_handle_t *pamh, char *data,
1285 The `pam_set_data()' function stores module specific data within the
1286 PAM handle. The `module_data_name' uniquely specifies the name to
1287 which some data and cleanup callback function can be attached. The
1288 cleanup function is called when `pam_end()' is invoked.
1293 char *module_data_name,
1297 The `pam_get_data()' function obtains module-specific data from the
1298 PAM handle stored previously by the `pam_get_data()' function. The
1299 `module_data_name' uniquely specifies the name for which data has to
1300 be obtained. This function is normally used to retrieve module
1301 specific state information.
1303 A.2. Authentication API's
1311 The `pam_authenticate()' function is called to verify the identity of
1312 the current user. The user is usually required to enter a password
1313 or similar authentication token, depending upon the authentication
1317 Samar, Schemers Page 20
1325 OSF-RFC 86.0 PAM October 1995
1329 module configured with the system. The user in question is specified
1330 by a prior call to `pam_start()', and is referenced by the
1331 authentication handle, `pamh'.
1339 The `pam_setcred()' function is called to set the credentials of the
1340 current process associated with the authentication handle, `pamh'.
1341 The actions that can be denoted through `flags' include credential
1342 initialization, refresh, reinitialization and deletion.
1344 A.3. Account Management API
1352 The function `pam_acct_mgmt()' is called to determine whether the
1353 current user's account and password are valid. This typically
1354 includes checking for password and account expiration, valid login
1355 times, etc. The user in question is specified by a prior call to
1356 `pam_start()', and is referenced by the authentication handle,
1359 A.4. Session Management API's
1367 `pam_open_session()' is called to inform the session modules that a
1368 new session has been initialized. All programs which use PAM should
1369 invoke `pam_open_session()' when beginning a new session.
1377 Upon termination of this session, the `pam_close_session()' function
1378 should be invoked to inform the underlying modules that the session
1383 Samar, Schemers Page 21
1391 OSF-RFC 86.0 PAM October 1995
1395 A.5. Password Management API's
1403 `pam_chauthtok()' is called to change the authentication token
1404 associated with the user referenced by the authentication handle
1405 `pamh'. After the call, the authentication token of the user will be
1406 changed in accordance with the authentication module configured on
1410 APPENDIX B. SAMPLE PAM APPLICATION
1412 This appendix shows a sample `login' application which uses the PAM
1413 API's. It is not meant to be a fully functional login program, as
1414 some functionality has been left out in order to emphasize the use of
1417 #include <security/pam_appl.h>
1419 static int login_conv(int num_msg, struct pam_message **msg,
1420 struct pam_response **response, void *appdata_ptr);
1422 static struct pam_conv pam_conv = {login_conv, NULL};
1424 static pam_handle_t *pamh; /* Authentication handle */
1427 main(int argc, char *argv[], char **renvp)
1431 * Call pam_start to initiate a PAM authentication operation
1434 if ((pam_start("login", user_name, &pam_conv, &pamh))
1438 pam_set_item(pamh, PAM_TTY, ttyn);
1439 pam_set_item(pamh, PAM_RHOST, remote_host);
1441 while (!authenticated && retry < MAX_RETRIES) {
1442 status = pam_authenticate(pamh, 0);
1443 authenticated = (status == PAM_SUCCESS);
1449 Samar, Schemers Page 22
1457 OSF-RFC 86.0 PAM October 1995
1461 if (status != PAM_SUCCESS) {
1462 fprintf(stderr,"error: %s\n", pam_strerror(status));
1466 /* now check if the authenticated user is allowed to login. */
1468 if ((status = pam_acct_mgmt(pamh, 0)) != PAM_SUCCESS) {
1469 if (status == PAM_AUTHTOK_EXPIRED) {
1470 status = pam_chauthtok(pamh, 0);
1471 if (status != PAM_SUCCESS)
1479 * call pam_open_session to open the authenticated session
1480 * pam_close_session gets called by the process that
1481 * cleans up the utmp entry (i.e., init)
1483 if (status = pam_open_session(pamh, 0) != PAM_SUCCESS) {
1487 /* set up the process credentials */
1488 setgid(pwd->pw_gid);
1491 * Initialize the supplementary group access list.
1492 * This should be done before pam_setcred because
1493 * the PAM modules might add groups during the pam_setcred call
1495 initgroups(user_name, pwd->pw_gid);
1497 status = pam_setcred(pamh, PAM_ESTABLISH_CRED);
1498 if (status != PAM_SUCCESS) {
1502 /* set the real (and effective) UID */
1503 setuid(pwd->pw_uid);
1505 pam_end(pamh, PAM_SUCCESS); /* Done using PAM */
1508 * Add DCE/Kerberos cred name, if any.
1509 * XXX - The module specific stuff should be removed from login
1510 * program eventually. This is better placed in DCE module and
1511 * will be once PAM has routines for "exporting" environment
1515 Samar, Schemers Page 23
1523 OSF-RFC 86.0 PAM October 1995
1529 krb5p = getenv("KRB5CCNAME");
1530 if (krb5p != NULL) {
1531 ENVSTRNCAT(krb5ccname, krb5p);
1532 envinit[basicenv++] = krb5ccname;
1534 environ = envinit; /* Switch to the new environment. */
1541 * login_exit - Call exit() and terminate.
1542 * This function is here for PAM so cleanup can
1543 * be done before the process exits.
1546 login_exit(int exit_code)
1549 pam_end(pamh, PAM_ABORT);
1556 * This is the conv (conversation) function called from
1557 * a PAM authentication module to print error messages
1558 * or garner information from the user.
1562 login_conv(int num_msg, struct pam_message **msg,
1563 struct pam_response **response, void *appdata_ptr)
1567 switch (m->msg_style) {
1569 case PAM_PROMPT_ECHO_OFF:
1570 r->resp = strdup(getpass(m->msg));
1573 case PAM_PROMPT_ECHO_ON:
1574 (void) fputs(m->msg, stdout);
1575 r->resp = malloc(PAM_MAX_RESP_SIZE);
1576 fgets(r->resp, PAM_MAX_RESP_SIZE, stdin);
1577 /* add code here to remove \n from fputs */
1581 Samar, Schemers Page 24
1589 OSF-RFC 86.0 PAM October 1995
1596 (void) fputs(m->msg, stderr);
1600 (void) fputs(m->msg, stdout);
1604 /* add code here to log error message, etc */
1608 return (PAM_SUCCESS);
1612 APPENDIX C. DCE MODULE
1614 This appendix describes a sample implementation of a DCE PAM module.
1615 In order to simplify the description, we do not address the issues
1616 raised by password-mapping or stacking. The intent is to show which
1617 DCE calls are being made by the DCE module.
1619 The `pam_sm_*()' functions implement the PAM SPI functions which are
1620 called from the PAM API functions.
1622 C.1. DCE Authentication Management
1624 The algorithm for authenticating with DCE (not including error
1625 checking, prompting for passwords, etc.) is as follows:
1627 pam_sm_authenticate()
1629 sec_login_setup_identity(...);
1631 sec_login_valid_and_cert_ident(...);
1637 sec_login_set_context(...);
1640 The `pam_sm_authenticate()' function for DCE uses the
1641 `pam_set_data()' and `pam_get_data()' functions to keep state (like
1642 the `sec_login_handle_t' context) between calls. The following
1643 cleanup function is also registered and gets called when `pam_end()'
1647 Samar, Schemers Page 25
1655 OSF-RFC 86.0 PAM October 1995
1663 if (/* PAM_SUCCESS and
1664 sec_login_valid_and_cert_ident success */) {
1665 sec_login_release_context(...);
1667 sec_login_purge_context(...);
1671 If everything was successful we release the login context, but leave
1672 the credentials file intact. If the status passed to `pam_end()' was
1673 not `PAM_SUCCESS' (i.e., a required module failed) we purge the login
1674 context which also removes the credentials file.
1676 C.2. DCE Account Management
1678 The algorithm for DCE account management is as follows:
1683 sec_login_inquire_net_info(...);
1684 /* check for expired password and account */
1685 sec_login_free_net_info(...);
1688 The `sec_login_inquire_net_info()' function is called to obtain
1689 information about when the user's account and/or password are going
1690 to expire. A warning message is displayed (using the conversation
1691 function) if the user's account or password is going to expire in the
1692 near future, or has expired. These warning messages can be disabled
1693 using the `nowarn' option in the `pam.conf' file.
1695 C.3. DCE Session Management
1697 The DCE session management functions are currently empty. They could
1698 be modified to optionally remove the DCE credentials file upon
1701 C.4. DCE Password Management
1703 The algorithm for DCE password management is as follows:
1713 Samar, Schemers Page 26
1721 OSF-RFC 86.0 PAM October 1995
1727 sec_rgy_site_open(...);
1728 sec_rgy_acct_lookup(...);
1729 sec_rgy_acct_passwd(...);
1730 sec_rgy_site_close(...);
1733 The `sec_rgy_acct_passwd()' function is called to change the user's
1734 password in the DCE registry.
1739 [Adamson 95] W. A. Adamson, J. Rees, and P. Honeyman, "Joining
1740 Security Realms: A Single Login for Netware and
1741 Kerberos", CITI Technical Report 95-1, Center for
1742 Information Technology Integration, University of
1743 Michigan, Ann Arbor, MI, February 1995.
1745 [Diffie 76] W. Diffie and M. E. Hellman, "New Directions in
1746 Cryptography", IEEE Transactions on Information
1747 Theory, November 1976.
1749 [Linn 93] J. Linn, "Generic Security Service Application
1750 Programming Interface", Internet RFC 1508, 1509, 1993.
1752 [Rivest 78] R. L. Rivest, A. Shamir, and L. Adleman., "A Method
1753 for Obtaining Digital Signatures and Pubic-key
1754 Cryptosystems", Communications of the ACM, 21(2),
1757 [SIA 95] "Digital UNIX Security", Digital Equipment
1758 Corporation, Order Number AA-Q0R2C-TE, July 1995.
1760 [Skey 94] N. M. Haller, "The S/Key One-Time Password System",
1761 ISOC Symposium on Network and Distributed Security,
1764 [Steiner 88] J.G. Steiner, B. C. Neuman, and J. I. Schiller,
1765 "Kerberos, An Authentication Service for Open Network
1766 Systems", in Proceedings of the Winter USENIX
1767 Conference, Dallas, Jan 1988.
1769 [Taylor 88] B. Taylor and D. Goldberg, "Secure Networking in the
1770 Sun Environment", Sun Microsystems Technical Paper,
1773 [XFN 94] "Federated Naming: the XFN Specifications", X/Open
1774 Preliminary Specification, X/Open Document #P403,
1775 ISBN:1-85912-045-8, X/Open Co. Ltd., July 1994.
1779 Samar, Schemers Page 27
1787 OSF-RFC 86.0 PAM October 1995
1793 Vipin Samar Internet email: vipin@eng.sun.com
1794 SunSoft, Inc. Telephone: +1-415-336-1002
1796 Mountain View, CA 94043
1799 Roland J. Schemers III Internet email: schemers@eng.sun.com
1800 SunSoft, Inc. Telephone: +1-415-336-1035
1802 Mountain View, CA 94043
1845 Samar, Schemers Page 28