Merge from vendor branch LIBARCHIVE:
[dragonfly.git] / contrib / libpam / doc / specs / rfc86.0.txt
1
2
3
4
5
6
7
8
9    Open Software Foundation                              V. Samar (SunSoft)
10    Request For Comments: 86.0                         R. Schemers (SunSoft)
11    October 1995
12
13
14
15                               UNIFIED LOGIN WITH
16                     PLUGGABLE AUTHENTICATION MODULES (PAM)
17
18
19    1. INTRODUCTION
20
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.
32
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
38       upgrades.
39
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.
48
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.
54
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
60
61
62
63    Samar, Schemers                                                   Page 1
64
65
66
67
68
69
70
71    OSF-RFC 86.0                      PAM                       October 1995
72
73
74
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.
79
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.
96
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-
101       use_.
102
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.
110
111
112    2. OVERVIEW OF IDENTIFICATION AND AUTHENTICATION MECHANISMS
113
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.
123
124       In most of the current UNIX systems, the login mechanism is based
125       upon verification of the password using the modified DES algorithm.
126
127
128
129    Samar, Schemers                                                   Page 2
130
131
132
133
134
135
136
137    OSF-RFC 86.0                      PAM                       October 1995
138
139
140
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
156       mechanisms.
157
158
159    3. DESIGN GOALS
160
161       The goals of the PAM framework are as follows:
162
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
166             card based system.
167
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
172             authentication.
173
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
180             machine.
181
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.
186
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.
191
192
193
194
195    Samar, Schemers                                                   Page 3
196
197
198
199
200
201
202
203    OSF-RFC 86.0                      PAM                       October 1995
204
205
206
207         (f) The architecture should allow for multiple passwords if
208             necessary to achieve higher security for users with specific
209             security requirements.
210
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.
215
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.
219
220         (i) For backward-compatibility reasons, the PAM API should support
221             the authentication requirements of the current system-entry
222             services.
223
224       There are certain issues that the PAM framework does not specifically
225       address:
226
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
235             mechanism.
236
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
243             clear.
244
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
253             `passwd_export').
254
255
256
257
258
259
260
261    Samar, Schemers                                                   Page 4
262
263
264
265
266
267
268
269    OSF-RFC 86.0                      PAM                       October 1995
270
271
272
273    4. OVERVIEW OF THE PAM FRAMEWORK
274
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_
278       (PAM) framework.
279
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.
286
287              ftp     telnet   login   (Applications)
288               |        |        |
289               |        |        |
290               +--------+--------+
291                        |
292                  +-----+-----+
293                  |  PAM API  |   <-- pam.conf file
294                  +-----+-----+
295                        |
296               +--------+--------+
297             UNIX   Kerberos  Smart Cards   (Mechanisms)
298
299                Figure 1: The Basic PAM Architecture
300
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
310       application.
311
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
319       the S/Key module.
320
321
322
323
324
325
326
327    Samar, Schemers                                                   Page 5
328
329
330
331
332
333
334
335    OSF-RFC 86.0                      PAM                       October 1995
336
337
338
339             Table 1: A Simplified View of a Sample PAM Configuration File.
340
341                                service    module_path
342                                -------    -----------
343                                login      pam_unix.so
344                                ftp        pam_skey.so
345                                telnet     pam_skey.so
346
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
355       module.
356
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.
364
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.
370
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.
377
378    4.1. Module Description
379
380       More details on specific API's are described in Appendix A.  A brief
381       description of four modules follows:
382
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
386             credentials.
387
388         (b) Account management: This set includes the `pam_acct_mgmt()'
389             function to check whether the authenticated user should be
390
391
392
393    Samar, Schemers                                                   Page 6
394
395
396
397
398
399
400
401    OSF-RFC 86.0                      PAM                       October 1995
402
403
404
405             given access to his/her account.  This function can implement
406             account expiration and access hour restrictions.
407
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.
412
413         (d) Password management: This set includes a function,
414             `pam_chauthtok()', to change the password.
415
416
417    5. FRAMEWORK INTERFACES
418
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.
423
424    5.1. Administrative Interfaces
425
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.
430
431       If there is any error with any of the PAM interfaces, the error
432       message can be printed with `pam_strerror()'.
433
434    5.2. Application-Module Communication
435
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.
441
442    5.3. User-Module Communication
443
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.
450
451
452
453
454
455
456
457
458
459    Samar, Schemers                                                   Page 7
460
461
462
463
464
465
466
467    OSF-RFC 86.0                      PAM                       October 1995
468
469
470
471    5.4. Inter-Module Communication
472
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.
479
480    5.5. Module State Information
481
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.
489
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
497       application.
498
499
500    6. MODULE CONFIGURATION MANAGEMENT
501
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.
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525    Samar, Schemers                                                   Page 8
526
527
528
529
530
531
532
533    OSF-RFC 86.0                      PAM                       October 1995
534
535
536
537             Table 2: Configuration File (pam.conf) with Different Modules
538                      and Control Flow
539
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
553
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
560       `OTHER' line.
561
562       The second field, _module_type_, indicates the type of the PAM
563       functional module.  It can be one of `auth', `account', `session', or
564       `password' modules.
565
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.
570
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.
574
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.
582
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.
587
588
589
590
591    Samar, Schemers                                                   Page 9
592
593
594
595
596
597
598
599    OSF-RFC 86.0                      PAM                       October 1995
600
601
602
603    7. INTEGRATING MULTIPLE AUTHENTICATION SERVICES WITH STACKING
604
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.
613
614       There are two problems to be addressed here:
615
616         (a) Supporting multiple authentication mechanisms.
617
618         (b) Providing unified login in the presence of multiple mechanisms.
619
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.
624
625    7.1. Design for Stacked Modules
626
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.
636
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
644       modules.
645
646
647
648
649
650
651
652
653
654
655
656
657    Samar, Schemers                                                  Page 10
658
659
660
661
662
663
664
665    OSF-RFC 86.0                      PAM                       October 1995
666
667
668
669                              login
670                                |
671                       +--------+--------+
672                       |        |        |
673                    session   auth    account
674                       |        |        |
675                    +--+--+  +--+--+  +--+--+
676                    | PAM |  | PAM |  | PAM |
677                    +--+--+  +--+--+  +--+--+
678                       |        |        |
679                     UNIX     UNIX     UNIX
680                    session   auth    account
681                                |
682                             Kerberos
683                               auth
684                                |
685                               RSA
686                               auth
687
688             Figure 2: Stacking With the PAM Architecture
689
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:
699
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_.
706
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.
711
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'.
716
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_
720
721
722
723    Samar, Schemers                                                  Page 11
724
725
726
727
728
729
730
731    OSF-RFC 86.0                      PAM                       October 1995
732
733
734
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.
740
741               Table 3: PAM Configuration File with Support for Stacking
742
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
748
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.
760
761             Table 4: PAM Configuration File for the rlogin service
762
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
767
768    7.2. Password-Mapping
769
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.
781
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
786
787
788
789    Samar, Schemers                                                  Page 12
790
791
792
793
794
795
796
797    OSF-RFC 86.0                      PAM                       October 1995
798
799
800
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.).
810
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.
814
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
818       returns.
819
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
826       dictionary attack.
827
828       Though password-mapping is voluntary, it is recommended that all
829       module providers add support for the following four mapping options:
830
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
836             multiple modules.
837
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.
841
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.
852
853
854
855    Samar, Schemers                                                  Page 13
856
857
858
859
860
861
862
863    OSF-RFC 86.0                      PAM                       October 1995
864
865
866
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.
870
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.
877
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.
890
891       Note that if a one-time password scheme (e.g., S/Key) is used,
892       password mapping cannot apply.
893
894    7.3. Implications of Stacking on the PAM Design
895
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.
903
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.
909
910       Stacking also forces the modules to be designed such that they can
911       occur anywhere in the stack without any side-effects.
912
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.
916
917
918
919
920
921    Samar, Schemers                                                  Page 14
922
923
924
925
926
927
928
929    OSF-RFC 86.0                      PAM                       October 1995
930
931
932
933    8. INTEGRATION WITH SMART CARDS
934
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.
948
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.
954
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.
962
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.
969
970
971    9. SECURITY ISSUES
972
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
975       decision.
976
977         (a) Sharing of passwords with multiple authentication mechanisms.
978
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
984
985
986
987    Samar, Schemers                                                  Page 15
988
989
990
991
992
993
994
995    OSF-RFC 86.0                      PAM                       October 1995
996
997
998
999             at the cost of ease-of-use.
1000
1001         (b) Password-mapping.
1002
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.
1015
1016         (c) Security of the configuration file.
1017
1018             Since the policy file dictates how the user is authenticated,
1019             this file should be protected from unauthorized modifications.
1020
1021         (d) Stacking various PAM modules.
1022
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.
1029
1030
1031    10. EXPERIENCE WITH PAM
1032
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.
1041
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
1045       being planned.
1046
1047       Some third parties have used the PAM interface to extend the security
1048       mechanisms offered by the Solaris environment.
1049
1050
1051
1052
1053    Samar, Schemers                                                  Page 16
1054
1055
1056
1057
1058
1059
1060
1061    OSF-RFC 86.0                      PAM                       October 1995
1062
1063
1064
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.
1068
1069
1070    11. FUTURE WORK
1071
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.
1076
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".
1081
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.
1087
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.
1094
1095       Administrative tools are needed to help system administrators modify
1096       `pam.conf', and perform sanity checks on it (i.e., a `pam_check'
1097       utility).
1098
1099
1100    12. CONCLUSION
1101
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.
1110
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.
1116
1117
1118
1119    Samar, Schemers                                                  Page 17
1120
1121
1122
1123
1124
1125
1126
1127    OSF-RFC 86.0                      PAM                       October 1995
1128
1129
1130
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.
1136
1137
1138    13. ACKNOWLEDGEMENTS
1139
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.
1148
1149
1150    APPENDIX A. PAM API'S
1151
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
1156       subject to change.
1157
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
1160       underlying modules.
1161
1162    A.1. Framework Layer API's
1163
1164             int
1165             pam_start(
1166                 char *service_name,
1167                 char *user,
1168                 struct pam_conv *pam_conversation,
1169                 pam_handle_t **pamh
1170             );
1171
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
1176       the PAM library.
1177
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'
1182
1183
1184
1185    Samar, Schemers                                                  Page 18
1186
1187
1188
1189
1190
1191
1192
1193    OSF-RFC 86.0                      PAM                       October 1995
1194
1195
1196
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.
1200
1201             int
1202             pam_end(
1203                 pam_handle_t *pamh,
1204                 int pam_status
1205             );
1206
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()'.
1210
1211             int
1212             pam_set_item(
1213                 pam_handle_t *pamh,
1214                 int item_type,
1215                 void *item
1216             );
1217
1218             int
1219             pam_get_item(
1220                 pam_handle_t *pamh,
1221                 int item_type,
1222                 void **item);
1223
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
1231       requested object.
1232
1233       The `item_type' is one of the following:
1234
1235                    Table 5: Possible Values for Item_type
1236
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
1247
1248
1249
1250
1251    Samar, Schemers                                                  Page 19
1252
1253
1254
1255
1256
1257
1258
1259    OSF-RFC 86.0                      PAM                       October 1995
1260
1261
1262
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
1266       application.
1267
1268             char *
1269             pam_strerror(
1270                 int errnum
1271             );
1272
1273       `pam_strerror()' maps the error number to a PAM error message string,
1274       and returns a pointer to that string.
1275
1276             int
1277             pam_set_data(
1278                 pam_handle_t *pamh,
1279                 char *module_data_name,
1280                 char *data,
1281                 (*cleanup)(pam_handle_t *pamh, char *data,
1282                            int error_status)
1283             );
1284
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.
1289
1290             int
1291             pam_get_data(
1292                 pam_handle_t *pamh,
1293                 char *module_data_name,
1294                 void **datap
1295             );
1296
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.
1302
1303    A.2. Authentication API's
1304
1305             int
1306             pam_authenticate(
1307                 pam_handle_t *pamh,
1308                 int flags
1309             );
1310
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
1314
1315
1316
1317    Samar, Schemers                                                  Page 20
1318
1319
1320
1321
1322
1323
1324
1325    OSF-RFC 86.0                      PAM                       October 1995
1326
1327
1328
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'.
1332
1333             int
1334             pam_setcred(
1335                 pam_handle_t *pamh,
1336                 int flags
1337             );
1338
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.
1343
1344    A.3. Account Management API
1345
1346             int
1347             pam_acct_mgmt(
1348                 pam_handle_t *pamh,
1349                 int flags
1350             );
1351
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,
1357       `pamh'.
1358
1359    A.4. Session Management API's
1360
1361             int
1362             pam_open_session(
1363                 pam_handle_t *pamh,
1364                 int flags
1365             );
1366
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.
1370
1371             int
1372             pam_close_session(
1373                 pam_handle_t *pamh,
1374                 int flags
1375             );
1376
1377       Upon termination of this session, the `pam_close_session()' function
1378       should be invoked to inform the underlying modules that the session
1379       has terminated.
1380
1381
1382
1383    Samar, Schemers                                                  Page 21
1384
1385
1386
1387
1388
1389
1390
1391    OSF-RFC 86.0                      PAM                       October 1995
1392
1393
1394
1395    A.5. Password Management API's
1396
1397             int
1398             pam_chauthtok(
1399                 pam_handle_t *pamh,
1400                 int flags
1401             );
1402
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
1407       the system.
1408
1409
1410    APPENDIX B. SAMPLE PAM APPLICATION
1411
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
1415       PAM API's.
1416
1417       #include <security/pam_appl.h>
1418
1419       static int login_conv(int num_msg, struct pam_message **msg,
1420           struct pam_response **response, void *appdata_ptr);
1421
1422       static struct pam_conv pam_conv = {login_conv, NULL};
1423
1424       static pam_handle_t *pamh;    /* Authentication handle */
1425
1426       void
1427       main(int argc, char *argv[], char **renvp)
1428       {
1429
1430           /*
1431            * Call pam_start to initiate a PAM authentication operation
1432            */
1433
1434           if ((pam_start("login", user_name, &pam_conv, &pamh))
1435                       != PAM_SUCCESS)
1436                       login_exit(1);
1437
1438           pam_set_item(pamh, PAM_TTY, ttyn);
1439           pam_set_item(pamh, PAM_RHOST, remote_host);
1440
1441           while (!authenticated && retry < MAX_RETRIES) {
1442               status = pam_authenticate(pamh, 0);
1443               authenticated = (status == PAM_SUCCESS);
1444           }
1445
1446
1447
1448
1449    Samar, Schemers                                                  Page 22
1450
1451
1452
1453
1454
1455
1456
1457    OSF-RFC 86.0                      PAM                       October 1995
1458
1459
1460
1461           if (status != PAM_SUCCESS) {
1462               fprintf(stderr,"error: %s\n", pam_strerror(status));
1463               login_exit(1);
1464           }
1465
1466           /* now check if the authenticated user is allowed to login. */
1467
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)
1472                        login_exit(1);
1473               } else {
1474                    login_exit(1);
1475               }
1476           }
1477
1478           /*
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)
1482            */
1483           if (status = pam_open_session(pamh, 0) != PAM_SUCCESS) {
1484               login_exit(status);
1485           }
1486
1487           /* set up the process credentials */
1488           setgid(pwd->pw_gid);
1489
1490           /*
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
1494            */
1495           initgroups(user_name, pwd->pw_gid);
1496
1497           status = pam_setcred(pamh, PAM_ESTABLISH_CRED);
1498           if (status != PAM_SUCCESS) {
1499               login_exit(status);
1500           }
1501
1502           /* set the real (and effective) UID */
1503           setuid(pwd->pw_uid);
1504
1505           pam_end(pamh, PAM_SUCCESS);    /* Done using PAM */
1506
1507           /*
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
1512
1513
1514
1515    Samar, Schemers                                                  Page 23
1516
1517
1518
1519
1520
1521
1522
1523    OSF-RFC 86.0                      PAM                       October 1995
1524
1525
1526
1527            * variables.
1528            */
1529           krb5p = getenv("KRB5CCNAME");
1530           if (krb5p != NULL) {
1531               ENVSTRNCAT(krb5ccname, krb5p);
1532               envinit[basicenv++] = krb5ccname;
1533           }
1534           environ = envinit; /* Switch to the new environment. */
1535           exec_the_shell();
1536
1537           /* All done */
1538       }
1539
1540       /*
1541        * login_exit        - Call exit()  and terminate.
1542        *              This function is here for PAM so cleanup can
1543        *              be done before the process exits.
1544        */
1545       static void
1546       login_exit(int exit_code)
1547       {
1548           if (pamh)
1549               pam_end(pamh, PAM_ABORT);
1550           exit(exit_code);
1551           /*NOTREACHED*/
1552       }
1553
1554       /*
1555        * login_conv():
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.
1559        */
1560
1561       static int
1562       login_conv(int num_msg, struct pam_message **msg,
1563           struct pam_response **response, void *appdata_ptr)
1564       {
1565
1566           while (num_msg--) {
1567               switch (m->msg_style) {
1568
1569               case PAM_PROMPT_ECHO_OFF:
1570                   r->resp = strdup(getpass(m->msg));
1571                   break;
1572
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 */
1578
1579
1580
1581    Samar, Schemers                                                  Page 24
1582
1583
1584
1585
1586
1587
1588
1589    OSF-RFC 86.0                      PAM                       October 1995
1590
1591
1592
1593                   break;
1594
1595               case PAM_ERROR_MSG:
1596                   (void) fputs(m->msg, stderr);
1597                   break;
1598
1599               case PAM_TEXT_INFO:
1600                   (void) fputs(m->msg, stdout);
1601                   break;
1602
1603               default:
1604                       /* add code here to log error message, etc */
1605                   break;
1606               }
1607           }
1608           return (PAM_SUCCESS);
1609       }
1610
1611
1612    APPENDIX C. DCE MODULE
1613
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.
1618
1619       The `pam_sm_*()' functions implement the PAM SPI functions which are
1620       called from the PAM API functions.
1621
1622    C.1. DCE Authentication Management
1623
1624       The algorithm for authenticating with DCE (not including error
1625       checking, prompting for passwords, etc.) is as follows:
1626
1627             pam_sm_authenticate()
1628             {
1629                 sec_login_setup_identity(...);
1630                 pam_set_data(...);
1631                 sec_login_valid_and_cert_ident(...);
1632             }
1633
1634             pam_sm_setcred()
1635             {
1636                 pam_get_data(...);
1637                 sec_login_set_context(...);
1638             }
1639
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()'
1644
1645
1646
1647    Samar, Schemers                                                  Page 25
1648
1649
1650
1651
1652
1653
1654
1655    OSF-RFC 86.0                      PAM                       October 1995
1656
1657
1658
1659       is called:
1660
1661             dce_cleanup()
1662             {
1663                 if (/* PAM_SUCCESS and
1664                        sec_login_valid_and_cert_ident success */) {
1665                    sec_login_release_context(...);
1666                 } else {
1667                    sec_login_purge_context(...);
1668                 }
1669             }
1670
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.
1675
1676    C.2. DCE Account Management
1677
1678       The algorithm for DCE account management is as follows:
1679
1680             pam_sm_acct_mgmt()
1681             {
1682                 pam_get_data(...);
1683                 sec_login_inquire_net_info(...);
1684                 /* check for expired password and account */
1685                 sec_login_free_net_info(...);
1686             }
1687
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.
1694
1695    C.3. DCE Session Management
1696
1697       The DCE session management functions are currently empty.  They could
1698       be modified to optionally remove the DCE credentials file upon
1699       logout, etc.
1700
1701    C.4. DCE Password Management
1702
1703       The algorithm for DCE password management is as follows:
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713    Samar, Schemers                                                  Page 26
1714
1715
1716
1717
1718
1719
1720
1721    OSF-RFC 86.0                      PAM                       October 1995
1722
1723
1724
1725             pam_sm_chauthtok
1726             {
1727                 sec_rgy_site_open(...);
1728                 sec_rgy_acct_lookup(...);
1729                 sec_rgy_acct_passwd(...);
1730                 sec_rgy_site_close(...);
1731             }
1732
1733       The `sec_rgy_acct_passwd()' function is called to change the user's
1734       password in the DCE registry.
1735
1736
1737    REFERENCES
1738
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.
1744
1745       [Diffie 76]    W. Diffie and M. E. Hellman, "New Directions in
1746                      Cryptography", IEEE Transactions on Information
1747                      Theory, November 1976.
1748
1749       [Linn 93]      J. Linn, "Generic Security Service Application
1750                      Programming Interface", Internet RFC 1508, 1509, 1993.
1751
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),
1755                      1978.
1756
1757       [SIA 95]       "Digital UNIX Security", Digital Equipment
1758                      Corporation, Order Number AA-Q0R2C-TE, July 1995.
1759
1760       [Skey 94]      N. M. Haller, "The S/Key One-Time Password System",
1761                      ISOC Symposium on Network and Distributed Security,
1762                      1994.
1763
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.
1768
1769       [Taylor 88]    B. Taylor and D. Goldberg, "Secure Networking in the
1770                      Sun Environment", Sun Microsystems Technical Paper,
1771                      1988.
1772
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.
1776
1777
1778
1779    Samar, Schemers                                                  Page 27
1780
1781
1782
1783
1784
1785
1786
1787    OSF-RFC 86.0                      PAM                       October 1995
1788
1789
1790
1791    AUTHOR'S ADDRESS
1792
1793    Vipin Samar                            Internet email: vipin@eng.sun.com
1794    SunSoft, Inc.                                 Telephone: +1-415-336-1002
1795    2550 Garcia Avenue
1796    Mountain View, CA 94043
1797    USA
1798
1799    Roland J. Schemers III              Internet email: schemers@eng.sun.com
1800    SunSoft, Inc.                                 Telephone: +1-415-336-1035
1801    2550 Garcia Avenue
1802    Mountain View, CA 94043
1803    USA
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845    Samar, Schemers                                                  Page 28
1846
1847
1848
1849
1850
1851