diff options
Diffstat (limited to 'doc/man/pam.3')
| -rw-r--r-- | doc/man/pam.3 | 287 |
1 files changed, 230 insertions, 57 deletions
diff --git a/doc/man/pam.3 b/doc/man/pam.3 index 9de478e5..b6033370 100644 --- a/doc/man/pam.3 +++ b/doc/man/pam.3 @@ -1,104 +1,272 @@ .\" Title: pam -.\" Author: -.\" Generator: DocBook XSL Stylesheets v1.73.1 <http://docbook.sf.net/> -.\" Date: 04/16/2008 +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/> +.\" Date: 03/02/2009 .\" Manual: Linux-PAM Manual .\" Source: Linux-PAM Manual +.\" Language: English .\" -.TH "PAM" "3" "04/16/2008" "Linux-PAM Manual" "Linux-PAM Manual" +.TH "PAM" "3" "03/02/2009" "Linux-PAM Manual" "Linux-PAM Manual" +.\" ----------------------------------------------------------------- +.\" * (re)Define some macros +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" toupper - uppercase a string (locale-aware) +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de toupper +.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ +\\$* +.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" SH-xref - format a cross-reference to an SH section +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de SH-xref +.ie n \{\ +.\} +.toupper \\$* +.el \{\ +\\$* +.\} +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" SH - level-one heading that works better for non-TTY output +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de1 SH +.\" put an extra blank line of space above the head in non-TTY output +.if t \{\ +.sp 1 +.\} +.sp \\n[PD]u +.nr an-level 1 +.set-an-margin +.nr an-prevailing-indent \\n[IN] +.fi +.in \\n[an-margin]u +.ti 0 +.HTML-TAG ".NH \\n[an-level]" +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +\." make the size of the head bigger +.ps +3 +.ft B +.ne (2v + 1u) +.ie n \{\ +.\" if n (TTY output), use uppercase +.toupper \\$* +.\} +.el \{\ +.nr an-break-flag 0 +.\" if not n (not TTY), use normal case (not uppercase) +\\$1 +.in \\n[an-margin]u +.ti 0 +.\" if not n (not TTY), put a border/line under subheading +.sp -.6 +\l'\n(.lu' +.\} +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" SS - level-two heading that works better for non-TTY output +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de1 SS +.sp \\n[PD]u +.nr an-level 1 +.set-an-margin +.nr an-prevailing-indent \\n[IN] +.fi +.in \\n[IN]u +.ti \\n[SN]u +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.ps \\n[PS-SS]u +\." make the size of the head bigger +.ps +2 +.ft B +.ne (2v + 1u) +.if \\n[.$] \&\\$* +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" BB/BE - put background/screen (filled box) around block of text +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de BB +.if t \{\ +.sp -.5 +.br +.in +2n +.ll -2n +.gcolor red +.di BX +.\} +.. +.de EB +.if t \{\ +.if "\\$2"adjust-for-leading-newline" \{\ +.sp -1 +.\} +.br +.di +.in +.ll +.gcolor +.nr BW \\n(.lu-\\n(.i +.nr BH \\n(dn+.5v +.ne \\n(BHu+.5v +.ie "\\$2"adjust-for-leading-newline" \{\ +\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[] +.\} +.el \{\ +\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[] +.\} +.in 0 +.sp -.5v +.nf +.BX +.in +.sp .5v +.fi +.\} +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" BM/EM - put colored marker in margin next to block of text +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de BM +.if t \{\ +.br +.ll -2n +.gcolor red +.di BX +.\} +.. +.de EM +.if t \{\ +.br +.di +.ll +.gcolor +.nr BH \\n(dn +.ne \\n(BHu +\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[] +.in 0 +.nf +.BX +.in +.fi +.\} +.. +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l -.SH "NAME" -pam - Pluggable Authentication Modules Library -.SH "SYNOPSIS" +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "Name" +pam \- Pluggable Authentication Modules Library +.SH "Synopsis" .sp .ft B +.fam C +.ps -1 .nf -#include <security/pam_appl\.h> +#include <security/pam_appl\&.h> .fi +.fam +.ps +1 .ft .sp .ft B +.fam C +.ps -1 .nf -#include <security/pam_modules\.h> +#include <security/pam_modules\&.h> .fi +.fam +.ps +1 .ft .sp .ft B +.fam C +.ps -1 .nf -#include <security/pam_ext\.h> +#include <security/pam_ext\&.h> .fi +.fam +.ps +1 .ft .SH "DESCRIPTION" .PP \fBPAM\fR -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 +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 \fBlogin\fR(1) and -\fBsu\fR(1)) defer to to perform standard authentication tasks\. +\fBsu\fR(1)) defer to to perform standard authentication tasks\&. .SS "Initialization and Cleanup" .PP The \fBpam_start\fR(3) -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\. +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\&. .PP The \fBpam_end\fR(3) -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\. +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\&. .SS "Authentication" .PP The \fBpam_authenticate\fR(3) -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\. +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\&. .PP The \fBpam_setcred\fR(3) -function manages the userscredentials\. +function manages the userscredentials\&. .SS "Account Management" .PP The \fBpam_acct_mgmt\fR(3) -function is used to determine if the users 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\. +function is used to determine if the users 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\&. .SS "Password Management" .PP The \fBpam_chauthtok\fR(3) -function is used to change the authentication token for a given user on request or because the token has expired\. +function is used to change the authentication token for a given user on request or because the token has expired\&. .SS "Session Management" .PP The \fBpam_open_session\fR(3) -function sets up a user session for a previously successful authenticated user\. The session should later be terminated with a call to -\fBpam_close_session\fR(3)\. +function sets up a user session for a previously successful authenticated user\&. The session should later be terminated with a call to +\fBpam_close_session\fR(3)\&. .SS "Conversation" .PP -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 +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 \fIstruct pam_conv\fR passed to \fBpam_start\fR(3) -at the start of the transaction\. See +at the start of the transaction\&. See \fBpam_conv\fR(3) -for details\. +for details\&. .SS "Data Objects" .PP The \fBpam_set_item\fR(3) and \fBpam_get_item\fR(3) -functions allows applications and PAM service modules to set and retrieve PAM informations\. +functions allows applications and PAM service modules to set and retrieve PAM informations\&. .PP The \fBpam_get_user\fR(3) -function is the preferred method to obtain the username\. +function is the preferred method to obtain the username\&. .PP The \fBpam_set_data\fR(3) and \fBpam_get_data\fR(3) -functions allows PAM service modules to set and retrieve free\-form data from one invocation to another\. +functions allows PAM service modules to set and retrieve free\-form data from one invocation to another\&. .SS "Environment and Error Management" .PP The @@ -106,158 +274,158 @@ The \fBpam_getenv\fR(3) and \fBpam_getenvlist\fR(3) -functions are for maintaining a set of private environment variables\. +functions are for maintaining a set of private environment variables\&. .PP The \fBpam_strerror\fR(3) -function returns a pointer to a string describing the given PAM error code\. +function returns a pointer to a string describing the given PAM error code\&. .SH "RETURN VALUES" .PP The following return codes are known by PAM: .PP PAM_ABORT .RS 4 -Critical error, immediate abort\. +Critical error, immediate abort\&. .RE .PP PAM_ACCT_EXPIRED .RS 4 -User account has expired\. +User account has expired\&. .RE .PP PAM_AUTHINFO_UNAVAIL .RS 4 -Authentication service cannot retrieve authentication info\. +Authentication service cannot retrieve authentication info\&. .RE .PP PAM_AUTHTOK_DISABLE_AGING .RS 4 -Authentication token aging disabled\. +Authentication token aging disabled\&. .RE .PP PAM_AUTHTOK_ERR .RS 4 -Authentication token manipulation error\. +Authentication token manipulation error\&. .RE .PP PAM_AUTHTOK_EXPIRED .RS 4 -Authentication token expired\. +Authentication token expired\&. .RE .PP PAM_AUTHTOK_LOCK_BUSY .RS 4 -Authentication token lock busy\. +Authentication token lock busy\&. .RE .PP PAM_AUTHTOK_RECOVERY_ERR .RS 4 -Authentication information cannot be recovered\. +Authentication information cannot be recovered\&. .RE .PP PAM_AUTH_ERR .RS 4 -Authentication failure\. +Authentication failure\&. .RE .PP PAM_BUF_ERR .RS 4 -Memory buffer error\. +Memory buffer error\&. .RE .PP PAM_CONV_ERR .RS 4 -Conversation failure\. +Conversation failure\&. .RE .PP PAM_CRED_ERR .RS 4 -Failure setting user credentials\. +Failure setting user credentials\&. .RE .PP PAM_CRED_EXPIRED .RS 4 -User credentials expired\. +User credentials expired\&. .RE .PP PAM_CRED_INSUFFICIENT .RS 4 -Insufficient credentials to access authentication data\. +Insufficient credentials to access authentication data\&. .RE .PP PAM_CRED_UNAVAIL .RS 4 -Authentication service cannot retrieve user credentials\. +Authentication service cannot retrieve user credentials\&. .RE .PP PAM_IGNORE .RS 4 -The return value should be ignored by PAM dispatch\. +The return value should be ignored by PAM dispatch\&. .RE .PP PAM_MAXTRIES .RS 4 -Have exhausted maximum number of retries for service\. +Have exhausted maximum number of retries for service\&. .RE .PP PAM_MODULE_UNKNOWN .RS 4 -Module is unknown\. +Module is unknown\&. .RE .PP PAM_NEW_AUTHTOK_REQD .RS 4 -Authentication token is no longer valid; new one required\. +Authentication token is no longer valid; new one required\&. .RE .PP PAM_NO_MODULE_DATA .RS 4 -No module specific data is present\. +No module specific data is present\&. .RE .PP PAM_OPEN_ERR .RS 4 -Failed to load module\. +Failed to load module\&. .RE .PP PAM_PERM_DENIED .RS 4 -Permission denied\. +Permission denied\&. .RE .PP PAM_SERVICE_ERR .RS 4 -Error in service module\. +Error in service module\&. .RE .PP PAM_SESSION_ERR .RS 4 -Cannot make/remove an entry for the specified session\. +Cannot make/remove an entry for the specified session\&. .RE .PP PAM_SUCCESS .RS 4 -Success\. +Success\&. .RE .PP PAM_SYMBOL_ERR .RS 4 -Symbol not found\. +Symbol not found\&. .RE .PP PAM_SYSTEM_ERR .RS 4 -System error\. +System error\&. .RE .PP PAM_TRY_AGAIN .RS 4 -Failed preliminary check by password service\. +Failed preliminary check by password service\&. .RE .PP PAM_USER_UNKNOWN .RS 4 -User not known to the underlying authentication module\. +User not known to the underlying authentication module\&. .RE .SH "SEE ALSO" .PP @@ -280,3 +448,8 @@ User not known to the underlying authentication module\. \fBpam_setcred\fR(3), \fBpam_start\fR(3), \fBpam_strerror\fR(3) +.SH "NOTES" +.PP +The +\fIlibpam\fR +interfaces are only thread\-safe if each thread within the multithreaded application uses its own PAM handle\&. |