From 9dff9513d4de61310fbae8308b31cc6909797e08 Mon Sep 17 00:00:00 2001 From: "Andrew G. Morgan" Date: Sat, 8 Dec 2001 18:56:47 +0000 Subject: Relevant BUGIDs: [tasks] 43507, 17426 Purpose of commit: documentation Commit summary: --------------- Generally more documentation with some cleanups and email address sanitization. --- CHANGELOG | 13 +++-- doc/modules/README | 2 +- doc/modules/pam_cracklib.sgml | 2 +- doc/modules/pam_deny.sgml | 4 +- doc/modules/pam_filter.sgml | 4 +- doc/modules/pam_ftp.sgml | 14 +++--- doc/modules/pam_group.sgml | 4 +- doc/modules/pam_mail.sgml | 4 +- doc/modules/pam_nologin.sgml | 2 +- doc/modules/pam_permit.sgml | 4 +- doc/modules/pam_rhosts.sgml | 2 +- doc/modules/pam_rootok.sgml | 4 +- doc/modules/pam_time.sgml | 4 +- doc/modules/pam_unix.sgml | 2 +- doc/modules/pam_warn.sgml | 4 +- doc/modules/pam_wheel.sgml | 2 +- doc/pam_appl.sgml | 66 ++++++++++++++++++------ doc/pam_modules.sgml | 8 +-- doc/pam_source.sgml | 95 +++++++++++++++++----------------- doc/specs/draft-morgan-pam.raw | 112 ++++++++++++++++++++++++++++++++--------- doc/specs/std-agent-id.raw | 95 ++++++++++++++++++++++++++++++++++ 21 files changed, 324 insertions(+), 123 deletions(-) create mode 100644 doc/specs/std-agent-id.raw diff --git a/CHANGELOG b/CHANGELOG index d7630f1a..7ceb3318 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -37,18 +37,26 @@ You can query the related bug description with the following URL: Where you should replace XXXXXX with a bug-id. -If you have found a bug in Linux-PAM, please consider filing such a +For general documentation completion work, I'm doing it all with +respect to specific tasks. Open tasks are listed here: + + http://sourceforge.net/pm/task.php?group_id=6663&group_project_id=2741&func=browse&set=open + +If you have found a bug in Linux-PAM (including a documentation bug, +or a new feature request and/or patch), please consider filing such a bug report - outstanding bugs are listed here: http://sourceforge.net/tracker/?atid=106663&group_id=6663&func=browse -(to file another bug see the 'submit bug' button on this page). +(to file another bug see the 'submit bug' button on that page). ==================================================================== 0.76: please submit patches for this section with actual code/doc patches! +* documentation: random typo fixes from Nalin and more stuff from me + (Bug 476949, Tasks 43507, 17426 - agmorgan) * pam_unix: fix 'likeauth' to kill off the memory leak once and for all. (Bug 483959 - vorlon) * pam_unix: restore handling of 'likeauth' argument to a known working @@ -56,7 +64,6 @@ bug report - outstanding bugs are listed here: pam_sm_setcred() (Bugs 483959, 113596 - vorlon) * pam_cracklib: another try at implementing similar() from Harald Welte and Nalin (Bugs 436053, 476957 - agmorgan) -* documentation: random typo fixes from Nalin (Bug 476949 - agmorgan) * pam_access: default access.conf file contained a type (console instead of LOCAL) fix from Nalin (Bug 476934 - agmorgan) * pam_unix: fixed bizarre memory leak pointed out by Fernando Trias diff --git a/doc/modules/README b/doc/modules/README index df091939..448aefc7 100644 --- a/doc/modules/README +++ b/doc/modules/README @@ -10,4 +10,4 @@ used as a blank form for new module descriptions. Please feel free to submit amendments/comments etc. regarding these files to: - Andrew G. Morgan + Andrew G. Morgan diff --git a/doc/modules/pam_cracklib.sgml b/doc/modules/pam_cracklib.sgml index 061a8a21..008e49f6 100644 --- a/doc/modules/pam_cracklib.sgml +++ b/doc/modules/pam_cracklib.sgml @@ -1,7 +1,7 @@ diff --git a/doc/modules/pam_deny.sgml b/doc/modules/pam_deny.sgml index 6e1f2992..7d9df7e7 100644 --- a/doc/modules/pam_deny.sgml +++ b/doc/modules/pam_deny.sgml @@ -1,7 +1,7 @@ The locking-out module @@ -15,7 +15,7 @@ pam_deny Author: -Andrew G. Morgan <morgan@parc.power.net> +Andrew G. Morgan <morgan@kernel.org> Maintainer: current + This file was written by Andrew G. Morgan --> The filter module @@ -17,7 +17,7 @@ pam_filter Author: -Andrew G. Morgan <morgan@parc.power.net> +Andrew G. Morgan <morgan@kernel.org> Maintainer: diff --git a/doc/modules/pam_ftp.sgml b/doc/modules/pam_ftp.sgml index 8c2c21d1..a9444733 100644 --- a/doc/modules/pam_ftp.sgml +++ b/doc/modules/pam_ftp.sgml @@ -1,7 +1,7 @@ Anonymous access module @@ -15,7 +15,7 @@ Author: -Andrew G. Morgan <morgan@linux.kernel.org> +Andrew G. Morgan <morgan@kernel.org> Maintainer: Author. @@ -56,11 +56,11 @@ mode of access. This module intercepts the user's name and password. If the name is `` The behavior of the module can be modified with the following flags: diff --git a/doc/modules/pam_group.sgml b/doc/modules/pam_group.sgml index 8251e3dd..0d8550d4 100644 --- a/doc/modules/pam_group.sgml +++ b/doc/modules/pam_group.sgml @@ -1,7 +1,7 @@ The group access module @@ -15,7 +15,7 @@ Author: -Andrew G. Morgan <morgan@parc.power.net> +Andrew G. Morgan <morgan@kernel.org> Maintainer: Author. diff --git a/doc/modules/pam_mail.sgml b/doc/modules/pam_mail.sgml index c1ed7a87..78ae95dc 100644 --- a/doc/modules/pam_mail.sgml +++ b/doc/modules/pam_mail.sgml @@ -1,7 +1,7 @@ The mail module @@ -15,7 +15,7 @@ Author: -Andrew G. Morgan <morgan@linux.kernel.org> +Andrew G. Morgan <morgan@kernel.org> Maintainer: Author diff --git a/doc/modules/pam_nologin.sgml b/doc/modules/pam_nologin.sgml index 90564d89..b1aa664b 100644 --- a/doc/modules/pam_nologin.sgml +++ b/doc/modules/pam_nologin.sgml @@ -17,7 +17,7 @@ Author: Written by Michael K. Johnson <johnsonm@redhat.com> (based on code taken from a module written by Andrew G. Morgan -<morgan@parc.power.net>). +<morgan@kernel.org>). Maintainer: Michael K. Johnson <johnsonm@redhat.com> diff --git a/doc/modules/pam_permit.sgml b/doc/modules/pam_permit.sgml index 8b201b7c..fe616ac3 100644 --- a/doc/modules/pam_permit.sgml +++ b/doc/modules/pam_permit.sgml @@ -1,7 +1,7 @@ The promiscuous module @@ -15,7 +15,7 @@ pam_permit Author: -Andrew G. Morgan, <morgan@parc.power.net> +Andrew G. Morgan, <morgan@kernel.org> Maintainer: Linux-PAM maintainer. diff --git a/doc/modules/pam_rhosts.sgml b/doc/modules/pam_rhosts.sgml index 00e55a9d..69885047 100644 --- a/doc/modules/pam_rhosts.sgml +++ b/doc/modules/pam_rhosts.sgml @@ -1,7 +1,7 @@ The rhosts module diff --git a/doc/modules/pam_rootok.sgml b/doc/modules/pam_rootok.sgml index e362a2a5..f6aa8a07 100644 --- a/doc/modules/pam_rootok.sgml +++ b/doc/modules/pam_rootok.sgml @@ -1,7 +1,7 @@ The root access module @@ -15,7 +15,7 @@ pam_rootok Author: -Andrew G. Morgan <morgan@parc.power.net> +Andrew G. Morgan <morgan@kernel.org> Maintainer: Linux-PAM maintainer diff --git a/doc/modules/pam_time.sgml b/doc/modules/pam_time.sgml index 7dd43feb..a1829c16 100644 --- a/doc/modules/pam_time.sgml +++ b/doc/modules/pam_time.sgml @@ -1,7 +1,7 @@ Time control @@ -15,7 +15,7 @@ Author: -Andrew G. Morgan <morgan@parc.power.net> +Andrew G. Morgan <morgan@kernel.org> Maintainer: Author diff --git a/doc/modules/pam_unix.sgml b/doc/modules/pam_unix.sgml index 71cb07e3..286cd3f8 100644 --- a/doc/modules/pam_unix.sgml +++ b/doc/modules/pam_unix.sgml @@ -1,5 +1,5 @@ diff --git a/doc/modules/pam_warn.sgml b/doc/modules/pam_warn.sgml index 2ca4cc82..4c2e3e18 100644 --- a/doc/modules/pam_warn.sgml +++ b/doc/modules/pam_warn.sgml @@ -1,7 +1,7 @@ Warning logger module @@ -15,7 +15,7 @@ Author: -Andrew G. Morgan <morgan@parc.power.net> +Andrew G. Morgan <morgan@kernel.org> Maintainer: Author. diff --git a/doc/modules/pam_wheel.sgml b/doc/modules/pam_wheel.sgml index 1eb62743..8c07a8b7 100644 --- a/doc/modules/pam_wheel.sgml +++ b/doc/modules/pam_wheel.sgml @@ -1,7 +1,7 @@ diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml index f033dff0..87c9e6e3 100644 --- a/doc/pam_appl.sgml +++ b/doc/pam_appl.sgml @@ -46,7 +46,7 @@ DAMAGE. The Linux-PAM Application Developers' Guide <author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.76 2001/05/26 +<date>DRAFT v0.76 2001/12/08 <abstract> This manual documents what an application developer needs to know about the <bf>Linux-PAM</bf> library. It describes how an application @@ -315,30 +315,62 @@ extern int pam_set_item(pam_handle_t *pamh, int item_type, <p><descrip> <tag><tt/PAM_SERVICE/</tag> - The service name + + The service name (which identifies that PAM stack that + <tt/libpam/ will use to authenticate the program). <tag><tt/PAM_USER/</tag> - The user name + + The username of the entity under who's identity service will + be given. That is, following authentication, <tt/PAM_USER/ + identifies the local entity that gets to use the + service. Note, this value can be mapped from something (eg., + "<tt/anonymous/") to something else (eg. "<tt/guest119/") by + any module in the PAM stack. As such an application should + consult the value of <tt/PAM_USER/ after each call to a + <tt/pam_*()/ function. <tag><tt/PAM_USER_PROMPT/</tag> + The string used when prompting for a user's name. The default -value for this string is ``Please enter username: ''. + value for this string is ``Please enter username: ''. <tag><tt/PAM_TTY/</tag> + The terminal name: prefixed by <tt>/dev/</tt> if it is a -device file; for graphical, X-based, applications the value for this -item should be the <tt/$DISPLAY/ variable. + device file; for graphical, X-based, applications the value + for this item should be the <tt/$DISPLAY/ variable. <tag><tt/PAM_RUSER/</tag> - The requesting user's username + + The requesting entity: user's username for a locally + requesting user or a remote requesting user - generally an + application or module will attempt to supply the value that is + most strongly authenticated (a local account before a remote + one. The level of trust in this value is embodied in the + actual authentication stack associated with the application, + so it is ultimately at the discretion of the system + administrator. It should generally match the current + <tt/PAM_RHOST/ value. That is, "<tt/PAM_RUSER@PAM_RHOST/" + should always identify the requesting user. In some cases, + <tt/PAM_RUSER/ may be NULL. In such situations, it is unclear + who the requesting entity is. <tag><tt/PAM_RHOST/</tag> - The requesting hostname (the hostname of the machine from which - the <tt/PAM_RUSER/ is requesting service) + + The requesting hostname (the hostname of the machine from + which the <tt/PAM_RUSER/ entity is requesting service). That + is "<tt/PAM_RUSER@PAM_RHOST/" does identify the requesting + user. "<tt/luser@localhost/" or "<tt/evil@evilcom.com/" are + valid "<tt/PAM_RUSER@PAM_RHOST/" examples. In some + applications, <tt/PAM_RHOST/ may be NULL. In such situations, + it is unclear where the authentication request is originating + from. <tag><tt/PAM_CONV/</tag> + The conversation structure (see section <ref -id="the-conversation-function" name="below">) + id="the-conversation-function" name="below">). <tag><tt/PAM_FAIL_DELAY/</tag> A function pointer to redirect centrally managed failure delays (see section <ref @@ -358,7 +390,7 @@ section <ref id="the-failure-delay-function" name="below">). <p> A successful call to this function returns <tt/PAM_SUCCESS/. However, -the application should expect one of the following errors: +the application should expect at least one the following errors: <p> <descrip> @@ -1134,7 +1166,11 @@ current <tt/uid/ (userid) of the running process; the identity of the privilege granting user is the <tt/euid/ (effective userid) of the running process; the identity of the user, under whose name the service will be executed, is given by the contents of the -<tt/PAM_USER/ <tt/pam_get_item(3)/. +<tt/PAM_USER/ <tt/pam_get_item(3)/. Note, modules can change the +values of <tt/PAM_USER/ and <tt/PAM_RUSER/ during any of the +<tt/pam_*()/ library calls. For this reason, the application should +take care to use the <tt/pam_get_item()/ every time it wishes to +establish who the authenticated user is (or will currently be). <p> For network-serving databases and other applications that provide @@ -1563,7 +1599,7 @@ purpose at the moment. Ideas/suggestions welcome! <p> This document was written by Andrew G. Morgan -(morgan@transmeta.com) with many contributions from +(morgan@kernel.org) with many contributions from <!-- insert credits here --> <!-- an sgml list of people to credit for their contributions to Linux-PAM @@ -1630,9 +1666,9 @@ credited for all the good work they have done. <sect>Copyright information for this document <p> -Copyright (c) Andrew G. Morgan 1996-9. All rights reserved. +Copyright (c) Andrew G. Morgan 1996-9,2000-1. All rights reserved. <newline> -Email: <tt><morgan@transmeta.com></tt> +Email: <tt><morgan@kernel.org></tt> <p> Redistribution and use in source and binary forms, with or without diff --git a/doc/pam_modules.sgml b/doc/pam_modules.sgml index 3490b3a5..babccb06 100644 --- a/doc/pam_modules.sgml +++ b/doc/pam_modules.sgml @@ -49,7 +49,7 @@ DAMAGE. <title>The Linux-PAM Module Writers' Guide <author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.76 2001/09/12 +<date>DRAFT v0.76 2001/12/08 <abstract> This manual documents what a programmer needs to know in order to write a module that conforms to the <bf/Linux-PAM/ standard. It also @@ -1375,7 +1375,7 @@ needed. <p> This document was written by Andrew G. Morgan -(<tt/morgan@transmeta.com/) with many contributions from +(<tt/morgan@kernel.org/) with many contributions from <!-- insert credits here --> <!-- an sgml list of people to credit for their contributions to Linux-PAM @@ -1443,9 +1443,9 @@ credited for all the good work they have done. <sect>Copyright information for this document <p> -Copyright (c) Andrew G. Morgan 1996, 1997. All rights reserved. +Copyright (c) Andrew G. Morgan 1996-9,2000-1. All rights reserved. <newline> -Email: <tt><morgan@transmeta.com></tt> +Email: <tt><morgan@kernel.org></tt> <p> Redistribution and use in source and binary forms, with or without diff --git a/doc/pam_source.sgml b/doc/pam_source.sgml index d24a53a3..160e9293 100644 --- a/doc/pam_source.sgml +++ b/doc/pam_source.sgml @@ -46,7 +46,7 @@ DAMAGE. <title>The Linux-PAM System Administrators' Guide <author>Andrew G. Morgan, <tt>morgan@kernel.org</tt> -<date>DRAFT v0.75 2001/03/18 +<date>DRAFT v0.76 2001/12/08 <abstract> This manual documents what a system-administrator needs to know about the <bf>Linux-PAM</bf> library. It covers the correct syntax of the @@ -103,7 +103,7 @@ locally with a system file, <tt>/etc/pam.conf</tt> (or a series of configuration files located in <tt>/etc/pam.d/</tt>) to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory -<tt>/usr/lib/security</tt> and take the form of dynamically loadable +<tt>/lib/security</tt> and take the form of dynamically loadable object files (see <tt/dlopen(3)/). <sect>Some comments on the text<label id="text-conventions"> @@ -122,11 +122,12 @@ directly from the text. <p> As an example of the above, where it is explicit, the text assumes that PAM loadable object files (the <em/modules/) are to be located in -the following directory: <tt>/usr/lib/security/</tt>. However, Red Hat -Linux, in agreement with the Linux File System Standard (the FSSTND), -places these files in <tt>/lib/security</tt>. Please be careful to -perform the necessary transcription when using the examples from the -text. +the following directory: <tt>/lib/security/</tt>. This is generally +the location that seems to be compatible with the Linux File System +Standard (the FSSTND). On Solaris, which has its own licensed version +of PAM, and some other implementations of UN*X, these files can be +found in <tt>/usr/lib/security</tt>. Please be careful to perform the +necessary transcription when using the examples from the text. <sect>Overview<label id="overview-section"> @@ -513,10 +514,10 @@ The <tt/actionI/ can be a positive integer or one of the following tokens: <tt/ignore/; <tt/ok/; <tt/done/; <tt/bad/; <tt/die/; and <tt/reset/. A positive integer, <tt/J/, when specified as the action, can be used to indicate that the next <em/J/ modules of the current -type will be skipped. In this way, the administrator can develop a -moderately sophisticated stack of modules with a number of different -paths of execution. Which path is taken can be determined by the -reactions of individual modules. +module-type will be skipped. In this way, the administrator can +develop a moderately sophisticated stack of modules with a number of +different paths of execution. Which path is taken can be determined +by the reactions of individual modules. <p> <itemize> @@ -553,7 +554,7 @@ transport protocol inherent to the client/server application. With the ``<tt/[ ... value=action ... ]/'' control syntax, it is possible for an application to be configured to support binary prompts with compliant clients, but to gracefully fall over into an alternative -authentication mode for older, legacy, applications. Flexible eh? +authentication mode for older, legacy, applications. <tag> <tt/module-path/</tag> @@ -561,8 +562,8 @@ The path-name of the dynamically loadable object file; <em/the pluggable module/ itself. If the first character of the module path is `<tt>/</tt>', it is assumed to be a complete path. If this is not the case, the given module path is appended to the default module path: -<tt>/usr/lib/security</tt> (but see the notes <ref -id="text-conventions" name="above">). +<tt>/lib/security</tt> (but see the notes <ref id="text-conventions" +name="above">). <tag> <tt/args/</tag> @@ -740,10 +741,10 @@ setting (which is not a bad place to start!): # # default; deny access # -OTHER auth required /usr/lib/security/pam_deny.so -OTHER account required /usr/lib/security/pam_deny.so -OTHER password required /usr/lib/security/pam_deny.so -OTHER session required /usr/lib/security/pam_deny.so +OTHER auth required pam_deny.so +OTHER account required pam_deny.so +OTHER password required pam_deny.so +OTHER session required pam_deny.so </verb> </tscreen> Whilst fundamentally a secure default, this is not very sympathetic to @@ -765,8 +766,8 @@ would provide a suitable warning to the administrator. # # default; wake up! This application is not configured # -OTHER auth required /usr/lib/security/pam_warn.so -OTHER password required /usr/lib/security/pam_warn.so +OTHER auth required pam_warn.so +OTHER password required pam_warn.so </verb> </tscreen> Having two ``<tt/OTHER auth/'' lines is an example of stacking. @@ -779,12 +780,12 @@ corresponding default setup would be achieved with the following file: # # default configuration: /etc/pam.d/other # -auth required /usr/lib/security/pam_warn.so -auth required /usr/lib/security/pam_deny.so -account required /usr/lib/security/pam_deny.so -password required /usr/lib/security/pam_warn.so -password required /usr/lib/security/pam_deny.so -session required /usr/lib/security/pam_deny.so +auth required pam_warn.so +auth required pam_deny.so +account required pam_deny.so +password required pam_warn.so +password required pam_deny.so +session required pam_deny.so </verb> </tscreen> This is the only explicit example we give for an <tt>/etc/pam.d/</tt> @@ -799,12 +800,12 @@ mimic the historically familiar Linux setup. <tscreen> <verb> # -# default; standard UNIX access +# default; standard UN*X access # -OTHER auth required /usr/lib/security/pam_unix_auth.so -OTHER account required /usr/lib/security/pam_unix_acct.so -OTHER password required /usr/lib/security/pam_unix_passwd.so -OTHER session required /usr/lib/security/pam_unix_session.so +OTHER auth required pam_unix.so +OTHER account required pam_unix.so +OTHER password required pam_unix.so +OTHER session required pam_unix.so </verb> </tscreen> In general this will provide a starting place for most applications. @@ -821,13 +822,13 @@ may be subject to change or the application will be fixed.) <verb> # # ftpd; add ftp-specifics. These lines enable anonymous ftp over -# standard UNIX access (the listfile entry blocks access to +# standard UN*X access (the listfile entry blocks access to # users listed in /etc/ftpusers) # -ftpd auth sufficient /usr/lib/security/pam_ftp.so -ftpd auth required /usr/lib/security/pam_unix_auth.so use_first_pass -ftpd auth required /usr/lib/security/pam_listfile.so \ - onerr=succeed item=user sense=deny file=/etc/ftpusers +ftpd auth sufficient pam_ftp.so +ftpd auth required pam_unix_auth.so use_first_pass +ftpd auth required pam_listfile.so \ + onerr=succeed item=user sense=deny file=/etc/ftpusers </verb> </tscreen> Note, the second line is necessary since the default entries are @@ -837,15 +838,15 @@ Again, this is an example of authentication module stacking. Note the use of the <tt/sufficient/ control-flag. It says that ``if this module authenticates the user, ignore the subsequent <tt/auth/ modules''. Also note the use of the ``<tt/use_first_pass/'' -module-argument, this instructs the UNIX authentication module that it -is not to prompt for a password but rely one already having been -obtained by the ftp module. +module-argument, this instructs the UN*X authentication module that it +is not to prompt for a password but rely on one already having been +obtained by the <tt/pam_ftp/ module. <sect>Security issues of Linux-PAM <p> -This section will discuss good practices for using Linux-PAM in a -secure manner. <em>It is currently sadly lacking...suggestions are +This section will discuss good practices for using PAM in a secure +manner. <em>It is currently sadly lacking...suggestions are welcome!</em> <sect1>If something goes wrong @@ -906,10 +907,10 @@ Here's how you make your configs nice again: and then use vi to create a file called "other" in this directory. It should contain the following four lines: - auth required pam_unix_auth.so - account required pam_unix_acct.so - password required pam_unix_passwd.so - session required pam_unix_session.so + auth required pam_unix.so + account required pam_unix.so + password required pam_unix.so + session required pam_unix.so Now you have the simplest possible PAM configuration that will work the way you're used to. Everything should @@ -990,7 +991,7 @@ the examples listed below. <p><descrip> -<tag><tt>/usr/lib/libpam.so.*</tt></tag> +<tag><tt>/lib/libpam.so.*</tt></tag> the shared library providing applications with access to <bf/Linux-PAM/. @@ -999,7 +1000,7 @@ the shared library providing applications with access to the <bf/Linux-PAM/ configuration file. -<tag><tt>/usr/lib/security/pam_*.so</tt></tag> +<tag><tt>/lib/security/pam_*.so</tt></tag> the primary location for <bf/Linux-PAM/ dynamically loadable object files; the modules. diff --git a/doc/specs/draft-morgan-pam.raw b/doc/specs/draft-morgan-pam.raw index 46db0013..45109f45 100644 --- a/doc/specs/draft-morgan-pam.raw +++ b/doc/specs/draft-morgan-pam.raw @@ -1,17 +1,18 @@ -PAM working group ## A.G. Morgan -Internet Draft: ## October 6, 1999 -Document: draft-morgan-pam-07.txt ## -Expires: June 13, 2000 ## -Obsoletes: draft-morgan-pam-06.txt## +Open-PAM working group ## A.G. Morgan +Internet Draft: ## Dec 8, 2001 +Document: draft-morgan-pam-08.txt ## +Expires: June 8, 2002 ## +Obsoletes: draft-morgan-pam-07.txt## -## Pluggable Authentication Modules ## +## Pluggable Authentication Modules (PAM) ## #$ Status of this memo -This document is an draft specification. The latest version of this -draft may be obtained from here: +This document is a draft specification. Its contents are subject to +change with revision. The latest version of this draft may be obtained +from here: - http://linux.kernel.org/pub/linux/libs/pam/pre/doc/ + http://www.kernel.org/pub/linux/libs/pam/pre/doc/ As @@ -187,12 +188,14 @@ The following control characters are only legal for exchanges between an agent and a client (it is the responsibility of the client to enforce this rule in the face of a rogue server): -## 0x41 PAM_BPC_GETENV - obtain client env.var ## -## 0x42 PAM_BPC_PUTENV - set client env.var ## -## 0x43 PAM_BPC_TEXT - display message ## -## 0x44 PAM_BPC_ERROR - display error message ## -## 0x45 PAM_BPC_PROMPT - echo'd text prompt ## -## 0x46 PAM_BPC_PASS - non-echo'd text prompt## +## 0x41 PAM_BPC_GETENV - obtain client env.var ## +## 0x42 PAM_BPC_PUTENV - set client env.var ## +## 0x43 PAM_BPC_TEXT - display message ## +## 0x44 PAM_BPC_ERROR - display error message ## +## 0x45 PAM_BPC_PROMPT - echo'd text prompt ## +## 0x46 PAM_BPC_PASS - non-echo'd text prompt ## +## 0x46 PAM_BPC_STATUS - ping all active clients## +## 0x47 PAM_BPC_ABORT - please abort session ## Note, length is always equal to the total length of the binary prompt and represented by a network ordered unsigned 32 bit integer. @@ -211,10 +214,10 @@ regexp: and has a specific form for each independent agent. -o Agent_ids that do not contain an at-sign (@) are reserved to be - assigned by IANA (Internet Assigned Numbers Authority). Names of - this format MUST NOT be used without first registering with IANA. - Registered names MUST NOT contain an at-sign (@). +o Agent_ids that do not contain an at-sign (@) are to be considered as + representing some authentication mode that is a "public + standard" see reference [#$R#{PAM_STD_AGENTIDS}]. Registered names + MUST NOT contain an at-sign (@). o Anyone can define additional agents by using names in the format name@domainname, e.g. "ouragent@example.com". The part following @@ -248,8 +251,23 @@ Some client-server implementations (telnet for example) provide effective full tty connections. In these cases, the four simple text string prompting cases (see below) can be handled as in the primary login step. In other words, the server absorbs most of the overhead of -propagating authentication messages. In these cases, there is special -client/server support for handling binary prompts. +propagating authentication messages. In these cases, there needs to be +special client/server support for handling binary prompts. + +In some circumstances, a legacy network transfer protocol can carry +authentication information. In such cases, a desire to support legacy +clients (with no client-side support for PAM) will neccessitate the +'hardcoding' of an agent protocol into the server application. Whilst +against the spirit of PAM, this special casing can be managed by the +server's 'conversation function' (see below). The guiding principle +when implementing such support is for the application developer to +relegate the authentication process to the PAM module -- simply +performing a transcription of data from binary-prompt to legacy +network 'packet' and visa-versa for propagating replies back to the +driving PAM module. A common case of this is with network protocols +that define an initialization packet of "user+password". In such cases +one should attempt to support the "userpass" agent-id and its defined +protocol. #$ Defined interfaces for information flow @@ -318,8 +336,8 @@ and a single fail): ## (C) | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_OK;} ## ## | {12;PAM_BPC_TEXT;"hello!"} | {5;PAM_BPC_FAIL;} ## ## --------------------------------------------------------------- ## -## (D) | {11;PAM_BPC_TEXT;"ouch!"} | {5;PAM_BPC_OK;} ## -## | {11;PAM_BPC_TEXT;"ouch!"} | {5;PAM_BPC_FAIL;} ## +## (D) | {11;PAM_BPC_ERROR;"ouch!"} | {5;PAM_BPC_OK;} ## +## | {11;PAM_BPC_ERROR;"ouch!"} | {5;PAM_BPC_FAIL;} ## ## --------------------------------------------------------------- ## ## (E) | {13;PAM_BPC_PROMPT;"login: "} | {9;PAM_BPC_OK;"joe"} ## ## | {13;PAM_BPC_PROMPT;"login: "} | {6;PAM_BPC_OK;""} ## @@ -570,6 +588,23 @@ should go to some effort to lower its level of privilege. It remains the responsibility of the applicant and the client to ensure that it is not compromised by a rogue agent. +#$$$$ Status of agents + + int pamc_status(pamc_handle_t *pch, pamc_bp_t *prompt_p); + +At any time, the client may ping all active agents for their status +(with a PAM_BPC_STATUS binary prompt). If any agent replies with +PAM_BPC_ABORT, the client is responsible for terminating the +connection to the server and then terminating all agents with a call +to pamc_end(). In such cases, the return value of pamc_status() is +PAM_BPC_FALSE. + +If the return status of pamc_status() is PAM_BPC_TRUE and *prompt_p is +non-NULL, then an agent is requesting access to a server module. + +XXX - how this information gets propagated to the server, and + ultimately to the server's module is yet to be determined. + #$$$$ Termination of agents When closing the authentication session and severing the connection @@ -627,6 +662,11 @@ decision about the authentication method adopted by the server. pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec) pam_get_env(pam_handle_t *pamh, const char *varname) pam_strerror(pam_handle_t *pamh, int pam_errno) + +Event driven support (XXX work in progress) + + pam_register_event() - app or module associates an event poller/handler + pam_select_event() - query for any outstanding event and act on any ] #$$$ Server <-> libpam @@ -677,6 +717,24 @@ functions provided to libpam by each module pam_sm_chauthtok ] +#$$$ The conversation function + +The server application, as part of its initialization of libpam, +provides a conversation function for use by modules and libpam. The +purpose of the conversation function is to enable direct communication +to the applicant ultimately via the client and selected agents. + +[ this section will contain a definition for the conversation + function, the conversation structure (appdata etc), and legitimate + return codes for the application supplied function. + + PAM_SUCCESS - ok conversation completed + PAM_CONV_ERR - conversation failed + PAM_CONV_AGAIN - application needs control to complete conv + PAM_CONV_RECONSIDER - application believes module should check if + it still needs to converse for this info + ] + #$ Security considerations This document is devoted to standardizing authentication @@ -693,10 +751,14 @@ The email list for discussing issues related to this document is [#{OSF_RFC_PAM}] OSF RFC 86.0, "Unified Login with Pluggable Authentication Modules (PAM)", October 1995 +[#{PAM_STD_AGENTIDS}] Definitions for standard agents, "REGISTERED + AGENTS AND THEIR AGENT-ID'S", to be found here: + +## http://www.kernel.org/pub/linux/libs/pam/pre/doc/std-agent-ids.txt ## + #$ Author's Address Andrew G. Morgan -Email: morgan@ftp.kernel.org +Email: morgan@kernel.org ## $Id$ ## - diff --git a/doc/specs/std-agent-id.raw b/doc/specs/std-agent-id.raw new file mode 100644 index 00000000..d5fbdd56 --- /dev/null +++ b/doc/specs/std-agent-id.raw @@ -0,0 +1,95 @@ +PAM working group ## A.G. Morgan + +## $Id$ ## + +## Pluggable Authentication Modules ## + +## REGISTERED AGENTS AND THEIR AGENT-ID'S ## + +#$ Purpose of this document + +#$$#{definition} Definition of an agent-id + +The most complete version of a "PAM agent-id" is contained in this +reference [#$R#{PAM_RFC2}]. A copy of a recent definition is +reproduced here for convenience. The reader is recommended to consult +reference [#{PAM_RFC2}] for definitions of other terms that are +used in this document. + +## -------------- ## + +The agent_id is a sequence of characters satisfying the following +regexp: + + /^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/ + +and has a specific form for each independent agent. + +o Agent_ids that do not contain an at-sign (@) are to be considered as + representing some authentication mode that is a "public + standard". Registered names MUST NOT contain an at-sign (@). + +o Anyone can define additional agents by using names in the format + name@domainname, e.g. "ouragent@example.com". The part following + the at-sign MUST be a valid fully qualified internet domain name + [RFC-1034] controlled by the person or organization defining the + name. (Said another way, if you control the email address that + your agent has as an identifier, they you are entitled to use + this identifier.) It is up to each domain how it manages its local + namespace. + +## -------------- ## + +#$ Registered agent-id's + +The structure of this section is a single subsection for each +registered agent-id. This section includes a full definition of binary +prompts accepted by the agent and example responses of said +agent. Using the defining section alone, it should be possible for a +third party to create a conforming agent and modules that can +interoperate with other implementations of these objects. + +*$ "userpass" - the user+password agent + +Many legacy authentication systems are hardcoded to support one and +only one authentication method. Namely, + + username: joe + password: <secret> + +Indeed, this authentication method is often embedded into parts of the +transport protocol. The "user+password" agent with PAM agent-id: + + "userpass" + +Is intended to support this legacy authentication scheme. The protocol +for binary prompt exchange with this 'standard agent' is as follows: + +Case 1: module does not know the username, but expects the agent to + obtain this information and also the user's password: + + module: {LENGTH;PAM_BP_SELECT;userpass;'/'} + agent: {} + +Case 2: module has suggested username, but would like agent to confirm + it and gather password: + + module: {} + agent: {} + +Case 3: module knows username and will not permit the agent to change it: + + module: {} + agent: {} + +#$ References + +[#{PAM_RFC2}] Internet draft, "Pluggable Authentication Modules + (PAM)", available here: + +# http://linux.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt # + +#$ Author's Address + +Andrew G. Morgan +Email: morgan@kernel.org -- cgit v1.2.3