horok/pam
1
0
Fork 0
Code Activity

Adding upstream version 1.7.0.

Browse source 
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
This commit is contained in:
Daniel Baumann 2025-06-21 06:53:43 +02:00
parent 3d1aa0caa1
commit 82f0236850
Signed by: daniel.baumann
GPG key ID: BCC918A2ABD66424
776 changed files with 129446 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

7
AUTHORS Normal file
View file

@ -0,0 +1,7 @@
Original authors and current maintainers of Linux-PAM:
Andrew G. Morgan <morgan@kernel.org>
Dmitry V. Levin <ldv@altlinux.org>
Thorsten Kukuk <kukuk@thkukuk.de>
Sebastien Tricaud <toady@gscore.org>
Tomas Mraz <t8m@centrum.cz>

40
COPYING Normal file
View file

@ -0,0 +1,40 @@
Unless otherwise *explicitly* stated the following text describes the
licensed conditions under which the contents of this Linux-PAM release
may be distributed:
-------------------------------------------------------------------------
Redistribution and use in source and binary forms of Linux-PAM, with
or without modification, are permitted provided that the following
conditions are met:
1. Redistributions of source code must retain any existing copyright
notice, and this entire permission notice in its entirety,
including the disclaimer of warranties.
2. Redistributions in binary form must reproduce all prior and current
copyright notices, this list of conditions, and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
3. The name of any author may not be used to endorse or promote
products derived from this software without their specific prior
written permission.
ALTERNATIVELY, this product may be distributed under the terms of the
GNU General Public License, in which case the provisions of the GNU
GPL are required INSTEAD OF the above restrictions. (This clause is
necessary due to a potential conflict between the GNU GPL and the
restrictions contained in a BSD-style copyright.)
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
-------------------------------------------------------------------------

40
Copyright Normal file
View file

@ -0,0 +1,40 @@
Unless otherwise *explicitly* stated the following text describes the
licensed conditions under which the contents of this Linux-PAM release
may be distributed:
-------------------------------------------------------------------------
Redistribution and use in source and binary forms of Linux-PAM, with
or without modification, are permitted provided that the following
conditions are met:
1. Redistributions of source code must retain any existing copyright
notice, and this entire permission notice in its entirety,
including the disclaimer of warranties.
2. Redistributions in binary form must reproduce all prior and current
copyright notices, this list of conditions, and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
3. The name of any author may not be used to endorse or promote
products derived from this software without their specific prior
written permission.
ALTERNATIVELY, this product may be distributed under the terms of the
GNU General Public License, in which case the provisions of the GNU
GPL are required INSTEAD OF the above restrictions. (This clause is
necessary due to a potential conflict between the GNU GPL and the
restrictions contained in a BSD-style copyright.)
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
-------------------------------------------------------------------------

518
NEWS Normal file
View file

@ -0,0 +1,518 @@
Linux-PAM NEWS -- history of user-visible changes.
Release 1.7.0
* build: changed build system from autotools to meson.
* libpam_misc: use ECHOCTL in the terminal input
* pam_access: support UID and GID in access.conf
* pam_env: install environment file in vendordir if vendordir is enabled
* pam_issue: only count class user if logind support is enabled
* pam_limits: use systemd-logind instead of utmp if logind support is enabled
* pam_unix: compare password hashes in constant time
* Multiple minor bug fixes, build fixes, portability fixes,
documentation improvements, and translation updates.
Release 1.6.1
* build: fail if specified configure options cannot be satisfied.
* pam_env: fixed --disable-econf --enable-vendordir support.
* pam_unix: do not warn if password aging is disabled.
* pam_unix: try to set uid to 0 before unix_chkpwd invocation.
* pam_unix: allow empty passwords with non-empty hashes.
* Multiple minor bug fixes, build fixes, portability fixes,
documentation improvements, and translation updates.
Release 1.6.0
* Added support of configuration files with arbitrarily long lines.
* build: fixed build outside of the source tree.
* libpam: added use of getrandom(2) as a source of randomness if available.
* libpam: fixed calculation of fail delay with very long delays.
* libpam: fixed potential infinite recursion with includes.
* libpam: implemented string to number conversions validation when parsing
controls in configuration.
* pam_access: added quiet_log option.
* pam_access: fixed truncation of very long group names.
* pam_canonicalize_user: new module to canonicalize user name.
* pam_echo: fixed file handling to prevent overflows and short reads.
* pam_env: added support of '\' character in environment variable values.
* pam_exec: allowed expose_authtok for password PAM_TYPE.
* pam_exec: fixed stack overflow with binary output of programs.
* pam_faildelay: implemented parameter ranges validation.
* pam_listfile: changed to treat \r and \n exactly the same in configuration.
* pam_mkhomedir: hardened directory creation against timing attacks.
Please note that using *at functions leads to more open file handles
during creation.
* pam_namespace: fixed potential local DoS (CVE-2024-22365).
* pam_nologin: fixed file handling to prevent short reads.
* pam_pwhistory: helper binary is now built only if SELinux support is enabled.
* pam_pwhistory: implemented reliable usernames handling when remembering
passwords.
* pam_shells: changed to allow shell entries with absolute paths only.
* pam_succeed_if: fixed treating empty strings as numerical value 0.
* pam_unix: added support of disabled password aging.
* pam_unix: synchronized password aging with shadow.
* pam_unix: implemented string to number conversions validation.
* pam_unix: fixed truncation of very long user names.
* pam_unix: corrected rounds retrieval for configured encryption method.
* pam_unix: implemented reliable usernames handling when remembering passwords.
* pam_unix: changed to always run the helper to obtain shadow password entries.
* pam_unix: unix_update helper binary is now built only if SELinux support
is enabled.
* pam_unix: added audit support to unix_update helper.
* pam_userdb: added gdbm support.
* Multiple minor bug fixes, portability fixes, documentation improvements,
and translation updates.
Release 1.5.3
* configure: added options to configure stylesheets.
* configure: added --enable-logind option to use logind instead of utmp
in pam_issue and pam_timestamp.
* pam_modutil_getlogin: changed to use getlogin() from libc instead of parsing utmp.
* Added libeconf support to pam_env and pam_shells.
* Added vendor directory support to pam_access, pam_env, pam_group, pam_faillock,
pam_limits, pam_namespace, pam_pwhistory, pam_sepermit, pam_shells, and pam_time.
* pam_limits: changed to not fail on missing config files.
* pam_pwhistory: added conf= option to specify config file location.
* pam_pwhistory: added file= option to specify password history file location.
* pam_shells: added shells.d support when libeconf and vendordir are enabled.
* Deprecated pam_lastlog: this module is no longer built by default because
it uses utmp, wtmp, btmp and lastlog, but none of them are Y2038 safe,
even on 64bit architectures.
pam_lastlog will be removed in one of the next releases, consider using
pam_lastlog2 (from https://github.com/thkukuk/lastlog2) and/or
pam_wtmpdb (from https://github.com/thkukuk/wtmpdb) instead.
* Deprecated _pam_overwrite(), _pam_overwrite_n(), and _pam_drop_reply() macros
provided by _pam_macros.h; the memory override performed by these macros can
be optimized out by the compiler and therefore can no longer be relied upon.
* Multiple minor bug fixes, portability fixes, documentation improvements,
and translation updates.
Release 1.5.2
* pam_exec: implemented quiet_log option.
* pam_mkhomedir: added support of HOME_MODE and UMASK from /etc/login.defs.
* pam_timestamp: changed hmac algorithm to call openssl instead of the bundled
sha1 implementation if selected, added option to select
the hash algorithm to use with HMAC.
* Added pkgconfig files for provided libraries.
* Added --with-systemdunitdir configure option to specify systemd unit
directory.
* Added --with-misc-conv-bufsize configure option to specify the buffer size
in libpam_misc's misc_conv() function, raised the default value for this
parameter from 512 to 4096.
* Multiple minor bug fixes, portability fixes, documentation improvements,
and translation updates.
Release 1.5.1
* pam_unix: fixed CVE-2020-27780 - authentication bypass when a user
doesn't exist and root password is blank
* pam_faillock: added nodelay option to not set pam_fail_delay
* pam_wheel: use pam_modutil_user_in_group to check for the group membership
with getgrouplist where it is available
Release 1.5.0
* Multiple minor bug fixes, portability fixes, and documentation improvements.
* Extended libpam API with pam_modutil_check_user_in_passwd function.
* configure: added --disable-unix option to disable build of pam_unix module.
* pam_faillock: changed /run/faillock/$USER permissions from 0600 to 0660.
* pam_limits: added support for nonewprivs item.
* pam_motd: read motd files with target user credentials skipping unreadable ones.
* pam_pwhistory: added a SELinux helper executable.
* pam_unix, pam_usertype: implemented avoidance of certain timing attacks.
* pam_wheel: implemented PAM_RUSER fallback for the case when getlogin fails.
* Removed deprecated pam_cracklib module, use pam_passwdqc (from passwdqc project)
or pam_pwquality (from libpwquality project) instead.
* Removed deprecated pam_tally and pam_tally2 modules, use pam_faillock instead.
* pam_env: Reading of the user environment is deprecated and will be removed
at some point in the future.
* libpam: pam_modutil_drop_priv() now correctly sets the target user's
supplementary groups, allowing pam_motd to filter messages accordingly
Release 1.4.0
* Multiple minor bug fixes and documentation improvements
* Fixed grammar of messages printed via pam_prompt
* Added support for a vendor directory and libeconf
* configure: Added --enable-Werror option to enable -Werror build
* configure: Allowed disabling documentation through --disable-doc
* pam_get_authtok_verify: Avoid duplicate password verification
* pam_cracklib: Fixed parsing of options without arguments
* pam_env: Changed the default to not read the user .pam_environment file
* pam_exec: Require a user name to be specified before the command is executed
* pam_faillock: New module for locking after multiple auth failures
* pam_group, pam_time: Fixed logical error with multiple ! operators
* pam_keyinit: In pam_sm_setcred do the same as in pam_sm_open_session
* pam_lastlog: Do not log info about failed login if the session was opened
with PAM_SILENT flag
* pam_lastlog: Limit lastlog file use by LASTLOG_UID_MAX option in login.defs
* pam_lastlog: With 'unlimited' option prevent SIGXFSZ due to reduced 'fsize'
limit
* pam_mkhomedir: Fixed return value when the user is unknown
* pam_motd: Export MOTD_SHOWN=pam after showing MOTD
* pam_motd: Support multiple motd paths specified, with filename overrides
* pam_namespace: Added a systemd service, which creates the namespaced
instance parent directories during boot
* pam_namespace: Support for noexec, nosuid and nodev flags for tmpfs mounts
* pam_selinux: Check unknown object classes or permissions in current policy
* pam_selinux: Fall back to log to syslog if audit logging fails
* pam_setquota: New module to set or modify disk quotas on session start
* pam_shells: Recognize /bin/sh as the default shell
* pam_succeed_if: Fixed potential override of the default prompt
* pam_succeed_if: Support lists in group membership checks
* pam_time: Added conffile= option to specify an alternative configuration file
* pam_tty_audit: If kernel audit is disabled return PAM_IGNORE
* pam_umask: Added new 'nousergroups' module argument and allowed specifying
the default for usergroups at build-time
* pam_unix: Added 'nullresetok' option to allow resetting blank passwords
* pam_unix: Report unusable hashes found by checksalt to syslog
* pam_unix: Return PAM_AUTHINFO_UNAVAIL when shadow entry is unavailable
* pam_unix: Support for (gost-)yescrypt hashing methods
* pam_unix: Use bcrypt b-variant when it bcrypt is chosen
* pam_usertype: New module to tell if uid is in login.defs ranges
* Fixed and documented possible values returned by pam_get_user()
* Added new API call pam_start_confdir() for special applications that
cannot use the system-default PAM configuration paths and need to
explicitly specify another path
* Deprecated pam_cracklib: this module is no longer built by default and will
be removed in the next release, use pam_passwdqc (from passwdqc project)
or pam_pwquality (from libpwquality project) instead
* Deprecated pam_tally and pam_tally2: these modules are no longer built
by default and will be removed in the next release, use pam_faillock instead
Release 1.3.1
* pam_motd: add support for a motd.d directory
* pam_umask: Fix documentation to align with order of loading umask
* pam_get_user.3: Fix missing word in documentation
* pam_tally2 --reset: avoid creating a missing tallylog file
* pam_mkhomedir: Allow creating parent of homedir under /
* access.conf.5: Add note about spaces around ':'
* pam.8: Workaround formatting problem
* pam_unix: Check return value of malloc used for setcred data
* pam_cracklib: Drop unused prompt macros
* pam_tty_audit: Support matching users by uid range
* pam_access: support parsing files in /etc/security/access.d/*.conf
* pam_localuser: Correct documentation
* pam_issue: Fix no prompting in parse escape codes mode
* Unification and cleanup of syslog log levels
Release 1.3.0
* Remove of static modules support
* pam_unix: pass_not_set was removed
* Lot of documentation fixes
* Use TI-RPC function calls if we build against libtirpc
* Add support for new, IPv6 enabled libnsl
* Lot of bug fixes
* Use fedora.zanata.org for translations
Release 1.2.1
* Fix CVE-2015-3238, affected PAM modules are pam_unix and pam_exec
Release 1.2.0
* Update documentation
* Update translations
* pam_unix: add quiet option
* libpam: support alternative configuration files in /usr/lib/pam.d
as fallback
* pam_env: add support for @{HOME} and @{SHELL}
* libpam: add grantor field to audit records
* libpam: Introduce pam_modutil_sanitize_helper_fds
Release 1.1.8
* pam_unix: bug fix for compiling with SELinux, fix crash at login time
Release 1.1.7
* Update translations
* pam_exec: add stdout and type= options
* pam_tty_audit: add options to control logging of passwords
* pam_unix: Read defaults from /etc/login.defs
* pam_userdb: Allow modern password hashes
* pam_selinux/pam_tally2: Add tty and rhost to audit data
* Lot of docu and code fixes
Release 1.1.6
* Update translations
* pam_cracklib: Add more checks for weak passwords
* pam_lastlog: Never lock out root
* Lot of bug fixes and smaller enhancements
Release 1.1.5
* pam_env: Fix CVE-2011-3148 and CVE-2011-3149
* pam_access: Add hostname resolution cache
* Documentation: Improvements/fixes
Release 1.1.4
* Add vietnamese translation
* pam_namespace: Add new functionality
* pam_securetty: Honour console= kernel option, add noconsole option
* pam_limits: Add %group syntax, drop change_uid option, add set_all option
* Lot of small bug fixes
* Lot of compiler warnings fixed
* Add support for libtirpc
Release 1.1.3
* pam_namespace: Clean environment for child processes (CVE-2010-3853)
* libpam: New interface to drop/regain privileges
* Drop root privileges in pam_env, pam_mail and pam_xauth before
accessing user files (CVE-2010-3430, CVE-2010-3431)
* pam_unix: Add minlen option, change default from 6 to 0
* Documentation improvements
* Lot of small bug fixes
Release 1.1.2
* pam_unix: Add minlen= option
* pam_group: Add support for UNIX groups beside netgroups
* pam_tally: Document that it is deprecated
* pam_rootok: Add support for chauthtok and acct_mgmt
* Update translations
Release 1.1.1
* Update translations
* pam_access: Revert netgroup match to original behavior, add new
syntax for adding the local hostname to netgroup match
* libpam: Add new functions pam_get_authtok_noverify() and
pam_get_authtok_verify()
* Add sepermit.conf.5 manual page
* Lot of bug fixes
Release 1.1.0
* Update translations
* Documentation updates and fixes
Release 1.0.92
* Update translations
* pam_succeed_if: Use provided username
* pam_mkhomedir: Fix handling of options
Release 1.0.91
* Fixed CVE-2009-0579 (minimum days limit on password change is ignored).
* Fix libpam internal config/argument parser
* Add optional file locking to pam_tally2
* Update translations
* pam_access improvements
* Changes in the behavior of the password stack. Results of PRELIM_CHECK
are not used for the final run.
Release 1.0.90
* Supply hostname of the machine to netgroup match call in pam_access
* Make pam_namespace to work safe on child directories of parent directories
owned by users
* Redefine LOCAL keyword of pam_access configuration file
* Add support for try_first_pass and use_first_pass to pam_cracklib
* Print informative messages for rejected login and add silent and
no_log_info options to pam_tally
* Add support for passing PAM_AUTHTOK to stdin of helpers from pam_exec
* New password quality tests in pam_cracklib
* New options for pam_lastlog to show last failed login attempt and
to disable lastlog update
* New pam_pwhistory module to store last used passwords
* New pam_tally2 module similar to pam_tally with wordsize independent
tally data format
* Make libpam not log missing module if its type is prepended with '-'
* New pam_timestamp module for authentication based on recent successful
login.
* Add blowfish support to pam_unix.
* Add support for user specific environment file to pam_env.
* Add pam_get_authtok to libpam as Linux-PAM extension.
* Rename type option of pam_cracklib to authtok_type.
Release 1.0.3
* Small bug fix release
Release 1.0.2
* Regression fixed in pam_selinux
* Problem with big UIDs fixed in pam_loginuid
Release 1.0.1
* Regression fixed in pam_set_item()
Release 1.0.0
* Small bug fixes
* Translation updates
Release 0.99.10.0
* New substack directive in config file syntax.
* New module pam_tty_audit.so for enabling and disabling tty
auditing.
* New PAM items PAM_XDISPLAY and PAM_XAUTHDATA.
* Auditing login denials based by origin (pam_access), time (pam_time),
and number of sessions (pam_limits) to the Linux audit subsystem.
* Support sha256 and sha512 algorithms in pam_unix when they are supported
by crypt().
* New pam_sepermit.so module for allowing/rejecting access based on
SELinux mode.
* Improved functionality of pam_namespace.so module (method flags,
namespace.d configuration directory, new options).
* Finally removed deprecated pam_rhosts_auth module.
Release 0.99.9.0
* misc_conv no longer blocks SIGINT; applications that don't want
user-interruptable prompts should block SIGINT themselves
* Merge fixes from Debian
* Fix parser for pam_group and pam_time
Release 0.99.8.1
* Fix a regression in audit code introduced with last release
* Fix compiling with --disable-nls
Release 0.99.8.0
* Add translations for ar, ca, da, ru, sv and zu.
* Update hungarian translation.
* Add support for limits.d directory to pam_limits.
* Improve pam_namespace module tobe more useful
for MLS, fixed crash with bad config files.
* Improve pam_selinux module to be more useful
for MLS.
* Add minclass option to pam_cracklib
* Add new group syntax to pam_access
Release 0.99.7.1
* Security fix for pam_unix.so (CVE-2007-0003).
Release 0.99.7.0
* Add manual page for pam_unix.so.
* Add pam_faildelay module to set pam_fail_delay() value.
* Fix possible seg.fault in libpam/pam_set_data().
* Cleanup of configure options.
* Update hungarian translation, fix german translation.
Release 0.99.6.3
* pam_loginuid: New PAM module.
* pam_access, pam_succeed_if: Support passwd and session services.
Release 0.99.6.2
* pam_lastlog: Don't refuse login if lastlog file got lost.
* pam_cracklib: Fix a user triggerable crash.
* documentation: Regenerate with fixed docbook stylesheet.
Release 0.99.6.1
* Fix bootstrapping problems.
* Bug fixes: pam_keyinit, pam_umask
Release 0.99.6.0
* pam_namespace: Code cleanup, add init script to tar archive.
* pam_succeed_if: Add support for service match.
* Add xtests (to run after installation).
* Documentation: Convert sgml guides to XML, unify documentation
for PAM functions and modules.
Release 0.99.5.0
* pam_tally: Fix support for large UIDs
* Fixed all problems found by Coverity
* Add support for Intel C Compiler
* Add manual page for pam_mkhomedir, pam_umask, pam_filter,
pam_issue, pam_ftp, pam_group, pam_lastlog, pam_listfile,
pam_localuser, pam_mail, pam_motd, pam_nologin, pam_permit,
pam_rootok, pam_securetty, pam_shells, pam_userdb, pam_warn,
pam_time, pam_limits, pam_debug, pam_tally
* The libpam memory debug code was removed
* pam_keyinit: New module to initialise kernel session keyring.
* pam_namespace: New module to configure private namespace for a session.
* pam_rhosts: New module which replaces pam_rhosts_auth, now IPv6 capable.
* pam_rhosts_auth: This module is now deprecated.
Release 0.99.4.0
* Add test suite
* Fix building of static variants of libpam, libpamc and libpam_misc
* pam_listfile: Add support for password and session management
* pam_exec: New PAM module to execute arbitrary commands
* Fix building of a static libpam including all PAM modules
* New/updated translations for: nl, pt, pl, fi, km, tr, uk, fr
* pam_access: Add network(address) / netmask and IPv6 support
* Add manual pages for pam_cracklib, pam_deny and pam_access
* pam_pwdb: This deprecated module was removed
* Manual pages: Major rewrite/cleanup
Release 0.99.3.0
* Fix NULL pointer checks in libpam.so
* pam_succeed_if, pam_group, pam_time: Support netgroup matching
* New translations for: nb, hu, fi, de, es, fr, it, ja, pt_BR, zh_CN, zh_TW
* Audit PAM calls if Linux Audit is available
* Compile upperLOWER and unix_chkpwd as PIE binaries
Release 0.99.2.1
* Fix install of PS, PDF, TXT and HTML files
* pam_mail: Update README
* Use %m consistent
* pam_modutil_getlogin: Fix parsing of PAM_TTY variable
Release 0.99.2.0
* Fix parsing of full path tty name in various modules
* pam_xauth: Look for xauth executable in multiple places
* pam_unix: Disable user check in unix_chkpwd only if real uid
is 0 (CVE-2005-2977). Log failed password check attempt.
* pam_env: Support /etc/environment again, but don't treat it as
error if it is missing.
* pam_userdb: Fix memory leak.
Release 0.99.1.0
* Use autoconf/automake/libtool
* Add gettext support
* Add translations for cs, de, es, fr, hu, it, ja, nb, pa, pt_BR,
pt, zh_CN and zh_TW
* libpam: Remove pam_authenticate_secondary stub
* libpam: Add pam_prompt,pam_vprompt,pam_error,pam_verror,pam_info
and pam_vinfo functions for use by modules as extension
* libpam: Add pam_syslog function for unified syslog messages from
PAM modules
* libpam: Moved functions from pammodutil to libpam
* pam_umask: New module for setting umask from GECOS field, /etc/login.defs
or /etc/default/login
* pam_echo: New PAM module for message output
* pam_userdb: Fix regression (crash when crypt param not specified)
* pam_limits: Fix regression from RLIMIT_NICE support (wrong limit
values for other limits are applied)
* pam_access: Support for NULL tty - matches ALL and NONE keywords
* pam_lastlog: Enable log to wtmp by default. Add "nowtmp" option
* pam_radius: This module was removed

50
README Normal file
View file

@ -0,0 +1,50 @@
Hello!
Thanks for downloading Linux-PAM.
NOTES:
How to use it is as follows:
Please look at the ci/install-dependencies.sh for the necessary
prerequisite packages to be able to build the Linux-PAM. The script
is targeted at Debian based Linux distributions so the package
names and availability might differ on other distributions.
First, configure the build using meson setup:
mkdir build
meson setup <your-options> build
Then compile:
meson compile -C build
To make sure everything was compiled correct, run:
meson test -C build
If a test fails, you should not continue to install this build.
These tests require a suitable file /etc/pam.d/other; if necessary,
create such a file containing, e.g., these five lines (not indented)
#%PAM-1.0
auth required pam_deny.so
account required pam_deny.so
password required pam_deny.so
session required pam_deny.so
Note, if you are worried - don't even think about doing the next line
(most Linux distributions already support PAM out of the box, so if
something goes wrong with installing the code from this version your
box may stop working..)
meson install -C build
That said, please report problems to the bug reporting database
at https://github.com/linux-pam/linux-pam/issues .
To generate manual pages from the XML source files you need the
docbook-xsl stylesheets in version 1.69.1 or newer, older versions had
a bug which generates a broken layout.

6
aux/chdir_meson_build_subdir.sh Executable file
View file

@ -0,0 +1,6 @@
#!/bin/sh -efu
exe=$1; shift
exe=$(readlink -ev -- "$exe")
cd "$MESON_BUILD_SUBDIR"
exec "$exe" "$@"

6
aux/redir_exe.sh Executable file
View file

@ -0,0 +1,6 @@
#!/bin/sh -efu
# stdin stdout ...
exec < "$1"; shift
exec > "$1"; shift
exec "$@"

53
ci/build.sh Executable file
View file

@ -0,0 +1,53 @@
#!/bin/sh -ex
#
# Copyright (c) 2018-2024 The strace developers.
# All rights reserved.
#
# SPDX-License-Identifier: GPL-2.0-or-later
opts='-Doptimization=2 -Dwerror=true -Dpam_lastlog=enabled'
case "${VENDORDIR-}" in
*/*)
opts="$opts -Dvendordir=$VENDORDIR"
;;
esac
case "${USE_OPENSSL-}" in
yes)
opts="$opts -Dopenssl=enabled"
;;
esac
case "${ENABLE_DEBUG-}" in
yes)
opts="$opts -Dpam-debug=true"
;;
esac
echo 'BEGIN OF BUILD ENVIRONMENT INFORMATION'
uname -a |head -1
libc="$(ldd /bin/sh |sed -n 's|^[^/]*\(/[^ ]*/libc\.so[^ ]*\).*|\1|p' |head -1)"
$libc |head -1
$CC --version |head -1
meson --version |head -1
ninja --version |head -1
kver="$(printf '%s\n%s\n' '#include <linux/version.h>' 'LINUX_VERSION_CODE' | $CC -E -P -)"
printf 'kernel-headers %s.%s.%s\n' $((kver/65536)) $((kver/256%256)) $((kver%256))
echo 'END OF BUILD ENVIRONMENT INFORMATION'
mkdir build
meson setup $opts build
# If "meson dist" supported -v option, it could be used here
# instead of all subsequent individual meson commands.
meson compile -v -C build
mkdir build/destdir
DESTDIR=$(pwd)/build/destdir meson install -C build
meson test -v -C build
if git status --porcelain |grep '^?'; then
echo >&2 'git status reported untracked files'
exit 1
fi

77
ci/install-dependencies.sh Executable file
View file

@ -0,0 +1,77 @@
#!/bin/sh -ex
#
# Copyright (c) 2018-2019 The strace developers.
# All rights reserved.
#
# SPDX-License-Identifier: GPL-2.0-or-later
j=-j`nproc` || j=
type sudo >/dev/null 2>&1 && sudo=sudo || sudo=
packages="
bison
docbook5-xml
docbook-xsl-ns
flex
gettext
libaudit-dev
libdb-dev
libfl-dev
libselinux1-dev
libssl-dev
libxml2-utils
meson
pkg-config
sed
w3m
xsltproc
xz-utils
$CC"
retry_if_failed()
{
for i in `seq 0 99`; do
"$@" && i= && break || sleep 1
done
[ -z "$i" ]
}
updated=
apt_get_install()
{
[ -n "$updated" ] || {
retry_if_failed $sudo apt-get -qq update
updated=1
}
retry_if_failed $sudo \
apt-get -qq --no-install-suggests --no-install-recommends \
install -y "$@"
}
case "$CC" in
gcc-*)
retry_if_failed \
$sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
;;
esac
case "$TARGET" in
x32|x86)
packages="$packages gcc-multilib"
case "$CC" in
gcc-*) packages="$packages $CC-multilib" ;;
esac
;;
esac
apt_get_install $packages
case "${CHECK-}" in
coverage)
apt_get_install lcov python-pip python-setuptools
retry_if_failed \
pip install --user codecov
;;
valgrind)
apt_get_install valgrind
;;
esac

36
conf/install_conf Executable file
View file

@ -0,0 +1,36 @@
#!/bin/sh
CONFILE="$FAKEROOT"$CONFIGED/pam.conf
IGNORE_AGE=./.ignore_age
CONF=./pam.conf
echo
if [ -f "$IGNORE_AGE" ]; then
echo "you don't want to be bothered with the age of your $CONFILE file"
yes="n"
elif [ ! -f "$CONFILE" ] || [ "$CONF" -nt "$CONFILE" ]; then
if [ -f "$CONFILE" ]; then
echo "\
An older Linux-PAM configuration file already exists ($CONFILE)"
WRITE=overwrite
fi
echo -n "\
Do you wish to copy the $CONF file in this distribution
to $CONFILE ? (y/n) [n] "
read yes
else
yes=n
fi
if [ "$yes" = "y" ]; then
echo " copying $CONF to $CONFILE"
cp $CONF $CONFILE
else
touch "$IGNORE_AGE"
echo " Skipping $CONF installation"
fi
echo
exit 0

43
conf/md5itall Executable file
View file

@ -0,0 +1,43 @@
#!/bin/bash
#
# $Id$
#
# Created by Andrew G. Morgan (morgan@parc.power.net)
#
MD5SUM=md5sum
CHKFILE1=./.md5sum
CHKFILE2=./.md5sum-new
which $MD5SUM > /dev/null
result=$?
if [ -x "$MD5SUM" ] || [ $result -eq 0 ]; then
rm -f $CHKFILE2
echo -n "computing md5 checksums."
for x in `cat ../.filelist` ; do
(cd ../.. ; $MD5SUM $x) >> $CHKFILE2
echo -n "."
done
echo
if [ -f "$CHKFILE1" ]; then
echo "\
---> Note, since the last \`make check', the following file(s) have changed:
==========================================================================="
diff $CHKFILE1 $CHKFILE2
if [ $? -eq 0 ]; then
echo "\
--------------------------- Nothing has changed ---------------------------"
fi
echo "\
==========================================================================="
fi
rm -f "$CHKFILE1"
mv "$CHKFILE2" "$CHKFILE1"
chmod 400 "$CHKFILE1"
else
echo "\
Please install \`$MD5SUM'.
[It is used to check the integrity of this distribution]
---> no check done."
fi

120
conf/pam.conf Normal file
View file

@ -0,0 +1,120 @@
# ---------------------------------------------------------------------------#
# /etc/pam.conf #
# #
# Last modified by Andrew G. Morgan <morgan@kernel.org> #
# ---------------------------------------------------------------------------#
# $Id$
# ---------------------------------------------------------------------------#
# serv. module ctrl module [path] ...[args..] #
# name type flag #
# ---------------------------------------------------------------------------#
#
# The PAM configuration file for the `chfn' service
#
chfn auth required pam_unix.so
chfn account required pam_unix.so
chfn password required pam_unix.so shadow md5 use_authtok
#
# The PAM configuration file for the `chsh' service
#
chsh auth required pam_unix.so
chsh account required pam_unix.so
chsh password required pam_unix.so shadow md5 use_authtok
#
# The PAM configuration file for the `ftp' service
#
ftp auth requisite pam_listfile.so \
item=user sense=deny file=/etc/ftpusers onerr=succeed
ftp auth requisite pam_shells.so
ftp auth required pam_unix.so
ftp account required pam_unix.so
#
# The PAM configuration file for the `imap' service
#
imap auth required pam_unix.so
imap account required pam_unix.so
#
# The PAM configuration file for the `login' service
#
login auth requisite pam_securetty.so
login auth required pam_unix.so
login auth optional pam_group.so
login account requisite pam_time.so
login account required pam_unix.so
login password required pam_unix.so shadow md5 use_authtok
login session required pam_unix.so
#
# The PAM configuration file for the `netatalk' service
#
netatalk auth required pam_unix.so
netatalk account required pam_unix.so
#
# The PAM configuration file for the `other' service
#
other auth required pam_deny.so
other auth required pam_warn.so
other account required pam_deny.so
other password required pam_deny.so
other password required pam_warn.so
other session required pam_deny.so
#
# The PAM configuration file for the `passwd' service
#
passwd password required pam_unix.so shadow md5 use_authtok
#
# The PAM configuration file for the `rexec' service
#
rexec auth requisite pam_securetty.so
rexec auth requisite pam_nologin.so
rexec auth sufficient pam_rhosts_auth.so
rexec auth required pam_unix.so
rexec account required pam_unix.so
rexec session required pam_unix.so
rexec session required pam_limits.so
#
# The PAM configuration file for the `rlogin' service
# this application passes control to `login' if it fails
#
rlogin auth requisite pam_securetty.so
rlogin auth requisite pam_nologin.so
rlogin auth required pam_rhosts_auth.so
rlogin account required pam_unix.so
rlogin password required pam_unix.so shadow md5 use_authtok
rlogin session required pam_unix.so
rlogin session required pam_limits.so
#
# The PAM configuration file for the `rsh' service
#
rsh auth requisite pam_securetty.so
rsh auth requisite pam_nologin.so
rsh auth sufficient pam_rhosts_auth.so
rsh auth required pam_unix.so
rsh account required pam_unix.so
rsh session required pam_unix.so
rsh session required pam_limits.so
#
# The PAM configuration file for the `samba' service
#
samba auth required pam_unix.so
samba account required pam_unix.so
#
# The PAM configuration file for the `su' service
#
su auth required pam_wheel.so
su auth sufficient pam_rootok.so
su auth required pam_unix.so
su account required pam_unix.so
su session required pam_unix.so
#
# The PAM configuration file for the `vlock' service
#
vlock auth required pam_unix.so
#
# The PAM configuration file for the `xdm' service
#
xdm auth required pam_unix.so
xdm account required pam_unix.so
#
# The PAM configuration file for the `xlock' service
#
xlock auth required pam_unix.so

8
conf/pam_conv1/README Normal file
View file

@ -0,0 +1,8 @@
This directory contains a utility to convert pam.conf files to a pam.d/
tree. The conversion program takes pam.conf from the standard input and
creates the pam.d/ directory in the current directory.
The program will fail if ./pam.d/ already exists.
Andrew Morgan, February 1997

25
conf/pam_conv1/meson.build Normal file
View file

@ -0,0 +1,25 @@
pam_conv_y = custom_target(
'pam_conv_y.[ch]',
input: 'pam_conv_y.y',
output: ['pam_conv_y.c', 'pam_conv_y.h'],
command: yacc_cmd,
)
pam_conv_l = custom_target(
'pam_conv_l.c',
input: 'pam_conv_l.l',
output: 'pam_conv_l.c',
depends: pam_conv_y,
command: [prog_flex, '-o', '@OUTPUT@', '@INPUT@'],
)
executable(
'pam_conv1',
sources: [pam_conv_l, pam_conv_y],
include_directories: [libpam_inc],
c_args: [
'-Wno-unused-function',
'-Wno-sign-compare',
],
link_args: exe_link_args,
)

45
conf/pam_conv1/pam_conv_l.l Normal file
View file

@ -0,0 +1,45 @@
%{
/*
* $Id$
*
* Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
*
* This file is covered by the Linux-PAM License (which should be
* distributed with this file.)
*/
#include <config.h>
#include <stdio.h>
#include "pam_conv_y.h"
extern unsigned long long current_line;
%}
%option noyywrap
%%
"#"[^\n]* ; /* skip comments (sorry) */
"\\\n" {
++current_line;
}
([^\n\t ]|[\\][^\n])+ {
return TOK;
}
[ \t]+ ; /* Ignore */
<<EOF>> {
return EOFILE;
}
[\n] {
++current_line;
return NL;
}
%%

217
conf/pam_conv1/pam_conv_y.y Normal file
View file

@ -0,0 +1,217 @@
%{
/*
* $Id$
*
* Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
*
* This file is covered by the Linux-PAM License (which should be
* distributed with this file.)
*/
#include <config.h>
#include <string.h>
#include <stdio.h>
#include <stdarg.h>
#include <stdlib.h>
#include <ctype.h>
#include <sys/stat.h>
#include <security/_pam_types.h>
extern int yylex(void);
unsigned long long current_line=0;
extern char *yytext;
/* XXX - later we'll change this to be the specific conf file(s) */
#define newpamf stderr
#define PAM_D "./pam.d"
#define PAM_D_MODE 0755
#define PAM_D_MAGIC_HEADER \
"#%%PAM-1.0\n" \
"#[For version 1.0 syntax, the above header is optional]\n"
#define PAM_D_FILE_FMT PAM_D "/%s"
const char *old_to_new_ctrl_flag(const char *old);
void yyerror(const char *format, ...);
%}
%union {
int def;
char *string;
}
%token NL EOFILE TOK
%type <string> tok path tokenls
%start complete
%%
complete
:
| complete NL
| complete line
| complete EOFILE {
return 0;
}
;
line
: tok tok tok path tokenls NL {
char *filename;
FILE *conf;
int i;
/* make sure we have lower case */
for (i=0; $1[i]; ++i) {
$1[i] = tolower((unsigned char)$1[i]);
}
/* $1 = service-name */
yyerror("Appending to " PAM_D "/%s", $1);
if (asprintf(&filename, PAM_D_FILE_FMT, $1) < 0) {
yyerror("unable to create filename - aborting");
exit(1);
}
conf = fopen(filename, "r");
if (conf == NULL) {
/* new file */
conf = fopen(filename, "w");
if (conf != NULL) {
fprintf(conf, PAM_D_MAGIC_HEADER);
fprintf(conf,
"#\n"
"# The PAM configuration file for the `%s' service\n"
"#\n", $1);
}
} else {
fclose(conf);
conf = fopen(filename, "a");
}
if (conf == NULL) {
yyerror("trouble opening %s - aborting", filename);
exit(1);
}
free(filename);
free($1);
/* $2 = module-type */
fprintf(conf, "%-10s", $2);
free($2);
/* $3 = required etc. */
{
const char *trans;
trans = old_to_new_ctrl_flag($3);
free($3);
fprintf(conf, " %-10s", trans);
}
/* $4 = module-path */
fprintf(conf, " %s", $4);
free($4);
/* $5 = arguments */
if ($5 != NULL) {
fprintf(conf, " \\\n\t\t%s", $5);
free($5);
}
/* end line */
fprintf(conf, "\n");
fclose(conf);
}
| error NL {
yyerror("malformed line");
}
;
tokenls
: {
$$=NULL;
}
| tokenls tok {
if ($1) {
if (asprintf(&$$, "%s %s", $1, $2) < 0) {
yyerror("failed to assemble tokenls");
exit(1);
}
free($1);
free($2);
} else {
$$ = $2;
}
}
;
path
: TOK {
/* XXX - this could be used to check if file present */
$$ = strdup(yytext);
if ($$ == NULL) {
yyerror("failed to duplicate path");
exit(1);
}
}
tok
: TOK {
$$ = strdup(yytext);
if ($$ == NULL) {
yyerror("failed to duplicate token");
exit(1);
}
}
%%
const char *old_to_new_ctrl_flag(const char *old)
{
static const char *const clist[] = {
"requisite",
"required",
"sufficient",
"optional",
NULL,
};
int i;
for (i=0; clist[i]; ++i) {
if (strcasecmp(clist[i], old) == 0) {
break;
}
}
return clist[i];
}
PAM_FORMAT((printf, 1, 2))
void yyerror(const char *format, ...)
{
va_list args;
fprintf(stderr, "line %llu: ", current_line);
va_start(args, format);
vfprintf(stderr, format, args);
va_end(args);
fprintf(stderr, "\n");
}
int main(void)
{
if (mkdir(PAM_D, PAM_D_MODE) != 0) {
yyerror(PAM_D " already exists.. aborting");
return 1;
}
yyparse();
return 0;
}

749
doc/adg/Linux-PAM_ADG.xml Normal file
View file

@ -0,0 +1,749 @@
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg">
<info>
<title>The Linux-PAM Application Developers' Guide</title>
<authorgroup>
<author><personname><firstname>Andrew G.</firstname><surname>Morgan</surname></personname><email>morgan@kernel.org</email></author>
<author><personname><firstname>Thorsten</firstname><surname>Kukuk</surname></personname><email>kukuk@thkukuk.de</email></author>
</authorgroup>
<releaseinfo>Version 1.1.2, 31. August 2010</releaseinfo>
<abstract>
<para>
This manual documents what an application developer needs to know
about the <emphasis remap="B">Linux-PAM</emphasis> library. It
describes how an application might use the
<emphasis remap="B">Linux-PAM</emphasis> library to authenticate
users. In addition it contains a description of the functions
to be found in <filename>libpam_misc</filename> library, that can
be used in general applications. Finally, it contains some comments
on PAM related security issues for the application developer.
</para>
</abstract>
</info>
<chapter xml:id="adg-introduction">
<title>Introduction</title>
<section xml:id="adg-introduction-description">
<title>Description</title>
<para>
<emphasis remap="B">Linux-PAM</emphasis>
(Pluggable Authentication Modules for Linux) is a library that enables
the local system administrator to choose how individual applications
authenticate users. For an overview of the
<emphasis remap="B">Linux-PAM</emphasis> library see the
<emphasis>Linux-PAM System Administrators' Guide</emphasis>.
</para>
<para>
It is the purpose of the <emphasis remap="B">Linux-PAM</emphasis>
project to liberate the development of privilege granting software
from the development of secure and appropriate authentication schemes.
This is accomplished by providing a documented library of functions
that an application may use for all forms of user authentication
management. This library dynamically loads locally configured
authentication modules that actually perform the authentication tasks.
</para>
<para>
From the perspective of an application developer the information
contained in the local configuration of the PAM library should not be
important. Indeed it is intended that an application treat the
functions documented here as a 'black box' that will deal with all
aspects of user authentication. 'All aspects' includes user
verification, account management, session initialization/termination
and also the resetting of passwords
(<emphasis>authentication tokens</emphasis>).
</para>
</section>
<section xml:id="adg-introduction-synopsis">
<title>Synopsis</title>
<para>
For general applications that wish to use the services provided by
<emphasis remap="B">Linux-PAM</emphasis> the following is a summary
of the relevant linking information:
<programlisting>
#include &lt;security/pam_appl.h&gt;
cc -o application .... -lpam
</programlisting>
</para>
<para>
In addition to <command>libpam</command>, there is a library of
miscellaneous functions that make the job of writing
<emphasis>PAM-aware</emphasis> applications easier (this library is not
covered in the DCE-RFC for PAM and is specific to the Linux-PAM
distribution):
<programlisting>
#include &lt;security/pam_appl.h&gt;
#include &lt;security/pam_misc.h&gt;
cc -o application .... -lpam -lpam_misc
</programlisting>
</para>
</section>
</chapter>
<chapter xml:id="adg-overview">
<title>Overview</title>
<para>
Most service-giving applications are restricted. In other words,
their service is not available to all and every prospective client.
Instead, the applying client must jump through a number of hoops to
convince the serving application that they are authorized to obtain
service.
</para>
<para>
The process of <emphasis>authenticating</emphasis> a client is what
PAM is designed to manage. In addition to authentication, PAM provides
account management, credential management, session management and
authentication-token (password changing) management services. It is
important to realize when writing a PAM based application that these
services are provided in a manner that is
<emphasis remap="B">transparent</emphasis> to the application. That is
to say, when the application is written, no assumptions can be made
about <emphasis>how</emphasis> the client will be authenticated.
</para>
<para>
The process of authentication is performed by the PAM library via a
call to <function>pam_authenticate()</function>. The return value
of this function will indicate whether a named client (the
<emphasis>user</emphasis>) has been authenticated. If the PAM library
needs to prompt the user for any information, such as their
<emphasis>name</emphasis> or a <emphasis>password</emphasis>
then it will do so. If the PAM library is configured to authenticate
the user using some silent protocol, it will do this too. (This
latter case might be via some hardware interface for example.)
</para>
<para>
It is important to note that the application must leave all decisions
about when to prompt the user at the discretion of the PAM library.
</para>
<para>
The PAM library, however, must work equally well for different styles
of application. Some applications, like the familiar
<command>login</command> and <command>passwd</command> are terminal
based applications, exchanges of information with the client in
these cases is as plain text messages. Graphically based applications,
however, have a more sophisticated interface. They generally interact
with the user via specially constructed dialogue boxes. Additionally,
network based services require that text messages exchanged with the
client are specially formatted for automated processing: one such
example is <command>ftpd</command> which prefixes each exchanged
message with a numeric identifier.
</para>
<para>
The presentation of simple requests to a client is thus something very
dependent on the protocol that the serving application will use. In
spite of the fact that PAM demands that it drives the whole
authentication process, it is not possible to leave such protocol
subtleties up to the PAM library. To overcome this potential problem,
the application provides the PAM library with a
<emphasis>conversation</emphasis> function. This function is called
from <emphasis>within</emphasis> the PAM library and enables the PAM
to directly interact with the client. The sorts of things that this
conversation function must be able to do are prompt the user with
text and/or obtain textual input from the user for processing by the
PAM library. The details of this function are provided in a later
section.
</para>
<para>
For example, the conversation function may be called by the PAM
library with a request to prompt the user for a password. Its job is
to reformat the prompt request into a form that the client will
understand. In the case of <command>ftpd</command>, this might involve
prefixing the string with the number <command>331</command> and sending
the request over the network to a connected client. The conversation
function will then obtain any reply and, after extracting the typed
password, will return this string of text to the PAM library. Similar
concerns need to be addressed in the case of an X-based graphical
server.
</para>
<para>
There are a number of issues that need to be addressed when one is
porting an existing application to become PAM compliant. A section
below has been devoted to this: Porting legacy applications.
</para>
<para>
Besides authentication, PAM provides other forms of management.
Session management is provided with calls to
<function>pam_open_session()</function> and
<function>pam_close_session()</function>. What these functions
actually do is up to the local administrator. But typically, they
could be used to log entry and exit from the system or for mounting
and unmounting the user's home directory. If an application provides
continuous service for a period of time, it should probably call
these functions, first open after the user is authenticated and then
close when the service is terminated.
</para>
<para>
Account management is another area that an application developer
should include with a call to <function>pam_acct_mgmt()</function>.
This call will perform checks on the good health of the user's account
(has it expired etc.). One of the things this function may check is
whether the user's authentication token has expired - in such a case the
application may choose to attempt to update it with a call to
<function>pam_chauthtok()</function>, although some applications
are not suited to this task (<command>ftp</command> for example)
and in this case the application should deny access to the user.
</para>
<para>
PAM is also capable of setting and deleting the user's credentials with
the call <function>pam_setcred()</function>. This function should
always be called after the user is authenticated and before service
is offered to the user. By convention, this should be the last call
to the PAM library before the PAM session is opened. What exactly a
credential is, is not well defined. However, some examples are given
in the glossary below.
</para>
</chapter>
<chapter xml:id="adg-interface">
<title>
The public interface to <emphasis remap="B">Linux-PAM</emphasis>
</title>
<para>
Firstly, the relevant include file for the
<emphasis remap="B">Linux-PAM</emphasis> library is
<function>&lt;security/pam_appl.h&gt;</function>.
It contains the definitions for a number of functions. After
listing these functions, we collect some guiding remarks for
programmers.
</para>
<section xml:id="adg-interface-by-app-expected">
<title>What can be expected by the application</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_start.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_end.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_set_item.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_get_item.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_strerror.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_fail_delay.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_authenticate.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_setcred.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_acct_mgmt.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_chauthtok.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_open_session.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_close_session.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_putenv.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_getenv.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_getenvlist.xml"/>
</section>
<section xml:id="adg-interface-of-app-expected">
<title>What is expected of an application</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_conv.xml"/>
</section>
<section xml:id="adg-interface-programming-notes">
<title>Programming notes</title>
<para>
Note, all of the authentication service function calls accept the
token <emphasis remap="B">PAM_SILENT</emphasis>, which instructs
the modules to not send messages to the application. This token
can be logically OR'd with any one of the permitted tokens specific
to the individual function calls.
<emphasis remap="B">PAM_SILENT</emphasis> does not override the
prompting of the user for passwords etc., it only stops informative
messages from being generated.
</para>
</section>
</chapter>
<chapter xml:id="adg-security">
<title>
Security issues of <emphasis remap="B">Linux-PAM</emphasis>
</title>
<para>
PAM, from the perspective of an application, is a convenient API for
authenticating users. PAM modules generally have no increased
privilege over that possessed by the application that is making use of
it. For this reason, the application must take ultimate responsibility
for protecting the environment in which PAM operates.
</para>
<para>
A poorly (or maliciously) written application can defeat any
<emphasis remap="B">Linux-PAM</emphasis> module's authentication
mechanisms by simply ignoring it's return values. It is the
applications task and responsibility to grant privileges and access
to services. The <emphasis remap="B">Linux-PAM</emphasis> library
simply assumes the responsibility of <emphasis>authenticating</emphasis>
the user; ascertaining that the user <emphasis>is</emphasis> who they
say they are. Care should be taken to anticipate all of the documented
behavior of the <emphasis remap="B">Linux-PAM</emphasis> library
functions. A failure to do this will most certainly lead to a future
security breach.
</para>
<section xml:id="adg-security-library-calls">
<title>Care about standard library calls</title>
<para>
In general, writers of authorization-granting applications should
assume that each module is likely to call any or
<emphasis>all</emphasis> 'libc' functions. For 'libc' functions
that return pointers to static/dynamically allocated structures
(ie. the library allocates the memory and the user is not expected
to '<function>free()</function>' it) any module call to this
function is likely to corrupt a pointer previously
obtained by the application. The application programmer should
either re-call such a 'libc' function after a call to the
<emphasis remap="B">Linux-PAM</emphasis> library, or copy the
structure contents to some safe area of memory before passing
control to the <emphasis remap="B">Linux-PAM</emphasis> library.
</para>
<para>
Two important function classes that fall into this category are
<citerefentry>
<refentrytitle>getpwnam</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and <citerefentry>
<refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</section>
<section xml:id="adg-security-service-name">
<title>Choice of a service name</title>
<para>
When picking the <emphasis>service-name</emphasis> that
corresponds to the first entry in the
<emphasis remap="B">Linux-PAM</emphasis> configuration file,
the application programmer should <emphasis>avoid</emphasis>
the temptation of choosing something related to
<varname>argv[0]</varname>. It is a trivial matter for any user
to invoke any application on a system under a different name and
this should not be permitted to cause a security breach.
</para>
<para>
In general, this is always the right advice if the program is
setuid, or otherwise more privileged than the user that invokes
it. In some cases, avoiding this advice is convenient, but as an
author of such an application, you should consider well the ways
in which your program will be installed and used. (Its often the
case that programs are not intended to be setuid, but end up
being installed that way for convenience. If your program falls
into this category, don't fall into the trap of making this mistake.)
</para>
<para>
To invoke some <emphasis>target</emphasis> application by
another name, the user may symbolically link the target application
with the desired name. To be precise all the user need do is,
<command>ln -s /target/application ./preferred_name</command>
and then run <command>./preferred_name</command>.
</para>
<para>
By studying the <emphasis remap="B">Linux-PAM</emphasis>
configuration file(s), an attacker can choose the
<command>preferred_name</command> to be that of a service enjoying
minimal protection; for example a game which uses
<emphasis remap="B">Linux-PAM</emphasis> to restrict access to
certain hours of the day. If the service-name were to be linked
to the filename under which the service was invoked, it
is clear that the user is effectively in the position of
dictating which authentication scheme the service uses. Needless
to say, this is not a secure situation.
</para>
<para>
The conclusion is that the application developer should carefully
define the service-name of an application. The safest thing is to
make it a single hard-wired name.
</para>
</section>
<section xml:id="adg-security-conv-function">
<title>The conversation function</title>
<para>
Care should be taken to ensure that the <function>conv()</function>
function is robust. Such a function is provided in the library
<command>libpam_misc</command> (see
<link linkend="adg-libpam-functions">below</link>).
</para>
</section>
<section xml:id="adg-security-user-identity">
<title>The identity of the user</title>
<para>
The <emphasis remap="B">Linux-PAM</emphasis> modules will need
to determine the identity of the user who requests a service,
and the identity of the user who grants the service. These two
users will seldom be the same. Indeed there is generally a third
user identity to be considered, the new (assumed) identity of
the user once the service is granted.
</para>
<para>
The need for keeping tabs on these identities is clearly an
issue of security. One convention that is actively used by
some modules is that the identity of the user requesting a
service should be the current <emphasis>UID</emphasis>
(user ID) of the running process; the identity of the
privilege granting user is the <emphasis>EUID</emphasis>
(effective user ID) of the running process; the identity of
the user, under whose name the service will be executed, is
given by the contents of the <emphasis>PAM_USER</emphasis>
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>. Note, modules can change the values of
<emphasis>PAM_USER</emphasis> and <emphasis>PAM_RUSER</emphasis>
during any of the <function>pam_*()</function> library calls.
For this reason, the application should take care to use the
<function>pam_get_item()</function> every time it wishes to
establish who the authenticated user is (or will currently be).
</para>
<para>
For network-serving databases and other applications that provide
their own security model (independent of the OS kernel) the above
scheme is insufficient to identify the requesting user.
</para>
<para>
A more portable solution to storing the identity of the requesting
user is to use the <emphasis>PAM_RUSER</emphasis> <citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>. The application should supply this value before
attempting to authenticate the user with
<function>pam_authenticate()</function>. How well this name can be
trusted will ultimately be at the discretion of the local
administrator (who configures PAM for your application) and a
selected module may attempt to override the value where it can
obtain more reliable data. If an application is unable to determine
the identity of the requesting entity/user, it should not call
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> to set <emphasis>PAM_RUSER</emphasis>.
</para>
<para>
In addition to the <emphasis>PAM_RUSER</emphasis> item, the
application should supply the <emphasis>PAM_RHOST</emphasis>
(<emphasis>requesting host</emphasis>) item. As a general rule,
the following convention for its value can be assumed:
NULL = unknown; localhost = invoked directly from the local system;
<emphasis>other.place.xyz</emphasis> = some component of the
user's connection originates from this remote/requesting host. At
present, PAM has no established convention for indicating whether
the application supports a trusted path to communication from
this host.
</para>
</section>
<section xml:id="adg-security-resources">
<title>Sufficient resources</title>
<para>
Care should be taken to ensure that the proper execution of an
application is not compromised by a lack of system resources. If an
application is unable to open sufficient files to perform its service,
it should fail gracefully, or request additional resources.
Specifically, the quantities manipulated by the <citerefentry>
<refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum>
</citerefentry> family of commands should be taken into consideration.
</para>
<para>
This is also true of conversation prompts. The application should not
accept prompts of arbitrary length with out checking for resource
allocation failure and dealing with such extreme conditions gracefully
and in a manner that preserves the PAM API. Such tolerance may be
especially important when attempting to track a malicious adversary.
</para>
</section>
</chapter>
<chapter xml:id="adg-libpam_misc">
<title>A library of miscellaneous helper functions</title>
<para>
To aid the work of the application developer a library of
miscellaneous functions is provided. It is called
<command>libpam_misc</command>, and contains a text based
conversation function, and routines for enhancing the standard
PAM-environment variable support.
</para>
<para>
The functions, structures and macros, made available by this
library can be defined by including
<function>&lt;security/pam_misc.h&gt;</function>. It should be
noted that this library is specific to
<emphasis remap="B">Linux-PAM</emphasis> and is not referred to in
the defining DCE-RFC (see <link linkend="adg-see-also">See also</link>)
below.
</para>
<section xml:id="adg-libpam-functions">
<title>Functions supplied</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_misc_conv.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_misc_paste_env.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_misc_drop_env.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_misc_setenv.xml"/>
</section>
</chapter>
<chapter xml:id="adg-porting">
<title>Porting legacy applications</title>
<para>
The point of PAM is that the application is not supposed to
have any idea how the attached authentication modules will choose
to authenticate the user. So all they can do is provide a conversation
function that will talk directly to the user(client) on the modules'
behalf.
</para>
<para>
Consider the case that you plug a retinal scanner into the login
program. In this situation the user would be prompted: "please look
into the scanner". No username or password would be needed - all this
information could be deduced from the scan and a database lookup. The
point is that the retinal scanner is an ideal task for a "module".
</para>
<para>
While it is true that a pop-daemon program is designed with the POP
protocol in mind and no-one ever considered attaching a retinal
scanner to it, it is also the case that the "clean" PAM'ification of
such a daemon would allow for the possibility of a scanner module
being be attached to it. The point being that the "standard"
pop-authentication protocol(s) [which will be needed to satisfy
inflexible/legacy clients] would be supported by inserting an
appropriate pam_qpopper module(s). However, having rewritten
<command>popd</command> once in this way any new protocols can be
implemented in-situ.
</para>
<para>
One simple test of a ported application would be to insert the
<command>pam_permit</command> module and see if the application
demands you type a password... In such a case, <command>xlock</command>
would fail to lock the terminal - or would at best be a screen-saver,
ftp would give password free access to all etc.. Neither of
these is a very secure thing to do, but they do illustrate how
much flexibility PAM puts in the hands of the local admin.
</para>
<para>
The key issue, in doing things correctly, is identifying what is part
of the authentication procedure (how many passwords etc..) the
exchange protocol (prefixes to prompts etc., numbers like 331 in the
case of ftpd) and what is part of the service that the application
delivers. PAM really needs to have total control in the
authentication "procedure", the conversation function should only
deal with reformatting user prompts and extracting responses from raw
input.
</para>
</chapter>
<chapter xml:id="adg-glossary">
<title>Glossary of PAM related terms</title>
<para>
The following are a list of terms used within this document.
</para>
<variablelist>
<varlistentry>
<term>Authentication token</term>
<listitem>
<para>
Generally, this is a password. However, users can authenticate
themselves in a variety of ways. Updating the user's
authentication token thus corresponds to
<emphasis>refreshing</emphasis> the object they use to
authenticate themselves with the system. The word password is
avoided to keep open the possibility that the authentication
involves a retinal scan or other non-textual mode of
challenge/response.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Credentials</term>
<listitem>
<para>
Having successfully authenticated the user, PAM is able to
establish certain characteristics/attributes of the user.
These are termed <emphasis>credentials</emphasis>. Examples
of which are group memberships to perform privileged tasks
with, and <emphasis>tickets</emphasis> in the form of
environment variables etc. . Some user-credentials, such as
the user's UID and GID (plus default group memberships) are
not deemed to be PAM-credentials. It is the responsibility
of the application to grant these directly.
</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter xml:id="adg-example">
<title>An example application</title>
<para>
To get a flavor of the way a <emphasis remap="B">Linux-PAM</emphasis>
application is written we include the following example. It prompts
the user for their password and indicates whether their account
is valid on the standard output, its return code also indicates
the success (<returnvalue>0</returnvalue> for success;
<returnvalue>1</returnvalue> for failure).
</para>
<programlisting>
/*
This program was contributed by Shane Watts
[modifications by AGM and kukuk]
You need to add the following (or equivalent) to the
/etc/pam.d/check_user file:
# check authorization
auth required pam_unix.so
account required pam_unix.so
*/
#include &lt;security/pam_appl.h&gt;
#include &lt;security/pam_misc.h&gt;
#include &lt;stdio.h&gt;
static struct pam_conv conv = {
misc_conv,
NULL
};
int main(int argc, char *argv[])
{
pam_handle_t *pamh=NULL;
int retval;
const char *user="nobody";
if(argc == 2) {
user = argv[1];
}
if(argc &gt; 2) {
fprintf(stderr, "Usage: check_user [username]\n");
exit(1);
}
retval = pam_start("check_user", user, &amp;conv, &amp;pamh);
if (retval == PAM_SUCCESS)
retval = pam_authenticate(pamh, 0); /* is user really user? */
if (retval == PAM_SUCCESS)
retval = pam_acct_mgmt(pamh, 0); /* permitted access? */
/* This is where we have been authorized or not. */
if (retval == PAM_SUCCESS) {
fprintf(stdout, "Authenticated\n");
} else {
fprintf(stdout, "Not Authenticated\n");
}
if (pam_end(pamh,retval) != PAM_SUCCESS) { /* close Linux-PAM */
pamh = NULL;
fprintf(stderr, "check_user: failed to release authenticator\n");
exit(1);
}
return ( retval == PAM_SUCCESS ? 0:1 ); /* indicate success */
}
</programlisting>
</chapter>
<chapter xml:id="adg-files">
<title>Files</title>
<variablelist>
<varlistentry>
<term>/usr/include/security/pam_appl.h</term>
<listitem>
<para>
Header file with interfaces for
<emphasis remap="B">Linux-PAM</emphasis> applications.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>/usr/include/security/pam_misc.h</term>
<listitem>
<para>
Header file for useful library functions for making
applications easier to write.
</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter xml:id="adg-see-also">
<title>See also</title>
<itemizedlist>
<listitem>
<para>
The Linux-PAM System Administrators' Guide.
</para>
</listitem>
<listitem>
<para>
The Linux-PAM Module Writers' Guide.
</para>
</listitem>
<listitem>
<para>
The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH
PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation
Request For Comments 86.0, October 1995.
</para>
</listitem>
</itemizedlist>
</chapter>
<chapter xml:id="adg-author">
<title>Author/acknowledgments</title>
<para>
This document was written by Andrew G. Morgan (morgan@kernel.org)
with many contributions from
Chris Adams, Peter Allgeyer, Tim Baverstock, Tim Berger, Craig S. Bell,
Derrick J. Brashear, Ben Buxton, Seth Chaiklin, Oliver Crow, Chris Dent,
Marc Ewing, Cristian Gafton, Emmanuel Galanos, Brad M. Garcia,
Eric Hester, Roger Hu, Eric Jacksch, Michael K. Johnson, David Kinchlea,
Olaf Kirch, Marcin Korzonek, Thorsten Kukuk, Stephen Langasek,
Nicolai Langfeldt, Elliot Lee, Luke Kenneth Casson Leighton,
Al Longyear, Ingo Luetkebohle, Marek Michalkiewicz, Robert Milkowski,
Aleph One, Martin Pool, Sean Reifschneider, Jan Rekorajski, Erik Troan,
Theodore Ts'o, Jeff Uphoff, Myles Uyema, Savochkin Andrey Vladimirovich,
Ronald Wahl, David Wood, John Wilmes, Joseph S. D. Yao
and Alex O. Yuriev.
</para>
<para>
Thanks are also due to Sun Microsystems, especially to Vipin Samar and
Charlie Lai for their advice. At an early stage in the development of
<emphasis remap="B">Linux-PAM</emphasis>, Sun graciously made the
documentation for their implementation of PAM available. This act
greatly accelerated the development of
<emphasis remap="B">Linux-PAM</emphasis>.
</para>
</chapter>
<chapter xml:id="adg-copyright">
<title>Copyright information for this document</title>
<programlisting>
Copyright (c) 2006 Thorsten Kukuk &lt;kukuk@thkukuk.de&gt;
Copyright (c) 1996-2002 Andrew G. Morgan &lt;morgan@kernel.org&gt;
</programlisting>
<para>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
</para>
<programlisting>
1. Redistributions of source code must retain the above copyright
notice, and the entire permission notice in its entirety,
including the disclaimer of warranties.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote
products derived from this software without specific prior
written permission.
</programlisting>
<para>
Alternatively, this product may be distributed under the terms of
the GNU General Public License (GPL), in which case the provisions
of the GNU GPL are required instead of the above restrictions.
(This clause is necessary due to a potential bad interaction between
the GNU GPL and the restrictions contained in a BSD-style copyright.)
</para>
<programlisting>
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
</programlisting>
</chapter>
</book>

1
doc/adg/html/meson.build Symbolic link
View file

@ -0,0 +1 @@
../../guide-html-meson.build

1
doc/adg/meson.build Symbolic link
View file

@ -0,0 +1 @@
../guide-meson.build

12
doc/adg/pam_acct_mgmt.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_acct_mgmt">
<title>Account validation management</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_acct_mgmt.3.xml" xpointer='xpointer(id("pam_acct_mgmt-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_acct_mgmt-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_acct_mgmt.3.xml" xpointer='xpointer(id("pam_acct_mgmt-description")/*)'/>
</section>
<section xml:id="adg-pam_acct_mgmt-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_acct_mgmt.3.xml" xpointer='xpointer(id("pam_acct_mgmt-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_authenticate.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_authenticate">
<title>Authenticating the user</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_authenticate.3.xml" xpointer='xpointer(id("pam_authenticate-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_authenticate-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_authenticate.3.xml" xpointer='xpointer(id("pam_authenticate-description")/*)'/>
</section>
<section xml:id="adg-pam_authenticate-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_authenticate.3.xml" xpointer='xpointer(id("pam_authenticate-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_chauthtok.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_chauthtok">
<title>Updating authentication tokens</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_chauthtok.3.xml" xpointer='xpointer(id("pam_chauthtok-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_chauthtok-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_chauthtok.3.xml" xpointer='xpointer(id("pam_chauthtok-description")/*)'/>
</section>
<section xml:id="adg-pam_chauthtok-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_chauthtok.3.xml" xpointer='xpointer(id("pam_chauthtok-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_close_session.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_close_session">
<title>terminating PAM session management</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_close_session.3.xml" xpointer='xpointer(id("pam_close_session-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_close_session-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_close_session.3.xml" xpointer='xpointer(id("pam_close_session-description")/*)'/>
</section>
<section xml:id="adg-pam_close_session-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_close_session.3.xml" xpointer='xpointer(id("pam_close_session-return_values")/*)'/>
</section>
</section>

29
doc/adg/pam_conv.xml Normal file
View file

@ -0,0 +1,29 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_conv">
<title>The conversation function</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_conv.3.xml" xpointer='xpointer(id("pam_conv-synopsis")/*)'/>
</funcsynopsis>
<programlisting>
struct pam_message {
int msg_style;
const char *msg;
};
struct pam_response {
char *resp;
int resp_retcode;
};
struct pam_conv {
int (*conv)(int num_msg, const struct pam_message **msg,
struct pam_response **resp, void *appdata_ptr);
void *appdata_ptr;
};
</programlisting>
<section xml:id="adg-pam_conv-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_conv.3.xml" xpointer='xpointer(id("pam_conv-description")/*)'/>
</section>
<section xml:id="adg-pam_conv-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_conv.3.xml" xpointer='xpointer(id("pam_conv-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_end.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_end">
<title>Termination of PAM transaction</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_end.3.xml" xpointer='xpointer(id("pam_end-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_end-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_end.3.xml" xpointer='xpointer(id("pam_end-description")/*)'/>
</section>
<section xml:id="adg-pam_end-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_end.3.xml" xpointer='xpointer(id("pam_end-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_fail_delay.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_fail_delay">
<title>Request a delay on failure</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_fail_delay.3.xml" xpointer='xpointer(id("pam_fail_delay-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_fail_delay-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_fail_delay.3.xml" xpointer='xpointer(id("pam_fail_delay-description")/*)'/>
</section>
<section xml:id="adg-pam_fail_delay-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_fail_delay.3.xml" xpointer='xpointer(id("pam_fail_delay-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_get_item.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_get_item">
<title>Getting PAM items</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_item.3.xml" xpointer='xpointer(id("pam_get_item-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_get_item-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_item.3.xml" xpointer='xpointer(id("pam_get_item-description")/*)'/>
</section>
<section xml:id="adg-pam_get_item-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_item.3.xml" xpointer='xpointer(id("pam_get_item-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_getenv.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_getenv">
<title>Get a PAM environment variable</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenv.3.xml" xpointer='xpointer(id("pam_getenv-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_getenv-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenv.3.xml" xpointer='xpointer(id("pam_getenv-description")/*)'/>
</section>
<section xml:id="adg-pam_getenv-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenv.3.xml" xpointer='xpointer(id("pam_getenv-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_getenvlist.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_getenvlist">
<title>Getting the PAM environment</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenvlist.3.xml" xpointer='xpointer(id("pam_getenvlist-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_getenvlist-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenvlist.3.xml" xpointer='xpointer(id("pam_getenvlist-description")/*)'/>
</section>
<section xml:id="adg-pam_getenvlist-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenvlist.3.xml" xpointer='xpointer(id("pam_getenvlist-return_values")/*)'/>
</section>
</section>

9
doc/adg/pam_misc_conv.xml Normal file
View file

@ -0,0 +1,9 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-misc_conv">
<title>Text based conversation function</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/misc_conv.3.xml" xpointer='xpointer(id("misc_conv-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-misc_conv-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/misc_conv.3.xml" xpointer='xpointer(id("misc_conv-description")/*)'/>
</section>
</section>

9
doc/adg/pam_misc_drop_env.xml Normal file
View file

@ -0,0 +1,9 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_misc_drop_env">
<title>Liberating a locally saved environment</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_misc_drop_env.3.xml" xpointer='xpointer(id("pam_misc_drop_env-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_misc_drop_env-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_misc_drop_env.3.xml" xpointer='xpointer(id("pam_misc_drop_env-description")/*)'/>
</section>
</section>

9
doc/adg/pam_misc_paste_env.xml Normal file
View file

@ -0,0 +1,9 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_misc_paste_env">
<title>Transcribing an environment to that of PAM</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_misc_paste_env.3.xml" xpointer='xpointer(id("pam_misc_paste_env-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_misc_paste_env-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_misc_paste_env.3.xml" xpointer='xpointer(id("pam_misc_paste_env-description")/*)'/>
</section>
</section>

9
doc/adg/pam_misc_setenv.xml Normal file
View file

@ -0,0 +1,9 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_misc_setenv">
<title>BSD like PAM environment variable setting</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_misc_setenv.3.xml" xpointer='xpointer(id("pam_misc_setenv-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_misc_setenv-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_misc_setenv.3.xml" xpointer='xpointer(id("pam_misc_setenv-description")/*)'/>
</section>
</section>

12
doc/adg/pam_open_session.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_open_session">
<title>Start PAM session management</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_open_session.3.xml" xpointer='xpointer(id("pam_open_session-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_open_session-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_open_session.3.xml" xpointer='xpointer(id("pam_open_session-description")/*)'/>
</section>
<section xml:id="adg-pam_open_session-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_open_session.3.xml" xpointer='xpointer(id("pam_open_session-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_putenv.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_putenv">
<title>Set or change PAM environment variable</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_putenv.3.xml" xpointer='xpointer(id("pam_putenv-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_putenv-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_putenv.3.xml" xpointer='xpointer(id("pam_putenv-description")/*)'/>
</section>
<section xml:id="adg-pam_putenv-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_putenv.3.xml" xpointer='xpointer(id("pam_putenv-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_set_item.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_set_item">
<title>Setting PAM items</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_set_item.3.xml" xpointer='xpointer(id("pam_set_item-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_set_item-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_set_item.3.xml" xpointer='xpointer(id("pam_set_item-description")/*)'/>
</section>
<section xml:id="adg-pam_set_item-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_set_item.3.xml" xpointer='xpointer(id("pam_set_item-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_setcred.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_setcred">
<title>Setting user credentials</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_setcred.3.xml" xpointer='xpointer(id("pam_setcred-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_setcred-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_setcred.3.xml" xpointer='xpointer(id("pam_setcred-description")/*)'/>
</section>
<section xml:id="adg-pam_setcred-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_setcred.3.xml" xpointer='xpointer(id("pam_setcred-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_start.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_start">
<title>Initialization of PAM transaction</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_start.3.xml" xpointer='xpointer(id("pam_start-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_start-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_start.3.xml" xpointer='xpointer(id("pam_start-description")/*)'/>
</section>
<section xml:id="adg-pam_start-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_start.3.xml" xpointer='xpointer(id("pam_start-return_values")/*)'/>
</section>
</section>

12
doc/adg/pam_strerror.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_strerror">
<title>Strings describing PAM error codes</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_strerror.3.xml" xpointer='xpointer(id("pam_strerror-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_strerror-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_strerror.3.xml" xpointer='xpointer(id("pam_strerror-description")/*)'/>
</section>
<section xml:id="adg-pam_strerror-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_strerror.3.xml" xpointer='xpointer(id("pam_strerror-return_values")/*)'/>
</section>
</section>

9
doc/custom-man.xsl.in Normal file
View file

@ -0,0 +1,9 @@
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:ss="http://docbook.sf.net/xmlns/string.subst/1.0" version="1.0">
<xsl:import href="MAN_STYLESHEET"/>
<xsl:param name="vendordir"/>
<xsl:param name="man.string.subst.map.local.pre">
<ss:substitution oldstring="%vendordir%" newstring="{$vendordir}" />
</xsl:param>
</xsl:stylesheet>

32
doc/guide-html-meson.build Normal file
View file

@ -0,0 +1,32 @@
# -*- mode: meson -*-
html = custom_target(
input: xml,
output: name + '.html',
command: [
prog_xsltproc,
'--nonet',
'--xinclude',
'--stringparam', 'base.dir', meson.current_build_dir(),
'--stringparam', 'root.filename', name,
'--stringparam', 'use.id.as.filename', '1',
'--stringparam', 'chunk.first.sections', '1',
'--stringparam', 'section.autolabel', '1',
'--stringparam', 'section.label.includes.component.label', '1',
'--stringparam', 'toc.max.depth', toc_max_depth,
'--stringparam', 'chunker.output.encoding', 'UTF-8',
html_stylesheet,
'@INPUT@',
],
install: true,
install_dir: htmldir,
install_tag: 'doc',
)
meson.add_install_script(
install_html,
meson.current_build_dir(),
htmldir,
html,
install_tag: 'doc',
)

90
doc/guide-meson.build Normal file
View file

@ -0,0 +1,90 @@
# -*- mode: meson -*-
guide = fs.name(meson.current_source_dir()).to_upper()
name = 'Linux-PAM_' + guide
xml = files(name + '.xml')
if guide == 'SAG'
toc_max_depth = '2'
else
toc_max_depth = '3'
endif
run_command(
[prog_xmllint,
'--noent',
'--nonet',
'--noout',
'--xinclude',
'--relaxng', docbook_rng,
xml],
check: true,
)
html = custom_target(
input: xml,
output: name + '.html',
command: [
prog_xsltproc,
'-o', '@OUTPUT@',
'--nonet',
'--xinclude',
'--stringparam', 'generate.toc', 'book toc',
'--stringparam', 'section.autolabel', '1',
'--stringparam', 'section.label.includes.component.label', '1',
'--stringparam', 'toc.max.depth', toc_max_depth,
txt_stylesheet,
'@INPUT@',
],
)
custom_target(
input: html,
output: name + '.txt',
command: [
redir_exe,
'@INPUT@',
'@OUTPUT@',
browser,
],
install: true,
install_dir: docdir,
install_tag: 'doc',
)
fop = custom_target(
input: xml,
output: name + '.fop',
command: [
prog_xsltproc,
'-o', '@OUTPUT@',
'--nonet',
'--xinclude',
'--stringparam', 'generate.toc', 'book toc',
'--stringparam', 'section.autolabel', '1',
'--stringparam', 'section.label.includes.component.label', '1',
'--stringparam', 'toc.max.depth', toc_max_depth,
pdf_stylesheet,
'@INPUT@',
],
)
custom_target(
input: fop,
output: name + '.pdf',
command: [
prog_fop,
'@INPUT@',
'@OUTPUT@',
],
install: true,
install_dir: pdfdir,
install_tag: 'doc',
)
subdir('html')

21
doc/index.html Normal file
View file

@ -0,0 +1,21 @@
<html>
<head>
<title>The Linux-PAM Administration and Developer Guides</title>
</head>
<body>
<center>
<h1>The Linux-PAM Guides</h1>
</center>
<hr>
<p>
Here is the documentation for Linux-PAM. As you will see it is
currently not complete.
<p>
<ul>
<li> <a href="Linux-PAM_SAG.html">The System Administrators' Guide</a>
<li> <a href="Linux-PAM_MWG.html">The Module Writers' Guide</a>
<li> <a href="Linux-PAM_ADG.html">The Application Developers' Guide</a>
</ul>
<hr>
</body>
</html>

7
doc/install-html.sh Executable file
View file

@ -0,0 +1,7 @@
#!/bin/sh -eu
cd "$1"; shift
MESON_INSTALL_DESTDIR=${MESON_INSTALL_DESTDIR_PREFIX%$MESON_INSTALL_PREFIX}
dest="$MESON_INSTALL_DESTDIR$1"; shift
install -p -m644 -t "$dest" -- *.html

67
doc/man/meson.build Normal file
View file

@ -0,0 +1,67 @@
foreach man: [['misc_conv.3', []],
['pam.3', []],
['pam_acct_mgmt.3', []],
['pam_authenticate.3', []],
['pam_chauthtok.3', []],
['pam_close_session.3', []],
['pam_conv.3', []],
['pam_end.3', []],
['pam_error.3', ['pam_verror.3']],
['pam_fail_delay.3', []],
['pam_get_authtok.3', ['pam_get_authtok_noverify.3', 'pam_get_authtok_verify.3']],
['pam_get_data.3', []],
['pam_get_item.3', []],
['pam_get_user.3', []],
['pam_getenv.3', []],
['pam_getenvlist.3', []],
['pam_info.3', ['pam_vinfo.3']],
['pam_misc_drop_env.3', []],
['pam_misc_paste_env.3', []],
['pam_misc_setenv.3', []],
['pam_open_session.3', []],
['pam_prompt.3', ['pam_vprompt.3']],
['pam_putenv.3', []],
['pam_set_data.3', []],
['pam_set_item.3', []],
['pam_setcred.3', []],
['pam_sm_acct_mgmt.3', []],
['pam_sm_authenticate.3', []],
['pam_sm_chauthtok.3', []],
['pam_sm_close_session.3', []],
['pam_sm_open_session.3', []],
['pam_sm_setcred.3', []],
['pam_start.3', []],
['pam_strerror.3', []],
['pam_syslog.3', ['pam_vsyslog.3']],
['pam_xauth_data.3', []],
['pam.conf.5', ['pam.d.5']],
['pam.8', ['PAM.8']],
]
xml = man[0] + '.xml'
run_command([prog_xmllint,
'--nonet',
'--noout',
'--xinclude',
'--relaxng', docbook_rng,
xml],
check: true)
custom_target(man[0],
input: xml,
output: man,
depends: custom_man_xsl,
command: [prog_xsltproc,
'-o', '@OUTPUT0@',
'--nonet',
'--xinclude',
'--path', meson.current_source_dir(),
stringparam_vendordir,
stringparam_profileconditions,
custom_man_xsl,
'@INPUT@'],
install: true,
install_dir: mandir / 'man' + man[0].substring(-1),
install_tag: 'man',
)
endforeach

185
doc/man/misc_conv.3.xml Normal file
View file

@ -0,0 +1,185 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="misc_conv">
<refmeta>
<refentrytitle>misc_conv</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="misc_conv-name">
<refname>misc_conv</refname>
<refpurpose>text based conversation function</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="misc_conv-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_misc.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>misc_conv</function></funcdef>
<paramdef>int <parameter>num_msg</parameter></paramdef>
<paramdef>const struct pam_message **<parameter>msgm</parameter></paramdef>
<paramdef>struct pam_response **<parameter>response</parameter></paramdef>
<paramdef>void *<parameter>appdata_ptr</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="misc_conv-description">
<title>DESCRIPTION</title>
<para>
The <function>misc_conv</function> function is part of
<command>libpam_misc</command> and not of the standard
<command>libpam</command> library. This function will prompt
the user with the appropriate comments and obtain the appropriate
inputs as directed by authentication modules.
</para>
<para>
In addition to simply slotting into the appropriate <citerefentry>
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, this function provides some time-out facilities.
The function exports five variables that can be used by an
application programmer to limit the amount of time this conversation
function will spend waiting for the user to type something. The
five variables are as follows:
</para>
<variablelist>
<varlistentry>
<term>time_t pam_misc_conv_warn_time;</term>
<listitem>
<para>
This variable contains the <emphasis>time</emphasis> (as
returned by <citerefentry>
<refentrytitle>time</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>) that the user should be first warned that
the clock is ticking. By default it has the value
<returnvalue>0</returnvalue>, which indicates that no such
warning will be given. The application may set its value to
sometime in the future, but this should be done prior to
passing control to the <emphasis>Linux-PAM</emphasis> library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>const char *pam_misc_conv_warn_line;</term>
<listitem>
<para>
Used in conjunction with
<varname>pam_misc_conv_warn_time</varname>, this variable is
a pointer to the string that will be displayed when it becomes
time to warn the user that the timeout is approaching. Its
default value is a translated version of
<quote>...Time is running out...</quote>, but this can be
changed by the application prior to passing control to
<emphasis>Linux-PAM</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>time_t pam_misc_conv_die_time;</term>
<listitem>
<para>
This variable contains the <emphasis>time</emphasis> (as
returned by <citerefentry>
<refentrytitle>time</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>) that the will time out. By default it has
the value <returnvalue>0</returnvalue>, which indicates that
the conversation function will not timeout. The application
may set its value to sometime in the future, but this should
be done prior to passing control to the
<emphasis>Linux-PAM</emphasis> library.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>const char *pam_misc_conv_die_line;</term>
<listitem>
<para>
Used in conjunction with
<varname>pam_misc_conv_die_time</varname>, this variable is
a pointer to the string that will be displayed when the
conversation times out. Its default value is a translated
version of
<quote>...Sorry, your time is up!</quote>, but this can be
changed by the application prior to passing control to
<emphasis>Linux-PAM</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>int pam_misc_conv_died;</term>
<listitem>
<para>
Following a return from the <emphasis>Linux-PAM</emphasis>
library, the value of this variable indicates whether the
conversation has timed out. A value of
<returnvalue>1</returnvalue> indicates the time-out occurred.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The following two function pointers are available for supporting
binary prompts in the conversation function. They are optimized
for the current incarnation of the <command>libpamc</command>
library and are subject to change.
</para>
<variablelist>
<varlistentry>
<term>
int (*pam_binary_handler_fn)(void *appdata, pamc_bp_t *prompt_p);
</term>
<listitem>
<para>
This function pointer is initialized to
<returnvalue>NULL</returnvalue> but can be filled with a
function that provides machine-machine (hidden) message
exchange. It is intended for use with hidden authentication
protocols such as RSA or Diffie-Hellman key exchanges.
(This is still under development.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
int (*pam_binary_handler_free)(void *appdata, pamc_bp_t *delete_me);
</term>
<listitem>
<para>
This function pointer is initialized to
<function>PAM_BP_RENEW(delete_me, 0, 0)</function>, but can be
redefined as desired by the application.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="misc_conv-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="misc_conv-standards">
<title>STANDARDS</title>
<para>
The <function>misc_conv</function> function is part of the
<command>libpam_misc</command> Library and not defined in any
standard.
</para>
</refsect1>
</refentry>

437
doc/man/pam.3.xml Normal file
View file

@ -0,0 +1,437 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam3">
<refmeta>
<refentrytitle>pam</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam3-name">
<refname>pam</refname>
<refpurpose>Pluggable Authentication Modules Library</refpurpose>
</refnamediv>
<refsynopsisdiv xml:id="pam3-synopsis">
<funcsynopsis>
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam3-description">
<title>DESCRIPTION</title>
<para>
<emphasis remap="B">PAM</emphasis> is a system of libraries
that handle the authentication tasks of applications (services)
on the system. The library provides a stable general interface
(Application Programming Interface - API) that privilege granting
programs (such as
<citerefentry>
<refentrytitle>login</refentrytitle><manvolnum>1</manvolnum>
</citerefentry> and <citerefentry>
<refentrytitle>su</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>)
defer to to perform standard authentication tasks.
</para>
<refsect2 xml:id="pam3-initialization_and_cleanup">
<title>Initialization and Cleanup</title>
<para>
The
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function creates the PAM context and initiates the
PAM transaction. It is the first of the PAM functions that needs to
be called by an application. The transaction state is contained
entirely within the structure identified by this handle, so it is
possible to have multiple transactions in parallel. But it is not
possible to use the same handle for different transactions, a new
one is needed for every new context.
</para>
<para>
The
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function terminates the PAM transaction and is the last
function an application should call in the PAM context. Upon return
the handle pamh is no longer valid and all memory associated with it
will be invalid. It can be called at any time to terminate a PAM
transaction.
</para>
</refsect2>
<refsect2 xml:id="pam3-authentication">
<title>Authentication</title>
<para>
The
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
function is used to
authenticate the user. The user is required to provide an
authentication token depending upon the authentication service,
usually this is a password, but could also be a finger print.
</para>
<para>
The
<citerefentry>
<refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
function manages the user's credentials.
</para>
</refsect2>
<refsect2 xml:id="pam3-account_management">
<title>Account Management</title>
<para>
The
<citerefentry>
<refentrytitle>pam_acct_mgmt</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function is used to determine if the user's account is
valid. It checks for authentication token and account expiration and
verifies access restrictions. It is typically called after the user
has been authenticated.
</para>
</refsect2>
<refsect2 xml:id="pam3-password_management">
<title>Password Management</title>
<para>
The
<citerefentry>
<refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function is used to change the authentication token
for a given user on request or because the token has expired.
</para>
</refsect2>
<refsect2 xml:id="pam3-session_management">
<title>Session Management</title>
<para>
The
<citerefentry>
<refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function sets up a user session for a previously
successful authenticated user. The session should later be terminated
with a call to
<citerefentry>
<refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect2>
<refsect2 xml:id="pam3-conversation">
<title>Conversation</title>
<para>
The PAM library uses an application-defined callback to allow
a direct communication between a loaded module and the application.
This callback is specified by the
<emphasis>struct pam_conv</emphasis> passed to
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> at the start of the transaction. See
<citerefentry>
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
for details.
</para>
</refsect2>
<refsect2 xml:id="pam3-data">
<title>Data Objects</title>
<para>
The
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
and
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
functions allow applications and PAM service modules to set and
retrieve PAM information.
</para>
<para>
The
<citerefentry>
<refentrytitle>pam_get_user</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
function is the preferred method to obtain the username.
</para>
<para>
The
<citerefentry>
<refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
and
<citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
function allows PAM service modules to set and retrieve free-form
data from one invocation to another.
</para>
</refsect2>
<refsect2 xml:id="pam3-miscellaneous">
<title>Environment and Error Management</title>
<para>
The
<citerefentry>
<refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_getenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and
<citerefentry>
<refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
functions are for maintaining a set of private environment variables.
</para>
<para>
The
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function returns a pointer to a string describing the
given PAM error code.
</para>
</refsect2>
</refsect1>
<refsect1 xml:id="pam3-return_values">
<title>RETURN VALUES</title>
<para>
The following return codes are known by PAM:
</para>
<variablelist>
<varlistentry>
<term>PAM_ABORT</term>
<listitem>
<para>Critical error, immediate abort.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_ACCT_EXPIRED</term>
<listitem>
<para>User account has expired.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHINFO_UNAVAIL</term>
<listitem>
<para>
Authentication service cannot retrieve authentication info.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_DISABLE_AGING</term>
<listitem>
<para>Authentication token aging disabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_ERR</term>
<listitem>
<para>Authentication token manipulation error.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_EXPIRED</term>
<listitem>
<para>Authentication token expired.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_LOCK_BUSY</term>
<listitem>
<para>Authentication token lock busy.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_RECOVERY_ERR</term>
<listitem>
<para>Authentication information cannot be recovered.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTH_ERR</term>
<listitem>
<para>Authentication failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>Memory buffer error.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CONV_ERR</term>
<listitem>
<para>Conversation failure.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_ERR</term>
<listitem>
<para>Failure setting user credentials.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_EXPIRED</term>
<listitem>
<para>User credentials expired.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_INSUFFICIENT</term>
<listitem>
<para>Insufficient credentials to access authentication data.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_UNAVAIL</term>
<listitem>
<para>Authentication service cannot retrieve user credentials.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_IGNORE</term>
<listitem>
<para>The return value should be ignored by PAM dispatch.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_MAXTRIES</term>
<listitem>
<para>Have exhausted maximum number of retries for service.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_MODULE_UNKNOWN</term>
<listitem>
<para>Module is unknown.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_NEW_AUTHTOK_REQD</term>
<listitem>
<para>
Authentication token is no longer valid; new one required.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_NO_MODULE_DATA</term>
<listitem>
<para>No module specific data is present.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_OPEN_ERR</term>
<listitem>
<para>Failed to load module.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_PERM_DENIED</term>
<listitem>
<para>Permission denied.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SERVICE_ERR</term>
<listitem>
<para>Error in service module.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SESSION_ERR</term>
<listitem>
<para>Cannot make/remove an entry for the specified session.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>Success.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYMBOL_ERR</term>
<listitem>
<para>Symbol not found.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>System error.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_TRY_AGAIN</term>
<listitem>
<para>Failed preliminary check by password service.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_UNKNOWN</term>
<listitem>
<para>User not known to the underlying authentication module.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="see_also"><title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_acct_mgmt</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_getenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_get_user</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, <citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam3-notes"><title>NOTES</title>
<para>
The <emphasis>libpam</emphasis> interfaces are only thread-safe if each
thread within the multithreaded application uses its own PAM handle.
</para>
</refsect1>
</refentry>

212
doc/man/pam.8.xml Normal file
View file

@ -0,0 +1,212 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam8">
<refmeta>
<refentrytitle>pam</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam8-name">
<refname>PAM</refname>
<refname>pam</refname>
<refpurpose>Pluggable Authentication Modules for Linux</refpurpose>
</refnamediv>
<refsect1 xml:id="pam8-description">
<title>DESCRIPTION</title>
<para>
This manual is intended to offer a quick introduction to
<emphasis remap="B">Linux-PAM</emphasis>. For more information
the reader is directed to the
<emphasis remap="B">Linux-PAM system administrators' guide</emphasis>.
</para>
<para>
<emphasis remap="B">Linux-PAM</emphasis> is a system of libraries
that handle the authentication tasks of applications (services) on
the system. The library provides a stable general interface
(Application Programming Interface - API) that privilege granting
programs (such as <citerefentry>
<refentrytitle>login</refentrytitle><manvolnum>1</manvolnum>
</citerefentry> and <citerefentry>
<refentrytitle>su</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>) defer to to perform standard authentication tasks.
</para>
<para>
The principal feature of the PAM approach is that the nature of the
authentication is dynamically configurable. In other words, the
system administrator is free to choose how individual
service-providing applications will authenticate users. This dynamic
configuration is set by the contents of the single
<emphasis remap="B">Linux-PAM</emphasis> configuration file
<filename>/etc/pam.conf</filename>. Alternatively and preferably,
the configuration can be set by individual configuration files
located in a <filename>pam.d</filename> directory. The presence of this
directory will cause <emphasis remap="B">Linux-PAM</emphasis> to
<emphasis remap="I">ignore</emphasis> <filename>/etc/pam.conf</filename>.
</para>
<para>
Vendor-supplied PAM configuration files might be installed in
the system directory <filename>/usr/lib/pam.d/</filename> or
a configurable vendor specific directory instead
of the machine configuration directory <filename>/etc/pam.d/</filename>.
If no machine configuration file is found, the vendor-supplied file
is used. All files in <filename>/etc/pam.d/</filename> override
files with the same name in other directories.
</para>
<para>From the point of view of the system administrator, for whom this
manual is provided, it is not of primary importance to understand the
internal behavior of the
<emphasis remap="B">Linux-PAM</emphasis>
library. The important point to recognize is that the configuration
file(s)
<emphasis remap="I">define</emphasis>
the connection between applications
<emphasis remap="B"/>(<emphasis remap="B">services</emphasis>)
and the pluggable authentication modules
<emphasis remap="B"/>(<emphasis remap="B">PAM</emphasis>s)
that perform the actual authentication tasks.</para>
<para><emphasis remap="B">Linux-PAM</emphasis>
separates the tasks of
<emphasis remap="I">authentication</emphasis>
into four independent management groups:
<emphasis remap="B">account</emphasis> management;
<emphasis remap="B">auth</emphasis>entication management;
<emphasis remap="B">password</emphasis> management;
and
<emphasis remap="B">session</emphasis> management.
(We highlight the abbreviations used for these groups in the
configuration file.)</para>
<para>Simply put, these groups take care of different aspects of a typical
user's request for a restricted service:</para>
<para><emphasis remap="B">account</emphasis> -
provide account verification types of service: has the user's password
expired?; is this user permitted access to the requested service?</para>
<!-- .br -->
<para><emphasis remap="B">auth</emphasis>entication -
authenticate a user and set up user credentials. Typically this is via
some challenge-response request that the user must satisfy: if you are
who you claim to be please enter your password. Not all authentications
are of this type, there exist hardware based authentication schemes
(such as the use of smart-cards and biometric devices), with suitable
modules, these may be substituted seamlessly for more standard
approaches to authentication - such is the flexibility of
<emphasis remap="B">Linux-PAM</emphasis>.</para>
<!-- .br -->
<para><emphasis remap="B">password</emphasis> -
this group's responsibility is the task of updating authentication
mechanisms. Typically, such services are strongly coupled to those of
the
<emphasis remap="B">auth</emphasis>
group. Some authentication mechanisms lend themselves well to being
updated with such a function. Standard UN*X password-based access is
the obvious example: please enter a replacement password.</para>
<!-- .br -->
<para><emphasis remap="B">session</emphasis> -
this group of tasks cover things that should be done prior to a
service being given and after it is withdrawn. Such tasks include the
maintenance of audit trails and the mounting of the user's home
directory. The
<emphasis remap="B">session</emphasis>
management group is important as it provides both an opening and
closing hook for modules to affect the services available to a user.</para>
</refsect1>
<refsect1 xml:id="pam8-files">
<title>FILES</title>
<variablelist>
<varlistentry>
<term>/etc/pam.conf</term>
<listitem>
<para>the configuration file</para>
</listitem>
</varlistentry>
<varlistentry>
<term>/etc/pam.d</term>
<listitem>
<para>
the <emphasis remap="B">Linux-PAM</emphasis> configuration
directory. Generally, if this directory is present, the
<filename>/etc/pam.conf</filename> file is ignored.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>/usr/lib/pam.d</term>
<listitem>
<para>
the <emphasis remap="B">Linux-PAM</emphasis> vendor configuration
directory. Files in <filename>/etc/pam.d</filename> override
files with the same name in this directory.
</para>
</listitem>
</varlistentry>
<varlistentry condition="with_vendordir">
<term>%vendordir%/pam.d</term>
<listitem>
<para>
additional <emphasis remap="B">Linux-PAM</emphasis> vendor
configuration directory. Files in <filename>/etc/pam.d</filename>
and <filename>/usr/lib/pam.d</filename> override files with the
same name in this directory.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam8-errors">
<title>ERRORS</title>
<para>
Typically errors generated by the
<emphasis remap="B">Linux-PAM</emphasis> system of libraries, will
be written to <citerefentry>
<refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
<refsect1 xml:id="pam8-conforming_to">
<title>CONFORMING TO</title>
<para>
DCE-RFC 86.0, October 1995.
Contains additional features, but remains backwardly compatible
with this RFC.
</para>
</refsect1>
<refsect1 xml:id="pam8-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_sm_setcred</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

19
doc/man/pam.conf-desc.xml Normal file
View file

@ -0,0 +1,19 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam.conf-desc">
<para>
When a <emphasis>PAM</emphasis> aware privilege granting application
is started, it activates its attachment to the PAM-API. This
activation performs a number of tasks, the most important being the
reading of the configuration file(s): <filename>/etc/pam.conf</filename>.
Alternatively and preferably, the configuration can be set by individual
configuration files located in a <filename>pam.d</filename> directory.
The presence of this directory will cause
<emphasis remap="B">Linux-PAM</emphasis> to
<emphasis remap="I">ignore</emphasis> <filename>/etc/pam.conf</filename>.
</para>
<para>
These files list the <emphasis>PAM</emphasis>s that will do the
authentication tasks required by this service, and the appropriate
behavior of the PAM-API in the event that individual
<emphasis>PAM</emphasis>s fail.
</para>
</section>

37
doc/man/pam.conf-dir.xml Normal file
View file

@ -0,0 +1,37 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam.conf-dir">
<para>
More flexible than the single configuration file is it to
configure libpam via the contents of
<filename>pam.d</filename> directories. In this case the
directories are filled with files each of which has a filename
equal to a service-name (in lower-case): it is the personal
configuration file for the named service.
</para>
<para>
Vendor-supplied PAM configuration files might be installed in
the system directory <filename>/usr/lib/pam.d/</filename> or
a configurable vendor specific directory instead
of the machine configuration directory <filename>/etc/pam.d/</filename>.
If no machine configuration file is found, the vendor-supplied file
is used. All files in <filename>/etc/pam.d/</filename> override
files with the same name in other directories.
</para>
<para>
The syntax of each file in pam.d is similar to that of the
<filename>/etc/pam.conf</filename> file and is made up of lines
of the following form:
</para>
<programlisting>
type control module-path module-arguments
</programlisting>
<para>
The only difference being that the service-name is not present. The
service-name is of course the name of the given configuration file.
For example, <filename>/etc/pam.d/login</filename> contains the
configuration for the <emphasis remap="B">login</emphasis> service.
</para>
</section>

423
doc/man/pam.conf-syntax.xml Normal file
View file

@ -0,0 +1,423 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam.conf-syntax">
<para>
The syntax of the <filename>/etc/pam.conf</filename>
configuration file is as follows. The file is made up of a list
of rules, each rule is typically placed on a single line,
but may be extended with an escaped end of line: `\&lt;LF&gt;'.
Comments are preceded with `#' marks and extend to the next end of
line.
</para>
<para>
The format of each rule is a space separated collection of tokens,
the first three being case-insensitive:
</para>
<para>
<emphasis remap="B"> service type control module-path module-arguments</emphasis>
</para>
<para>
The syntax of files contained in the <filename>/etc/pam.d/</filename>
directory, are identical except for the absence of any
<emphasis>service</emphasis> field. In this case, the
<emphasis>service</emphasis> is the name of the file in the
<filename>/etc/pam.d/</filename> directory. This filename must be
in lower case.
</para>
<para>
An important feature of <emphasis>PAM</emphasis>, is that a
number of rules may be <emphasis>stacked</emphasis> to combine
the services of a number of PAMs for a given authentication task.
</para>
<para>
The <emphasis>service</emphasis> is typically the familiar name of
the corresponding application: <emphasis>login</emphasis> and
<emphasis>su</emphasis> are good examples. The
<emphasis>service</emphasis>-name, <emphasis>other</emphasis>,
is reserved for giving <emphasis>default</emphasis> rules.
Only lines that mention the current service (or in the absence
of such, the <emphasis>other</emphasis> entries) will be associated
with the given service-application.
</para>
<para>
The <emphasis>type</emphasis> is the management group that the rule
corresponds to. It is used to specify which of the management groups
the subsequent module is to be associated with. Valid entries are:
</para>
<variablelist>
<varlistentry>
<term>account</term>
<listitem>
<para>
this module type performs non-authentication based account
management. It is typically used to restrict/permit access
to a service based on the time of day, currently available
system resources (maximum number of users) or perhaps the
location of the applicant user -- 'root' login only on the
console.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>auth</term>
<listitem>
<para>
this module type provides two aspects of authenticating
the user. Firstly, it establishes that the user is who they
claim to be, by instructing the application to prompt the user
for a password or other means of identification. Secondly, the
module can grant group membership or other privileges through
its credential granting properties.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>password</term>
<listitem>
<para>
this module type is required for updating the authentication
token associated with the user. Typically, there is one module
for each 'challenge/response' based authentication (auth) type.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>session</term>
<listitem>
<para>
this module type is associated with doing things that need to
be done for the user before/after they can be given service.
Such things include the logging of information concerning the
opening/closing of some data exchange with a user, mounting
directories, etc.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
If the <emphasis>type</emphasis> value from the list above is prepended
with a <emphasis>-</emphasis> character the PAM library will not log to
the system log if it is not possible to load the module because it is
missing in the system. This can be useful especially for modules which
are not always installed on the system and are not required for correct
authentication and authorization of the login session.
</para>
<para>
The third field, <emphasis>control</emphasis>, indicates the
behavior of the PAM-API should the module fail to succeed in its
authentication task. There are two types of syntax for this control
field: the simple one has a single simple keyword; the more
complicated one involves a square-bracketed selection of
<emphasis>value=action</emphasis> pairs.
</para>
<para>
For the simple (historical) syntax valid <emphasis>control</emphasis>
values are:
</para>
<variablelist>
<varlistentry>
<term>required</term>
<listitem>
<para>
failure of such a PAM will ultimately lead to the PAM-API
returning failure but only after the remaining
<emphasis>stacked</emphasis> modules (for this
<emphasis>service</emphasis> and <emphasis>type</emphasis>)
have been invoked.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>requisite</term>
<listitem>
<para>
like <emphasis>required</emphasis>, however, in the case that
such a module returns a failure, control is directly returned
to the application or to the superior PAM stack.
The return value is that associated with
the first required or requisite module to fail. Note, this flag
can be used to protect against the possibility of a user getting
the opportunity to enter a password over an unsafe medium. It is
conceivable that such behavior might inform an attacker of valid
accounts on a system. This possibility should be weighed against
the not insignificant concerns of exposing a sensitive password
in a hostile environment.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>sufficient</term>
<listitem>
<para>
if such a module succeeds and no prior <emphasis>required</emphasis>
module has failed the PAM framework returns success to
the application or to the superior PAM stack immediately without
calling any further modules in the stack. A failure of a
<emphasis>sufficient</emphasis> module is ignored and processing
of the PAM module stack continues unaffected.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>optional</term>
<listitem>
<para>
the success or failure of this module is only important if
it is the only module in the stack associated with this
<emphasis>service</emphasis>+<emphasis>type</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>include</term>
<listitem>
<para>
include all lines of given type from the configuration
file specified as an argument to this control.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>substack</term>
<listitem>
<para>
include all lines of given type from the configuration
file specified as an argument to this control. This differs from
<emphasis>include</emphasis> in that evaluation of the
<emphasis>done</emphasis> and <emphasis>die</emphasis> actions
in a substack does not cause skipping the rest of the complete
module stack, but only of the substack. Jumps in a substack
also can not make evaluation jump out of it, and the whole substack
is counted as one module when the jump is done in a parent stack.
The <emphasis>reset</emphasis> action will reset the state of a
module stack to the state it was in as of beginning of the substack
evaluation.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
For the more complicated syntax valid <emphasis>control</emphasis>
values have the following form:
</para>
<programlisting>
[value1=action1 value2=action2 ...]
</programlisting>
<para>
Where <emphasis>valueN</emphasis> corresponds to the return code
from the function invoked in the module for which the line is
defined. It is selected from one of these:
<emphasis>success</emphasis>, <emphasis>open_err</emphasis>,
<emphasis>symbol_err</emphasis>, <emphasis>service_err</emphasis>,
<emphasis>system_err</emphasis>, <emphasis>buf_err</emphasis>,
<emphasis>perm_denied</emphasis>, <emphasis>auth_err</emphasis>,
<emphasis>cred_insufficient</emphasis>,
<emphasis>authinfo_unavail</emphasis>,
<emphasis>user_unknown</emphasis>, <emphasis>maxtries</emphasis>,
<emphasis>new_authtok_reqd</emphasis>,
<emphasis>acct_expired</emphasis>, <emphasis>session_err</emphasis>,
<emphasis>cred_unavail</emphasis>, <emphasis>cred_expired</emphasis>,
<emphasis>cred_err</emphasis>, <emphasis>no_module_data</emphasis>,
<emphasis>conv_err</emphasis>, <emphasis>authtok_err</emphasis>,
<emphasis>authtok_recover_err</emphasis>,
<emphasis>authtok_lock_busy</emphasis>,
<emphasis>authtok_disable_aging</emphasis>,
<emphasis>try_again</emphasis>, <emphasis>ignore</emphasis>,
<emphasis>abort</emphasis>, <emphasis>authtok_expired</emphasis>,
<emphasis>module_unknown</emphasis>, <emphasis>bad_item</emphasis>,
<emphasis>conv_again</emphasis>, <emphasis>incomplete</emphasis>,
and <emphasis>default</emphasis>.
</para>
<para>
The last of these, <emphasis>default</emphasis>, implies 'all
<emphasis>valueN</emphasis>'s not mentioned explicitly. Note, the
full list of PAM errors is available in
<filename>/usr/include/security/_pam_types.h</filename>. The
<emphasis>actionN</emphasis> can take one of the following forms:
</para>
<variablelist>
<varlistentry>
<term>ignore</term>
<listitem>
<para>
when used with a stack of modules, the module's return
status will not contribute to the return code the application
obtains.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>bad</term>
<listitem>
<para>
this action indicates that the return code should be thought
of as indicative of the module failing. If this module is the
first in the stack to fail, its status value will be used for
that of the whole stack. This is the default action for
all return codes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>die</term>
<listitem>
<para>
equivalent to <emphasis>bad</emphasis> with the side effect of
terminating the module stack and PAM immediately returning to
the application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ok</term>
<listitem>
<para>
this tells PAM that the administrator thinks this return code
should contribute directly to the return code of the full
stack of modules. In other words, if the former state of the
stack would lead to a return of <emphasis>PAM_SUCCESS</emphasis>,
the module's return code will override this value. Note, if
the former state of the stack holds some value that is
indicative of a modules failure, this 'ok' value will not be
used to override that value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>done</term>
<listitem>
<para>
equivalent to <emphasis>ok</emphasis> with the side effect of
terminating the module stack and PAM immediately returning to the
application unless there was a non-ignored module failure before.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>N (an unsigned integer)</term>
<listitem>
<para>
jump over the next N modules in the stack.
Note that N equal to 0 is not allowed,
it would be treated as <emphasis>ignore</emphasis> in such case.
The side effect depends on the PAM function call:
for <emphasis>pam_authenticate</emphasis>,
<emphasis>pam_acct_mgmt</emphasis>,
<emphasis>pam_chauthtok</emphasis>, and
<emphasis>pam_open_session</emphasis>
it is <emphasis>ignore</emphasis>;
for <emphasis>pam_setcred</emphasis> and
<emphasis>pam_close_session</emphasis> it is
one of <emphasis>ignore</emphasis>, <emphasis>ok</emphasis>,
or <emphasis>bad</emphasis> depending on the module's return value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>reset</term>
<listitem>
<para>
clear all memory of the state of the module stack and
start again with the next stacked module.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
If a return code's action is not specifically defined via a
<emphasis>valueN</emphasis> token, and the
<emphasis>default</emphasis> value is not specified, that return
code's action defaults to <emphasis>bad</emphasis>.
</para>
<para>
Each of the four keywords: required; requisite; sufficient; and
optional, have an equivalent expression in terms of the [...]
syntax. They are as follows:
</para>
<variablelist>
<varlistentry>
<term>required</term>
<listitem>
<para>
[success=ok new_authtok_reqd=ok ignore=ignore default=bad]
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>requisite</term>
<listitem>
<para>
[success=ok new_authtok_reqd=ok ignore=ignore default=die]
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>sufficient</term>
<listitem>
<para>
[success=done new_authtok_reqd=done default=ignore]
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>optional</term>
<listitem>
<para>
[success=ok new_authtok_reqd=ok default=ignore]
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<emphasis>module-path</emphasis> is either the full filename
of the PAM to be used by the application (it begins with a '/'),
or a relative pathname from the default module location:
<filename>/lib/security/</filename> or
<filename>/lib64/security/</filename>, depending on the architecture.
</para>
<para>
<emphasis>module-arguments</emphasis> are a space separated list
of tokens that can be used to modify the specific behavior of the
given PAM. Such arguments will be documented for each individual
module. Note, if you wish to include spaces in an argument, you
should surround that argument with square brackets.
</para>
<programlisting>
squid auth required pam_mysql.so user=passwd_query passwd=mada \
db=eminence [query=select user_name from internet_service \
where user_name='%u' and password=PASSWORD('%p') and \
service='web_proxy']
</programlisting>
<para>
When using this convention, you can include `[' characters
inside the string, and if you wish to include a `]' character
inside the string that will survive the argument parsing, you
should use `\]'. In other words:
</para>
<programlisting>
[..[..\]..] --&gt; ..[..]..
</programlisting>
<para>
Any line in (one of) the configuration file(s), that is not formatted
correctly, will generally tend (erring on the side of caution) to make
the authentication process fail. A corresponding error is written to
the system log files with a call to
<citerefentry>
<refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</section>

85
doc/man/pam.conf.5.xml Normal file
View file

@ -0,0 +1,85 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam.conf">
<refmeta>
<refentrytitle>pam.conf</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam.conf-name">
<refname>pam.conf</refname>
<refname>pam.d</refname>
<refpurpose>PAM configuration files</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsect1 xml:id="pam.conf-description">
<title>DESCRIPTION</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam.conf-desc.xml" xpointer='xpointer(id("pam.conf-desc")/*)' />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam.conf-syntax.xml" xpointer='xpointer(id("pam.conf-syntax")/*)' />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam.conf-dir.xml" xpointer='xpointer(id("pam.conf-dir")/*)' />
</refsect1>
<refsect1 xml:id="pam8-files">
<title>FILES</title>
<variablelist>
<varlistentry>
<term>/etc/pam.conf</term>
<listitem>
<para>the configuration file</para>
</listitem>
</varlistentry>
<varlistentry>
<term>/etc/pam.d</term>
<listitem>
<para>
the <emphasis remap="B">Linux-PAM</emphasis> configuration
directory. Generally, if this directory is present, the
<filename>/etc/pam.conf</filename> file is ignored.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>/usr/lib/pam.d</term>
<listitem>
<para>
the <emphasis remap="B">Linux-PAM</emphasis> vendor configuration
directory. Files in <filename>/etc/pam.d</filename> override
files with the same name in this directory.
</para>
</listitem>
</varlistentry>
<varlistentry condition="with_vendordir">
<term>%vendordir%/pam.d</term>
<listitem>
<para>
additional <emphasis remap="B">Linux-PAM</emphasis> vendor
configuration directory. Files in <filename>/etc/pam.d</filename>
and <filename>/usr/lib/pam.d</filename> override files with the
same name in this directory.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam.conf-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

143
doc/man/pam_acct_mgmt.3.xml Normal file
View file

@ -0,0 +1,143 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_acct_mgmt">
<refmeta>
<refentrytitle>pam_acct_mgmt</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_acct_mgmt-name">
<refname>pam_acct_mgmt</refname>
<refpurpose>PAM account validation management</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_acct_mgmt-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_acct_mgmt</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_acct_mgmt-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_acct_mgmt</function> function is used to determine
if the user's account is valid. It checks for authentication token
and account expiration and verifies access restrictions. It is
typically called after the user has been authenticated.
</para>
<para>
The <emphasis>pamh</emphasis> argument is an authentication
handle obtained by a prior call to pam_start().
The flags argument is the binary or of zero or more of the
following values:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_DISALLOW_NULL_AUTHTOK</term>
<listitem>
<para>
The PAM module service should return PAM_NEW_AUTHTOK_REQD
if the user has a null authentication token.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_acct_mgmt-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_ACCT_EXPIRED</term>
<listitem>
<para>
User account has expired.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTH_ERR</term>
<listitem>
<para>
Authentication failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_NEW_AUTHTOK_REQD</term>
<listitem>
<para>
The user account is valid but their authentication token
is <emphasis>expired</emphasis>. The correct response to
this return-value is to require that the user satisfies
the <function>pam_chauthtok()</function> function before
obtaining service. It may not be possible for some
applications to do this. In such cases, the user should be
denied access until such time as they can update their password.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_PERM_DENIED</term>
<listitem>
<para>
Permission denied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The authentication token was successfully updated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_UNKNOWN</term>
<listitem>
<para>
User unknown to password service.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_acct_mgmt-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

167
doc/man/pam_authenticate.3.xml Normal file
View file

@ -0,0 +1,167 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_authenticate">
<refmeta>
<refentrytitle>pam_authenticate</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_authenticate-name">
<refname>pam_authenticate</refname>
<refpurpose>account authentication</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_authenticate-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_authenticate</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_authenticate-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_authenticate</function> function is used to
authenticate the user. The user is required to provide an
authentication token depending upon the authentication service,
usually this is a password, but could also be a finger print.
</para>
<para>
The PAM service module may request that the user enter their
username via the conversation mechanism (see
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and
<citerefentry>
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>). The name of the authenticated user
will be present in the PAM item PAM_USER. This item may be
recovered with a call to
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<para>
The <emphasis>pamh</emphasis> argument is an authentication
handle obtained by a prior call to pam_start().
The flags argument is the binary or of zero or more of the
following values:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_DISALLOW_NULL_AUTHTOK</term>
<listitem>
<para>
The PAM module service should return PAM_AUTH_ERR
if the user does not have a registered authentication token.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_authenticate-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_ABORT</term>
<listitem>
<para>
The application should exit immediately after calling
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> first.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTH_ERR</term>
<listitem>
<para>
The user was not authenticated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_INSUFFICIENT</term>
<listitem>
<para>
For some reason the application does not have sufficient
credentials to authenticate the user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHINFO_UNAVAIL</term>
<listitem>
<para>
The modules were not able to access the authentication
information. This might be due to a network or hardware
failure etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_MAXTRIES</term>
<listitem>
<para>
One or more of the authentication modules has reached its
limit of tries authenticating the user. Do not try again.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The user was successfully authenticated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_UNKNOWN</term>
<listitem>
<para>
User unknown to authentication service.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_authenticate-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

162
doc/man/pam_chauthtok.3.xml Normal file
View file

@ -0,0 +1,162 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_chauthtok">
<refmeta>
<refentrytitle>pam_chauthtok</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_chauthtok-name">
<refname>pam_chauthtok</refname>
<refpurpose>updating authentication tokens</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_chauthtok-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_chauthtok</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_chauthtok-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_chauthtok</function> function is used to change the
authentication token for a given user (as indicated by the state
associated with the handle <emphasis>pamh</emphasis>).
</para>
<para>
The <emphasis>pamh</emphasis> argument is an authentication
handle obtained by a prior call to pam_start().
The flags argument is the binary or of zero or more of the
following values:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CHANGE_EXPIRED_AUTHTOK</term>
<listitem>
<para>
This argument indicates to the modules that the user's
authentication token (password) should only be changed
if it has expired.
If this argument is not passed, the application requires
that all authentication tokens are to be changed.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_chauthtok-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_AUTHTOK_ERR</term>
<listitem>
<para>
A module was unable to obtain the new authentication token.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_RECOVERY_ERR</term>
<listitem>
<para>
A module was unable to obtain the old authentication token.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_LOCK_BUSY</term>
<listitem>
<para>
One or more of the modules was unable to change the
authentication token since it is currently locked.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_DISABLE_AGING</term>
<listitem>
<para>
Authentication token aging has been disabled for at least
one of the modules.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_PERM_DENIED</term>
<listitem>
<para>
Permission denied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The authentication token was successfully updated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_TRY_AGAIN</term>
<listitem>
<para>
Not all of the modules were in a position to update the
authentication token(s). In such a case none of the user's
authentication tokens are updated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_UNKNOWN</term>
<listitem>
<para>
User unknown to password service.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_chauthtok-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

112
doc/man/pam_close_session.3.xml Normal file
View file

@ -0,0 +1,112 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_send">
<refmeta>
<refentrytitle>pam_close_session</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_close_session-name">
<refname>pam_close_session</refname>
<refpurpose>terminate PAM session management</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_close_session-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_close_session</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_close_session-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_close_session</function> function is used
to indicate that an authenticated session has ended.
The session should have been created with a call to
<citerefentry>
<refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<para>
It should be noted that the effective uid,
<citerefentry>
<refentrytitle>geteuid</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>. of the application should be of sufficient
privilege to perform such tasks as unmounting the
user's home directory for example.
</para>
<para>
The flags argument is the binary or of zero or more of the
following values:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_close_session-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_ABORT</term>
<listitem>
<para>
General failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SESSION_ERR</term>
<listitem>
<para>
Session failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Session was successful terminated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_close_session-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

226
doc/man/pam_conv.3.xml Normal file
View file

@ -0,0 +1,226 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_conv">
<refmeta>
<refentrytitle>pam_conv</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_conv-name">
<refname>pam_conv</refname>
<refpurpose>PAM conversation function</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_conv-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
</funcsynopsis>
<programlisting>
struct pam_message {
int msg_style;
const char *msg;
};
struct pam_response {
char *resp;
int resp_retcode;
};
struct pam_conv {
int (*conv)(int num_msg, const struct pam_message **msg,
struct pam_response **resp, void *appdata_ptr);
void *appdata_ptr;
};
</programlisting>
</refsynopsisdiv>
<refsect1 xml:id="pam_conv-description">
<title>DESCRIPTION</title>
<para>
The PAM library uses an application-defined callback to allow
a direct communication between a loaded module and the application.
This callback is specified by the
<emphasis>struct pam_conv</emphasis> passed to
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
at the start of the transaction.
</para>
<para>
When a module calls the referenced conv() function, the argument
<emphasis>appdata_ptr</emphasis> is set to the second element of
this structure.
</para>
<para>
The other arguments of a call to conv() concern the information
exchanged by module and application. That is to say,
<emphasis>num_msg</emphasis> holds the length of the array of
pointers, <emphasis>msg</emphasis>. After a successful return, the
pointer <emphasis>resp</emphasis> points to an array of pam_response
structures, holding the application supplied text. The
<emphasis>resp_retcode</emphasis> member of this struct is unused and
should be set to zero. It is the caller's responsibility to release
both, this array and the responses themselves, using
<citerefentry>
<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>. Note, <emphasis>*resp</emphasis> is a
<emphasis>struct pam_response</emphasis> array and not an array of
pointers.
</para>
<para>
The number of responses is always equal to the
<emphasis>num_msg</emphasis> conversation function argument.
This does require that the response array is
<citerefentry>
<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>'d after
every call to the conversation function. The index of the
responses corresponds directly to the prompt index in the
pam_message array.
</para>
<para>
On failure, the conversation function should release any resources
it has allocated, and return one of the predefined PAM error codes.
</para>
<para>
Each message can have one of four types, specified by the
<emphasis>msg_style</emphasis> member of
<emphasis>struct pam_message</emphasis>:
</para>
<variablelist>
<varlistentry>
<term>PAM_PROMPT_ECHO_OFF</term>
<listitem>
<para>
Obtain a string without echoing any text.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_PROMPT_ECHO_ON</term>
<listitem>
<para>
Obtain a string whilst echoing text.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_ERROR_MSG</term>
<listitem>
<para>
Display an error message.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_TEXT_INFO</term>
<listitem>
<para>
Display some text.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The point of having an array of messages is that it becomes possible
to pass a number of things to the application in a single call from
the module. It can also be convenient for the application that related
things come at once: a windows based application can then present a
single form with many messages/prompts on at once.
</para>
<para>
In passing, it is worth noting that there is a discrepancy between
the way Linux-PAM handles the const struct pam_message **msg
conversation function argument and the way that Solaris' PAM
(and derivatives, known to include HP/UX, are there others?) does.
Linux-PAM interprets the msg argument as entirely equivalent to the
following prototype
const struct pam_message *msg[] (which, in spirit, is consistent with
the commonly used prototypes for argv argument to the familiar main()
function: char **argv; and char *argv[]). Said another way Linux-PAM
interprets the msg argument as a pointer to an array of num_msg read
only 'struct pam_message' pointers. Solaris' PAM implementation
interprets this argument as a pointer to a pointer to an array of
num_msg pam_message structures. Fortunately, perhaps, for most
module/application developers when num_msg has a value of one these
two definitions are entirely equivalent. Unfortunately, casually
raising this number to two has led to unanticipated compatibility
problems.
</para>
<para>
For what its worth the two known module writer work-arounds for trying
to maintain source level compatibility with both PAM implementations
are:
</para>
<itemizedlist>
<listitem>
<para>
never call the conversation function with num_msg greater than one.
</para>
</listitem>
<listitem>
<para>
set up msg as doubly referenced so both types of conversation
function can find the messages. That is, make
</para>
<programlisting>
msg[n] = &amp; (( *msg )[n])
</programlisting>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 xml:id="pam_conv-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CONV_ERR</term>
<listitem>
<para>
Conversation failure. The application should not set
<emphasis>*resp</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Success.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_conv-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

119
doc/man/pam_end.3.xml Normal file
View file

@ -0,0 +1,119 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_end">
<refmeta>
<refentrytitle>pam_end</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_end-name">
<refname>pam_end</refname>
<refpurpose>termination of PAM transaction</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_end-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_end</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>pam_status</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_end-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_end</function> function terminates the PAM
transaction and is the last function an application should call
in the PAM context. Upon return the handle <emphasis>pamh</emphasis>
is no longer valid and all memory associated with it will be
invalid.
</para>
<para>
The <emphasis>pam_status</emphasis> argument should be set to
the value returned to the application by the last PAM
library call.
</para>
<para>
The value taken by <emphasis>pam_status</emphasis> is used as
an argument to the module specific callback function,
<function>cleanup()</function>
(See <citerefentry>
<refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and
<citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>). In this way the module can be given notification
of the pass/fail nature of the tear-down process, and perform any
last minute tasks that are appropriate to the module before it is
unlinked. This argument can be logically OR'd with
<emphasis>PAM_DATA_SILENT</emphasis> to indicate that
the module should not treat the call too seriously. It is generally
used to indicate that the current closing of the library is in a
<citerefentry>
<refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>ed
process, and that the parent will take care of cleaning up things
that exist outside of the current process space (files etc.).
</para>
<para>
This function <emphasis>free</emphasis>'s all memory for items
associated with the
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> functions. Pointers associated with such objects
are not valid anymore after <function>pam_end</function> was called.
</para>
</refsect1>
<refsect1 xml:id="pam_end-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Transaction was successful terminated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
System error, for example a NULL pointer was submitted
as PAM handle or the function was called by a module.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_end-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

118
doc/man/pam_error.3.xml Normal file
View file

@ -0,0 +1,118 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_error">
<refmeta>
<refentrytitle>pam_error</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_error-name">
<refname>pam_error</refname>
<refname>pam_verror</refname>
<refpurpose>display error messages to the user</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv xml:id="pam_error-synopsis">
<funcsynopsis>
<funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_error</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>fmt</parameter></paramdef>
<paramdef><parameter>...</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>pam_verror</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>fmt</parameter></paramdef>
<paramdef>va_list <parameter>args</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_error-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_error</function> function prints error messages
through the conversation function to the user.
</para>
<para>
The <function>pam_verror</function> function performs the same
task as <function>pam_error()</function> with the difference
that it takes a set of arguments which have been obtained using
the <citerefentry>
<refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> variable argument list macros.
</para>
</refsect1>
<refsect1 xml:id="pam_error-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CONV_ERR</term>
<listitem>
<para>
Conversation failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Error message was displayed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
System error.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_error-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_info</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_vinfo</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_prompt</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_vprompt</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam_error-standards">
<title>STANDARDS</title>
<para>
The <function>pam_error</function> and <function>pam_verror</function>
functions are Linux-PAM extensions.
</para>
</refsect1>
</refentry>

206
doc/man/pam_fail_delay.3.xml Normal file
View file

@ -0,0 +1,206 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_fail_delay">
<refmeta>
<refentrytitle>pam_fail_delay</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_fail_delay-name">
<refname>pam_fail_delay</refname>
<refpurpose>request a delay on failure</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_fail_delay-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_fail_delay</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>unsigned int <parameter>usec</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_fail_delay-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_fail_delay</function> function provides a
mechanism by which an application or module can suggest a minimum
delay of <emphasis>usec</emphasis> micro-seconds. The
function keeps a record of the longest time requested with this
function. Should
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> fail, the failing return to the application is
delayed by an amount of time randomly distributed (by up to 50%)
about this longest value.
</para>
<para>
Independent of success, the delay time is reset to its zero
default value when the PAM service module returns control to
the application. The delay occurs <emphasis>after</emphasis> all
authentication modules have been called, but <emphasis>before</emphasis>
control is returned to the service application.
</para>
<para>
When using this function the programmer should check if it is
available with:
</para>
<programlisting>
#ifdef HAVE_PAM_FAIL_DELAY
....
#endif /* HAVE_PAM_FAIL_DELAY */
</programlisting>
<para>
For applications written with a single thread that are event
driven in nature, generating this delay may be undesirable.
Instead, the application may want to register the delay in some
other way. For example, in a single threaded server that serves
multiple authentication requests from a single event loop, the
application might want to simply mark a given connection as
blocked until an application timer expires. For this reason
the delay function can be changed with the
<emphasis>PAM_FAIL_DELAY</emphasis> item. It can be queried and
set with
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
and
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> respectively. The value used to set it should be
a function pointer of the following prototype:
<programlisting>
void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);
</programlisting>
The arguments being the <emphasis>retval</emphasis> return code
of the module stack, the <emphasis>usec_delay</emphasis>
micro-second delay that libpam is requesting and the
<emphasis>appdata_ptr</emphasis> that the application has associated
with the current <emphasis>pamh</emphasis>. This last value was set
by the application when it called
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> or explicitly with
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<para>
Note that the PAM_FAIL_DELAY item is set to NULL by default. This
indicates that PAM should perform a random delay as described
above when authentication fails and a delay has been suggested.
If an application does not want the PAM library to perform any
delay on authentication failure, then the application must define
a custom delay function that executes no statements and set
the PAM_FAIL_DELAY item to point to this function.
</para>
</refsect1>
<refsect1 xml:id="pam_fail_delay-rationale">
<title>RATIONALE</title>
<para>
It is often possible to attack an authentication scheme by exploiting
the time it takes the scheme to deny access to an applicant user. In
cases of <emphasis>short</emphasis> timeouts, it may prove possible
to attempt a <emphasis>brute force</emphasis> dictionary attack --
with an automated process, the attacker tries all possible passwords
to gain access to the system. In other cases, where individual
failures can take measurable amounts of time (indicating the nature
of the failure), an attacker can obtain useful information about the
authentication process. These latter attacks make use of procedural
delays that constitute a <emphasis>covert channel</emphasis>
of useful information.
</para>
<para>
To minimize the effectiveness of such attacks, it is desirable to
introduce a random delay in a failed authentication process.
Preferable this value should be set by the application or a special
PAM module. Standard PAM modules should not modify the delay
unconditional.
</para>
</refsect1>
<refsect1 xml:id="pam_fail_delay-example">
<title>EXAMPLE</title>
<para>
For example, a login application may require a failure delay of
roughly 3 seconds. It will contain the following code:
</para>
<programlisting>
pam_fail_delay (pamh, 3000000 /* micro-seconds */ );
pam_authenticate (pamh, 0);
</programlisting>
<para>
if the modules do not request a delay, the failure delay will be
between 1.5 and 4.5 seconds.
</para>
<para>
However, the modules, invoked in the authentication process, may
also request delays:
</para>
<programlisting>
module #1: pam_fail_delay (pamh, 2000000);
module #2: pam_fail_delay (pamh, 4000000);
</programlisting>
<para>
in this case, it is the largest requested value that is used to
compute the actual failed delay: here between 2 and 6 seconds.
</para>
</refsect1>
<refsect1 xml:id="pam_fail_delay-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Delay was successful adjusted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
A NULL pointer was submitted as PAM handle.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_fail_delay-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam_fail_delay-standards">
<title>STANDARDS</title>
<para>
The <function>pam_fail_delay</function> function is an
Linux-PAM extension.
</para>
</refsect1>
</refentry>

246
doc/man/pam_get_authtok.3.xml Normal file
View file

@ -0,0 +1,246 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_get_authtok">
<refmeta>
<refentrytitle>pam_get_authtok</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_get_authtok-name">
<refname>pam_get_authtok</refname>
<refname>pam_get_authtok_verify</refname>
<refname>pam_get_authtok_noverify</refname>
<refpurpose>get authentication token</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv xml:id="pam_get_authtok-synopsis">
<funcsynopsis>
<funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_get_authtok</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>item</parameter></paramdef>
<paramdef>const char **<parameter>authtok</parameter></paramdef>
<paramdef>const char *<parameter>prompt</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>pam_get_authtok_noverify</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char **<parameter>authtok</parameter></paramdef>
<paramdef>const char *<parameter>prompt</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>pam_get_authtok_verify</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char **<parameter>authtok</parameter></paramdef>
<paramdef>const char *<parameter>prompt</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_get_authtok-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_get_authtok</function> function returns the
cached authentication token, or prompts the user if no token is
currently cached. It is intended for internal use by Linux-PAM and
PAM service modules. Upon successful return,
<emphasis>authtok</emphasis> contains a pointer to the value of the
authentication token. Note, this is a pointer to the
<emphasis>actual</emphasis> data and should
<emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
over-written!
</para>
<para>
The <emphasis>prompt</emphasis> argument specifies a prompt to use
if no token is cached. If a NULL pointer
is given, <function>pam_get_authtok</function> uses pre-defined prompts.
</para>
<para>
The following values are supported for <emphasis>item</emphasis>:
</para>
<variablelist>
<varlistentry>
<term>PAM_AUTHTOK</term>
<listitem>
<para>
Returns the current authentication token. Called from
<citerefentry><refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> <function>pam_get_authtok</function> will
ask the user to confirm the new token by retyping it. If
a prompt was specified, "Retype" will be used as prefix.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_OLDAUTHTOK</term>
<listitem>
<para>
Returns the previous authentication token when changing
authentication tokens.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The <function>pam_get_authtok_noverify</function> function can
only be used for changing the password
(from <citerefentry>
<refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>). It returns the cached
authentication token, or prompts the user if no token is
currently cached. The difference to <function>pam_get_authtok</function>
is, that this function does not ask a second time for the password
to verify it. Upon successful return, <emphasis>authtok</emphasis>
contains a pointer to the value of the authentication token. Note,
this is a pointer to the
<emphasis>actual</emphasis> data and should
<emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
over-written!
</para>
<para>
The <function>pam_get_authtok_verify</function> function can
only be used to verify a password for mistypes gotten by
<citerefentry>
<refentrytitle>pam_get_authtok_noverify</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>. This function asks a second time for the password
and verify it with the password provided by <emphasis>authtok</emphasis>
argument. In case of an error, the value of <emphasis>authtok</emphasis>
is undefined. Else this argument will point to the
<emphasis>actual</emphasis> data and should
<emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
over-written!
</para>
</refsect1>
<refsect1 xml:id="pam_get_authtok-options">
<title>OPTIONS</title>
<para>
<function>pam_get_authtok</function> honours the following module
options:
</para>
<variablelist>
<varlistentry>
<term>
try_first_pass
</term>
<listitem>
<para>
Before prompting the user for their password, the module first
tries the previous stacked module's password in case that
satisfies this module as well.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
use_first_pass
</term>
<listitem>
<para>
The argument <option>use_first_pass</option> forces the module
to use a previous stacked modules password and will never prompt
the user - if no password is available or the password is not
appropriate, the user will be denied access.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
use_authtok
</term>
<listitem>
<para>
When password changing enforce the module to set the new
token to the one provided by a previously stacked
<option>password</option> module. If no token is available
token changing will fail.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
authtok_type=XXX
</term>
<listitem>
<para>
The default action is for the module to use the
following prompts when requesting passwords:
"New UNIX password: " and "Retype UNIX password: ".
The example word <emphasis>UNIX</emphasis> can
be replaced with this option, by default it is empty.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_get_authtok-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_AUTH_ERR</term>
<listitem>
<para>
Authentication token could not be retrieved.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_ERR</term>
<listitem>
<para>
New authentication could not be retrieved.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Authentication token was successfully retrieved.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
A NULL pointer was specified as the PAM handle, or
no space for an authentication token was provided.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_TRY_AGAIN</term>
<listitem>
<para>
New authentication tokens mismatch.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_get_authtok-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam_get_authtok-standards">
<title>STANDARDS</title>
<para>
The <function>pam_get_authtok</function> function is a Linux-PAM
extensions.
</para>
</refsect1>
</refentry>

104
doc/man/pam_get_data.3.xml Normal file
View file

@ -0,0 +1,104 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_get_data">
<refmeta>
<refentrytitle>pam_get_data</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_get_data-name">
<refname>pam_get_data</refname>
<refpurpose>
get module internal data
</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_get_data-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_get_data</function></funcdef>
<paramdef>const pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>module_data_name</parameter></paramdef>
<paramdef>const void **<parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_get_data-description">
<title>DESCRIPTION</title>
<para>
This function together with the
<citerefentry>
<refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function
is useful to manage module-specific data meaningful only to
the calling PAM module.
</para>
<para>
The <function>pam_get_data</function> function looks up the
object associated with the (hopefully) unique string
<emphasis>module_data_name</emphasis> in the PAM context
specified by the <emphasis>pamh</emphasis> argument.
A successful call to
<function>pam_get_data</function> will result in
<emphasis>data</emphasis> pointing to the object. Note,
this data is <emphasis>not</emphasis> a copy and should be
treated as <emphasis>constant</emphasis> by the module.
</para>
</refsect1>
<refsect1 xml:id="pam_get_data-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Data was successful retrieved.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
A NULL pointer was submitted as PAM handle or the
function was called by an application.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_NO_MODULE_DATA</term>
<listitem>
<para>
No module specific data is present.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_get_data-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

132
doc/man/pam_get_item.3.xml Normal file
View file

@ -0,0 +1,132 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_get_item">
<refmeta>
<refentrytitle>pam_get_item</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_get_item-name">
<refname>pam_get_item</refname>
<refpurpose>
getting PAM information
</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_get_item-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_get_item</function></funcdef>
<paramdef>const pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>item_type</parameter></paramdef>
<paramdef>const void **<parameter>item</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_get_item-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_get_item</function> function allows applications
and PAM service modules to access and retrieve PAM information
of <emphasis>item_type</emphasis>. Upon successful return,
<emphasis>item</emphasis> contains a pointer to the value of the
corresponding item. Note, this is a pointer to the
<emphasis>actual</emphasis> data and should
<emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
over-written! The following values are supported for
<emphasis>item_type</emphasis>:
</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_item_types_std.inc.xml"/>
<para>
The following additional items are specific to Linux-PAM and should not be used in
portable applications:
</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_item_types_ext.inc.xml"/>
<para>
If a service module wishes to obtain the name of the user,
it should not use this function, but instead perform a call to
<citerefentry>
<refentrytitle>pam_get_user</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<para>
Only a service module is privileged to read the
authentication tokens, PAM_AUTHTOK and PAM_OLDAUTHTOK.
</para>
</refsect1>
<refsect1 xml:id="pam_get_item-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_BAD_ITEM</term>
<listitem>
<para>
The application attempted to set an undefined or inaccessible
item.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_PERM_DENIED</term>
<listitem>
<para>
The value of <emphasis>item</emphasis> was NULL.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Data was successful updated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
The <emphasis>pam_handle_t</emphasis> passed as first
argument was invalid.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_get_item-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

161
doc/man/pam_get_user.3.xml Normal file
View file

@ -0,0 +1,161 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_get_user">
<refmeta>
<refentrytitle>pam_get_user</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_get_user-name">
<refname>pam_get_user</refname>
<refpurpose>
get user name
</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_get_user-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_get_user</function></funcdef>
<paramdef>const pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char **<parameter>user</parameter></paramdef>
<paramdef>const char *<parameter>prompt</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_get_user-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_get_user</function> function returns the
name of the user specified by
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>. If no user was specified it returns what
<function>pam_get_item (pamh, PAM_USER, ... );</function> would
have returned. If this is NULL it obtains the username via the
<citerefentry>
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> mechanism, it prompts the user with the first
non-NULL string in the following list:
</para>
<itemizedlist>
<listitem>
<para>
The <emphasis>prompt</emphasis> argument passed to the function.
</para>
</listitem>
<listitem>
<para>
What is returned by pam_get_item (pamh, PAM_USER_PROMPT, ... );
</para>
</listitem>
<listitem>
<para>
The default prompt: "login: "
</para>
</listitem>
</itemizedlist>
<para>
By whatever means the username is obtained, a pointer to it is
returned as the contents of <emphasis>*user</emphasis>. Note,
this memory should <emphasis remap="B">not</emphasis> be
<emphasis>free()</emphasis>'d or <emphasis>modified</emphasis>
by the module.
</para>
<para>
This function sets the <emphasis>PAM_USER</emphasis> item
associated with the
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> functions.
</para>
</refsect1>
<refsect1 xml:id="pam_get_user-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
User name was successful retrieved.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
A NULL pointer was submitted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CONV_ERR</term>
<listitem>
<para>
The conversation method supplied by the
application failed to obtain the username.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_ABORT</term>
<listitem>
<para>
Error resuming an old conversation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CONV_AGAIN</term>
<listitem>
<para>
The conversation method supplied by the application
is waiting for an event.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_get_user-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

65
doc/man/pam_getenv.3.xml Normal file
View file

@ -0,0 +1,65 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_getenv">
<refmeta>
<refentrytitle>pam_getenv</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_getenv-name">
<refname>pam_getenv</refname>
<refpurpose>get a PAM environment variable</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_getenv-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>const char *<function>pam_getenv</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_getenv-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_getenv</function> function searches the
PAM environment list as associated with the handle
<emphasis>pamh</emphasis> for an item that matches the string
pointed to by <emphasis>name</emphasis> and returns a pointer
to the value of the environment variable. The application is
not allowed to free the data.
</para>
</refsect1>
<refsect1 xml:id="pam_getenv-return_values">
<title>RETURN VALUES</title>
<para>
The <function>pam_getenv</function> function returns NULL
on failure.
</para>
</refsect1>
<refsect1 xml:id="pam_getenv-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

83
doc/man/pam_getenvlist.3.xml Normal file
View file

@ -0,0 +1,83 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_getenvlist">
<refmeta>
<refentrytitle>pam_getenvlist</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_getenvlist-name">
<refname>pam_getenvlist</refname>
<refpurpose>getting the PAM environment</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_getenvlist-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>char **<function>pam_getenvlist</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_getenvlist-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_getenvlist</function> function returns a complete
copy of the PAM environment as associated with the handle
<emphasis>pamh</emphasis>. The PAM environment variables
represent the contents of the regular environment variables of the
authenticated user when service is granted.
</para>
<para>
The format of the memory is a malloc()'d array of char pointers,
the last element of which is set to NULL. Each of the non-NULL
entries in this array point to a NUL terminated and malloc()'d
char string of the form: "<emphasis>name=value</emphasis>".
</para>
<para>
It should be noted that this memory will never be free()'d by
libpam. Once obtained by a call to
<function>pam_getenvlist</function>, it is the responsibility of
the calling application to free() this memory.
</para>
<para>
It is by design, and not a coincidence, that the format and contents
of the returned array matches that required for the third argument of
the
<citerefentry>
<refentrytitle>execle</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function call.
</para>
</refsect1>
<refsect1 xml:id="pam_getenvlist-return_values">
<title>RETURN VALUES</title>
<para>
The <function>pam_getenvlist</function> function returns NULL
on failure.
</para>
</refsect1>
<refsect1 xml:id="pam_getenvlist-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_getenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

106
doc/man/pam_info.3.xml Normal file
View file

@ -0,0 +1,106 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_info">
<refmeta>
<refentrytitle>pam_info</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_info-name">
<refname>pam_info</refname>
<refname>pam_vinfo</refname>
<refpurpose>display messages to the user</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv xml:id="pam_info-synopsis">
<funcsynopsis>
<funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_info</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>fmt</parameter></paramdef>
<paramdef><parameter>...</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>pam_vinfo</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>fmt</parameter></paramdef>
<paramdef>va_list <parameter>args</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_info-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_info</function> function prints messages
through the conversation function to the user.
</para>
<para>
The <function>pam_vinfo</function> function performs the same
task as <function>pam_info()</function> with the difference
that it takes a set of arguments which have been obtained using
the <citerefentry>
<refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> variable argument list macros.
</para>
</refsect1>
<refsect1 xml:id="pam_info-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CONV_ERR</term>
<listitem>
<para>
Conversation failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Transaction was successful created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
System error.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_info-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam_info-standards">
<title>STANDARDS</title>
<para>
The <function>pam_info</function> and <function>pam_vinfo</function>
functions are Linux-PAM extensions.
</para>
</refsect1>
</refentry>

60
doc/man/pam_item_types_ext.inc.xml Normal file
View file

@ -0,0 +1,60 @@
<!-- this file is included by pam_set_item and pam_get_item -->
<variablelist xmlns="http://docbook.org/ns/docbook" version="5.0">
<varlistentry>
<term>PAM_FAIL_DELAY</term>
<listitem>
<para>
A function pointer to redirect centrally managed
failure delays. See
<citerefentry>
<refentrytitle>pam_fail_delay</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_XDISPLAY</term>
<listitem>
<para>
The name of the X display. For graphical, X-based applications the
value for this item should be the <emphasis>$DISPLAY</emphasis>
variable. This value may be used independently of
<emphasis>PAM_TTY</emphasis> for passing the
name of the display.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_XAUTHDATA</term>
<listitem>
<para>
A pointer to a structure containing the X authentication data
required to make a connection to the display specified by
<emphasis>PAM_XDISPLAY</emphasis>, if such information is
necessary. See
<citerefentry>
<refentrytitle>pam_xauth_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_TYPE</term>
<listitem>
<para>
The default action is for the module to use the
following prompts when requesting passwords:
"New UNIX password: " and "Retype UNIX password: ".
The example word <emphasis>UNIX</emphasis> can
be replaced with this item, by default it is empty.
This item is used by <citerefentry>
<refentrytitle>pam_get_authtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</listitem>
</varlistentry>
</variablelist>

139
doc/man/pam_item_types_std.inc.xml Normal file
View file

@ -0,0 +1,139 @@
<!-- this file is included by pam_set_item and pam_get_item -->
<variablelist xmlns="http://docbook.org/ns/docbook" version="5.0">
<varlistentry>
<term>PAM_SERVICE</term>
<listitem>
<para>
The service name (which identifies that PAM stack that
the PAM functions will use to authenticate the program).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER</term>
<listitem>
<para>
The username of the entity under whose identity service
will be given. That is, following authentication,
<emphasis>PAM_USER</emphasis> identifies the local entity
that gets to use the service. Note, this value can be mapped
from something (eg., "anonymous") to something else (eg.
"guest119") by any module in the PAM stack. As such an
application should consult the value of
<emphasis>PAM_USER</emphasis> after each call to a PAM function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_PROMPT</term>
<listitem>
<para>
The string used when prompting for a user's name. The default
value for this string is a localized version of "login: ".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_TTY</term>
<listitem>
<para>
The terminal name prefixed by <filename>/dev/</filename> for
device files.
In the past, graphical X-based applications used to store the
<emphasis>$DISPLAY</emphasis> variable here, but with the
introduction of <emphasis>PAM_XDISPLAY</emphasis> this usage
is deprecated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_RUSER</term>
<listitem>
<para>
The requesting user name: local name for a locally
requesting user or a remote user name for a remote
requesting user.
</para>
<para>
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.
</para>
<para>
<emphasis>PAM_RUSER@PAM_RHOST</emphasis> should always identify
the requesting user. In some cases,
<emphasis>PAM_RUSER</emphasis> may be NULL. In such situations,
it is unclear who the requesting entity is.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_RHOST</term>
<listitem>
<para>
The requesting hostname (the hostname of the machine from
which the <emphasis>PAM_RUSER</emphasis> entity is requesting
service). That is <emphasis>PAM_RUSER@PAM_RHOST</emphasis>
does identify the requesting user. In some applications,
<emphasis>PAM_RHOST</emphasis> may be NULL. In such situations,
it is unclear where the authentication request is originating
from.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK</term>
<listitem>
<para>
The authentication token (often a password). This token
should be ignored by all module functions besides
<citerefentry>
<refentrytitle>pam_sm_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and
<citerefentry>
<refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
In the former function it is used to pass the most recent
authentication token from one stacked module to another. In
the latter function the token is used for another purpose.
It contains the currently active authentication token.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_OLDAUTHTOK</term>
<listitem>
<para>
The old authentication token. This token should be ignored
by all module functions except
<citerefentry>
<refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CONV</term>
<listitem>
<para>
The pam_conv structure. See
<citerefentry>
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</listitem>
</varlistentry>
</variablelist>

60
doc/man/pam_misc_drop_env.3.xml Normal file
View file

@ -0,0 +1,60 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_misc_drop_env">
<refmeta>
<refentrytitle>pam_misc_drop_env</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_misc_drop_env-name">
<refname>pam_misc_drop_env</refname>
<refpurpose>liberating a locally saved environment</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_misc_drop_env-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_misc.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_misc_drop_env</function></funcdef>
<paramdef>char **<parameter>env</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_misc_drop_env-description">
<title>DESCRIPTION</title>
<para>
This function is defined to complement the <citerefentry>
<refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> function. It liberates the memory associated
with <parameter>env</parameter>, <emphasis>overwriting</emphasis>
with <emphasis>0</emphasis> all memory before
<function>free()</function>ing it.
</para>
</refsect1>
<refsect1 xml:id="pam_misc_drop_env-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam_misc_drop_env-standards">
<title>STANDARDS</title>
<para>
The <function>pam_misc_drop_env</function> function is part of the
<command>libpam_misc</command> Library and not defined in any
standard.
</para>
</refsect1>
</refentry>

58
doc/man/pam_misc_paste_env.3.xml Normal file
View file

@ -0,0 +1,58 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_misc_paste_env">
<refmeta>
<refentrytitle>pam_misc_paste_env</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_misc_paste_env-name">
<refname>pam_misc_paste_env</refname>
<refpurpose>transcribing an environment to that of PAM</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_misc_paste_env-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_misc.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_misc_paste_env</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char * const *<parameter>user</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_misc_paste_env-description">
<title>DESCRIPTION</title>
<para>
This function takes the supplied list of environment pointers and
<emphasis>uploads</emphasis> its contents to the PAM environment.
Success is indicated by <errorname>PAM_SUCCESS</errorname>.
</para>
</refsect1>
<refsect1 xml:id="pam_misc_paste_env-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam_misc_paste_env-standards">
<title>STANDARDS</title>
<para>
The <function>pam_misc_paste_env</function> function is part of the
<command>libpam_misc</command> Library and not defined in any
standard.
</para>
</refsect1>
</refentry>

65
doc/man/pam_misc_setenv.3.xml Normal file
View file

@ -0,0 +1,65 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_misc_setenv">
<refmeta>
<refentrytitle>pam_misc_setenv</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_misc_setenv-name">
<refname>pam_misc_setenv</refname>
<refpurpose>BSD like PAM environment variable setting</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_misc_setenv-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_misc.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_misc_setenv</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>const char *<parameter>value</parameter></paramdef>
<paramdef>int <parameter>readonly</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_misc_setenv-description">
<title>DESCRIPTION</title>
<para>
This function performs a task equivalent to <citerefentry>
<refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, its syntax is, however, more like the BSD style
function; <function>setenv()</function>. The <parameter>name</parameter>
and <parameter>value</parameter> are concatenated with an '=' to
form a name=value and passed to <function>pam_putenv()</function>.
If, however, the PAM variable is already set, the replacement will
only be applied if the last argument, <parameter>readonly</parameter>,
is zero.
</para>
</refsect1>
<refsect1 xml:id="pam_misc_setenv-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam_misc_setenv-standards">
<title>STANDARDS</title>
<para>
The <function>pam_misc_setenv</function> function is part of the
<command>libpam_misc</command> Library and not defined in any
standard.
</para>
</refsect1>
</refentry>

112
doc/man/pam_open_session.3.xml Normal file
View file

@ -0,0 +1,112 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_send">
<refmeta>
<refentrytitle>pam_open_session</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_open_session-name">
<refname>pam_open_session</refname>
<refpurpose>start PAM session management</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_open_session-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_open_session</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_open_session-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_open_session</function> function sets up a
user session for a previously successful authenticated user.
The session should later be terminated with a call to
<citerefentry>
<refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<para>
It should be noted that the effective uid,
<citerefentry>
<refentrytitle>geteuid</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>, of the application should be of sufficient
privilege to perform such tasks as creating or mounting the
user's home directory for example.
</para>
<para>
The flags argument is the binary or of zero or more of the
following values:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_open_session-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_ABORT</term>
<listitem>
<para>
General failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SESSION_ERR</term>
<listitem>
<para>
Session failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Session was successful created.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_open_session-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

111
doc/man/pam_prompt.3.xml Normal file
View file

@ -0,0 +1,111 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_prompt">
<refmeta>
<refentrytitle>pam_prompt</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_prompt-name">
<refname>pam_prompt</refname>
<refname>pam_vprompt</refname>
<refpurpose>interface to conversation function</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv xml:id="pam_prompt-synopsis">
<funcsynopsis>
<funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_prompt</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>style</parameter></paramdef>
<paramdef>char **<parameter>response</parameter></paramdef>
<paramdef>const char *<parameter>fmt</parameter></paramdef>
<paramdef><parameter>...</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>pam_vprompt</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>style</parameter></paramdef>
<paramdef>char **<parameter>response</parameter></paramdef>
<paramdef>const char *<parameter>fmt</parameter></paramdef>
<paramdef>va_list <parameter>args</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_prompt-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_prompt</function> function constructs a message
from the specified format string and arguments and passes it to the
conversation function as set by the service. Upon successful return,
<emphasis>response</emphasis> is set to point to a string
returned from the conversation function. This string is allocated
on heap and should be freed.
</para>
</refsect1>
<refsect1 xml:id="pam_prompt-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CONV_ERR</term>
<listitem>
<para>
Conversation failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Conversation succeeded, response is set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
System error.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_prompt-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam_prompt-standards">
<title>STANDARDS</title>
<para>
The <function>pam_prompt</function> and <function>pam_vprompt</function>
functions are Linux-PAM extensions.
</para>
</refsect1>
</refentry>

150
doc/man/pam_putenv.3.xml Normal file
View file

@ -0,0 +1,150 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_putenv">
<refmeta>
<refentrytitle>pam_putenv</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_putenv-name">
<refname>pam_putenv</refname>
<refpurpose>set or change PAM environment variable</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_putenv-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_putenv</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>name_value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_putenv-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_putenv</function> function is used to
add or change the value of PAM environment variables as
associated with the <emphasis>pamh</emphasis> handle.
</para>
<para>
The <emphasis>pamh</emphasis> argument is an authentication
handle obtained by a prior call to pam_start().
The <emphasis>name_value</emphasis> argument is a single NUL
terminated string of one of the following forms:
</para>
<variablelist>
<varlistentry>
<term>NAME=value of variable</term>
<listitem>
<para>
In this case the environment variable of the given NAME
is set to the indicated value:
<emphasis>value of variable</emphasis>. If this variable
is already known, it is overwritten. Otherwise it is added
to the PAM environment.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NAME=</term>
<listitem>
<para>
This function sets the variable to an empty value. It is
listed separately to indicate that this is the correct way
to achieve such a setting.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NAME</term>
<listitem>
<para>
Without an '=' the <function>pam_putenv</function>() function
will delete the
corresponding variable from the PAM environment.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<function>pam_putenv</function>() operates on a copy of
<emphasis>name_value</emphasis>, which means in contrast to
<citerefentry>
<refentrytitle>putenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>, the application is responsible for freeing the data.
</para>
</refsect1>
<refsect1 xml:id="pam_putenv-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_PERM_DENIED</term>
<listitem>
<para>
Argument <emphasis>name_value</emphasis> given is a NULL pointer.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BAD_ITEM</term>
<listitem>
<para>
Variable requested (for deletion) is not currently set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_ABORT</term>
<listitem>
<para>
The <emphasis>pamh</emphasis> handle is corrupt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The environment variable was successfully updated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_putenv-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_getenv</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

175
doc/man/pam_set_data.3.xml Normal file
View file

@ -0,0 +1,175 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_set_data">
<refmeta>
<refentrytitle>pam_set_data</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_set_data-name">
<refname>pam_set_data</refname>
<refpurpose>
set module internal data
</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_set_data-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_set_data</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>module_data_name</parameter></paramdef>
<paramdef>void *<parameter>data</parameter></paramdef>
<paramdef>void <parameter>(*cleanup)(pam_handle_t *pamh, void *data, int error_status)</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_set_data-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_set_data</function> function associates a pointer
to an object with the (hopefully) unique string
<emphasis>module_data_name</emphasis> in the PAM context specified
by the <emphasis>pamh</emphasis> argument.
</para>
<para>
PAM modules may be dynamically loadable objects. In general such files
should not contain <emphasis>static</emphasis> variables. This function
and its counterpart
<citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
provide a mechanism for a module to associate some data with
the handle <emphasis>pamh</emphasis>. Typically a module will call the
<function>pam_set_data</function> function to register some data
under a (hopefully) unique <emphasis>module_data_name</emphasis>.
The data is available for use by other modules too but
<emphasis>not</emphasis> by an application. Since this functions
stores only a pointer to the <emphasis>data</emphasis>, the module
should not modify or free the content of it.
</para>
<para>
The function <function>cleanup()</function> is associated with the
<emphasis>data</emphasis> and, if non-NULL, it is called when this
data is over-written or following a call to
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<para>
The <emphasis>error_status</emphasis> argument is used to indicate
to the module the sort of action it is to take in cleaning this data
item. As an example, Kerberos creates a ticket file during the
authentication phase, this file might be associated with a data item.
When
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
is called by the module, the <emphasis>error_status</emphasis>
carries the return value of the
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
or other <emphasis>libpam</emphasis> function as appropriate. Based
on this value the Kerberos module may choose to delete the ticket file
(<emphasis>authentication failure</emphasis>) or leave it in place.
</para>
<para>
The <emphasis>error_status</emphasis> may have been logically
OR'd with either of the following two values:
</para>
<variablelist>
<varlistentry>
<term>PAM_DATA_REPLACE</term>
<listitem>
<para>
When a data item is being replaced (through a second call to
<function>pam_set_data</function>) this mask is used.
Otherwise, the call is assumed to be from
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_DATA_SILENT</term>
<listitem>
<para>
Which indicates that the process would prefer to perform the
<function>cleanup()</function> quietly. That is, discourages
logging/messages to the user. It is generally used to indicate that
the current closing of the library is in a
<citerefentry>
<refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>ed
process, and that the parent will take care of cleaning up things
that exist outside of the current process space (files etc.).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_set_data-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Data was successful stored.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
A NULL pointer was submitted as PAM handle or the
function was called by an application.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_set_data-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

125
doc/man/pam_set_item.3.xml Normal file
View file

@ -0,0 +1,125 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_set_item">
<refmeta>
<refentrytitle>pam_set_item</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_set_item-name">
<refname>pam_set_item</refname>
<refpurpose>
set and update PAM information
</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_set_item-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_set_item</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>item_type</parameter></paramdef>
<paramdef>const void *<parameter>item</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_set_item-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_set_item</function> function allows applications
and PAM service modules to access and to update PAM information
of <emphasis>item_type</emphasis>. For this a copy
of the object pointed to by the <emphasis>item</emphasis> argument
is created. The following <emphasis>item_type</emphasis>s are
supported:
</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_item_types_std.inc.xml"/>
<para>
The following additional items are specific to Linux-PAM and should not be used in
portable applications:
</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_item_types_ext.inc.xml"/>
<para>
For all <emphasis>item_type</emphasis>s, other than PAM_CONV and
PAM_FAIL_DELAY, <emphasis>item</emphasis> is a pointer to a &lt;NUL&gt;
terminated character string. In the case of PAM_CONV,
<emphasis>item</emphasis> points to an initialized
<emphasis>pam_conv</emphasis> structure. In the case of
PAM_FAIL_DELAY, <emphasis>item</emphasis> is a function pointer:
<function>void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)</function>
</para>
<para>
Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reset before
returning to the application. Which means an application is not
able to access the authentication tokens.
</para>
</refsect1>
<refsect1 xml:id="pam_set_item-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_BAD_ITEM</term>
<listitem>
<para>
The application attempted to set an undefined or inaccessible
item.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Data was successful updated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
The <emphasis>pam_handle_t</emphasis> passed as first
argument was invalid.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_set_item-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

177
doc/man/pam_setcred.3.xml Normal file
View file

@ -0,0 +1,177 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_setcred">
<refmeta>
<refentrytitle>pam_setcred</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_setcred-name">
<refname>pam_setcred</refname>
<refpurpose>
establish / delete user credentials
</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_setcred-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_setcred</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_setcred-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_setcred</function> function is used to establish,
maintain and delete the credentials of a user. It should be called
to set the credentials after a user has been authenticated and before
a session is opened for the user (with
<citerefentry>
<refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>). The credentials should be deleted after the session
has been closed (with
<citerefentry>
<refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>).
</para>
<para>
A credential is something that the user possesses. It is some
property, such as a <emphasis>Kerberos</emphasis> ticket, or a
supplementary group membership that make up the uniqueness of a
given user. On a Linux system the user's <emphasis>UID</emphasis>
and <emphasis>GID</emphasis>'s are credentials too. However, it
has been decided that these properties (along with the default
supplementary groups of which the user is a member) are credentials
that should be set directly by the application and not by PAM.
Such credentials should be established, by the application, prior
to a call to this function. For example,
<citerefentry>
<refentrytitle>initgroups</refentrytitle><manvolnum>2</manvolnum>
</citerefentry> (or equivalent) should have been performed.
</para>
<para>
Valid <emphasis>flags</emphasis>, any one of which, may be
logically OR'd with <option>PAM_SILENT</option>, are:
</para>
<variablelist>
<varlistentry>
<term>PAM_ESTABLISH_CRED</term>
<listitem>
<para>Initialize the credentials for the user.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_DELETE_CRED</term>
<listitem>
<para>Delete the user's credentials.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_REINITIALIZE_CRED</term>
<listitem>
<para>Fully reinitialize the user's credentials.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_REFRESH_CRED</term>
<listitem>
<para>Extend the lifetime of the existing credentials.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_setcred-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_ERR</term>
<listitem>
<para>
Failed to set user credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_EXPIRED</term>
<listitem>
<para>
User credentials are expired.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_UNAVAIL</term>
<listitem>
<para>
Failed to retrieve user credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Data was successful stored.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
A NULL pointer was submitted as PAM handle, the
function was called by a module or another system
error occurred.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_UNKNOWN</term>
<listitem>
<para>
User is not known to an authentication module.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_set_data-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

152
doc/man/pam_sm_acct_mgmt.3.xml Normal file
View file

@ -0,0 +1,152 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_sm_acct_mgmt">
<refmeta>
<refentrytitle>pam_sm_acct_mgmt</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_sm_acct_mgmt-name">
<refname>pam_sm_acct_mgmt</refname>
<refpurpose>PAM service function for account management</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_sm_acct_mgmt-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_sm_acct_mgmt</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int <parameter>argc</parameter></paramdef>
<paramdef>const char **<parameter>argv</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_sm_acct_mgmt-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_sm_acct_mgmt</function> function is the service
module's implementation of the
<citerefentry>
<refentrytitle>pam_acct_mgmt</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> interface.
</para>
<para>
This function performs the task of establishing whether the user is
permitted to gain access at this time. It should be understood that
the user has previously been validated by an authentication
module. This function checks for other things. Such things might be:
the time of day or the date, the terminal line, remote hostname, etc.
This function may also determine things like the expiration on
passwords, and respond that the user change it before continuing.
</para>
<para>
Valid flags, which may be logically OR'd with
<emphasis>PAM_SILENT</emphasis>, are:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_DISALLOW_NULL_AUTHTOK</term>
<listitem>
<para>
Return <emphasis remap="B">PAM_AUTH_ERR</emphasis> if the
database of authentication tokens for this authentication
mechanism has a <emphasis>NULL</emphasis> entry for the user.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_sm_acct_mgmt-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_ACCT_EXPIRED</term>
<listitem>
<para>
User account has expired.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTH_ERR</term>
<listitem>
<para>
Authentication failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_NEW_AUTHTOK_REQD</term>
<listitem>
<para>
The user's authentication token has expired. Before calling
this function again the application will arrange for a new
one to be given. This will likely result in a call to
<function>pam_sm_chauthtok()</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_PERM_DENIED</term>
<listitem>
<para>
Permission denied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The authentication token was successfully updated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_UNKNOWN</term>
<listitem>
<para>
User unknown to password service.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_sm_acct_mgmt-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_acct_mgmt</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

149
doc/man/pam_sm_authenticate.3.xml Normal file
View file

@ -0,0 +1,149 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_sm_authenticate">
<refmeta>
<refentrytitle>pam_sm_authenticate</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_sm_authenticate-name">
<refname>pam_sm_authenticate</refname>
<refpurpose>PAM service function for user authentication</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_sm_authenticate-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_sm_authenticate</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int <parameter>argc</parameter></paramdef>
<paramdef>const char **<parameter>argv</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_sm_authenticate-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_sm_authenticate</function> function is the service
module's implementation of the
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> interface.
</para>
<para>
This function performs the task of authenticating the user.
</para>
<para>
Valid flags, which may be logically OR'd with
<emphasis>PAM_SILENT</emphasis>, are:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_DISALLOW_NULL_AUTHTOK</term>
<listitem>
<para>
Return <emphasis remap="B">PAM_AUTH_ERR</emphasis> if the
database of authentication tokens for this authentication
mechanism has a <emphasis>NULL</emphasis> entry for the user.
Without this flag, such a <emphasis>NULL</emphasis> token
will lead to a success without the user being prompted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_sm_authenticate-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_AUTH_ERR</term>
<listitem>
<para>
Authentication failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_INSUFFICIENT</term>
<listitem>
<para>
For some reason the application does not have sufficient
credentials to authenticate the user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHINFO_UNAVAIL</term>
<listitem>
<para>
The modules were not able to access the authentication
information. This might be due to a network or hardware
failure etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The authentication token was successfully updated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_UNKNOWN</term>
<listitem>
<para>
The supplied username is not known to the authentication
service.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_MAXTRIES</term>
<listitem>
<para>
One or more of the authentication modules has reached its
limit of tries authenticating the user. Do not try again.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_sm_authenticate-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_sm_setcred</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

202
doc/man/pam_sm_chauthtok.3.xml Normal file
View file

@ -0,0 +1,202 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_sm_chauthtok">
<refmeta>
<refentrytitle>pam_sm_chauthtok</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_sm_chauthtok-name">
<refname>pam_sm_chauthtok</refname>
<refpurpose>PAM service function for authentication token management</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_sm_chauthtok-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_sm_chauthtok</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int <parameter>argc</parameter></paramdef>
<paramdef>const char **<parameter>argv</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_sm_chauthtok-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_sm_chauthtok</function> function is the service
module's implementation of the
<citerefentry>
<refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> interface.
</para>
<para>
This function is used to (re-)set the authentication token of the user.
</para>
<para>
Valid flags, which may be logically OR'd with
<emphasis>PAM_SILENT</emphasis>, are:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CHANGE_EXPIRED_AUTHTOK</term>
<listitem>
<para>
This argument indicates to the module that the user's
authentication token (password) should only be changed if
it has expired. This flag is optional and
<emphasis>must</emphasis> be combined with one of the
following two flags. Note, however, the following two options
are <emphasis>mutually exclusive</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_PRELIM_CHECK</term>
<listitem>
<para>
This indicates that the modules are being probed as to
their ready status for altering the user's authentication
token. If the module requires access to another system over
some network it should attempt to verify it can connect to
this system on receiving this flag. If a module cannot establish
it is ready to update the user's authentication token it should
return <emphasis remap="B">PAM_TRY_AGAIN</emphasis>, this
information will be passed back to the application.
</para>
<para>
If the control value <emphasis>sufficient</emphasis> is used in
the password stack, the <emphasis>PAM_PRELIM_CHECK</emphasis> section
of the modules following that control value is not always executed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_UPDATE_AUTHTOK</term>
<listitem>
<para>
This informs the module that this is the call it should change
the authorization tokens. If the flag is logically OR'd with
<emphasis remap="B">PAM_CHANGE_EXPIRED_AUTHTOK</emphasis>, the
token is only changed if it has actually expired.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The PAM library calls this function twice in succession. The first
time with <emphasis remap="B">PAM_PRELIM_CHECK</emphasis> and then,
if the module does not return
<emphasis remap="B">PAM_TRY_AGAIN</emphasis>, subsequently with
<emphasis remap="B">PAM_UPDATE_AUTHTOK</emphasis>. It is only on
the second call that the authorization token is (possibly) changed.
</para>
</refsect1>
<refsect1 xml:id="pam_sm_chauthtok-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_AUTHTOK_ERR</term>
<listitem>
<para>
The module was unable to obtain the new authentication token.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_RECOVERY_ERR</term>
<listitem>
<para>
The module was unable to obtain the old authentication token.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_LOCK_BUSY</term>
<listitem>
<para>
Cannot change the authentication token since it is currently
locked.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_AUTHTOK_DISABLE_AGING</term>
<listitem>
<para>
Authentication token aging has been disabled.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_PERM_DENIED</term>
<listitem>
<para>
Permission denied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_TRY_AGAIN</term>
<listitem>
<para>
Preliminary check was unsuccessful. Signals an immediate
return to the application is desired.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The authentication token was successfully updated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_UNKNOWN</term>
<listitem>
<para>
User unknown to password service.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_sm_chauthtok-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

97
doc/man/pam_sm_close_session.3.xml Normal file
View file

@ -0,0 +1,97 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_sm_close_session">
<refmeta>
<refentrytitle>pam_sm_close_session</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_sm_close_session-name">
<refname>pam_sm_close_session</refname>
<refpurpose>PAM service function to terminate session management</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_sm_close_session-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_sm_close_session</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int <parameter>argc</parameter></paramdef>
<paramdef>const char **<parameter>argv</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_sm_close_session-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_sm_close_session</function> function is the service
module's implementation of the
<citerefentry>
<refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> interface.
</para>
<para>
This function is called to terminate a session. The only valid
value for <varname role="parameter">flags</varname> is zero or:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_sm_close_session-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_SESSION_ERR</term>
<listitem>
<para>
Cannot make/remove an entry for the specified session.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The session was successfully terminated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_sm_close_session-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_sm_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

97
doc/man/pam_sm_open_session.3.xml Normal file
View file

@ -0,0 +1,97 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_sm_open_session">
<refmeta>
<refentrytitle>pam_sm_open_session</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_sm_open_session-name">
<refname>pam_sm_open_session</refname>
<refpurpose>PAM service function to start session management</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_sm_open_session-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_sm_open_session</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int <parameter>argc</parameter></paramdef>
<paramdef>const char **<parameter>argv</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_sm_open_session-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_sm_open_session</function> function is the service
module's implementation of the
<citerefentry>
<refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> interface.
</para>
<para>
This function is called to commence a session. The only valid
value for <varname role="parameter">flags</varname> is zero or:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_sm_open_session-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_SESSION_ERR</term>
<listitem>
<para>
Cannot make/remove an entry for the specified session.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The session was successfully started.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_sm_open_session-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_sm_close_session</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

182
doc/man/pam_sm_setcred.3.xml Normal file
View file

@ -0,0 +1,182 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_sm_setcred">
<refmeta>
<refentrytitle>pam_sm_setcred</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_sm_setcred-name">
<refname>pam_sm_setcred</refname>
<refpurpose>PAM service function to alter credentials</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_sm_setcred-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_sm_setcred</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
<paramdef>int <parameter>argc</parameter></paramdef>
<paramdef>const char **<parameter>argv</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_sm_setcred-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_sm_setcred</function> function is the service
module's implementation of the
<citerefentry>
<refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> interface.
</para>
<para>
This function performs the task of altering the credentials of the
user with respect to the corresponding authorization
scheme. Generally, an authentication module may have access to more
information about a user than their authentication token. This
function is used to make such information available to the
application. It should only be called <emphasis>after</emphasis> the
user has been authenticated but before a session has been established.
</para>
<para>
Valid flags, which may be logically OR'd with
<emphasis>PAM_SILENT</emphasis>, are:
</para>
<variablelist>
<varlistentry>
<term>PAM_SILENT</term>
<listitem>
<para>
Do not emit any messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_ESTABLISH_CRED</term>
<listitem>
<para>Initialize the credentials for the user.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_DELETE_CRED</term>
<listitem>
<para>
Delete the credentials associated with the authentication service.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_REINITIALIZE_CRED</term>
<listitem>
<para>
Reinitialize the user credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_REFRESH_CRED</term>
<listitem>
<para>
Extend the lifetime of the user credentials.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The way the <emphasis remap="B">auth</emphasis> stack is
navigated in order to evaluate the <function>pam_setcred</function>()
function call, independent of the <function>pam_sm_setcred</function>()
return codes, is exactly the same way that it was navigated when
evaluating the <function>pam_authenticate</function>() library
call. Typically, if a stack entry was ignored in evaluating
<function>pam_authenticate</function>(), it will be ignored when
libpam evaluates the <function>pam_setcred</function>() function
call. Otherwise, the return codes from each module specific
<function>pam_sm_setcred</function>() call are treated as
<emphasis remap="B">required</emphasis>.
</para>
</refsect1>
<refsect1 xml:id="pam_sm_setcred-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_CRED_UNAVAIL</term>
<listitem>
<para>
This module cannot retrieve the user's credentials.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_EXPIRED</term>
<listitem>
<para>
The user's credentials have expired.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_CRED_ERR</term>
<listitem>
<para>
This module was unable to set the credentials of the user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
The user credential was successfully set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_USER_UNKNOWN</term>
<listitem>
<para>
The user is not known to this authentication module.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
These, non-<emphasis>PAM_SUCCESS</emphasis>, return values will
typically lead to the credential stack <emphasis>failing</emphasis>.
The first such error will dominate in the return value of
<function>pam_setcred</function>().
</para>
</refsect1>
<refsect1 xml:id="pam_sm_setcred-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_sm_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

164
doc/man/pam_start.3.xml Normal file
View file

@ -0,0 +1,164 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_start">
<refmeta>
<refentrytitle>pam_start</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_start-name">
<refname>pam_start</refname>
<refname>pam_start_confdir</refname>
<refpurpose>initialization of PAM transaction</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_start-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_start</function></funcdef>
<paramdef>const char *<parameter>service_name</parameter></paramdef>
<paramdef>const char *<parameter>user</parameter></paramdef>
<paramdef>const struct pam_conv *<parameter>pam_conversation</parameter></paramdef>
<paramdef>pam_handle_t **<parameter>pamh</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>pam_start_confdir</function></funcdef>
<paramdef>const char *<parameter>service_name</parameter></paramdef>
<paramdef>const char *<parameter>user</parameter></paramdef>
<paramdef>const struct pam_conv *<parameter>pam_conversation</parameter></paramdef>
<paramdef>const char *<parameter>confdir</parameter></paramdef>
<paramdef>pam_handle_t **<parameter>pamh</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_start-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_start</function> function creates the PAM context
and initiates the PAM transaction. It is the first of the PAM
functions that needs to be called by an application. The transaction
state is contained entirely within the structure identified by this
handle, so it is possible to have multiple transactions in parallel.
But it is not possible to use the same handle for different
transactions, a new one is needed for every new context.
</para>
<para>
The <emphasis>service_name</emphasis> argument specifies the name
of the service to apply and will be stored as PAM_SERVICE item in
the new context. The policy for the service will be read from the
file <filename>/etc/pam.d/service_name</filename> or, if that file
does not exist, from <filename>/etc/pam.conf</filename>.
</para>
<para>
The <emphasis>user</emphasis> argument can specify the name
of the target user and will be stored as PAM_USER item. If
the argument is NULL, the module has to ask for this item if
necessary.
</para>
<para>
The <emphasis>pam_conversation</emphasis> argument points to
a <emphasis>struct pam_conv</emphasis> describing the
conversation function to use. An application must provide this
for direct communication between a loaded module and the
application.
</para>
<para>
Following a successful return (PAM_SUCCESS) the contents of
<emphasis>pamh</emphasis> is a handle that contains the PAM
context for successive calls to the PAM functions. In an error
case is the content of <emphasis>pamh</emphasis> undefined.
</para>
<para>
The <emphasis>pam_handle_t</emphasis> is a blind structure and
the application should not attempt to probe it directly for
information. Instead the PAM library provides the functions
<citerefentry>
<refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
The PAM handle cannot be used for multiple authentications at the
same time as long as <function>pam_end</function> was not called on
it before.
</para>
<para>
The <function>pam_start_confdir</function> function behaves
like the <function>pam_start</function> function but it also
allows setting <emphasis>confdir</emphasis> argument with
a path to a directory to override the default
(<filename>/etc/pam.d</filename>) path for service policy
files. If the <emphasis>confdir</emphasis> is NULL, the function
works exactly the same as <function>pam_start</function>.
</para>
</refsect1>
<refsect1 xml:id="pam_start-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_ABORT</term>
<listitem>
<para>
General failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Transaction was successfully started.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
System error, for example a NULL pointer was submitted
instead of a pointer to data.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="pam_start-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

55
doc/man/pam_strerror.3.xml Normal file
View file

@ -0,0 +1,55 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_strerror">
<refmeta>
<refentrytitle>pam_strerror</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_strerror-name">
<refname>pam_strerror</refname>
<refpurpose>return string describing PAM error code</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_strerror-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>const char *<function>pam_strerror</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>errnum</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_strerror-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_strerror</function> function returns a pointer to
a string describing the error code passed in the argument
<emphasis>errnum</emphasis>, possibly using the LC_MESSAGES part of
the current locale to select the appropriate language. This string
must not be modified by the application. No library function will
modify this string.
</para>
</refsect1>
<refsect1 xml:id="pam_strerror-return_values">
<title>RETURN VALUES</title>
<para>
This function returns always a pointer to a string.
</para>
</refsect1>
<refsect1 xml:id="pam_strerror-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

79
doc/man/pam_syslog.3.xml Normal file
View file

@ -0,0 +1,79 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_syslog">
<refmeta>
<refentrytitle>pam_syslog</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_syslog-name">
<refname>pam_syslog</refname>
<refname>pam_vsyslog</refname>
<refpurpose>send messages to the system logger</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv xml:id="pam_syslog-synopsis">
<funcsynopsis>
<funcsynopsisinfo>#include &lt;syslog.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;security/pam_ext.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>pam_syslog</function></funcdef>
<paramdef>const pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>priority</parameter></paramdef>
<paramdef>const char *<parameter>fmt</parameter></paramdef>
<paramdef><parameter>...</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>pam_vsyslog</function></funcdef>
<paramdef>const pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>int <parameter>priority</parameter></paramdef>
<paramdef>const char *<parameter>fmt</parameter></paramdef>
<paramdef>va_list <parameter>args</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="pam_syslog-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_syslog</function> function logs messages using
<citerefentry>
<refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> and is intended for internal use by Linux-PAM and
PAM service modules. The <emphasis>priority</emphasis> argument is
formed by ORing the facility and the level values as documented
in the <citerefentry>
<refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> manual page.
</para>
<para>
The <function>pam_vsyslog</function> function performs the same
task as <function>pam_syslog()</function> with the difference
that it takes a set of arguments which have been obtained using
the <citerefentry>
<refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> variable argument list macros.
</para>
</refsect1>
<refsect1 xml:id="pam_syslog-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1 xml:id="pam_syslog-standards">
<title>STANDARDS</title>
<para>
The <function>pam_syslog</function> and <function>pam_vsyslog</function>
functions are Linux-PAM extensions.
</para>
</refsect1>
</refentry>

91
doc/man/pam_xauth_data.3.xml Normal file
View file

@ -0,0 +1,91 @@
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_xauth_data">
<refmeta>
<refentrytitle>pam_xauth_data</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class="source">Linux-PAM</refmiscinfo>
<refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv xml:id="pam_xauth_data-name">
<refname>pam_xauth_data</refname>
<refpurpose>structure containing X authentication data</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis xml:id="pam_xauth_data-synopsis">
<funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
</funcsynopsis>
<programlisting>
struct pam_xauth_data {
int namelen;
char *name;
int datalen;
char *data;
};
</programlisting>
</refsynopsisdiv>
<refsect1 xml:id="pam_xauth_data-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_xauth_data</function> structure contains X
authentication data used to make a connection to an X display.
Using this mechanism, an application can communicate X
authentication data to PAM service modules. This allows modules to
make a connection to the user's X display in order to label the
user's session on login, display visual feedback or for other
purposes.
</para>
<para>
The <emphasis>name</emphasis> field contains the name of the
authentication method, such as "MIT-MAGIC-COOKIE-1". The
<emphasis>namelen</emphasis> field contains the length of this string,
not including the trailing NUL character.
</para>
<para>
The <emphasis>data</emphasis> field contains the authentication
method-specific data corresponding to the specified name. The
<emphasis>datalen</emphasis> field contains its length in bytes.
</para>
<para>
The X authentication data can be changed with the
<emphasis>PAM_XAUTH_DATA</emphasis> item. It can be queried and
set with
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
and
<citerefentry>
<refentrytitle>pam_set_item </refentrytitle><manvolnum>3</manvolnum>
</citerefentry> respectively. The value used to set it should be
a pointer to a pam_xauth_data structure. An internal copy of both
the structure itself and its fields is made by PAM when setting the
item.
</para>
</refsect1>
<refsect1 xml:id="pam_xauth_data-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
</para>
</refsect1>
<refsect1 xml:id="pam_xauth_data-standards">
<title>STANDARDS</title>
<para>
The <function>pam_xauth_data</function> structure and
<emphasis>PAM_XAUTH_DATA</emphasis> item are
Linux-PAM extensions.
</para>
</refsect1>
</refentry>

26
doc/meson.build Normal file
View file

@ -0,0 +1,26 @@
custom_man_xsl = custom_target(
'custom-man.xsl',
input: 'custom-man.xsl.in',
output: ['custom-man.xsl'],
command: [
redir_exe,
'@INPUT@',
'@OUTPUT@',
'sed',
's+MAN_STYLESHEET+' + man_stylesheet + '+g'
]
)
install_data(
'index.html',
install_dir: htmldir,
install_tag: 'doc',
)
install_html = files('install-html.sh')
subdir('man')
subdir('specs')
subdir('sag')
subdir('adg')
subdir('mwg')

604
doc/mwg/Linux-PAM_MWG.xml Normal file
View file

@ -0,0 +1,604 @@
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="mwg">
<info>
<title>The Linux-PAM Module Writers' Guide</title>
<authorgroup>
<author><personname><firstname>Andrew G.</firstname><surname>Morgan</surname></personname><email>morgan@kernel.org</email></author>
<author><personname><firstname>Thorsten</firstname><surname>Kukuk</surname></personname><email>kukuk@thkukuk.de</email></author>
</authorgroup>
<releaseinfo>Version 1.1.2, 31. August 2010</releaseinfo>
<abstract>
<para>
This manual documents what a programmer needs to know in order
to write a module that conforms to the
<emphasis remap="B">Linux-PAM</emphasis> standard.It also
discusses some security issues from the point of view of the
module programmer.
</para>
</abstract>
</info>
<chapter xml:id="mwg-introduction">
<title>Introduction</title>
<section xml:id="mwg-introduction-description">
<title>Description</title>
<para>
<emphasis remap="B">Linux-PAM</emphasis> (Pluggable Authentication
Modules for Linux) is a library that enables the local system
administrator to choose how individual applications authenticate
users. For an overview of the
<emphasis remap="B">Linux-PAM</emphasis> library see the
<emphasis>Linux-PAM System Administrators' Guide</emphasis>.
</para>
<para>
A <emphasis remap="B">Linux-PAM</emphasis> module is a single
executable binary file that can be loaded by the
<emphasis remap="B">Linux-PAM</emphasis> interface library.
This PAM library is configured locally with a system file,
<filename>/etc/pam.conf</filename>, to authenticate a user
request via the locally available authentication modules. The
modules themselves will usually be located in the directory
<filename>/lib/security</filename> (or
<filename>/lib64/security</filename>, depending on the architecture)
and take the form of dynamically loadable object files (see
<citerefentry>
<refentrytitle>dlopen</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>. Alternatively, the modules can be statically
linked into the <emphasis remap="B">Linux-PAM</emphasis> library;
this is mostly to allow <emphasis remap="B">Linux-PAM</emphasis> to
be used on platforms without dynamic linking available, but this is
a <emphasis>deprecated</emphasis> functionality. It is the
<emphasis remap="B">Linux-PAM</emphasis> interface that is called
by an application and it is the responsibility of the library to
locate, load and call the appropriate functions in a
<emphasis remap="B">Linux-PAM</emphasis>-module.
</para>
<para>
Except for the immediate purpose of interacting with the user
(entering a password etc..) the module should never call the
application directly. This exception requires a "conversation
mechanism" which is documented below.
</para>
</section>
<section xml:id="mwg-introduction-synopsis">
<title>Synopsis</title>
<programlisting>
#include &lt;security/pam_modules.h&gt;
gcc -fPIC -c pam_module.c
gcc -shared -o pam_module.so pam_module.o -lpam
</programlisting>
</section>
</chapter>
<chapter xml:id="mwg-expected-by-module">
<title>What can be expected by the module</title>
<para>
Here we list the interface that the conventions that all
<emphasis remap="B">Linux-PAM</emphasis> modules must adhere to.
</para>
<section xml:id="mwg-expected-by-module-item">
<title>
Getting and setting <emphasis>PAM_ITEM</emphasis>s and
<emphasis>data</emphasis>
</title>
<para>
First, we cover what the module should expect from the
<emphasis remap="B">Linux-PAM</emphasis> library and a
<emphasis remap="B">Linux-PAM</emphasis> aware application.
Essentially this is the <filename>libpam.*</filename> library.
</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_set_data.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_get_data.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_set_item.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_get_item.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_get_user.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_conv.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_putenv.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_getenv.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_getenvlist.xml"/>
</section>
<section xml:id="mwg-expected-by-module-other">
<title>
Other functions provided by <filename>libpam</filename>
</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_strerror.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_fail_delay.xml"/>
</section>
</chapter>
<chapter xml:id="mwg-expected-of-module">
<title>What is expected of a module</title>
<para>
The module must supply a sub-set of the six functions listed
below. Together they define the function of a
<emphasis remap="B">Linux-PAM module</emphasis>. Module developers
are strongly urged to read the comments on security that follow
this list.
</para>
<section xml:id="mwg-expected-of-module-overview">
<title>Overview</title>
<para>
The six module functions are grouped into four independent
management groups. These groups are as follows:
<emphasis>authentication</emphasis>, <emphasis>account</emphasis>,
<emphasis>session</emphasis> and <emphasis>password</emphasis>.
To be properly defined, a module must define all functions within
at least one of these groups. A single module may contain the
necessary functions for <emphasis>all</emphasis> four groups.
</para>
<section xml:id="mwg-expected-of-module-overview-1">
<title>Functional independence</title>
<para>
The independence of the four groups of service a module can
offer means that the module should allow for the possibility
that any one of these four services may legitimately be called
in any order. Thus, the module writer should consider the
appropriateness of performing a service without the prior
success of some other part of the module.
</para>
<para>
As an informative example, consider the possibility that an
application applies to change a user's authentication token,
without having first requested that
<emphasis remap="B">Linux-PAM</emphasis> authenticate the
user. In some cases this may be deemed appropriate: when
<command>root</command> wants to change the authentication
token of some lesser user. In other cases it may not be
appropriate: when <command>joe</command> maliciously wants
to reset <command>alice</command>'s password; or when anyone
other than the user themself wishes to reset their
<emphasis>KERBEROS</emphasis> authentication token. A policy
for this action should be defined by any reasonable
authentication scheme, the module writer should consider
this when implementing a given module.
</para>
</section>
<section xml:id="mwg-expected-of-module-overview-2">
<title>Minimizing administration problems</title>
<para>
To avoid system administration problems and the poor
construction of a <filename>/etc/pam.conf</filename> file,
the module developer may define all six of the following
functions. For those functions that would not be called,
the module should return <errorname>PAM_SERVICE_ERR</errorname>
and write an appropriate message to the system log. When
this action is deemed inappropriate, the function would
simply return <errorname>PAM_IGNORE</errorname>.
</para>
</section>
<section xml:id="mwg-expected-of-module-overview-3">
<title>Arguments supplied to the module</title>
<para>
The <parameter>flags</parameter> argument of each of
the following functions can be logically OR'd with
<parameter>PAM_SILENT</parameter>, which is used to inform the
module to not pass any <emphasis>text</emphasis> (errors or
warnings) application.
</para>
<para>
The <parameter>argc</parameter> and <parameter>argv</parameter>
arguments are taken from the line appropriate to this
module---that is, with the <emphasis>service_name</emphasis>
matching that of the application---in the configuration file
(see the <emphasis remap="B">Linux-PAM</emphasis>
System Administrators' Guide). Together these two parameters
provide the number of arguments and an array of pointers to
the individual argument tokens. This will be familiar to C
programmers as the ubiquitous method of passing command arguments
to the function <function>main()</function>. Note, however, that
the first argument (<parameter>argv[0]</parameter>) is a true
argument and <emphasis>not</emphasis> the name of the module.
</para>
</section>
</section>
<section xml:id="mwg-expected-of-module-auth">
<title>Authentication management</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_sm_authenticate.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_sm_setcred.xml"/>
</section>
<section xml:id="mwg-expected-of-module-acct">
<title>Account management</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_sm_acct_mgmt.xml"/>
</section>
<section xml:id="mwg-expected-of-module-session">
<title>Session management</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_sm_open_session.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_sm_close_session.xml"/>
</section>
<section xml:id="mwg-expected-of-module-chauthtok">
<title>Authentication token management</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_sm_chauthtok.xml"/>
</section>
</chapter>
<chapter xml:id="mwg-see-options">
<title>Generic optional arguments</title>
<para>
Here we list the generic arguments that all modules can expect to
be passed. They are not mandatory, and their absence should be
accepted without comment by the module.
</para>
<variablelist>
<varlistentry>
<term>debug</term>
<listitem>
<para>
Use the <citerefentry>
<refentrytitle>pam_syslog</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> call to log debugging information to the system
log files.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>use_first_pass</term>
<listitem>
<para>
The module should not prompt the user for a password.
Instead, it should obtain the previously typed password
(by a call to <function>pam_get_item()</function> for the
<parameter>PAM_AUTHTOK</parameter> item), and use that. If
that doesn't work, then the user will not be authenticated.
(This option is intended for <command>auth</command> and
<command>passwd</command> modules only).
</para>
</listitem>
</varlistentry>
</variablelist>
</chapter>
<chapter xml:id="mwg-see-programming">
<title>Programming notes</title>
<para>
Here we collect some pointers for the module writer to bear in mind
when writing/developing a <emphasis remap="B">Linux-PAM</emphasis>
compatible module.
</para>
<section xml:id="mwg-see-programming-sec">
<title>Security issues for module creation</title>
<section xml:id="mwg-see-programming-sec-res">
<title>Sufficient resources</title>
<para>
Care should be taken to ensure that the proper execution
of a module is not compromised by a lack of system resources.
If a module is unable to open sufficient files to perform its
task, it should fail gracefully, or request additional resources.
Specifically, the quantities manipulated by the <citerefentry>
<refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum>
</citerefentry> family of commands should be taken into
consideration.
</para>
</section>
<section xml:id="mwg-see-programming-sec-who">
<title>Who´s who?</title>
<para>
Generally, the module may wish to establish the identity of
the user requesting a service. This may not be the same as
the username returned by <function>pam_get_user()</function>.
Indeed, that is only going to be the name of the user under
whose identity the service will be given. This is not
necessarily the user that requests the service.
</para>
<para>
In other words, user X runs a program that is setuid-Y, it
grants the user to have the permissions of Z. A specific example
of this sort of service request is the <command>su</command>
program: user <command>joe</command> executes
<command>su</command> to become the user <command>jane</command>.
In this situation X=<command>joe</command>, Y=<command>root</command>
and Z=<command>jane</command>. Clearly, it is important that
the module does not confuse these different users and grant an
inappropriate level of privilege.
</para>
<para>
The following is the convention to be adhered to when juggling
user-identities.
</para>
<itemizedlist>
<listitem>
<para>
X, the identity of the user invoking the service request.
This is the user identifier; returned by the function
<citerefentry>
<refentrytitle>getuid</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
</para>
</listitem>
<listitem>
<para>
Y, the privileged identity of the application used to
grant the requested service. This is the
<emphasis>effective</emphasis> user identifier;
returned by the function <citerefentry>
<refentrytitle>geteuid</refentrytitle><manvolnum>2</manvolnum>
</citerefentry>.
</para>
</listitem>
<listitem>
<para>
Z, the user under whose identity the service will be granted.
This is the username returned by
<function>pam_get_user()</function> and also stored in the
<emphasis remap="B">Linux-PAM</emphasis> item,
<emphasis>PAM_USER</emphasis>.
</para>
</listitem>
<listitem>
<para>
<emphasis remap="B">Linux-PAM</emphasis> has a place for
an additional user identity that a module may care to make
use of. This is the <emphasis>PAM_RUSER</emphasis> item.
Generally, network sensitive modules/applications may wish
to set/read this item to establish the identity of the user
requesting a service from a remote location.
</para>
</listitem>
</itemizedlist>
<para>
Note, if a module wishes to modify the identity of either the
<emphasis>uid</emphasis> or <emphasis>euid</emphasis> of the
running process, it should take care to restore the original
values prior to returning control to the
<emphasis remap="B">Linux-PAM</emphasis> library.
</para>
</section>
<section xml:id="mwg-see-programming-sec-conv">
<title>Using the conversation function</title>
<para>
Prior to calling the conversation function, the module should
reset the contents of the pointer that will return the applications
response. This is a good idea since the application may fail
to fill the pointer and the module should be in a position to
notice!
</para>
<para>
The module should be prepared for a failure from the
conversation. The generic error would be
<emphasis>PAM_CONV_ERR</emphasis>, but anything other than
<emphasis>PAM_SUCCESS</emphasis> should be treated as
indicating failure.
</para>
</section>
<section xml:id="mwg-see-programming-sec-token">
<title>Authentication tokens</title>
<para>
To ensure that the authentication tokens are not left lying
around the items, <emphasis>PAM_AUTHTOK</emphasis> and
<emphasis>PAM_OLDAUTHTOK</emphasis>, are not available to
the application: they are defined in
<filename>&lt;security/pam_modules.h&gt;</filename>. This
is ostensibly for security reasons, but a maliciously
programmed application will always have access to all memory
of the process, so it is only superficially enforced. As a
general rule the module should overwrite authentication tokens
as soon as they are no longer needed. Especially before
<function>free()</function>'ing them. The
<emphasis remap="B">Linux-PAM</emphasis> library is
required to do this when either of these authentication
token items are (re)set.
</para>
<para>
Not to dwell too little on this concern; should the module
store the authentication tokens either as (automatic) function
variables or using <function>pam_[gs]et_data()</function> the
associated memory should be over-written explicitly before it
is released. In the case of the latter storage mechanism, the
associated <function>cleanup()</function> function should
explicitly overwrite the <varname>*data</varname> before
<function>free()</function>'ing it: for example,
<programlisting>
/*
* An example cleanup() function for releasing memory that was used to
* store a password.
*/
int cleanup(pam_handle_t *pamh, void *data, int error_status)
{
char *xx;
if ((xx = data)) {
while (*xx)
*xx++ = '\0';
free(data);
}
return PAM_SUCCESS;
}
</programlisting>
</para>
</section>
</section>
<section xml:id="mwg-see-programming-syslog">
<title>Use of <citerefentry>
<refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
</citerefentry></title>
<para>
Only rarely should error information be directed to the user.
Usually, this is to be limited to
<quote><emphasis>sorry you cannot login now</emphasis></quote>
type messages. Information concerning errors in the configuration
file, <filename>/etc/pam.conf</filename>, or due to some system
failure encountered by the module, should be written to
<citerefentry>
<refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum>
</citerefentry> with <emphasis>facility-type</emphasis>
<emphasis remap="B">LOG_AUTHPRIV</emphasis>.
</para>
<para>
With a few exceptions, the level of logging is, at the discretion
of the module developer. Here is the recommended usage of different
logging levels:
</para>
<itemizedlist>
<listitem>
<para>
As a general rule, errors encountered by a module should be
logged at the <emphasis>LOG_ERR</emphasis> level. However,
information regarding an unrecognized argument, passed to a
module from an entry in the <filename>/etc/pam.conf</filename>
file, is <emphasis>required</emphasis> to be logged at the
<emphasis>LOG_ERR</emphasis> level.
</para>
</listitem>
<listitem>
<para>
Debugging information, as activated by the
<command>debug</command> argument to the module in
<filename>/etc/pam.conf</filename>, should be logged
at the <emphasis>LOG_DEBUG</emphasis> level.
</para>
</listitem>
<listitem>
<para>
If a module discovers that its personal configuration
file or some system file it uses for information is
corrupted or somehow unusable, it should indicate this
by logging messages at level, <emphasis>LOG_ALERT</emphasis>.
</para>
</listitem>
<listitem>
<para>
Shortages of system resources, such as a failure to
manipulate a file or <function>malloc()</function> failures
should be logged at level <emphasis>LOG_CRIT</emphasis>.
</para>
</listitem>
<listitem>
<para>
Authentication failures, associated with an incorrectly
typed password should be logged at level,
<emphasis>LOG_NOTICE</emphasis>.
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="mwg-see-programming-libs">
<title>Modules that require system libraries</title>
<para>
Writing a module is much like writing an application. You
have to provide the "conventional hooks" for it to work
correctly, like <function>pam_sm_authenticate()</function>
etc., which would correspond to the <function>main()</function>
function in a normal function.
</para>
<para>
Typically, the author may want to link against some standard system
libraries. As when one compiles a normal program, this can be
done for modules too: you simply append the
<parameter>-l</parameter><emphasis>XXX</emphasis> arguments
for the desired libraries when you create the shared module object.
To make sure a module is linked to the
<command>libwhatever.so</command> library
when it is <function>dlopen()</function>ed, try:
<programlisting>
% gcc -shared -o pam_module.so pam_module.o -lwhatever
</programlisting>
</para>
</section>
</chapter>
<chapter xml:id="mwg-example">
<title>An example module</title>
<para>
At some point, we may include a fully commented example of a module in
this document. For now, please look at the modules directory of the
<emphasis remap="B">Linux-PAM</emphasis> sources.
</para>
</chapter>
<chapter xml:id="mwg-see-also">
<title>See also</title>
<itemizedlist>
<listitem>
<para>
The Linux-PAM System Administrators' Guide.
</para>
</listitem>
<listitem>
<para>
The Linux-PAM Application Developers' Guide.
</para>
</listitem>
<listitem>
<para>
The V. Samar and R. Schemers (SunSoft), ``UNIFIED LOGIN WITH
PLUGGABLE AUTHENTICATION MODULES'', Open Software Foundation
Request For Comments 86.0, October 1995.
</para>
</listitem>
</itemizedlist>
</chapter>
<chapter xml:id="mwg-author">
<title>Author/acknowledgments</title>
<para>
This document was written by Andrew G. Morgan (morgan@kernel.org)
with many contributions from
Chris Adams, Peter Allgeyer, Tim Baverstock, Tim Berger, Craig S. Bell,
Derrick J. Brashear, Ben Buxton, Seth Chaiklin, Oliver Crow, Chris Dent,
Marc Ewing, Cristian Gafton, Emmanuel Galanos, Brad M. Garcia,
Eric Hester, Roger Hu, Eric Jacksch, Michael K. Johnson, David Kinchlea,
Olaf Kirch, Marcin Korzonek, Thorsten Kukuk, Stephen Langasek,
Nicolai Langfeldt, Elliot Lee, Luke Kenneth Casson Leighton,
Al Longyear, Ingo Luetkebohle, Marek Michalkiewicz, Robert Milkowski,
Aleph One, Martin Pool, Sean Reifschneider, Jan Rekorajski, Erik Troan,
Theodore Ts'o, Jeff Uphoff, Myles Uyema, Savochkin Andrey Vladimirovich,
Ronald Wahl, David Wood, John Wilmes, Joseph S. D. Yao
and Alex O. Yuriev.
</para>
<para>
Thanks are also due to Sun Microsystems, especially to Vipin Samar and
Charlie Lai for their advice. At an early stage in the development of
<emphasis remap="B">Linux-PAM</emphasis>, Sun graciously made the
documentation for their implementation of PAM available. This act
greatly accelerated the development of
<emphasis remap="B">Linux-PAM</emphasis>.
</para>
</chapter>
<chapter xml:id="mwg-copyright">
<title>Copyright information for this document</title>
<programlisting>
Copyright (c) 2006 Thorsten Kukuk &lt;kukuk@thkukuk.de&gt;
Copyright (c) 1996-2002 Andrew G. Morgan &lt;morgan@kernel.org&gt;
</programlisting>
<para>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
</para>
<programlisting>
1. Redistributions of source code must retain the above copyright
notice, and the entire permission notice in its entirety,
including the disclaimer of warranties.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote
products derived from this software without specific prior
written permission.
</programlisting>
<para>
Alternatively, this product may be distributed under the terms of
the GNU General Public License (GPL), in which case the provisions
of the GNU GPL are required instead of the above restrictions.
(This clause is necessary due to a potential bad interaction between
the GNU GPL and the restrictions contained in a BSD-style copyright.)
</para>
<programlisting>
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
</programlisting>
</chapter>
</book>

1
doc/mwg/html/meson.build Symbolic link
View file

@ -0,0 +1 @@
../../guide-html-meson.build

1
doc/mwg/meson.build Symbolic link
View file

@ -0,0 +1 @@
../guide-meson.build

29
doc/mwg/pam_conv.xml Normal file
View file

@ -0,0 +1,29 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="mwg-pam_conv">
<title>The conversation function</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_conv.3.xml" xpointer='xpointer(id("pam_conv-synopsis")/*)'/>
</funcsynopsis>
<programlisting>
struct pam_message {
int msg_style;
const char *msg;
};
struct pam_response {
char *resp;
int resp_retcode;
};
struct pam_conv {
int (*conv)(int num_msg, const struct pam_message **msg,
struct pam_response **resp, void *appdata_ptr);
void *appdata_ptr;
};
</programlisting>
<section xml:id="mwg-pam_conv-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_conv.3.xml" xpointer='xpointer(id("pam_conv-description")/*)'/>
</section>
<section xml:id="mwg-pam_conv-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_conv.3.xml" xpointer='xpointer(id("pam_conv-return_values")/*)'/>
</section>
</section>

12
doc/mwg/pam_fail_delay.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_fail_delay">
<title>Request a delay on failure</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_fail_delay.3.xml" xpointer='xpointer(id("pam_fail_delay-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_fail_delay-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_fail_delay.3.xml" xpointer='xpointer(id("pam_fail_delay-description")/*)'/>
</section>
<section xml:id="adg-pam_fail_delay-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_fail_delay.3.xml" xpointer='xpointer(id("pam_fail_delay-return_values")/*)'/>
</section>
</section>

12
doc/mwg/pam_get_data.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="mwg-pam_get_data">
<title>Get module internal data</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_data.3.xml" xpointer='xpointer(id("pam_get_data-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="mwg-pam_get_data-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_data.3.xml" xpointer='xpointer(id("pam_get_data-description")/*)'/>
</section>
<section xml:id="mwg-pam_get_data-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_data.3.xml" xpointer='xpointer(id("pam_get_data-return_values")/*)'/>
</section>
</section>

12
doc/mwg/pam_get_item.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="mwg-pam_get_item">
<title>Getting PAM items</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_item.3.xml" xpointer='xpointer(id("pam_get_item-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="mwg-pam_get_item-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_item.3.xml" xpointer='xpointer(id("pam_get_item-description")/*)'/>
</section>
<section xml:id="mwg-pam_get_item-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_item.3.xml" xpointer='xpointer(id("pam_get_item-return_values")/*)'/>
</section>
</section>

12
doc/mwg/pam_get_user.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="mwg-pam_get_user">
<title>Get user name</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_user.3.xml" xpointer='xpointer(id("pam_get_user-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="mwg-pam_get_user-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_user.3.xml" xpointer='xpointer(id("pam_get_user-description")/*)'/>
</section>
<section xml:id="mwg-pam_get_user-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_get_user.3.xml" xpointer='xpointer(id("pam_get_user-return_values")/*)'/>
</section>
</section>

12
doc/mwg/pam_getenv.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_getenv">
<title>Get a PAM environment variable</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenv.3.xml" xpointer='xpointer(id("pam_getenv-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_getenv-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenv.3.xml" xpointer='xpointer(id("pam_getenv-description")/*)'/>
</section>
<section xml:id="adg-pam_getenv-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenv.3.xml" xpointer='xpointer(id("pam_getenv-return_values")/*)'/>
</section>
</section>

12
doc/mwg/pam_getenvlist.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_getenvlist">
<title>Getting the PAM environment</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenvlist.3.xml" xpointer='xpointer(id("pam_getenvlist-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_getenvlist-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenvlist.3.xml" xpointer='xpointer(id("pam_getenvlist-description")/*)'/>
</section>
<section xml:id="adg-pam_getenvlist-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_getenvlist.3.xml" xpointer='xpointer(id("pam_getenvlist-return_values")/*)'/>
</section>
</section>

12
doc/mwg/pam_putenv.xml Normal file
View file

@ -0,0 +1,12 @@
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="adg-pam_putenv">
<title>Set or change PAM environment variable</title>
<funcsynopsis>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_putenv.3.xml" xpointer='xpointer(id("pam_putenv-synopsis")/*)'/>
</funcsynopsis>
<section xml:id="adg-pam_putenv-description">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_putenv.3.xml" xpointer='xpointer(id("pam_putenv-description")/*)'/>
</section>
<section xml:id="adg-pam_putenv-return_values">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../man/pam_putenv.3.xml" xpointer='xpointer(id("pam_putenv-return_values")/*)'/>
</section>
</section>

Some files were not shown because too many files have changed in this diff Show more