From 1cbeedd65b10f4eee830e3d222519b2701050f77 Mon Sep 17 00:00:00 2001 From: Thorsten Kukuk Date: Thu, 22 Jun 2006 19:44:29 +0000 Subject: Relevant BUGIDs: Purpose of commit: bugfix Commit summary: --------------- 2006-06-23 Thorsten Kukuk * modules/pam_access/access.conf.5.xml: Fix syntax for SAG. * modules/pam_access/pam_access.8.xml: Likewise. * modules/pam_deny/pam_deny.8.xml: Likewise. * modules/pam_echo/pam_echo.8.xml: Likewise. * modules/pam_env/pam_env.8.xml: Likewise. * modules/pam_env/pam_env.conf.5.xml: Likewise. * modules/pam_group/group.conf.5.xml: Likewise. * modules/pam_group/pam_group.8.xml: Likewise. * modules/pam_limits/limits.conf.5.xml: Likewise. * modules/pam_listfile/pam_listfile.8.xml: Likewise. * modules/pam_succeed_if/pam_succeed_if.8.xml: Likewise. * modules/pam_time/pam_time.8.xml: Likewise. * modules/pam_time/time.conf.5.xml: Likewise. * modules/pam_access/access.conf.5: Regenerate. * modules/pam_access/pam_access.8: Likewise. * modules/pam_deny/pam_deny.8: Likewise. * modules/pam_echo/README: Likewise. * modules/pam_echo/pam_echo.8: Likewise. * modules/pam_env/pam_env.8: Likewise. * modules/pam_env/pam_env.conf.5: Likewise. * modules/pam_group/README: Likewise. * modules/pam_group/group.conf.5: Likewise. * modules/pam_group/pam_group.8: Likewise. * modules/pam_limits/limits.conf.5: Likewise. * modules/pam_listfile/README: Likewise. * modules/pam_listfile/pam_listfile.8: Likewise. * modules/pam_succeed_if/pam_succeed_if.8: Likewise. * modules/pam_time/pam_time.8: Likewise. * modules/pam_time/time.conf.5: Likewise. * doc/man/Makefile.am: Add pam.conf-desc.xml, pam.conf-dir.xml and pam.conf-syntax.xml. * doc/man/pam.conf.5.xml: Split into different pieces for SAG. * doc/man/pam.conf.5: Regenerated. * doc/man/pam.conf-desc.xml: New. * doc/man/pam.conf-dir.xml: New. * doc/man/pam.conf-syntax.xml: New. --- doc/man/Makefile.am | 4 +- doc/man/pam.conf-desc.xml | 21 +++ doc/man/pam.conf-dir.xml | 30 ++++ doc/man/pam.conf-syntax.xml | 372 ++++++++++++++++++++++++++++++++++++++++ doc/man/pam.conf.5 | 18 +- doc/man/pam.conf.5.xml | 410 +------------------------------------------- 6 files changed, 449 insertions(+), 406 deletions(-) create mode 100644 doc/man/pam.conf-desc.xml create mode 100644 doc/man/pam.conf-dir.xml create mode 100644 doc/man/pam.conf-syntax.xml (limited to 'doc') diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 3ce244a9..78b9e66c 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -36,10 +36,12 @@ XMLS = pam.3.xml pam.8.xml \ pam_sm_close_session.3.xml pam_sm_open_session.3.xml \ pam_sm_setcred.3.xml pam_start.3.xml pam_strerror.3.xml \ pam_sm_chauthtok.3.xml \ - pam_item_types.inc.xml + pam_item_types.inc.xml \ + pam.conf-desc.xml pam.conf-dir.xml pam.conf-syntax.xml if ENABLE_REGENERATE_MAN pam_get_item.3: pam_item_types.inc.xml pam_set_data.3: pam_item_types.inc.xml +pam.conf.5: pam.conf-desc.xml pam.conf-dir.xml pam.conf-syntax.xml -include $(top_srcdir)/Make.xml.rules endif diff --git a/doc/man/pam.conf-desc.xml b/doc/man/pam.conf-desc.xml new file mode 100644 index 00000000..909dcdbe --- /dev/null +++ b/doc/man/pam.conf-desc.xml @@ -0,0 +1,21 @@ + + +
+ + When a 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. The presence of this + directory will cause Linux-PAM to ignore + /etc/pam.conf. + + + 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. + +
diff --git a/doc/man/pam.conf-dir.xml b/doc/man/pam.conf-dir.xml new file mode 100644 index 00000000..8446cf35 --- /dev/null +++ b/doc/man/pam.conf-dir.xml @@ -0,0 +1,30 @@ + + +
+ + More flexible than the single configuration file is it to + configure libpam via the contents of the + /etc/pam.d/ directory. In this case the + directory is filled with files each of which has a filename + equal to a service-name (in lower-case): it is the personal + configuration file for the named service. + + + + The syntax of each file in /etc/pam.d/ is similar to that of the + /etc/pam.conf file and is made up of lines + of the following form: + + + +type control module-path module-arguments + + + + The only difference being that the service-name is not present. The + service-name is of course the name of the given configuration file. + For example, /etc/pam.d/login contains the + configuration for the login service. + +
diff --git a/doc/man/pam.conf-syntax.xml b/doc/man/pam.conf-syntax.xml new file mode 100644 index 00000000..b422cba9 --- /dev/null +++ b/doc/man/pam.conf-syntax.xml @@ -0,0 +1,372 @@ + + + +
+ + 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 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 + + + this module type performs non-authentication based account + management. It is typically used to restrict/permit access + to a service based on the time of day, currently available + system resources (maximum number of users) or perhaps the + location of the applicant user -- 'root' login only on the + console. + + + + + auth + + + this module type provides two aspects of authenticating + the user. Firstly, it establishes that the user is who they + claim to be, by instructing the application to prompt the user + for a password or other means of identification. Secondly, the + module can grant group membership or other privileges through + its credential granting properties. + + + + + password + + + this module type is required for updating the authentication + token associated with the user. Typically, there is one module + for each 'challenge/response' based authentication (auth) type. + + + + + session + + + this module type is associated with doing things that need to + be done for the user before/after they can be given service. + Such things include the logging of information concerning the + opening/closing of some data exchange with a user, mounting + directories, etc. + + + + + + + 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: + + + + 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. + + + + + requisite + + + like required, however, in the case that + such a module returns a failure, control is directly returned + to the application. The return value is that associated with + the first required or requisite module to fail. Note, this flag + can be used to protect against the possibility of a user getting + the opportunity to enter a password over an unsafe medium. It is + conceivable that such behavior might inform an attacker of valid + accounts on a system. This possibility should be weighed against + the not insignificant concerns of exposing a sensitive password + in a hostile environment. + + + + + 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). A failure + of this module is not deemed as fatal to satisfying the + application that this type has succeeded. + + + + + 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. + + + + + 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=action1 value2=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, + n, signifying an action of 'jump over the + next n 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. + + + + + + + Each of the four keywords: required; requisite; sufficient; and + optional, have an equivalent expression in terms of the [...] + syntax. They are as follows: + + + + required + + + [success=ok new_authtok_reqd=ok ignore=ignore default=bad] + + + + + requisite + + + [success=ok new_authtok_reqd=ok ignore=ignore default=die] + + + + + sufficient + + + [success=done new_authtok_reqd=done default=ignore] + + + + + optional + + + [success=ok new_authtok_reqd=ok default=ignore] + + + + + + + module-path 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/ or + /lib64/security/, depending on the architecture. + + + + module-arguments are a space separated list + of tokens that can be used to modify the specific behavior of the + given PAM. Such arguments will be documented for each individual + module. Note, if you wish to include spaces in an argument, you + should surround that argument with square brackets. + + + squid auth required pam_mysql.so user=passwd_query passwd=mada \ + db=eminence [query=select user_name from internet_service \ + where user_name='%u' and password=PASSWORD('%p') and \ + service='web_proxy'] + + + When using this convention, you can include `[' characters + inside the string, and if you wish to include a `]' character + inside the string that will survive the argument parsing, you + should use `\['. In other words: + + + [..[..\]..] --> ..[..].. + + + + Any line in (one of) the configuration file(s), that is not formatted + correctly, will generally tend (erring on the side of caution) to make + the authentication process fail. A corresponding error is written to + the system log files with a call to + + syslog3 + . + + +
diff --git a/doc/man/pam.conf.5 b/doc/man/pam.conf.5 index fcedd7d7..11f8737d 100644 --- a/doc/man/pam.conf.5 +++ b/doc/man/pam.conf.5 @@ -1,11 +1,11 @@ .\" Title: pam.conf .\" Author: .\" Generator: DocBook XSL Stylesheets v1.70.1 -.\" Date: 06/19/2006 +.\" Date: 06/21/2006 .\" Manual: Linux\-PAM Manual .\" Source: Linux\-PAM Manual .\" -.TH "PAM.CONF" "5" "06/19/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.TH "PAM.CONF" "5" "06/21/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -244,9 +244,19 @@ directory. In this case the directory is filled with files each of which has a f The syntax of each file in /etc/pam.d/ is similar to that of the \fI/etc/pam.conf\fR file and is made up of lines of the following form: +.sp +.RS 3n +.nf +type control module\-path module\-arguments + +.fi +.RE .PP - -\fB type control module\-path module\-arguments\fR +The only difference being that the service\-name is not present. The service\-name is of course the name of the given configuration file. For example, +\fI/etc/pam.d/login\fR +contains the configuration for the +\fBlogin\fR +service. .SH "SEE ALSO" .PP diff --git a/doc/man/pam.conf.5.xml b/doc/man/pam.conf.5.xml index d744dac0..68f576af 100644 --- a/doc/man/pam.conf.5.xml +++ b/doc/man/pam.conf.5.xml @@ -19,409 +19,17 @@ DESCRIPTION - - When a 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. The presence of this - directory will cause Linux-PAM to ignore - /etc/pam.conf. - - - - 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 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 - - - this module type performs non-authentication based account - management. It is typically used to restrict/permit access - to a service based on the time of day, currently available - system resources (maximum number of users) or perhaps the - location of the applicant user -- 'root' login only on the - console. - - - - - auth - - - this module type provides two aspects of authenticating - the user. Firstly, it establishes that the user is who they - claim to be, by instructing the application to prompt the user - for a password or other means of identification. Secondly, the - module can grant group membership or other privileges through - its credential granting properties. - - - - - password - - - this module type is required for updating the authentication - token associated with the user. Typically, there is one module - for each 'challenge/response' based authentication (auth) type. - - - - - session - - - this module type is associated with doing things that need to - be done for the user before/after they can be given service. - Such things include the logging of information concerning the - opening/closing of some data exchange with a user, mounting - directories, etc. - - - - - - - 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: - - - - 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. - - - - - requisite - - - like required, however, in the case that - such a module returns a failure, control is directly returned - to the application. The return value is that associated with - the first required or requisite module to fail. Note, this flag - can be used to protect against the possibility of a user getting - the opportunity to enter a password over an unsafe medium. It is - conceivable that such behavior might inform an attacker of valid - accounts on a system. This possibility should be weighed against - the not insignificant concerns of exposing a sensitive password - in a hostile environment. - - - - - 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). A failure - of this module is not deemed as fatal to satisfying the - application that this type has succeeded. - - - - - 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. - - - - - 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=action1 value2=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, - n, signifying an action of 'jump over the - next n 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. - - - - - - - Each of the four keywords: required; requisite; sufficient; and - optional, have an equivalent expression in terms of the [...] - syntax. They are as follows: - - - - required - - - [success=ok new_authtok_reqd=ok ignore=ignore default=bad] - - - - - requisite - - - [success=ok new_authtok_reqd=ok ignore=ignore default=die] - - - - - sufficient - - - [success=done new_authtok_reqd=done default=ignore] - - - - - optional - - - [success=ok new_authtok_reqd=ok default=ignore] - - - - - - - module-path 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/ or - /lib64/security/, depending on the architecture. - - - - module-arguments are a space separated list - of tokens that can be used to modify the specific behavior of the - given PAM. Such arguments will be documented for each individual - module. Note, if you wish to include spaces in an argument, you - should surround that argument with square brackets. - - - squid auth required pam_mysql.so user=passwd_query passwd=mada \ - db=eminence [query=select user_name from internet_service \ - where user_name='%u' and password=PASSWORD('%p') and \ - service='web_proxy'] - - - When using this convention, you can include `[' characters - inside the string, and if you wish to include a `]' character - inside the string that will survive the argument parsing, you - should use `\['. In other words: - - - [..[..\]..] --> ..[..].. - - - - Any line in (one of) the configuration file(s), that is not formatted - correctly, will generally tend (erring on the side of caution) to make - the authentication process fail. A corresponding error is written to - the system log files with a call to - - syslog3 - . - - - - More flexible than the single configuration file is it to - configure libpam via the contents of the - /etc/pam.d/ directory. In this case the - directory is filled with files each of which has a filename - equal to a service-name (in lower-case): it is the personal - configuration file for the named service. - - - - The syntax of each file in /etc/pam.d/ is similar to that of the - /etc/pam.conf file and is made up of lines - of the following form: - - - - type control module-path module-arguments - + + -- cgit v1.2.3