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
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
Please feel free to submit amendments/comments etc. regarding these
files to:
- Andrew G. Morgan <morgan@parc.power.net>
+ Andrew G. Morgan <morgan@kernel.org>
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
long password amendments are from Philip W. Dalrymple III <pwd@mdtsoft.com>
-->
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>The locking-out module
pam_deny
<tag><bf>Author:</bf></tag>
-Andrew G. Morgan <morgan@parc.power.net>
+Andrew G. Morgan <morgan@kernel.org>
<tag><bf>Maintainer:</bf></tag>
current <bf/Linux-PAM/ maintainer
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>The filter module
<tag><bf>Author:</bf></tag>
-Andrew G. Morgan <morgan@parc.power.net>
+Andrew G. Morgan <morgan@kernel.org>
<tag><bf>Maintainer:</bf></tag>
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>Anonymous access module
<tt/pam_ftp.so/
<tag><bf>Author:</bf></tag>
-Andrew G. Morgan <morgan@linux.kernel.org>
+Andrew G. Morgan <morgan@kernel.org>
<tag><bf>Maintainer:</bf></tag>
Author.
This module intercepts the user's name and password. If the name is
``<tt/ftp/'' or ``<tt/anonymous/'', the user's password is broken up
-at the `<tt/@/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/
-part; these pam-items being set accordingly. The username is set to
-``<tt/ftp/''. In this case the module succeeds. Alternatively, the
-module sets the <tt/PAM_AUTHTOK/ item with the entered password and
-fails.
+at the `<tt/@/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/
+part; these pam-items being set accordingly. The username
+(<tt/PAM_USER/) is set to ``<tt/ftp/''. In this case the module
+succeeds. Alternatively, the module sets the <tt/PAM_AUTHTOK/ item
+with the entered password and fails.
<p>
The behavior of the module can be modified with the following flags:
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>The group access module
<tt/pam_group/
<tag><bf>Author:</bf></tag>
-Andrew G. Morgan <morgan@parc.power.net>
+Andrew G. Morgan <morgan@kernel.org>
<tag><bf>Maintainer:</bf></tag>
Author.
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>The mail module
<tt/pam_mail/
<tag><bf>Author:</bf></tag>
-Andrew G. Morgan <morgan@linux.kernel.org>
+Andrew G. Morgan <morgan@kernel.org>
<tag><bf>Maintainer:</bf></tag>
Author
<tag><bf>Author:</bf></tag>
Written by Michael K. Johnson <johnsonm@redhat.com><newline>
(based on code taken from a module written by Andrew G. Morgan
-<morgan@parc.power.net>).
+<morgan@kernel.org>).
<tag><bf>Maintainer:</bf></tag>
Michael K. Johnson <johnsonm@redhat.com>
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>The promiscuous module
pam_permit
<tag><bf>Author:</bf></tag>
-Andrew G. Morgan, <morgan@parc.power.net>
+Andrew G. Morgan, <morgan@kernel.org>
<tag><bf>Maintainer:</bf></tag>
Linux-PAM maintainer.
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>The rhosts module
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>The root access module
pam_rootok
<tag><bf>Author:</bf></tag>
-Andrew G. Morgan <morgan@parc.power.net>
+Andrew G. Morgan <morgan@kernel.org>
<tag><bf>Maintainer:</bf></tag>
<bf>Linux-PAM</bf> maintainer
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>Time control
<tt/pam_time/
<tag><bf>Author:</bf></tag>
-Andrew G. Morgan <tt><morgan@parc.power.net></tt>
+Andrew G. Morgan <tt><morgan@kernel.org></tt>
<tag><bf>Maintainer:</bf></tag>
Author
<!--
- This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
Converted from the pam_pwdb.sgml file for pam_unix by Ben Collins <bcollins@debian.org>
-->
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
-->
<sect1>Warning logger module
<tt/pam_warn/
<tag><bf>Author:</bf></tag>
-Andrew G. Morgan <morgan@parc.power.net>
+Andrew G. Morgan <morgan@kernel.org>
<tag><bf>Maintainer:</bf></tag>
Author.
<!--
$Id$
- This file was written by Andrew G. Morgan <morgan@parc.power.net>
+ This file was written by Andrew G. Morgan <morgan@kernel.org>
from notes provided by Cristian Gafton.
-->
<title>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
<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
<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>
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
<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
<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
<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
<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
<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
<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
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">
<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">
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>
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>
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>
#
# 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
#
# 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.
#
# 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>
<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.
<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
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
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
<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/.
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.
-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
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.
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
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
## (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;""} ##
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
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
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
[#{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$ ##
-
--- /dev/null
+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
projects / linux-pam / commitdiff