From f7827ccfd255e23f285eb8aec7ddf71af94dd6ff Mon Sep 17 00:00:00 2001 From: Thorsten Kukuk Date: Sun, 12 Feb 2006 22:24:34 +0000 Subject: Relevant BUGIDs: Purpose of commit: cleanup Commit summary: --------------- Merge manual pages and sgml docu as xml, update them. 2006-02-12 Thorsten Kukuk * configure.in: Add doc/man/Makefile. * Make.xml.rules: Enable xincludes for manual pages. * doc/Makefile.am (EXRA_DIST): Remove manual pages. (SUBDIR): Add man subdirectory. * doc/man/Makefile.am: New. * doc/man/pam_acct_mgmt.3: New. * doc/man/pam_acct_mgmt.3.xml: New. * doc/man/pam_get_data.3: New. * doc/man/pam_get_data.3.xml: New. * doc/man/pam_set_data.3: New. * doc/man/pam_set_data.3.xml: New. * doc/man/pam.8.xml: New. * doc/man/pam.8: Regenerated from xml file. * doc/man/pam_authenticate.3.xml: New. * doc/man/pam_authenticate.3: Regenerated from xml file. * doc/man/pam_chauthtok.3.xml: New. * doc/man/pam_chauthtok.3: Regenerated from xml file. * doc/man/pam_close_session.3.xml: New. * doc/man/pam_close_session.3: Regenerated from xml file. * doc/man/pam_end.3.xml: New. * doc/man/pam_end.3: Regenerated from xml file. * doc/man/pam_fail_delay.3.xml: New. * doc/man/pam_fail_delay.3: Regenerated from xml file. * doc/man/pam_get_item.3.xml: New. * doc/man/pam_get_item.3: Regenerated from xml file. * doc/man/pam_item_types.inc.xml: New. * doc/man/pam_open_session.3.xml: New. * doc/man/pam_open_session.3: Regenerated from xml file. * doc/man/pam_set_item.3.xml: New. * doc/man/pam_set_item.3: Regenerated from xml file. * doc/man/pam_setcred.3.xml: New. * doc/man/pam_setcred.3: Regenerated from xml file. * doc/man/pam_start.3.xml: New. * doc/man/pam_start.3: Regenerated from xml file. * doc/man/pam_strerror.3.xml: New. * doc/man/pam_strerror.3: Regenerated from xml file. * doc/man/template-man: Removed. --- doc/man/.cvsignore | 2 + doc/man/Makefile.am | 33 +++ doc/man/pam.8 | 535 +++++++++++++++------------------------- doc/man/pam.8.xml | 392 +++++++++++++++++++++++++++++ doc/man/pam_acct_mgmt.3 | 60 +++++ doc/man/pam_acct_mgmt.3.xml | 145 +++++++++++ doc/man/pam_authenticate.3 | 153 +++++------- doc/man/pam_authenticate.3.xml | 169 +++++++++++++ doc/man/pam_chauthtok.3 | 160 +++++------- doc/man/pam_chauthtok.3.xml | 164 ++++++++++++ doc/man/pam_close_session.3 | 48 +++- doc/man/pam_close_session.3.xml | 115 +++++++++ doc/man/pam_end.3 | 53 +++- doc/man/pam_end.3.xml | 109 ++++++++ doc/man/pam_fail_delay.3 | 216 ++++++++-------- doc/man/pam_fail_delay.3.xml | 175 +++++++++++++ doc/man/pam_get_data.3 | 52 ++++ doc/man/pam_get_data.3.xml | 108 ++++++++ doc/man/pam_get_item.3 | 117 ++++++++- doc/man/pam_get_item.3.xml | 134 ++++++++++ doc/man/pam_item_types.inc.xml | 151 ++++++++++++ doc/man/pam_open_session.3 | 140 ++++------- doc/man/pam_open_session.3.xml | 115 +++++++++ doc/man/pam_set_data.3 | 85 +++++++ doc/man/pam_set_data.3.xml | 172 +++++++++++++ doc/man/pam_set_item.3 | 164 ++++++++---- doc/man/pam_set_item.3.xml | 127 ++++++++++ doc/man/pam_setcred.3 | 139 +++++------ doc/man/pam_setcred.3.xml | 173 +++++++++++++ doc/man/pam_start.3 | 160 +++++------- doc/man/pam_start.3.xml | 143 +++++++++++ doc/man/pam_strerror.3 | 77 ++---- doc/man/pam_strerror.3.xml | 58 +++++ doc/man/template-man | 52 ---- 34 files changed, 3641 insertions(+), 1055 deletions(-) create mode 100644 doc/man/.cvsignore create mode 100644 doc/man/Makefile.am create mode 100644 doc/man/pam.8.xml create mode 100644 doc/man/pam_acct_mgmt.3 create mode 100644 doc/man/pam_acct_mgmt.3.xml create mode 100644 doc/man/pam_authenticate.3.xml create mode 100644 doc/man/pam_chauthtok.3.xml create mode 100644 doc/man/pam_close_session.3.xml create mode 100644 doc/man/pam_end.3.xml create mode 100644 doc/man/pam_fail_delay.3.xml create mode 100644 doc/man/pam_get_data.3 create mode 100644 doc/man/pam_get_data.3.xml create mode 100644 doc/man/pam_get_item.3.xml create mode 100644 doc/man/pam_item_types.inc.xml create mode 100644 doc/man/pam_open_session.3.xml create mode 100644 doc/man/pam_set_data.3 create mode 100644 doc/man/pam_set_data.3.xml create mode 100644 doc/man/pam_set_item.3.xml create mode 100644 doc/man/pam_setcred.3.xml create mode 100644 doc/man/pam_start.3.xml create mode 100644 doc/man/pam_strerror.3.xml delete mode 100644 doc/man/template-man (limited to 'doc/man') diff --git a/doc/man/.cvsignore b/doc/man/.cvsignore new file mode 100644 index 00000000..282522db --- /dev/null +++ b/doc/man/.cvsignore @@ -0,0 +1,2 @@ +Makefile +Makefile.in diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am new file mode 100644 index 00000000..49eefacc --- /dev/null +++ b/doc/man/Makefile.am @@ -0,0 +1,33 @@ +# +# Copyright (c) 2006 Thorsten Kukuk +# + +CLEANFILES = *~ + +EXTRA_DIST = $(MANS) $(XMLS) + +man_MANS = pam.8 pam.conf.5 pam.d.5 \ + pam_acct_mgmt.3 pam_authenticate.3 \ + pam_chauthtok.3 pam_close_session.3 \ + pam_end.3 \ + pam_fail_delay.3 \ + pam_get_data.3 pam_get_item.3 \ + pam_open_session.3 \ + pam_set_data.3 pam_set_item.3 \ + pam_setcred.3 pam_start.3 pam_strerror.3 +XMLS = pam.8.xml \ + pam_acct_mgmt.3.xml pam_authenticate.3.xml \ + pam_chauthtok.3.xml pam_close_session.3.xml \ + pam_end.3.xml \ + pam_fail_delay.3.xml \ + pam_get_data.3.xml pam_get_item.3.xml \ + pam_open_session.3.xml \ + pam_set_data.3.xml pam_set_item.3.xml \ + pam_setcred.3.xml pam_start.3.xml pam_strerror.3.xml \ + pam_item_types.inc.xml + +if ENABLE_REGENERATE_MAN +pam_get_item.3: pam_item_types.inc.xml +pam_set_data.3: pam_item_types.inc.xml +-include $(top_srcdir)/Make.xml.rules +endif diff --git a/doc/man/pam.8 b/doc/man/pam.8 index fc032bcc..3e511174 100644 --- a/doc/man/pam.8 +++ b/doc/man/pam.8 @@ -1,375 +1,246 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996-7,2001 -.TH PAM 8 "2005 Oct 27" "Linux-PAM 1.0" "Linux-PAM Manual" -.SH NAME - -Linux-PAM \- Pluggable Authentication Modules for Linux - -.SH SYNOPSIS -.B /etc/pam.conf -.sp 2 -.SH DESCRIPTION - +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM" "8" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam \- Pluggable Authentication Modules for Linux +.SH "DESCRIPTION" +.PP This manual is intended to offer a quick introduction to -.BR Linux-PAM ". " -For more information the reader is directed to the -.BR "Linux-PAM system administrators' guide". - -.sp -.BR Linux-PAM -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 -.BR login "(1) " +\fILinux\-PAM\fR. For more information the reader is directed to the +\fILinux\-PAM system administrators' guide\fR. +.PP +\fILinux\-PAM\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 +\fBlogin\fR(1) and -.BR su "(1)) " -defer to to perform standard authentication tasks. - -.sp -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 -.BR Linux-PAM +\fBsu\fR(1)) defer to to perform standard authentication tasks. +.PP +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 +\fILinux\-PAM\fR configuration file -.BR /etc/pam.conf "." -Alternatively, the configuration can be set by individual -configuration files located in the -.B /etc/pam.d/ +\fI/etc/pam.conf\fR. Alternatively, the configuration can be set by individual configuration files located in the +\fI/etc/pam.d/\fR directory. -.IB "The presence of this directory will cause " Linux-PAM " to ignore" -.BI /etc/pam.conf "." - -.sp -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 -.BR Linux-PAM -library. The important point to recognize is that the configuration -file(s) -.I define +\fIThe presence of this directory will cause \fR\fILinux\-PAM\fR\fI to ignore\fR\fI/etc/pam.conf\fR. +.PP +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 +\fILinux\-PAM\fR +library. The important point to recognize is that the configuration file(s) +\fIdefine\fR the connection between applications -.BR "" "(" services ")" -and the pluggable authentication modules -.BR "" "(" PAM "s)" -that perform the actual authentication tasks. - -.sp -.BR Linux-PAM +(\fIservices\fR) and the pluggable authentication modules +(\fIPAM\fRs) that perform the actual authentication tasks. +.PP +\fILinux\-PAM\fR separates the tasks of -.I authentication +\fIauthentication\fR into four independent management groups: -.BR "account" " management; " -.BR "auth" "entication management; " -.BR "password" " management; " -and -.BR "session" " management." -(We highlight the abbreviations used for these groups in the -configuration file.) - -.sp -Simply put, these groups take care of different aspects of a typical -user's request for a restricted service: - -.sp -.BR account " - " -provide account verification types of service: has the user's password -expired?; is this user permitted access to the requested service? - -.br -.BR auth "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 -.BR Linux-PAM "." - -.br -.BR password " - " -this group's responsibility is the task of updating authentication -mechanisms. Typically, such services are strongly coupled to those of -the -.BR auth -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. - -.br -.BR session " - " -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 -.BR session -management group is important as it provides both an opening and -closing hook for modules to affect the services available to a user. - -.SH The configuration file(s) - +\fIaccount\fR +management; +\fIauth\fRentication management; +\fIpassword\fR +management; and +\fIsession\fR +management. (We highlight the abbreviations used for these groups in the configuration file.) +.PP +Simply put, these groups take care of different aspects of a typical user's request for a restricted service: +.PP +\fIaccount\fR +\- provide account verification types of service: has the user's password expired?; is this user permitted access to the requested service? +.PP +\fIauth\fRentication \- 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 +\fILinux\-PAM\fR. +.PP +\fIpassword\fR +\- this group's responsibility is the task of updating authentication mechanisms. Typically, such services are strongly coupled to those of the +\fIauth\fR +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. +.PP +\fIsession\fR +\- 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 +\fIsession\fR +management group is important as it provides both an opening and closing hook for modules to affect the services available to a user. +.SH "THE CONFIGURATION FILE(S)" +.PP When a -.BR Linux-PAM -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): -.BR /etc/pam.conf "." -Alternatively, this may be the contents of the -.BR /etc/pam.d/ +\fILinux\-PAM\fR +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): +\fI/etc/pam.conf\fR. Alternatively, this may be the contents of the +\fI/etc/pam.d/\fR directory. - +.PP These files list the -.BR PAM "s" -that will do the authentication tasks required by this service, and -the appropriate behavior of the PAM-API in the event that individual -.BR PAM "s " -fail. - -.sp +\fIPAM\fRs that will do the authentication tasks required by this service, and the appropriate behavior of the PAM\-API in the event that individual +\fIPAM\fRs fail. +.PP The syntax of the -.B /etc/pam.conf -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: `\\'. Comments -are preceded with `#' marks and extend to the next end of line. - -.sp -The format of each rule is a space separated collection of tokens, the -first three being case-insensitive: - -.sp -.br -.BR " service type control module-path module-arguments" - -.sp +\fI/etc/pam.conf\fR +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: `\\'. Comments are preceded with `#' marks and extend to the next end of line. +.PP +The format of each rule is a space separated collection of tokens, the first three being case\-insensitive: +.PP +\fI service type control module\-path module\-arguments\fR +.PP The syntax of files contained in the -.B /etc/pam.d/ +\fI/etc/pam.d/\fR directory, are identical except for the absence of any -.I service +\fIservice\fR field. In this case, the -.I service +\fIservice\fR is the name of the file in the -.B /etc/pam.d/ +\fI/etc/pam.d/\fR directory. This filename must be in lower case. - -.sp +.PP An important feature of -.BR Linux-PAM ", " -is that a number of rules may be -.I stacked -to combine the services of a number of PAMs for a given authentication -task. - -.sp +\fILinux\-PAM\fR, is that a number of rules may be +\fIstacked\fR +to combine the services of a number of PAMs for a given authentication task. +.PP The -.BR service +\fIservice\fR is typically the familiar name of the corresponding application: -.BR login +\fIlogin\fR and -.BR su +\fIsu\fR are good examples. The -.BR service "-name, " other ", " -is reserved for giving -.I default -rules. Only lines that mention the current service (or in the absence -of such, the -.BR other -entries) will be associated with the given service-application. - -.sp +\fIservice\fR\-name, +\fIother\fR, is reserved for giving +\fIdefault\fR +rules. Only lines that mention the current service (or in the absence of such, the +\fIother\fR +entries) will be associated with the given service\-application. +.PP The -.BR type -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: -.BR account "; " -.BR auth "; " -.BR password "; " -and -.BR session "." -The meaning of each of these tokens was explained above. - -.sp +\fItype\fR +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: +\fIaccount\fR; +\fIauth\fR; +\fIpassword\fR; and +\fIsession\fR. The meaning of each of these tokens was explained above. +.PP The third field, -.BR control ", " -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 -.B value=action +\fIcontrol\fR, 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 +\fIvalue=action\fR pairs. - -.sp +.PP For the simple (historical) syntax valid -.BR control +\fIcontrol\fR values are: -.BR requisite -- failure of such a PAM results in the immediate termination of the -authentication process; -.BR required -- failure of such a PAM will ultimately lead to the PAM-API returning -failure but only after the remaining -.I stacked +\fIrequisite\fR +\- failure of such a PAM results in the immediate termination of the authentication process; +\fIrequired\fR +\- failure of such a PAM will ultimately lead to the PAM\-API returning failure but only after the remaining +\fIstacked\fR modules (for this -.BR service +\fIservice\fR and -.BR type ")" -have been invoked; -.BR sufficient -- success of such a module is enough to satisfy the authentication -requirements of the stack of modules (if a prior -.BR required +\fItype\fR) have been invoked; +\fIsufficient\fR +\- success of such a module is enough to satisfy the authentication requirements of the stack of modules (if a prior +\fIrequired\fR module has failed the success of this one is -.IR ignored "); " -.BR optional -- the success or failure of this module is only important if it is the -only module in the stack associated with this -.BR service "+" type "." - -.sp +\fIignored\fR); +\fIoptional\fR +\- the success or failure of this module is only important if it is the only module in the stack associated with this +\fIservice\fR+\fItype\fR. +.PP New control directive first introduced in ALT Linux is -.BR include -- include all lines of given type from the configuration -file specified as an argument to this control. - -.sp +\fIinclude\fR +\- include all lines of given type from the configuration file specified as an argument to this control. +.PP For the more complicated syntax valid -.B control +\fIcontrol\fR values have the following form: -.sp -.RB [value1=action1 value2=action2 ...] -.sp +.PP +[value1=action1\fIvalue2=action2\fR...] +.PP Where -.B valueN -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: -.BR success ; -.BR open_err ; -.BR symbol_err ; -.BR service_err ; -.BR system_err ; -.BR buf_err ; -.BR perm_denied ; -.BR auth_err ; -.BR cred_insufficient ; -.BR authinfo_unavail ; -.BR user_unknown ; -.BR maxtries ; -.BR new_authtok_reqd ; -.BR acct_expired ; -.BR session_err ; -.BR cred_unavail ; -.BR cred_expired ; -.BR cred_err ; -.BR no_module_data ; -.BR conv_err ; -.BR authtok_err ; -.BR authtok_recover_err ; -.BR authtok_lock_busy ; -.BR authtok_disable_aging ; -.BR try_again ; -.BR ignore ; -.BR abort ; -.BR authtok_expired ; -.BR module_unknown ; -.BR bad_item "; and" -.BR default . -The last of these, -.BR default , -implies 'all -.BR valueN 's -not mentioned explicitly. Note, the full list of PAM errors is -available in /usr/include/security/_pam_types.h . The -.B actionN +\fIvalueN\fR +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: +\fIsuccess\fR; +\fIopen_err\fR; +\fIsymbol_err\fR; +\fIservice_err\fR; +\fIsystem_err\fR; +\fIbuf_err\fR; +\fIperm_denied\fR; +\fIauth_err\fR; +\fIcred_insufficient\fR; +\fIauthinfo_unavail\fR; +\fIuser_unknown\fR; +\fImaxtries\fR; +\fInew_authtok_reqd\fR; +\fIacct_expired\fR; +\fIsession_err\fR; +\fIcred_unavail\fR; +\fIcred_expired\fR; +\fIcred_err\fR; +\fIno_module_data\fR; +\fIconv_err\fR; +\fIauthtok_err\fR; +\fIauthtok_recover_err\fR; +\fIauthtok_lock_busy\fR; +\fIauthtok_disable_aging\fR; +\fItry_again\fR; +\fIignore\fR; +\fIabort\fR; +\fIauthtok_expired\fR; +\fImodule_unknown\fR; +\fIbad_item\fR; and +\fIdefault\fR. The last of these, +\fIdefault\fR, implies 'all +\fIvalueN\fR's not mentioned explicitly. Note, the full list of PAM errors is available in /usr/include/security/_pam_types.h . The +\fIactionN\fR can be: an unsigned integer, -.BR J , -signifying an action of 'jump over the next J modules in the stack'; -or take one of the following forms: -.br -.B ignore -- when used with a stack of modules, the module's return status will -not contribute to the return code the application obtains; -.br -.B bad -- 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. -.br -.B die -- equivalent to bad with the side effect of terminating the module -stack and PAM immediately returning to the application. -.br -.B ok -- 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 -.BR PAM_SUCCESS , -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. -.br -.B done -- equivalent to ok with the side effect of terminating the module -stack and PAM immediately returning to the application. -.br -.B reset -- clear all memory of the state of the module stack and start again -with the next stacked module. - -.sp -.BR module-path -- this 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: -.BR /lib/security/ . - -.sp -.BR module-arguments -- these 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. - +\fIJ\fR, signifying an action of 'jump over the next J modules in the stack'; or take one of the following forms:\fIignore\fR +\- when used with a stack of modules, the module's return status will not contribute to the return code the application obtains;\fIbad\fR +\- 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.\fIdie\fR +\- equivalent to bad with the side effect of terminating the module stack and PAM immediately returning to the application.\fIok\fR +\- 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 +\fIPAM_SUCCESS\fR, 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.\fIdone\fR +\- equivalent to ok with the side effect of terminating the module stack and PAM immediately returning to the application.\fIreset\fR +\- clear all memory of the state of the module stack and start again with the next stacked module. +.PP +\fImodule\-path\fR +\- this 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: +\fI/lib/security/\fR. +.PP +\fImodule\-arguments\fR +\- these 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. .SH "FILES" -.BR /etc/pam.conf " - the configuration file" -.br -.BR /etc/pam.d/ " - the" -.BR Linux-PAM +.PP +\fI/etc/pam.conf\fR +\- the configuration file\fI/etc/pam.d/\fR +\- the +\fILinux\-PAM\fR configuration directory. Generally, if this directory is present, the -.B /etc/pam.conf -file is ignored. -.br -.BR /lib/libpam.so.X " - the dynamic library" -.br -.BR /lib/security/*.so " - the PAMs - -.SH ERRORS +\fI/etc/pam.conf\fR +file is ignored.\fI/lib/libpam.so.X\fR +\- the dynamic library\fI/lib/security/*.so\fR +\- the PAMs +.SH "ERRORS" +.PP Typically errors generated by the -.BR Linux-PAM +\fILinux\-PAM\fR system of libraries, will be written to -.BR syslog "(3)." - +\fBsyslog\fR(3). .SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. -.br -Contains additional features, but remains backwardly compatible with -this RFC. - -.SH BUGS -.sp 2 +.PP +DCE\-RFC 86.0, October 1995.Contains additional features, but remains backwardly compatible with this RFC. +.SH "BUGS" +.PP None known. - .SH "SEE ALSO" - +.PP The three -.BR Linux-PAM +\fILinux\-PAM\fR Guides, for -.BR "system administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " +\fIsystem administrators\fR, +\fImodule developers\fR, and +\fIapplication developers\fR. diff --git a/doc/man/pam.8.xml b/doc/man/pam.8.xml new file mode 100644 index 00000000..e8a78234 --- /dev/null +++ b/doc/man/pam.8.xml @@ -0,0 +1,392 @@ + + + + +pam +8 +Linux-PAM Manual + + +pam +Pluggable Authentication Modules for Linux + + + +DESCRIPTION +This manual is intended to offer a quick introduction to +Linux-PAM. +For more information the reader is directed to the +Linux-PAM system administrators' guide. + + +Linux-PAM +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 +login1 +and +su1) +defer to to perform standard authentication tasks. + + +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 +Linux-PAM +configuration file +/etc/pam.conf. +Alternatively, the configuration can be set by individual +configuration files located in the +/etc/pam.d/ +directory. +The presence of this directory will cause Linux-PAM to ignore +/etc/pam.conf. + + +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 +Linux-PAM +library. The important point to recognize is that the configuration +file(s) +define +the connection between applications +(services) +and the pluggable authentication modules +(PAMs) +that perform the actual authentication tasks. + + +Linux-PAM +separates the tasks of +authentication +into four independent management groups: +account management; +authentication management; +password management; +and +session management. +(We highlight the abbreviations used for these groups in the +configuration file.) + + +Simply put, these groups take care of different aspects of a typical +user's request for a restricted service: + + +account - +provide account verification types of service: has the user's password +expired?; is this user permitted access to the requested service? + + +authentication - +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 +Linux-PAM. + + +password - +this group's responsibility is the task of updating authentication +mechanisms. Typically, such services are strongly coupled to those of +the +auth +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. + + +session - +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 +session +management group is important as it provides both an opening and +closing hook for modules to affect the services available to a user. + + + +The configuration file(s) +When a +Linux-PAM +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): +/etc/pam.conf. +Alternatively, this may be the contents of the +/etc/pam.d/ +directory. + +These files list the +PAMs +that will do the authentication tasks required by this service, and +the appropriate behavior of the PAM-API in the event that individual +PAMs +fail. + + +The syntax of the +/etc/pam.conf +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: `\<LF>'. Comments +are preceded with `#' marks and extend to the next end of line. + + +The format of each rule is a space separated collection of tokens, the +first three being case-insensitive: + + + + service type control module-path module-arguments + + +The syntax of files contained in the +/etc/pam.d/ +directory, are identical except for the absence of any +service +field. In this case, the +service +is the name of the file in the +/etc/pam.d/ +directory. This filename must be in lower case. + + +An important feature of +Linux-PAM, +is that a number of rules may be +stacked +to combine the services of a number of PAMs for a given authentication +task. + + +The +service +is typically the familiar name of the corresponding application: +login +and +su +are good examples. The +service-name, other, +is reserved for giving +default +rules. Only lines that mention the current service (or in the absence +of such, the +other +entries) will be associated with the given service-application. + + +The +type +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: +account; +auth; +password; +and +session. +The meaning of each of these tokens was explained above. + + +The third field, +control, +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 +value=action +pairs. + + +For the simple (historical) syntax valid +control +values are: +requisite +- failure of such a PAM results in the immediate termination of the +authentication process; +required +- failure of such a PAM will ultimately lead to the PAM-API returning +failure but only after the remaining +stacked +modules (for this +service +and +type) +have been invoked; +sufficient +- success of such a module is enough to satisfy the authentication +requirements of the stack of modules (if a prior +required +module has failed the success of this one is +ignored); +optional +- the success or failure of this module is only important if it is the +only module in the stack associated with this +service+type. + + +New control directive first introduced in ALT Linux is +include +- include all lines of given type from the configuration +file specified as an argument to this control. + + +For the more complicated syntax valid +control +values have the following form: + +[value1=action1value2=action2...] + +Where +valueN +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: +success; +open_err; +symbol_err; +service_err; +system_err; +buf_err; +perm_denied; +auth_err; +cred_insufficient; +authinfo_unavail; +user_unknown; +maxtries; +new_authtok_reqd; +acct_expired; +session_err; +cred_unavail; +cred_expired; +cred_err; +no_module_data; +conv_err; +authtok_err; +authtok_recover_err; +authtok_lock_busy; +authtok_disable_aging; +try_again; +ignore; +abort; +authtok_expired; +module_unknown; +bad_item; and +default. +The last of these, +default, +implies 'all +valueN's +not mentioned explicitly. Note, the full list of PAM errors is +available in /usr/include/security/_pam_types.h . The +actionN +can be: an unsigned integer, +J, +signifying an action of 'jump over the next J modules in the stack'; +or take one of the following forms: + +ignore +- when used with a stack of modules, the module's return status will +not contribute to the return code the application obtains; + +bad +- 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. + +die +- equivalent to bad with the side effect of terminating the module +stack and PAM immediately returning to the application. + +ok +- 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 +PAM_SUCCESS, +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. + +done +- equivalent to ok with the side effect of terminating the module +stack and PAM immediately returning to the application. + +reset +- clear all memory of the state of the module stack and start again +with the next stacked module. + + +module-path +- this 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: +/lib/security/. + + +module-arguments +- these 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. + + + +FILES +/etc/pam.conf - the configuration file + +/etc/pam.d/ - the +Linux-PAM +configuration directory. Generally, if this directory is present, the +/etc/pam.conf +file is ignored. + +/lib/libpam.so.X - the dynamic library + +/lib/security/*.so - the PAMs + + + +ERRORS +Typically errors generated by the +Linux-PAM +system of libraries, will be written to +syslog3. + + + +CONFORMING TO +DCE-RFC 86.0, October 1995. + +Contains additional features, but remains backwardly compatible with +this RFC. + + + +BUGS + + +None known. + + + +SEE ALSO +The three +Linux-PAM +Guides, for +system administrators, +module developers, +and +application developers. + + + diff --git a/doc/man/pam_acct_mgmt.3 b/doc/man/pam_acct_mgmt.3 new file mode 100644 index 00000000..6ac39ab1 --- /dev/null +++ b/doc/man/pam_acct_mgmt.3 @@ -0,0 +1,60 @@ +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_ACCT_MGMT" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_acct_mgmt \- PAM account validation management +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 18 +\fBint\ \fBpam_acct_mgmt\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_acct_mgmt\fR +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. +.PP +The +\fIpamh\fR +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: +.TP +PAM_SILENT +Do not emit any messages. +.TP +PAM_DISALLOW_NULL_AUTHTOK +The PAM module service should return PAM_NEW_AUTHTOK_REQD if the user has a null authentication token. +.SH "RETURN VALUES" +.TP +PAM_ACCT_EXPIRED +User account has expired. +.TP +PAM_AUTH_ERR +Authentication failure. +.TP +PAM_NEW_AUTHTOK_REQD +The user account is valid but their authentication token is +\fIexpired\fR. The correct response to this return\-value is to require that the user satisfies the +\fBpam_chauthtok()\fR +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. +.TP +PAM_PERM_DENIED +Permission denied. +.TP +PAM_SUCCESS +The authentication token was successfully updated. +.TP +PAM_USER_UNKNOWN +User unknown to password service. +.SH "SEE ALSO" +.PP +\fBpam_start\fR(3), +\fBpam_authenticate\fR(3), +\fBpam_chauthtok\fR(3), +\fBpam_strerror\fR(3), +\fBpam\fR(8) diff --git a/doc/man/pam_acct_mgmt.3.xml b/doc/man/pam_acct_mgmt.3.xml new file mode 100644 index 00000000..e1f6492f --- /dev/null +++ b/doc/man/pam_acct_mgmt.3.xml @@ -0,0 +1,145 @@ + + + + + pam_acct_mgmt + 3 + Linux-PAM Manual + + + + pam_acct_mgmt + PAM account validation management + + + + + + + #include <security/pam_appl.h> + + int pam_acct_mgmt + pam_handle_t *pamh + int flags + + + + + + + DESCRIPTION + + The pam_acct_mgmt 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. + + + The pamh 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: + + + + PAM_SILENT + + + Do not emit any messages. + + + + + PAM_DISALLOW_NULL_AUTHTOK + + + The PAM module service should return PAM_NEW_AUTHTOK_REQD + if the user has a null authentication token. + + + + + + + + RETURN VALUES + + + PAM_ACCT_EXPIRED + + + User account has expired. + + + + + PAM_AUTH_ERR + + + Authentication failure. + + + + + PAM_NEW_AUTHTOK_REQD + + + The user account is valid but their authentication token + is expired. The correct response to + this return-value is to require that the user satisfies + the pam_chauthtok() 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. + + + + + PAM_PERM_DENIED + + + Permission denied. + + + + + PAM_SUCCESS + + + The authentication token was successfully updated. + + + + + PAM_USER_UNKNOWN + + + User unknown to password service. + + + + + + + + SEE ALSO + + + pam_start3 + , + + pam_authenticate3 + , + + pam_chauthtok3 + , + + pam_strerror3 + , + + pam8 + + + + diff --git a/doc/man/pam_authenticate.3 b/doc/man/pam_authenticate.3 index ba1bc52e..b0385a39 100644 --- a/doc/man/pam_authenticate.3 +++ b/doc/man/pam_authenticate.3 @@ -1,91 +1,68 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996-7 -.TH PAM_AUTHENTICATE 3 "1996 Dec 9" "Linux-PAM 0.55" "App. Programmers' Manual" -.SH NAME - -pam_authenticate \- authenticate a user - -.SH SYNOPSIS -.B #include -.sp -.BI "int pam_authenticate(pam_handle_t " *pamh ", int " flags ");" -.sp 2 -.SH DESCRIPTION -.B pam_authenticate - -.br -Use this function to authenticate an applicant user. It is linked -.I dynamically -to the authentication modules by -.BR Linux-PAM ". " -It is the task of these module to perform such an authentication. The -specific nature of the authentication is not the concern of the -application. - -.br -Following successful completion, the -.BR name -of the authenticated user will be present in the -.BR Linux-PAM -item -.BR PAM_USER ". " -This item may be recovered with a call to -.BR pam_get_item "(3)." - -.br -The application developer should note that the modules may request -that the user enter their username via the conversation mechanism (see -.BR pam_start "(3))." -Should this be the case, the user-prompt string can be set via -the -.BR PAM_USER_PROMPT -item (see -.BR pam_set_item "(3))." - -.SH "RETURN VALUE" -On success -.BR PAM_SUCCESS -is returned. All other returns should be considered -authentication failures and will be -.I delayed -by an amount specified with prior calls to -.BR pam_fail_delay "(3). " -Specific failures that demand special attention are the following: +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_AUTHENTICATE" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_authenticate \- account authentication +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 21 +\fBint\ \fBpam_authenticate\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_authenticate\fR +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 PAM service module may request that the user enter their username vio the the conversation mechanism (see +\fBpam_start\fR(3) +and +\fBpam_conv\fR(3)). The name of the authenticated user will be present in the PAM item PAM_USER. This item may be recovered with a call to +\fBpam_get_item\fR(3). +.PP +The +\fIpamh\fR +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: +.TP +PAM_SILENT +Do not emit any messages. +.TP +PAM_DISALLOW_NULL_AUTHTOK +The PAM module service should return PAM_AUTH_ERR if the user does not have a registered authentication token. +.SH "RETURN VALUES" +.TP +PAM_ABORT +The application should exit immediately after calling +\fBpam_end\fR(3) +first. +.TP +PAM_AUTH_ERR +The user was not authenticated. .TP -.B PAM_ABORT -the application should exit immediately. Of course, -.BR pam_end "(3)" -should be called first. - +PAM_CRED_INSUFFICIENT +For some reason the application does not have sufficient credentials to authenticate the user. .TP -.B PAM_MAXTRIES -the application has tried too many times to authenticate the -user, authentication should not be attempted again. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - +PAM_AUTHINFO_UNVAIL +The modules were not able to access the authentication information. This might be due to a network or hardware failure etc. +.TP +PAM_MAXTRIES +One or more of the authentication modules has reached its limit of tries authenticating the user. Do not try again. +.TP +PAM_SUCCESS +The user was successfully authenticated. +.TP +PAM_USER_UNKNOWN +User unknown to authentication service. .SH "SEE ALSO" - -.BR pam_start "(3), " -.BR pam_get_item "(3) " -.BR pam_fail_delay "(3) " -and -.BR pam_strerror "(3). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " +.PP +\fBpam_start\fR(3), +\fBpam_setcred\fR(3), +\fBpam_chauthtok\fR(3), +\fBpam_strerror\fR(3), +\fBpam\fR(8) diff --git a/doc/man/pam_authenticate.3.xml b/doc/man/pam_authenticate.3.xml new file mode 100644 index 00000000..c5ed777b --- /dev/null +++ b/doc/man/pam_authenticate.3.xml @@ -0,0 +1,169 @@ + + + + + pam_authenticate + 3 + Linux-PAM Manual + + + + pam_authenticate + account authentication + + + + + + + #include <security/pam_appl.h> + + int pam_authenticate + pam_handle_t *pamh + int flags + + + + + + + DESCRIPTION + + The pam_authenticate 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. + + + The PAM service module may request that the user enter their + username vio the the conversation mechanism (see + + pam_start3 + and + + pam_conv3 + ). The name of the authenticated user + will be present in the PAM item PAM_USER. This item may be + recovered with a call to + + pam_get_item3 + . + + + The pamh 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: + + + + PAM_SILENT + + + Do not emit any messages. + + + + + PAM_DISALLOW_NULL_AUTHTOK + + + The PAM module service should return PAM_AUTH_ERR + if the user does not have a registered authentication token. + + + + + + + + RETURN VALUES + + + PAM_ABORT + + + The application should exit immediately after calling + + pam_end3 + first. + + + + + PAM_AUTH_ERR + + + The user was not authenticated. + + + + + PAM_CRED_INSUFFICIENT + + + For some reason the application does not have sufficient + credentials to authenticate the user. + + + + + PAM_AUTHINFO_UNVAIL + + + The modules were not able to access the authentication + information. This might be due to a network or hardware + failure etc. + + + + + PAM_MAXTRIES + + + One or more of the authentication modules has reached its + limit of tries authenticating the user. Do not try again. + + + + + PAM_SUCCESS + + + The user was successfully authenticated. + + + + + PAM_USER_UNKNOWN + + + User unknown to authentication service. + + + + + + + + SEE ALSO + + + pam_start3 + , + + pam_setcred3 + , + + pam_chauthtok3 + , + + pam_strerror3 + , + + pam8 + + + + diff --git a/doc/man/pam_chauthtok.3 b/doc/man/pam_chauthtok.3 index 63904da3..8264da14 100644 --- a/doc/man/pam_chauthtok.3 +++ b/doc/man/pam_chauthtok.3 @@ -1,101 +1,65 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1997 -.TH PAM_CHAUTHTOK 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual" -.SH NAME - +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_CHAUTHTOK" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" pam_chauthtok \- updating authentication tokens - -.SH SYNOPSIS -.B #include -.sp -.BI "int pam_chauthtok(pam_handle_t " *pamh ", int " flags ");" -.sp 2 -.SH DESCRIPTION -.B pam_chauthtok - -.br -Use this function to rejuvenate the authentication tokens (passwords -etc.) of an applicant user. - -.br -Note, the application should not pre-authenticate the user, as this is -performed (if required) by the -.BR Linux-PAM -framework. - -.br +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 18 +\fBint\ \fBpam_chauthtok\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP The -.I flags -argument can -.I optionally -take the value, -.BR PAM_CHANGE_EXPIRED_AUTHTOK "." -In such cases the framework is only required to update those -authentication tokens that have expired. Without this argument, the -framework will attempt to obtain new tokens for all configured -authentication mechanisms. The details of the types and number of such -schemes should not concern the calling application. - -.SH RETURN VALUE -A successful return from this function will be indicated with -.BR PAM_SUCCESS "." - -.br -Specific errors of special interest when calling this function are - -.br -.BR PAM_AUTHTOK_ERROR -- a valid new token was not obtained - -.br -.BR PAM_AUTHTOK_RECOVERY_ERR -- old authentication token was not available - -.br -.BR PAM_AUTHTOK_LOCK_BUSY -- a resource needed to update the token was locked (try again later) - -.br -.BR PAM_AUTHTOK_DISABLE_AGING -- one or more of the authentication modules does not honor -authentication token aging - -.br -.BR PAM_TRY_AGAIN -- one or more authentication mechanism is not prepared to update a -token at this time - -.br -In general other return values may be returned. They should be treated -as indicating failure. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - +\fBpam_chauthtok\fR +function is used to change the authentication token for a given user (as indicated by the state associated with the handle +\fIpamh\fR. +.PP +The +\fIpamh\fR +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: +.TP +PAM_SILENT +Do not emit any messages. +.TP +PAM_CHANGE_EXPIRED_AUTHTOK +This argument indicates to the modules that the users 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. +.SH "RETURN VALUES" +.TP +PAM_AUTHTOK_ERR +A module was unable to obtain the new authentication token. +.TP +PAM_AUTHTOK_RECOVERY_ERR +A module was unable to obtain the old authentication token. +.TP +PAM_AUTHTOK_LOCK_BUSY +One or more of the modules was unable to change the authentication token since it is currently locked. +.TP +PAM_AUTHTOK_DISABLE_AGING +Authentication token aging has been disabled for at least one of the modules. +.TP +PAM_PERM_DENIED +Permission denied. +.TP +PAM_SUCCESS +The authentication token was successfully updated. +.TP +PAM_TRY_AGAIN +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. +.TP +PAM_USER_UNKNOWN +User unknown to password service. .SH "SEE ALSO" - -.BR pam_start "(3), " -.BR pam_authenticate "(3), " -.BR pam_setcred "(3), " -.BR pam_get_item "(3), " -.BR pam_strerror "(3) " -and -.BR pam "(8)." - -.br -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " +.PP +\fBpam_start\fR(3), +\fBpam_authenticate\fR(3), +\fBpam_setcred\fR(3), +\fBpam_get_item\fR(3), +\fBpam_strerror\fR(3), +\fBpam\fR(8) diff --git a/doc/man/pam_chauthtok.3.xml b/doc/man/pam_chauthtok.3.xml new file mode 100644 index 00000000..e1bf67d0 --- /dev/null +++ b/doc/man/pam_chauthtok.3.xml @@ -0,0 +1,164 @@ + + + + + pam_chauthtok + 3 + Linux-PAM Manual + + + + pam_chauthtok + updating authentication tokens + + + + + + + #include <security/pam_appl.h> + + int pam_chauthtok + pam_handle_t *pamh + int flags + + + + + + + DESCRIPTION + + The pam_chauthtok function is used to change the + authentication token for a given user (as indicated by the state + associated with the handle pamh. + + + The pamh 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: + + + + PAM_SILENT + + + Do not emit any messages. + + + + + PAM_CHANGE_EXPIRED_AUTHTOK + + + This argument indicates to the modules that the users + 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. + + + + + + + + RETURN VALUES + + + PAM_AUTHTOK_ERR + + + A module was unable to obtain the new authentication token. + + + + + PAM_AUTHTOK_RECOVERY_ERR + + + A module was unable to obtain the old authentication token. + + + + + PAM_AUTHTOK_LOCK_BUSY + + + One or more of the modules was unable to change the + authentication token since it is currently locked. + + + + + PAM_AUTHTOK_DISABLE_AGING + + + Authentication token aging has been disabled for at least + one of the modules. + + + + + PAM_PERM_DENIED + + + Permission denied. + + + + + PAM_SUCCESS + + + The authentication token was successfully updated. + + + + + PAM_TRY_AGAIN + + + 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. + + + + + PAM_USER_UNKNOWN + + + User unknown to password service. + + + + + + + + SEE ALSO + + + pam_start3 + , + + pam_authenticate3 + , + + pam_setcred3 + , + + pam_get_item3 + , + + pam_strerror3 + , + + pam8 + + + + diff --git a/doc/man/pam_close_session.3 b/doc/man/pam_close_session.3 index c809a0e4..0c10aa32 100644 --- a/doc/man/pam_close_session.3 +++ b/doc/man/pam_close_session.3 @@ -1 +1,47 @@ -.so man3/pam_open_session.3 +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_CLOSE_SESSION" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_close_session \- terminating PAM session management +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 22 +\fBint\ \fBpam_close_session\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_close_session\fR +function is used to indicate that an authenticated session has ended. The session should have been created with a call to +\fBpam_open_session\fR(3). +.PP +It should be noted that the effective uid, +\fBgeteuid\fR(2). of the application should be of sufficient privilege to perform such tasks as unmounting the user's home directory for example. +.PP +The flags argument is the binary or of zero or more of the following values: +.TP +PAM_SILENT +Do not emit any messages. +.SH "RETURN VALUES" +.TP +PAM_ABORT +General failure. +.TP +PAM_BUF_ERR +Memory buffer error. +.TP +PAM_SESSION_ERR +Session failure. +.TP +PAM_SUCCESS +Session was successful terminated. +.SH "SEE ALSO" +.PP +\fBpam_open_session\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_close_session.3.xml b/doc/man/pam_close_session.3.xml new file mode 100644 index 00000000..bfc29b2e --- /dev/null +++ b/doc/man/pam_close_session.3.xml @@ -0,0 +1,115 @@ + + + + + + + pam_close_session + 3 + Linux-PAM Manual + + + + pam_close_session + terminating PAM session management + + + + + + + #include <security/pam_appl.h> + + int pam_close_session + pam_handle_t *pamh + int flags + + + + + + + DESCRIPTION + + The pam_close_session function is used + to indicate that an authenticated session has ended. + The session should have been created with a call to + + pam_open_session3 + . + + + It should be noted that the effective uid, + + geteuid2 + . of the application should be of sufficient + privilege to perform such tasks as unmounting the + user's home directory for example. + + + The flags argument is the binary or of zero or more of the + following values: + + + + PAM_SILENT + + + Do not emit any messages. + + + + + + + + RETURN VALUES + + + PAM_ABORT + + + General failure. + + + + + PAM_BUF_ERR + + + Memory buffer error. + + + + + PAM_SESSION_ERR + + + Session failure. + + + + + PAM_SUCCESS + + + Session was successful terminated. + + + + + + + + SEE ALSO + + + pam_open_session3 + , + + pam_strerror3 + + + + diff --git a/doc/man/pam_end.3 b/doc/man/pam_end.3 index 06fdabb9..e074c6c5 100644 --- a/doc/man/pam_end.3 +++ b/doc/man/pam_end.3 @@ -1 +1,52 @@ -.so man3/pam_start.3 +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_END" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_end \- termination of PAM transaction +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 12 +\fBint\ \fBpam_end\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIpam_status\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_end\fR +function terminates the PAM transaction and is the last function an application should call in the PAM contenxt. Upon return the handle +\fIpamh\fR +is no longer valid and all memory associated with it will be invalid. +.PP +The +\fIpam_status\fR +argument should be set to the value returned to the application by the last PAM library call. +.PP +The value taken by +\fIpam_status\fR +is used as an argument to the module specific callback function, +\fBcleanup()\fR +(See +\fBpam_set_data\fR(3) +and +\fBpam_get_data\fR(3)). 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 +\fIPAM_DATA_SILENT\fR +to indicate 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 +\fBfork\fR(2)ed process, and that the parent will take care of cleaning up things that exist outside of the current process space (files etc.). +.SH "RETURN VALUES" +.TP +PAM_SUCCESS +Transaction was successful terminated. +.TP +PAM_SYSTEM_ERR +System error, for example a NULL pointer was submitted as PAM handle or the function was called by a module. +.SH "SEE ALSO" +.PP +\fBpam_get_data\fR(3), +\fBpam_set_data\fR(3), +\fBpam_start\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_end.3.xml b/doc/man/pam_end.3.xml new file mode 100644 index 00000000..64dd3900 --- /dev/null +++ b/doc/man/pam_end.3.xml @@ -0,0 +1,109 @@ + + + + + + + pam_end + 3 + Linux-PAM Manual + + + + pam_end + termination of PAM transaction + + + + + + + #include <security/pam_appl.h> + + int pam_end + pam_handle_t *pamh + int pam_status + + + + + + + DESCRIPTION + + The pam_end function terminates the PAM + transaction and is the last function an application should call + in the PAM contenxt. Upon return the handle pamh + is no longer valid and all memory associated with it will be + invalid. + + + The pam_status argument should be set to + the value returned to the application by the last PAM + library call. + + + The value taken by pam_status is used as + an argument to the module specific callback function, + cleanup() + (See + pam_set_data3 + and + + pam_get_data3 + ). 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 + PAM_DATA_SILENT to indicate 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 + + fork2 + ed + process, and that the parent will take care of cleaning up things + that exist outside of the current process space (files etc.). + + + + RETURN VALUES + + + PAM_SUCCESS + + + Transaction was successful terminated. + + + + + PAM_SYSTEM_ERR + + + System error, for example a NULL pointer was submitted + as PAM handle or the function was called by a module. + + + + + + + + SEE ALSO + + + pam_get_data3 + , + + pam_set_data3 + , + + pam_start3 + , + + pam_strerror3 + + + + diff --git a/doc/man/pam_fail_delay.3 b/doc/man/pam_fail_delay.3 index f6cd238a..8e1cd09d 100644 --- a/doc/man/pam_fail_delay.3 +++ b/doc/man/pam_fail_delay.3 @@ -1,130 +1,108 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1997 -.TH PAM_FAIL_DELAY 3 "1997 Jan 12" "Linux-PAM 0.56" "Programmers' Manual" -.SH NAME - +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_FAIL_DELAY" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" pam_fail_delay \- request a delay on failure - -.SH SYNOPSIS -.B #include -.br -or, -.br -.B #include -.sp -.BI "int pam_fail_delay(pam_handle_t " "*pamh" ", unsigned int " "usec" ");" -.sp 2 -.SH DESCRIPTION -.br -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 -.I short -timeouts, it may prove possible to attempt a -.I brute force -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 -.I covert channel -of useful information. - -.br -To minimize the effectiveness of such attacks, it is desirable to -introduce a random delay in a failed authentication process. -.B Linux-PAM -provides such a facility. The delay occurs upon failure of the -.BR pam_authenticate "(3) " -and -.BR pam_chauthtok "(3) " -functions. It occurs -.I after +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 19 +\fBint\ \fBpam_fail_delay\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBunsigned\ int\ \fR\fB\fIusec\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_fail_delay\fR +function provides a mechanism by which an application or module can suggest a minimum delay of +\fIusec\fR +micro\-seconds. The function keeps a record of the longest time requested with this function. Should +\fBpam_authenticate\fR(3) +fail, the failing return to the application is delayed by an amount of time randomly distributed (by up to 25%) about this longest value. +.PP +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 +\fIafter\fR all authentication modules have been called, but -.I before +\fIbefore\fR control is returned to the service application. - -.br -The function, -.BR pam_fail_delay "(3)," -is used to specify a required minimum for the length of the -failure-delay; the -.I usec -argument. This function can be called by the service application -and/or the authentication modules, both may have an interest in -delaying a reapplication for service by the user. The length of the -delay is computed at the time it is required. Its length is -pseudo-gausianly distributed about the -.I maximum -requested value; the resultant delay will differ by as much as 25% of -this maximum requested value (both up and down). - -.br -On return from -.BR pam_authenticate "(3) or " pam_chauthtok "(3)," -independent of success or failure, the new requested delay is reset to -its default value: zero. - -.SH EXAMPLE -.br -For example, a -.B login -application may require a failure delay of roughly 3 seconds. It will -contain the following code: +.PP +When using this function the application programmer should check if it is available with: .sp -.br -.B " pam_fail_delay(pamh, 3000000 /* micro-seconds */ );" -.br -.B " pam_authenticate(pamh, 0);" +.nf +#ifdef PAM_FAIL_DELAY + .... +#endif /* PAM_FAIL_DELAY */ + +.fi +.PP +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 +\fIPAM_FAIL_DELAY\fR +item. It can be queried and set with +\fBpam_get_item\fR(3) +and +\fBpam_set_item \fR(3) +respectively. The value used to set it should be a function pointer of the following prototype: .sp -.br -if the modules do not request a delay, the failure delay will be -between 2.25 and 3.75 seconds. - -.br -However, the modules, invoked in the authentication process, may -also request delays: +.nf +void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr); + +.fi .sp -.br -.RB " (module #1) " "pam_fail_delay(pamh, 2000000);" +The arguments being the +\fIretval\fR +return code of the module stack, the +\fIusec_delay\fR +micro\-second delay that libpam is requesting and the +\fIappdata_ptr\fR +that the application has associated with the current +\fIpamh\fR. This last value was set by the application when it called +\fBpam_start\fR(3) +or explicitly with +\fBpam_set_item\fR(3). Note, if PAM_FAIL_DELAY is unset (or set to NULL), then no delay will be performed. +.SH "RATIONALE" +.PP +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 +\fIshort\fR +timeouts, it may prove possible to attempt a +\fIbrute force\fR +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 +\fIcovert channel\fR +of useful information. +.PP +To minimize the effectiveness of such attacks, it is desirable to introduce a random delay in a failed authentication process. +.SH "EXAMPLE" +.PP +For example, a login application may require a failure delay of roughly 3 seconds. It will contain the following code: .sp -.br -.RB " (module #2) " "pam_fail_delay(pamh, 4000000);" +.nf + pam_fail_delay (pamh, 3000000 /* micro\-seconds */ ); + pam_authenticate (pamh, 0); + +.fi +.PP +if the modules do not request a delay, the failure delay will be between 2.25 and 3.75 seconds. +.PP +However, the modules, invoked in the authentication process, may also request delays: .sp -.br -in this case, it is the largest requested value that is used to -compute the actual failed delay: here between 3 and 5 seconds. - +.nf +module #1: pam_fail_delay (pamh, 2000000); +module #2: pam_fail_delay (pamh, 4000000); + +.fi +.PP +in this case, it is the largest requested value that is used to compute the actual failed delay: here between 3 and 5 seconds. .SH "RETURN VALUE" +.PP Following a successful call to -.BR pam_fail_delay "(3), " PAM_SUCCESS -is returned. All other returns should be considered serious failures. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -Under consideration by the X/Open group for future inclusion in the -PAM RFC. 1996/1/10 - -.SH BUGS -.sp 2 -none known. - +\fBpam_fail_delay\fR(3), +\fIPAM_SUCCESS\fR +is returned. All other returns should be considered serious failures. .SH "SEE ALSO" - -.BR pam_start "(3), " -.BR pam_get_item "(3) " -and -.BR pam_strerror "(3). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " +.PP +\fBpam_start\fR(3), +\fBpam_get_item\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_fail_delay.3.xml b/doc/man/pam_fail_delay.3.xml new file mode 100644 index 00000000..86d1fff4 --- /dev/null +++ b/doc/man/pam_fail_delay.3.xml @@ -0,0 +1,175 @@ + + + + + + + pam_fail_delay + 3 + Linux-PAM Manual + + + + pam_fail_delay + request a delay on failure + + + + + + + #include <security/pam_appl.h> + + int pam_fail_delay + pam_handle_t *pamh + unsigned int usec + + + + + + DESCRIPTION + + The pam_fail_delay function provides a + mechanism by which an application or module can suggest a minimum + delay of usec micro-seconds. The + function keeps a record of the longest time requested with this + function. Should + + pam_authenticate3 + fail, the failing return to the application is + delayed by an amount of time randomly distributed (by up to 25%) + about this longest value. + + + 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 after all + authentication modules have been called, but before + control is returned to the service application. + + + When using this function the application programmer should check if + it is available with: + + +#ifdef PAM_FAIL_DELAY + .... +#endif /* PAM_FAIL_DELAY */ + + + + 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 + PAM_FAIL_DELAY item. It can be queried and + set with + + pam_get_item3 + + and + + pam_set_item 3 + respectively. The value used to set it should be + a function pointer of the following prototype: + +void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr); + + The arguments being the retval return code + of the module stack, the usec_delay + micro-second delay that libpam is requesting and the + appdata_ptr that the application has associated + with the current pamh. This last value was set + by the application when it called + + pam_start3 + or explicitly with + + pam_set_item3 + . + Note, if PAM_FAIL_DELAY is unset (or set to NULL), then no delay + will be performed. + + + + + RATIONALE + + 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 short timeouts, it may prove possible + to attempt a brute force 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 covert channel + of useful information. + + + To minimize the effectiveness of such attacks, it is desirable to + introduce a random delay in a failed authentication process. + + + + + EXAMPLE + + For example, a login application may require a failure delay of + roughly 3 seconds. It will contain the following code: + + + pam_fail_delay (pamh, 3000000 /* micro-seconds */ ); + pam_authenticate (pamh, 0); + + + + if the modules do not request a delay, the failure delay will be + between 2.25 and 3.75 seconds. + + + + However, the modules, invoked in the authentication process, may + also request delays: + + + +module #1: pam_fail_delay (pamh, 2000000); +module #2: pam_fail_delay (pamh, 4000000); + + + + in this case, it is the largest requested value that is used to + compute the actual failed delay: here between 3 and 5 seconds. + + + +RETURN VALUE +Following a successful call to +pam_fail_delay3, PAM_SUCCESS +is returned. All other returns should be considered serious failures. + + + + + SEE ALSO + + + pam_start3 + , + + pam_get_item3 + , + + pam_strerror3 + + + + diff --git a/doc/man/pam_get_data.3 b/doc/man/pam_get_data.3 new file mode 100644 index 00000000..30901564 --- /dev/null +++ b/doc/man/pam_get_data.3 @@ -0,0 +1,52 @@ +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_GET_DATA" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_get_data \- get module internal data +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 17 +\fBint\ \fBpam_get_data\fR\fR\fB(\fR\fBconst\ pam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fImodule_data_name\fR\fR\fB, \fR\fBconst\ void\ **\fR\fB\fIdata\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +This function together with the +\fBpam_set_data\fR(3) +function is useful to manage module\-specific data meaningful only to the calling PAM module. +.PP +The +\fBpam_get_data\fR +function looks up the object associated with the (hopefully) unique string +\fImodule_data_name\fR +in the PAM context specified by the +\fIpamh\fR +argument. A successful call to +\fBpam_get_data\fR +will result in +\fIdata\fR +pointing to the object. Note, this data is +\fInot\fR +a copy and should be treated as +\fIconstant\fR +by the module. +.SH "RETURN VALUES" +.TP +PAM_SUCCESS +Data was successful retrieved. +.TP +PAM_SYSTEM_ERR +A NULL pointer was submitted as PAM handle or the function was called by an application. +.TP +PAM_NO_MODULE_DATA +Module data not found or there is an entry, but it has the value NULL. +.SH "SEE ALSO" +.PP +\fBpam_end\fR(3), +\fBpam_set_data\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_get_data.3.xml b/doc/man/pam_get_data.3.xml new file mode 100644 index 00000000..d0c77321 --- /dev/null +++ b/doc/man/pam_get_data.3.xml @@ -0,0 +1,108 @@ + + + + + + + pam_get_data + 3 + Linux-PAM Manual + + + + pam_get_data + + get module internal data + + + + + + + + + + #include <security/pam_modules.h> + + int pam_get_data + const pam_handle_t *pamh + const char *module_data_name + const void **data + + + + + + + + DESCRIPTION + + This function together with the + + pam_set_data3 + function + is useful to manage module-specific data meaningful only to + the calling PAM module. + + + The pam_get_data function looks up the + object associated with the (hopefully) unique string + module_data_name in the PAM context + specified by the pamh argument. + A successful call to + pam_get_data will result in + data pointing to the object. Note, + this data is not a copy and should be + treated as constant by the module. + + + + + RETURN VALUES + + + PAM_SUCCESS + + + Data was successful retrieved. + + + + + PAM_SYSTEM_ERR + + + A NULL pointer was submitted as PAM handle or the + function was called by an application. + + + + + PAM_NO_MODULE_DATA + + + Module data not found or there is an entry, but it has + the value NULL. + + + + + + + + SEE ALSO + + + pam_end3 + , + + pam_set_data3 + , + + pam_strerror3 + + + + + diff --git a/doc/man/pam_get_item.3 b/doc/man/pam_get_item.3 index 06df97bb..12ce870e 100644 --- a/doc/man/pam_get_item.3 +++ b/doc/man/pam_get_item.3 @@ -1 +1,116 @@ -.so man3/pam_set_item.3 +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_GET_ITEM" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_get_item \- getting PAM informations +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 17 +\fBint\ \fBpam_get_item\fR\fR\fB(\fR\fBconst\ pam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIitem_type\fR\fR\fB, \fR\fBconst\ void\ **\fR\fB\fIitem\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_get_item\fR +function allows applications and PAM service modules to access and retrieve PAM informations of +\fIitem_type\fR. Upon successful return, +\fIitem\fR +contains a pointer to the value of the corresponding item. Note, this is a pointer to the +\fIactual\fR +data and should +\fInot\fR +be +\fIfree()\fR'ed or over\-written! The following values are supported for +\fIitem_type\fR: +.TP +PAM_SERVICE +The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program). +.TP +PAM_USER +The username of the entity under whose identity service will be given. That is, following authentication, +\fIPAM_USER\fR +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 +\fIPAM_USER\fR +after each call to a PAM function. +.TP +PAM_USER_PROMPT +The string used when prompting for a user's name. The default value for this string is a localized version of "login: ". +.TP +PAM_TTY +The terminal name: prefixed by +\fI/dev/\fR +if it is a device file; for graphical, X\-based, applications the value for this item should be the +\fI$DISPLAY\fR +variable. +.TP +PAM_RUSER +The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user. +.sp +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. +.sp +\fIPAM_RUSER@PAM_RHOST\fR +should always identify the requesting user. In some cases, +\fIPAM_RUSER\fR +may be NULL. In such situations, it is unclear who the requesting entity is. +.TP +PAM_RHOST +The requesting hostname (the hostname of the machine from which the +\fIPAM_RUSER\fR +entity is requesting service). That is +\fIPAM_RUSER@PAM_RHOST\fR +does identify the requesting user. In some applications, +\fIPAM_RHOST\fR +may be NULL. In such situations, it is unclear where the authentication request is originating from. +.TP +PAM_AUTHTOK +The authentication token (often a password). This token should be ignored by all module functions besides +\fBpam_sm_authenticate\fR(3) +and +\fBpam_sm_chauthtok\fR(3). 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. +.TP +PAM_OLDAUTHTOK +The old authentication token. This token should be ignored by all module functions except +\fBpam_sm_chauthtok\fR(3). +.TP +PAM_CONV +The pam_conv structure. See +\fBpam_conv\fR(3). +.TP +PAM_FAIL_DELAY +A function pointer to redirect centrally managed failure delays. See +\fBpam_fail_delay\fR(3). +.PP +If a service module wishes to obtain the name of the user, it should not use this function, but instead perform a call to +\fBpam_get_user\fR(3). +.PP +Only a service module is privileged to read the authentication tokens, PAM_AUTHTOK and PAM_OLDAUTHTOK. +.SH "RETURN VALUES" +.TP +PAM_BAD_ITEM +The application attempted to set an undefined or inaccessible item. +.TP +PAM_BUF_ERR +Memory buffer error. +.TP +PAM_PERM_DENIED +The value of +\fIitem\fR +was NULL. +.TP +PAM_SUCCESS +Data was successful updated. +.TP +PAM_SYSTEM_ERR +The +\fIpam_handle_t\fR +passed as first argument was invalid. +.SH "SEE ALSO" +.PP +\fBpam_set_item\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_get_item.3.xml b/doc/man/pam_get_item.3.xml new file mode 100644 index 00000000..2f7fca5b --- /dev/null +++ b/doc/man/pam_get_item.3.xml @@ -0,0 +1,134 @@ + + +--> +]> + + + + + pam_get_item + 3 + Linux-PAM Manual + + + + pam_get_item + + getting PAM informations + + + + + + + + + + #include <security/pam_modules.h> + + int pam_get_item + const pam_handle_t *pamh + int item_type + const void **item + + + + + + + + DESCRIPTION + + The pam_get_item function allows applications + and PAM service modules to access and retrieve PAM informations + of item_type. Upon successful return, + item contains a pointer to the value of the + corresponding item. Note, this is a pointer to the + actual data and should + not be free()'ed or + over-written! The following values are supported for + item_type: + + + + + + If a service module wishes to obtain the name of the user, + it should not use this function, but instead perform a call to + + pam_get_user3 + . + + + Only a service module is privileged to read the + authentication tokens, PAM_AUTHTOK and PAM_OLDAUTHTOK. + + + + + + RETURN VALUES + + + PAM_BAD_ITEM + + + The application attempted to set an undefined or inaccessible + item. + + + + + PAM_BUF_ERR + + + Memory buffer error. + + + + + PAM_PERM_DENIED + + + The value of item was NULL. + + + + + PAM_SUCCESS + + + Data was successful updated. + + + + + PAM_SYSTEM_ERR + + + The pam_handle_t passed as first + argument was invalid. + + + + + + + + SEE ALSO + + + pam_set_item3 + , + + pam_strerror3 + + + + + diff --git a/doc/man/pam_item_types.inc.xml b/doc/man/pam_item_types.inc.xml new file mode 100644 index 00000000..9d70087b --- /dev/null +++ b/doc/man/pam_item_types.inc.xml @@ -0,0 +1,151 @@ + + + + + PAM_SERVICE + + + The service name (which identifies that PAM stack that + the PAM functions will use to authenticate the program). + + + + + + PAM_USER + + + The username of the entity under whose identity service + will be given. That is, following authentication, + PAM_USER 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 + PAM_USER after each call to a PAM function. + + + + + + PAM_USER_PROMPT + + + The string used when prompting for a user's name. The default + value for this string is a localized version of "login: ". + + + + + + PAM_TTY + + + The terminal name: prefixed by /dev/ if + it is a device file; for graphical, X-based, applications the + value for this item should be the + $DISPLAY variable. + + + + + + PAM_RUSER + + + The requesting user name: local name for a locally + requesting user or a remote user name for a remote + requesting user. + + + Generally an application or module will attempt to supply + the value that is most strongly authenticated (a local account + before a remote one. The level of trust in this value is + embodied in the actual authentication stack associated with + the application, so it is ultimately at the discretion of the + system administrator. + + + PAM_RUSER@PAM_RHOST should always identify + the requesting user. In some cases, + PAM_RUSER may be NULL. In such situations, + it is unclear who the requesting entity is. + + + + + + PAM_RHOST + + + The requesting hostname (the hostname of the machine from + which the PAM_RUSER entity is requesting + service). That is PAM_RUSER@PAM_RHOST + does identify the requesting user. In some applications, + PAM_RHOST may be NULL. In such situations, + it is unclear where the authentication request is originating + from. + + + + + + PAM_AUTHTOK + + + The authentication token (often a password). This token + should be ignored by all module functions besides + + pam_sm_authenticate3 + and + + pam_sm_chauthtok3 + . + 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. + + + + + + PAM_OLDAUTHTOK + + + The old authentication token. This token should be ignored + by all module functions except + + pam_sm_chauthtok3 + . + + + + + + + PAM_CONV + + + The pam_conv structure. See + + pam_conv3 + . + + + + + + PAM_FAIL_DELAY + + + A function pointer to redirect centrally managed + failure delays. See + + pam_fail_delay3 + . + + + + + diff --git a/doc/man/pam_open_session.3 b/doc/man/pam_open_session.3 index 4e63b5c4..ef6d545d 100644 --- a/doc/man/pam_open_session.3 +++ b/doc/man/pam_open_session.3 @@ -1,99 +1,47 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1997 -.TH PAM_OPEN_SESSION 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual" -.SH NAME - -pam_open/close_session \- PAM session management - -.SH SYNOPSIS -.B #include -.sp -.BI "int pam_open_session(pam_handle_t " *pamh ", int " flags ");" -.sp -.BI "int pam_close_session(pam_handle_t " *pamh ", int " flags ");" -.sp 2 -.SH DESCRIPTION - -PAM provides management-hooks for the initialization and termination -of a session. - +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_OPEN_SESSION" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_open_session \- start PAM session management +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 21 +\fBint\ \fBpam_open_session\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_open_session\fR +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). +.PP +It should be noted that the effective uid, +\fBgeteuid\fR(2). of the application should be of sufficient privilege to perform such tasks as creating or mounting the user's home directory for example. +.PP +The flags argument is the binary or of zero or more of the following values: .TP -.B pam_open_session -.br -Use this function to signal that an authenticated user session has -begun. It should be called only after the user is properly identified -and (where necessary) has been granted their credentials with -.BR pam_authenticate "(3)" -and -.BR pam_setcred "(3)" -respectively. - -.br -Some types of functions associated with session -initialization are logging for the purposes of system-audit and -mounting directories (the user's home directory for example). These -should not concern the application. It should be noted that the -.I effective -uid, -.BR geteuid "(2)," -of the application should be of sufficient privilege to perform such -tasks. - +PAM_SILENT +Do not emit any messages. +.SH "RETURN VALUES" .TP -.B pam_close_session -.br -Use this function to signal that a user session has -terminated. In general this function may not need to be located in the -same application as the initialization function, -.BR pam_open_session "." - -.br -Typically, this function will undo the actions of -.BR pam_open_session "." -That is, log audit information concerning the end of the user session -or unmount the user's home directory. Apart from having sufficient -privilege the details of the session termination should not concern -the calling application. It is good programming practice, however, to -cease acting on behalf of the user on returning from this call. - -.SH RETURN VALUE -A successful return from the session management functions will be -indicated with -.BR PAM_SUCCESS "." - -.br -The specific error indicating a failure to open or close a session is -.BR PAM_SESSION_ERR "." -In general other return values may be returned. They should be treated -as indicating failure. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -OSF-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - +PAM_ABORT +General failure. +.TP +PAM_BUF_ERR +Memory buffer error. +.TP +PAM_SESSION_ERR +Session failure. +.TP +PAM_SUCCESS +Session was successful created. .SH "SEE ALSO" - -.BR pam_start "(3), " -.BR pam_authenticate "(3), " -.BR pam_setcred "(3), " -.BR pam_get_item "(3), " -.BR pam_strerror "(3) " -and -.BR pam "(3)." - -.br -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " +.PP +\fBpam_close_session\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_open_session.3.xml b/doc/man/pam_open_session.3.xml new file mode 100644 index 00000000..3ae05877 --- /dev/null +++ b/doc/man/pam_open_session.3.xml @@ -0,0 +1,115 @@ + + + + + + + pam_open_session + 3 + Linux-PAM Manual + + + + pam_open_session + start PAM session management + + + + + + + #include <security/pam_appl.h> + + int pam_open_session + pam_handle_t *pamh + int flags + + + + + + + DESCRIPTION + + The pam_open_session function sets up a + user session for a previously successful authenticated user. + The session should later be terminated with a call to + + pam_close_session3 + . + + + It should be noted that the effective uid, + + geteuid2 + . of the application should be of sufficient + privilege to perform such tasks as creating or mounting the + user's home directory for example. + + + The flags argument is the binary or of zero or more of the + following values: + + + + PAM_SILENT + + + Do not emit any messages. + + + + + + + + RETURN VALUES + + + PAM_ABORT + + + General failure. + + + + + PAM_BUF_ERR + + + Memory buffer error. + + + + + PAM_SESSION_ERR + + + Session failure. + + + + + PAM_SUCCESS + + + Session was successful created. + + + + + + + + SEE ALSO + + + pam_close_session3 + , + + pam_strerror3 + + + + diff --git a/doc/man/pam_set_data.3 b/doc/man/pam_set_data.3 new file mode 100644 index 00000000..55fdeb9c --- /dev/null +++ b/doc/man/pam_set_data.3 @@ -0,0 +1,85 @@ +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_SET_DATA" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_set_data \- set module internal data +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 17 +\fBint\ \fBpam_set_data\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fImodule_data_name\fR\fR\fB, \fR\fBvoid\ *\fR\fB\fIdata\fR\fR\fB, \fR\fBvoid\ \fR\fB\fI(*cleanup)(pam_handle_t\ *pamh,\ void\ *data,\ int\ error_status)\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_set_data\fR +function associates a pointer to an object with the (hopefully) unique string +\fImodule_data_name\fR +in the PAM context specified by the +\fIpamh\fR +argument. +.PP +PAM modules may be dynamically loadable objects. In general such files should not contain +\fIstatic\fR +variables. This function and its counterpart +\fBpam_get_data\fR(3), provide a mechanism for a module to associate some data with the handle +\fIpamh\fR. Typically a module will call the +\fBpam_set_data\fR +function to register some data under a (hopefully) unique +\fImodule_data_name\fR. The data is available for use by other modules too but +\fInot\fR +by an application. Since this functions stores only a pointer to the +\fIdata\fR, the module should not modify or free the content of it. +.PP +The function +\fBcleanup()\fR +is associated with the +\fIdata\fR +and, if non\-NULL, it is called when this data is over\-written or following a call to +\fBpam_end\fR(3). +.PP +The +\fIerror_status\fR +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 +\fBpam_end\fR(3) +is called by the module, the +\fIerror_status\fR +carries the return value of the +\fBpam_authenticate\fR(3) +or other +\fIlibpam\fR +function as appropriate. Based on this value the Kerberos module may choose to delete the ticket file (\fIauthentication failure\fR) or leave it in place. +.PP +The +\fIerror_status\fR +may have been logically OR'd with either of the following two values: +.TP +PAM_DATA_REPLACE +When a data item is being replaced (through a second call to +\fBpam_set_data\fR) this mask is used. Otherwise, the call is assumed to be from +\fBpam_end\fR(3). +.TP +PAM_DATA_SILENT +Which indicates that the process would prefer to perform the +\fBcleanup()\fR +quietly. That is, discourages logging/messages to the user. +.SH "RETURN VALUES" +.TP +PAM_BUF_ERR +Memory buffer error. +.TP +PAM_SUCCESS +Data was successful stored. +.TP +PAM_SYSTEM_ERR +A NULL pointer was submitted as PAM handle or the function was called by an application. +.SH "SEE ALSO" +.PP +\fBpam_end\fR(3), +\fBpam_get_data\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_set_data.3.xml b/doc/man/pam_set_data.3.xml new file mode 100644 index 00000000..bc2f05b3 --- /dev/null +++ b/doc/man/pam_set_data.3.xml @@ -0,0 +1,172 @@ + + + + + + + pam_set_data + 3 + Linux-PAM Manual + + + + pam_set_data + + set module internal data + + + + + + + + + + #include <security/pam_modules.h> + + int pam_set_data + pam_handle_t *pamh + const char *module_data_name + void *data + void (*cleanup)(pam_handle_t *pamh, void *data, int error_status) + + + + + + + + DESCRIPTION + + The pam_set_data function associates a pointer + to an object with the (hopefully) unique string + module_data_name in the PAM context specified + by the pamh argument. + + + + PAM modules may be dynamically loadable objects. In general such files + should not contain static variables. This function + and its counterpart + + pam_get_data3 + , + provide a mechanism for a module to associate some data with + the handle pamh. Typically a module will call the + pam_set_data function to register some data + under a (hopefully) unique module_data_name. + The data is available for use by other modules too but + not by an application. Since this functions + stores only a pointer to the data, the module + should not modify or free the content of it. + + + + The function cleanup() is associated with the + data and, if non-NULL, it is called when this + data is over-written or following a call to + + pam_end3 + . + + + + The error_status 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 + + pam_end3 + + is called by the module, the error_status + carries the return value of the + + pam_authenticate3 + + or other libpam function as appropriate. Based + on this value the Kerberos module may choose to delete the ticket file + (authentication failure) or leave it in place. + + + + The error_status may have been logically + OR'd with either of the following two values: + + + + + PAM_DATA_REPLACE + + + When a data item is being replaced (through a second call to + pam_set_data) this mask is used. + Otherwise, the call is assumed to be from + + pam_end3 + . + + + + + + PAM_DATA_SILENT + + + Which indicates that the process would prefer to perform the + cleanup() quietly. That is, discourages + logging/messages to the user. + + + + + + + + RETURN VALUES + + + PAM_BUF_ERR + + + Memory buffer error. + + + + + PAM_SUCCESS + + + Data was successful stored. + + + + + PAM_SYSTEM_ERR + + + A NULL pointer was submitted as PAM handle or the + function was called by an application. + + + + + + + + SEE ALSO + + + pam_end3 + , + + pam_get_data3 + , + + pam_strerror3 + + + + + diff --git a/doc/man/pam_set_item.3 b/doc/man/pam_set_item.3 index b0582778..0fe861c6 100644 --- a/doc/man/pam_set_item.3 +++ b/doc/man/pam_set_item.3 @@ -1,55 +1,115 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996,1997 -.TH PAM_SET_ITEM 3 "2001 Jan 21" "Linux-PAM" "App. Programmers' Manual" -.SH NAME - -pam_set_item, pam_get_item \- item manipulation under PAM - -.SH SYNOPSIS -.B #include -.br -or -.br -.B #include +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_SET_ITEM" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_set_item \- set and update PAM informations +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 17 +\fBint\ \fBpam_set_item\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIitem_type\fR\fR\fB, \fR\fBconst\ void\ *\fR\fB\fIitem\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_set_item\fR +function allows applications and PAM service modules to access and to update PAM informations of +\fIitem_type\fR. For this a copy of the object pointed to by the +\fIitem\fR +argument is created. The following +\fIitem_type\fRs are supported: +.TP +PAM_SERVICE +The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program). +.TP +PAM_USER +The username of the entity under whose identity service will be given. That is, following authentication, +\fIPAM_USER\fR +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 +\fIPAM_USER\fR +after each call to a PAM function. +.TP +PAM_USER_PROMPT +The string used when prompting for a user's name. The default value for this string is a localized version of "login: ". +.TP +PAM_TTY +The terminal name: prefixed by +\fI/dev/\fR +if it is a device file; for graphical, X\-based, applications the value for this item should be the +\fI$DISPLAY\fR +variable. +.TP +PAM_RUSER +The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user. .sp -.BI "int pam_set_item(pam_handle_t " *pamh ", int " item_type ", void " *item ");" +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. .sp -.BI "int pam_get_item(const pam_handle_t " *pamh ", int " item_type ", const void " **item_p ");" -.sp 2 -.SH DESCRIPTION -.B pam_set_item -.sp -.B pam_set_item - -These functions are currently undocumented in a man page, but see the -end of this man page for more information (the PAM guides). - -On success -.BR PAM_SUCCESS -is returned, all other return values should be treated as errors. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - -.SH "SEE ALSO" - -.BR pam (8) +\fIPAM_RUSER@PAM_RHOST\fR +should always identify the requesting user. In some cases, +\fIPAM_RUSER\fR +may be NULL. In such situations, it is unclear who the requesting entity is. +.TP +PAM_RHOST +The requesting hostname (the hostname of the machine from which the +\fIPAM_RUSER\fR +entity is requesting service). That is +\fIPAM_RUSER@PAM_RHOST\fR +does identify the requesting user. In some applications, +\fIPAM_RHOST\fR +may be NULL. In such situations, it is unclear where the authentication request is originating from. +.TP +PAM_AUTHTOK +The authentication token (often a password). This token should be ignored by all module functions besides +\fBpam_sm_authenticate\fR(3) and -.BR pam_strerror "(3)." - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " +\fBpam_sm_chauthtok\fR(3). 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. +.TP +PAM_OLDAUTHTOK +The old authentication token. This token should be ignored by all module functions except +\fBpam_sm_chauthtok\fR(3). +.TP +PAM_CONV +The pam_conv structure. See +\fBpam_conv\fR(3). +.TP +PAM_FAIL_DELAY +A function pointer to redirect centrally managed failure delays. See +\fBpam_fail_delay\fR(3). +.PP +For all +\fIitem_type\fRs, other than PAM_CONV and PAM_FAIL_DELAY, +\fIitem\fR +is a pointer to a terminated character string. In the case of PAM_CONV, +\fIitem\fR +points to an initialized +\fIpam_conv\fR +structure. In the case of PAM_FAIL_DELAY, +\fIitem\fR +is a function pointer: +\fBvoid (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)\fR +.PP +Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reseted before returning to the application. Which means an application is not able to access the authentication tokens. +.SH "RETURN VALUES" +.TP +PAM_BAD_ITEM +The application attempted to set an undefined or inaccessible item. +.TP +PAM_BUF_ERR +Memory buffer error. +.TP +PAM_SUCCESS +Data was successful updated. +.TP +PAM_SYSTEM_ERR +The +\fIpam_handle_t\fR +passed as first argument was invalid. +.SH "SEE ALSO" +.PP +\fBpam_get_item\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_set_item.3.xml b/doc/man/pam_set_item.3.xml new file mode 100644 index 00000000..8390ab95 --- /dev/null +++ b/doc/man/pam_set_item.3.xml @@ -0,0 +1,127 @@ + + +--> +]> + + + + + pam_set_item + 3 + Linux-PAM Manual + + + + pam_set_item + + set and update PAM informations + + + + + + + + + + #include <security/pam_modules.h> + + int pam_set_item + pam_handle_t *pamh + int item_type + const void *item + + + + + + + + DESCRIPTION + + The pam_set_item function allows applications + and PAM service modules to access and to update PAM informations + of item_type. For this a copy + of the object pointed to by the item argument + is created. The following item_types are + supported: + + + + + + For all item_types, other than PAM_CONV and + PAM_FAIL_DELAY, item is a pointer to a <NUL> + terminated character string. In the case of PAM_CONV, + item points to an initialized + pam_conv structure. In the case of + PAM_FAIL_DELAY, item is a function pointer: + void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr) + + + + Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reseted before + returning to the application. Which means an application is not + able to access the authentication tokens. + + + + + + RETURN VALUES + + + PAM_BAD_ITEM + + + The application attempted to set an undefined or inaccessible + item. + + + + + PAM_BUF_ERR + + + Memory buffer error. + + + + + PAM_SUCCESS + + + Data was successful updated. + + + + + PAM_SYSTEM_ERR + + + The pam_handle_t passed as first + argument was invalid. + + + + + + + + SEE ALSO + + + pam_get_item3 + , + + pam_strerror3 + + + + + diff --git a/doc/man/pam_setcred.3 b/doc/man/pam_setcred.3 index 8c00fe71..22c728fb 100644 --- a/doc/man/pam_setcred.3 +++ b/doc/man/pam_setcred.3 @@ -1,79 +1,74 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996,1997 -.TH PAM_SETCRED 3 "1997 July 6" "Linux-PAM 0.58" "App. Programmers' Manual" -.SH NAME - -pam_setcred \- set the credentials for the user - -.SH SYNOPSIS -.B #include -.sp -.BI "int pam_setcred(pam_handle_t " *pamh ", int " flags ");" -.sp 2 -.SH DESCRIPTION -.B pam_setcred - -This function is used to establish, maintain and delete the -credentials of a user. It should be called after a user has been -authenticated and before a session is opened for the user (with -.BR pam_open_session "(3))." - -It should be noted that credentials come in many forms. Examples -include: group memberships; ticket-files; and Linux-PAM environment -variables. For this reason, it is important that the basic identity -of the user is established, by the application, prior to a call to -this function. For example, the default -.BR Linux-PAM -environment variables should be set and also -.BR initgroups "(2) " +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_SETCRED" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_setcred \- establish / delete user credentials +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 16 +\fBint\ \fBpam_setcred\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_setcred\fR +function is used to establish, maintain and delete the credentials of a user. It should be called after a user has been authenticated and before a session is opened for the user (with +\fBpam_open_session\fR(3)). +.PP +A credential is something that the user possesses. It is some property, such as a +\fIKerberos\fR +ticket, or a supplementary group membership that make up the uniqueness of a given user. On a Linux system the user's +\fIUID\fR +and +\fIGID\fR'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, +\fBinitgroups\fR(2) (or equivalent) should have been performed. - -.SH "VALID FLAGS" +.PP +Valid +\fIflags\fR, any one of which, may be logically OR'd with +\fBPAM_SILENT\fR, are: .TP -.BR PAM_ESTABLISH_CRED -initialize the credentials for the user. - +PAM_ESTABLISH_CRED +Initialize the credentials for the user. .TP -.BR PAM_DELETE_CRED -delete the user's credentials. - +PAM_DELETE_CRED +Delete the user's credentials. .TP -.BR PAM_REINITIALIZE_CRED -delete and then initialize the user's credentials. - +PAM_REINITIALIZE_CRED +Fully reinitialize the user's credentials. .TP -.BR PAM_REFRESH_CRED -extend the lifetime of the existing credentials. - +PAM_REFRESH_CRED +Extend the lifetime of the existing credentials. .SH "RETURN VALUE" - -On success -.BR PAM_SUCCESS -is returned, all other return values should be treated as errors. - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - +.TP +PAM_BUF_ERR +Memory buffer error. +.TP +PAM_CRED_ERR +Failed to set user credentials. +.TP +PAM_CRED_EXPIRED +User credentials are expired. +.TP +PAM_CRED_UNAVAIL +Failed to retrieve user credentials. +.TP +PAM_SUCCESS +Data was successful stored. +.TP +PAM_SYSTEM_ERR +A NULL pointer was submitted as PAM handle, the function was called by a module or another system error occured. +.TP +PAM_USER_UNKNOWN +User is not known to an authentication module. .SH "SEE ALSO" - -.BR pam_authenticate "(3), " -.BR pam_strerror "(3)" -and -.BR pam_open_session "(3). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " +.PP +\fBpam_authenticate\fR(3), +\fBpam_open_session\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_setcred.3.xml b/doc/man/pam_setcred.3.xml new file mode 100644 index 00000000..5ecbeec5 --- /dev/null +++ b/doc/man/pam_setcred.3.xml @@ -0,0 +1,173 @@ + + + + + + + pam_setcred + 3 + Linux-PAM Manual + + + + pam_setcred + + establish / delete user credentials + + + + + + + #include <security/pam_appl.h> + + int pam_setcred + pam_handle_t *pamh + int flags + + + + + + + DESCRIPTION + + The pam_setcred function is used to establish, + maintain and delete the credentials of a user. It should be called + after a user has been authenticated and before a session is opened + for the user (with + + pam_open_session3 + ). + + + + A credential is something that the user possesses. It is some + property, such as a Kerberos ticket, or a + supplementary group membership that make up the uniqueness of a + given user. On a Linux system the user's UID + and GID'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, + + initgroups2 + (or equivalent) should have been performed. + + + + Valid flags, any one of which, may be + logically OR'd with , are: + + + + + PAM_ESTABLISH_CRED + + Initialize the credentials for the user. + + + + PAM_DELETE_CRED + + Delete the user's credentials. + + + + PAM_REINITIALIZE_CRED + + Fully reinitialize the user's credentials. + + + + PAM_REFRESH_CRED + + Extend the lifetime of the existing credentials. + + + + + + + RETURN VALUE + + + PAM_BUF_ERR + + + Memory buffer error. + + + + + PAM_CRED_ERR + + + Failed to set user credentials. + + + + + PAM_CRED_EXPIRED + + + User credentials are expired. + + + + + PAM_CRED_UNAVAIL + + + Failed to retrieve user credentials. + + + + + PAM_SUCCESS + + + Data was successful stored. + + + + + PAM_SYSTEM_ERR + + + A NULL pointer was submitted as PAM handle, the + function was called by a module or another system + error occured. + + + + + PAM_USER_UNKNOWN + + + User is not known to an authentication module. + + + + + + + + + SEE ALSO + + + pam_authenticate3 + , + + pam_open_session3 + , + + pam_strerror3 + + + + diff --git a/doc/man/pam_start.3 b/doc/man/pam_start.3 index 9c11fd73..ac6454b7 100644 --- a/doc/man/pam_start.3 +++ b/doc/man/pam_start.3 @@ -1,98 +1,72 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996-7 -.TH PAM_START 3 "1997 Feb 15" "Linux-PAM 0.56" "Application Programmers' Manual" -.SH NAME - -pam_start, pam_end \- activating Linux-PAM - -.SH SYNOPSIS -.B #include -.sp -.BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");" -.sp -.BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");" -.sp 2 -.SH DESCRIPTION +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_START" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_start \- initialization of PAM transaction +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 14 +\fBint\ \fBpam_start\fR\fR\fB(\fR\fBconst\ char\ *\fR\fB\fIservice_name\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fIuser\fR\fR\fB, \fR\fBconst\ struct\ pam_conv\ *\fR\fB\fIpam_conversation\fR\fR\fB, \fR\fBpam_handle_t\ **\fR\fB\fIpamh\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_start\fR +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. +.PP +The +\fIservice_name\fR +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 +\fI/etc/pam.d/service_name\fR +or, if that file does not exist, from +\fI/etc/pam.conf\fR. +.PP +The +\fIuser\fR +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. +.PP +The +\fIpam_conversation\fR +argument points to a +\fIstruct pam_conv\fR +describing the conversation function to use. An application must provide this for direct communication between a loaded module and the application. +.PP +Following a successful return (PAM_SUCCESS) the contents of +\fIpamh\fR +is a handle that contains the PAM context for successive calls to the PAM functions. In an error case is the content of +\fIpamh\fR +undefined. +.PP +The +\fIpam_handle_t\fR +is a blind structure and the application should not attempt to probe it directly for information. Instead the PAM library provides the functions +\fBpam_set_item\fR(3) +and +\fBpam_get_item\fR(3). The PAM handle cannot be used for mulitiple authentications at the same time as long as +\fBpam_end\fR +was not called on it before. +.SH "RETURN VALUES" .TP -.B pam_start -Initialize the -.I Linux-PAM -library. Identifying the application with a particular -.IR service -name. The -.IR user "name" -can take the value -.IR NULL ", " -if not known at the time the interface is initialized. The -conversation structure is passed to the library via the -.IR conv -argument. (For a complete description of this and other structures -the reader is directed to the more verbose -.IR Linux-PAM -application developers' guide). Upon successful initialization, an -opaque pointer-handle for future access to the library is returned -through the contents of the -.IR pamh_p -pointer. - +PAM_ABORT +General failure. .TP -.B pam_end -Terminate the -.B Linux-PAM -library. The service application associated with the -.IR pamh -handle, is terminated. The argument, -.IR pam_status ", " -passes the value most recently returned to the application from the -library; it indicates the manner in which the library should be -shutdown. Besides carrying a return value, this argument may be -logically OR'd with -.IR PAM_DATA_SILENT -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 -.IR fork "(2)ed" -process, and that the parent will take care of cleaning up things that -exist outside of the current process space (files etc.). - -.SH "RETURN VALUE" +PAM_BUF_ERR +Memory buffer error. .TP -.B pam_start +PAM_SUCCESS +Transaction was successful created. .TP -.B pam_end -On success, -.BR PAM_SUCCESS -is returned - -.SH ERRORS -May be translated to text with -.BR pam_strerror "(3). " - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. -.sp -Note, the -.BR PAM_DATA_SILENT -flag is pending acceptance with the DCE (as of 1996/12/4). - -.SH BUGS -.sp 2 -None known. - +PAM_SYSTEM_ERR +System error, for example a NULL pointer was submitted instead of a pointer to data. .SH "SEE ALSO" - -.BR fork "(2), " -.BR pam_authenticate "(3), " -.BR pam_acct_mgmt "(3), " -.BR pam_open_session "(3), " -and -.BR pam_chauthtok "(3)." - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " +.PP +\fBpam_get_data\fR(3), +\fBpam_set_data\fR(3), +\fBpam_end\fR(3), +\fBpam_strerror\fR(3) diff --git a/doc/man/pam_start.3.xml b/doc/man/pam_start.3.xml new file mode 100644 index 00000000..2850b15d --- /dev/null +++ b/doc/man/pam_start.3.xml @@ -0,0 +1,143 @@ + + + + + + + pam_start + 3 + Linux-PAM Manual + + + + pam_start + initialization of PAM transaction + + + + + + + #include <security/pam_appl.h> + + int pam_start + const char *service_name + const char *user + const struct pam_conv *pam_conversation + pam_handle_t **pamh + + + + + + + DESCRIPTION + + The pam_start 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 service_name 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 /etc/pam.d/service_name or, if that file + does not exist, from /etc/pam.conf. + + + + The user 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. + + + + The pam_conversation argument points to + a struct pam_conv describing the + conversation function to use. An application must provide this + for direct communication between a loaded module and the + application. + + + + Following a successful return (PAM_SUCCESS) the contents of + pamh is a handle that contains the PAM + context for successive calls to the PAM functions. In an error + case is the content of pamh undefined. + + + + The pam_handle_t is a blind structure and + the application should not attempt to probe it directly for + information. Instead the PAM library provides the functions + + pam_set_item3 + and + + pam_get_item3 + . + The PAM handle cannot be used for mulitiple authentications at the + same time as long as pam_end was not called on + it before. + + + + RETURN VALUES + + + PAM_ABORT + + + General failure. + + + + + PAM_BUF_ERR + + + Memory buffer error. + + + + + PAM_SUCCESS + + + Transaction was successful created. + + + + + PAM_SYSTEM_ERR + + + System error, for example a NULL pointer was submitted + instead of a pointer to data. + + + + + + + + SEE ALSO + + + pam_get_data3 + , + + pam_set_data3 + , + + pam_end3 + , + + pam_strerror3 + + + + diff --git a/doc/man/pam_strerror.3 b/doc/man/pam_strerror.3 index 01ee0635..1a096baf 100644 --- a/doc/man/pam_strerror.3 +++ b/doc/man/pam_strerror.3 @@ -1,51 +1,28 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" ripped off from Rick Faith's getgroups man page -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1996-7 -.TH PAM_STRERROR 3 "1999 Oct 4" "Linux-PAM 0.70" "Programmers' Manual" -.SH NAME - -pam_strerror \- return a textual description of a Linux-PAM error - -.SH SYNOPSIS -.B #include -.br -or, -.br -.B #include -.sp -.BI "const char * pam_strerror( pam_handle_t " "*pamh" ", int " pam_error ");" -.sp 2 -.SH DESCRIPTION -.B pam_strerror - -This function returns some text describing the -.BR Linux-PAM -error associated with the -.B pam_error -argument. - -.SH "RETURN VALUE" - -On success this function returns a description of the indicated -error. Should the function not recognize the error, ``Unknown -Linux-PAM error'' is returned. - -.SH "CONFORMING TO" -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -This function should be internationalized. - +.\" ** You probably do not want to edit this file directly ** +.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). +.\" Instead of manually editing it, you probably should edit the DocBook XML +.\" source for it and then use the DocBook XSL Stylesheets to regenerate it. +.TH "PAM_STRERROR" "3" "02/08/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" +pam_strerror \- return string describing PAM error code +.SH "SYNOPSIS" +.PP +\fB#include \fR +.HP 25 +\fBconst\ char\ *\fBpam_strerror\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIerrnum\fR\fR\fB);\fR +.SH "DESCRIPTION" +.PP +The +\fBpam_strerror\fR +function returns a pointer to a string describing the error code passed in the argument +\fIerrnum\fR, 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. +.SH "RETURN VALUES" +.PP +This function returns always a pointer to a string. .SH "SEE ALSO" - -.BR pam "(8). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " +.PP +\fBpam\fR(8) diff --git a/doc/man/pam_strerror.3.xml b/doc/man/pam_strerror.3.xml new file mode 100644 index 00000000..bc488a21 --- /dev/null +++ b/doc/man/pam_strerror.3.xml @@ -0,0 +1,58 @@ + + + + + + + pam_strerror + 3 + Linux-PAM Manual + + + + pam_strerror + return string describing PAM error code + + + + + + + #include <security/pam_appl.h> + + const char *pam_strerror + pam_handle_t *pamh + int errnum + + + + + + + DESCRIPTION + + The pam_strerror function returns a pointer to + a string describing the error code passed in the argument + errnum, 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. + + + + RETURN VALUES + + This function returns always a pointer to a string. + + + + + SEE ALSO + + + pam8 + + + + diff --git a/doc/man/template-man b/doc/man/template-man deleted file mode 100644 index b8159eb6..00000000 --- a/doc/man/template-man +++ /dev/null @@ -1,52 +0,0 @@ -.\" Hey Emacs! This file is -*- nroff -*- source. -.\" $Id$ -.\" Copyright (c) Andrew G. Morgan 1997 -.TH PAM_???? 2 "1997 Jan 4" "Linux-PAM 0.55" "Application Programmers' Manual" -.SH NAME - -function names \- brief summary of function - -.SH SYNOPSIS -.B #include -.sp -.BI "int pam_???(pam_handle_t " pamh ", int " flags); -.sp 2 -.SH DESCRIPTION -.TP -.B pam_??? -Here goes the -.I explanation -it may be quite -.IR long . -.TP -.SH "RETURN VALUE" -.B pam_??? -On success... -.BR PAM_SUCCESS -is returned -.TP -.SH ERRORS -May be translated to text with -.BR pam_strerror "(2). " - -.SH "CONFORMING TO" -.B pam_??? -DCE-RFC 86.0, October 1995. - -.SH BUGS -.sp 2 -none known. - -.SH "SEE ALSO" - -.BR pam_??? "(2), " -and -.BR pam_??? "(2). " - -Also, see the three -.BR Linux-PAM -Guides, for -.BR "System administrators" ", " -.BR "module developers" ", " -and -.BR "application developers" ". " -- cgit v1.2.3