|author||Andrew G. Morgan <firstname.lastname@example.org>||2001-12-08 18:56:47 +0000|
|committer||Andrew G. Morgan <email@example.com>||2001-12-08 18:56:47 +0000|
Relevant BUGIDs: [tasks] 43507, 17426
Purpose of commit: documentation Commit summary: --------------- Generally more documentation with some cleanups and email address sanitization.
Diffstat (limited to 'doc/pam_appl.sgml')
1 files changed, 51 insertions, 15 deletions
diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml
index f033dff0..87c9e6e3 100644
@@ -46,7 +46,7 @@ DAMAGE.
<title>The Linux-PAM Application Developers' Guide
<author>Andrew G. Morgan, <tt>firstname.lastname@example.org</tt>
-<date>DRAFT v0.76 2001/05/26
+<date>DRAFT v0.76 2001/12/08
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,
- The service name
+ The service name (which identifies that PAM stack that
+ <tt/libpam/ will use to authenticate the program).
- 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.
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: ''.
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.
- 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.
- 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 "<email@example.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
The conversation structure (see section <ref
+ 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">).
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:
@@ -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)/. 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).
For network-serving databases and other applications that provide
@@ -1563,7 +1599,7 @@ purpose at the moment. Ideas/suggestions welcome!
This document was written by Andrew G. Morgan
-(firstname.lastname@example.org) with many contributions from
+(email@example.com) 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
-Copyright (c) Andrew G. Morgan 1996-9. All rights reserved.
+Copyright (c) Andrew G. Morgan 1996-9,2000-1. All rights reserved.
Redistribution and use in source and binary forms, with or without