mirrors/pam-modules
1
0
Fork 0
mirror of git://git.gnu.org.ua/pam-modules.git synced 2025-04-29 09:59:52 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update

Browse source 
git-svn-id: file:///svnroot/pam-modules/trunk@54 56984be4-0537-0410-a56c-fcb268c96130
This commit is contained in:
Sergey Poznyakoff 2007-08-11 16:24:05 +00:00
parent d5d08779b3
commit 1c487cbd52
2 changed files with 135 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

4
doc/gendocs_template
View file

@ -5,9 +5,9 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head> <head>
<title>%%TITLE%% - Free Software - gray.gnu.org.ua</title> <title>%%TITLE%% - Free Software - puszcza.gnu.org.ua</title>
<meta http-equiv="content-type" content='text/html; charset=utf-8' /> <meta http-equiv="content-type" content='text/html; charset=utf-8' />
<link rel="stylesheet" type="text/css" href="/gnu.css" /> <link rel="stylesheet" type="text/css" href="/local/css/gnu.css" />
<link rev="made" href="mailto:gray@gnu.org" /> <link rev="made" href="mailto:gray@gnu.org" />
<link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png" /> <link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png" />
</head> </head>

198
doc/pam-modules.texi
View file

@ -6,6 +6,11 @@
@c %**end of header @c %**end of header
@setchapternewpage odd @setchapternewpage odd
@defcodeindex pr
@defcodeindex op
@syncodeindex pr cp
@syncodeindex op cp
@include version.texi @include version.texi
@ifinfo @ifinfo
@ -79,26 +84,33 @@ Appendices
@node Intro, fshadow, Top, Top @node Intro, fshadow, Top, Top
@chapter Introduction to PAM-modules @chapter Introduction to PAM-modules
PAM-modules is a collection of useful @acronym{PAM PAM-modules is a collection of @acronym{PAM
modules}. It includes modules for user authentication and logging. modules} for user authentication and logging. This manual describes
each module in detail. The reader is expected to be sufficiently
proficient with general @acronym{UNIX} administration issues and with
Pluggable Authentication Modules (@acronym{PAM}) in particular.
All modules from the package support the following command line All modules from the package support the following command line
arguments: arguments:
@anchor{common options} @anchor{common options}
@table @option @table @option
@opindex debug, common option
@cindex debugging hints
@item debug[=@var{level}] @item debug[=@var{level}]
Change debugging level (0 <= @var{level} <= 100). The debugging Change debugging level (0 <= @var{level} <= 100). The debugging
information will be logged via @code{syslog} channel information will be logged via @code{syslog} channel
@code{auth.debug}. Notice, that debugging output can reveal @code{auth.debug}. Notice, that debugging output can reveal
authentication credentials (user password, in particular). authentication credentials (user password, in particular).
@opindex waitdebug, common option
@item waitdebug[=@var{interval}] @item waitdebug[=@var{interval}]
Enter a dead loop. This option is intended for Wait for @var{interval} seconds before starting the operation.
the package developers and is not enabled unless you configure This option is intended for the package developers and is not enabled,
the package with symbol @code{DEBUG_MODE} defined. Most probably you unless you configure the package with symbol @code{DEBUG_MODE}
will not need it. The following description is provided in case you defined. Most probably you will not need this option. The following
decide to participate in further development: description is provided in case you decide to participate in
@command{PAM-modules} development:
When this option is present, the module displays the When this option is present, the module displays the
following diagnostics in @command{syslog} @code{auth.crit} channel: following diagnostics in @command{syslog} @code{auth.crit} channel:
@ -108,23 +120,18 @@ WAITING FOR DEBUG AT pam_regex.c:240
@end smallexample @end smallexample
@noindent @noindent
and waits for @var{interval} seconds (default 3600). The developer is and waits for @var{interval} seconds (default 3600) before actually
supposed to attach to the process with a debugger, set the @code{interval} starting to do anything. The developer is supposed to attach to the
variable to 0 and to continue execution of the module in the debugging process with a debugger, set the @code{interval} variable to 0 and to
mode. continue execution of the module in the debugging mode.
@end table @end table
The following chapters discuss each module in detail. The reader is
expected to be sufficiently proficient with general @acronym{UNIX}
administration issues and with Pluggable Authentication Modules
(@acronym{PAM}) in particular.
@node fshadow, regex, Intro, Top @node fshadow, regex, Intro, Top
@chapter pam_fshadow @chapter Authentication against an alternative shadow file.
@cindex pam_fshadow @prindex pam_fshadow
This module provides authentication against an alternative This module provides authentication against an alternative
@file{shadow} file (or @file{passwd} / @file{shadow}) pair or pairs. @file{shadow} file, or @file{passwd} / @file{shadow} pair (or pairs).
There are two main operation modes: @dfn{plain} mode, in which There are two main operation modes: @dfn{plain} mode, in which
@command{pam_fshadow} uses only one @file{passwd}/@file{shadow} pair, @command{pam_fshadow} uses only one @file{passwd}/@file{shadow} pair,
and @dfn{virtual domain} mode, which allows to select the pair to use and @dfn{virtual domain} mode, which allows to select the pair to use
@ -133,38 +140,46 @@ describe the plain mode.
@cindex plain mode, pam_fshadow @cindex plain mode, pam_fshadow
@cindex pam_fshadow, plain @cindex pam_fshadow, plain
In plain mode, @command{pam_fshadow} uses the authentication token Plain mode is the default operation mode for
as the user name and verifies it against the @command{pam_fshadow}. In this mode, the module uses the
authentication token as the user name and verifies it against the
@file{passwd}/@file{shadow} pair located in the system configuration @file{passwd}/@file{shadow} pair located in the system configuration
directory (which is set when configuring the package and directory (which is set when configuring the package and
defaults to @file{@var{prefix}/etc}). This default location can be defaults to @file{@var{prefix}/etc}). This default location can be
changed using the @option{sysconfdir} option (see below). The changed using the @option{sysconfdir} option (see below). The
authentication goes as follows: authentication is performed as follows:
First, the user name is looked up in @file{passwd} file and the First, the user name is looked up in @file{passwd} file and the
corresponding record is fetched. If this record contains a valid corresponding record is fetched. If this record contains a valid
password hash (i.e. its second field is at least 2 characters long), password hash (i.e. its second field is at least 2 characters long),
it is compared with the supplied password using @code{crypt} function. the system @code{crypt} function is called on the supplied password
Otherwise, if @file{passwd} contains no password, the shadow file is with the retrieved hash as its second argument (the @code{seed}) and
its result is compared with the hash. If the two strings are the
same, the user is authenticated successfully.
Otherwise, if @file{passwd} contains no password, the shadow file is
examined and the hash retrieved from there is used. If the record examined and the hash retrieved from there is used. If the record
retrieved from the shadow file has not expired, and if its password retrieved from the shadow file has not expired, and if its password
hash field matches the supplied password, the user is authenticated hash field matches the supplied password (using the algorithm
successfully. described above), the user is authenticated successfully.
Several options are provided to alter the default behavior. All Several options are provided to alter the default behavior. All
of them, except @command{sysconfdir}, have the same effect in the of them, except @command{sysconfdir}, have the same effect in the
virtual domain mode as well. The table below summarizes these options. virtual domain mode as well. The table below summarizes these options.
@table @option @table @option
@opindex nopasswd, @command{pam_fshadow} option
@item nopasswd @item nopasswd
Do not require @file{passwd} file to be present. Only Do not require @file{passwd} file to be present. Only
@file{shadow} is used for authentication. @file{shadow} is used for authentication.
@opindex sysconfdir, @command{pam_fshadow} option
@item sysconfdir=@var{dir} @item sysconfdir=@var{dir}
Set full name of the directory where @file{shadow} and Set full name of the directory where @file{shadow} and
@file{passwd} are located. By default the system configuration @file{passwd} are located. By default the system configuration
directory will be used. directory will be used.
@opindex use_authtok, @command{pam_fshadow} option
@item use_authtok @item use_authtok
Do not prompt the user for password, take it from the saved Do not prompt the user for password, take it from the saved
authentication tokens. This option is useful when @command{pam_fshadow} authentication tokens. This option is useful when @command{pam_fshadow}
@ -185,17 +200,20 @@ tuhs auth required pam_fshadow.so \
In @dfn{virtual domain} mode, @command{pam_fshadow} uses the In @dfn{virtual domain} mode, @command{pam_fshadow} uses the
authentication token to determine where to look for the authentication token to determine where to look for the
@file{passwd}/@file{shadow} file pair. The token is split into @file{passwd}/@file{shadow} file pair. The token is split into
the @dfn{user name proper} and @dfn{authentication domain}. The the @dfn{user name proper} and the @dfn{authentication domain}. The
configuration directory name is then obtained by appending to the configuration directory name is then obtained by concatenating the
system configuration directory name a directory separator (@samp{/}) system configuration directory, a directory separator character (@samp{/}),
and the name of the authentication domain. Then, the authentication and the name of the authentication domain. Then, the authentication
goes on as described above for the plain mode. If the supplied proceeds as described above for the plain mode. If the supplied
authentication token does not match the regular expression, authentication token does not match the regular expression,
@command{pam_fshadow} proceeds as in plain mode. @command{pam_fshadow} proceeds as in plain mode.
@opindex regex, @command{pam_fshadow} option
@cindex enabling virtual domain mode, @command{pam_fshadow}
@cindex virtual domain mode, enabling (@command{pam_fshadow})
This mode is enabled by the option @option{regex}, which supplies This mode is enabled by the option @option{regex}, which supplies
a regular expression used to split the authentication token. This a regular expression used to split the authentication token. This
regular expression must contain two parenthesized groups. First of regular expression must contain two parenthesized @dfn{groups}. First of
them is used to extract the user name, and the second one is used them is used to extract the user name, and the second one is used
to extract the authentication domain. For example, the following option: to extract the authentication domain. For example, the following option:
@ -209,20 +227,25 @@ instructs @command{pam_fshadow} to use any characters before the
authentication domain. authentication domain.
Several options are provided, that control the flavor of the Several options are provided, that control the flavor of the
regular expression and the group indices used to retrieve regular expression and the way of retrieving the authentication data
authentication data. These are: from the token. These options are:
@table @option @table @option
@opindex basic, @command{pam_fshadow} option
@item basic @item basic
Use basic regular expression. This is the default. Use basic regular expression. This is the default.
@opindex extended, @command{pam_fshadow} option
@item extended @item extended
Use extended regular expression. Use extended regular expression.
@opindex ignore-case, @command{pam_fshadow} option
@opindex icase, @command{pam_fshadow} option
@item ignore-case @item ignore-case
@itemx icase @itemx icase
Use case-insensitive regular expression. Use case-insensitive regular expression.
@opindex revert-index, @command{pam_fshadow} option
@item revert-index @item revert-index
Use group 2 as the user name and group 1 as the authentication domain. Use group 2 as the user name and group 1 as the authentication domain.
@end table @end table
@ -238,48 +261,58 @@ check auth required pam_fshadow.so \
It instructs @command{pam_fshadow} to use @samp{@@} as the It instructs @command{pam_fshadow} to use @samp{@@} as the
username/domain separator and to look up for the password databases username/domain separator and to look up for the password databases
under the @file{/etc/auth} directory. For example, if the supplied under the @file{/etc/auth} directory. For example, if the supplied
authentication token was @samp{smith@@ftp}, the module will look up authentication token was @samp{smith@@ftp}, then the module will look
for the user name @samp{smith} in the files for the user name @samp{smith} in the files
@file{/etc/auth/ftp/passwd} and @file{/etc/auth/ftp/shadow}. @file{/etc/auth/ftp/passwd} and @file{/etc/auth/ftp/shadow}.
@node regex, log, fshadow, Top @node regex, log, fshadow, Top
@chapter pam_regex @chapter Authentication using regular expressions.
@cindex pam_regex @prindex pam_regex
The module @command{pam_regex} allows to control user access by The module @command{pam_regex} allows to control user access by
matching their login name against the given regular expression. It matching their login name against a regular expression. It
is useful in authentication stacks for such services as may be useful, for example, in authentication stacks for such services
@acronym{FTP} or @acronym{HTTP}. as @acronym{FTP} or @acronym{HTTP}.
@table @code @table @code
@opindex basic, @command{pam_regex} option
@item basic @item basic
Use basic regular expression. Use basic regular expression.
@opindex case, @command{pam_regex} option
@item case @item case
Use case-insensitive regular expression. Use case-insensitive regular expression.
@opindex extended, @command{pam_regex} option
@item extended @item extended
Use extended regular expression. Use extended regular expression.
@item icase @opindex icase, @command{pam_regex} option
@opindex ignore-case, @command{pam_regex} option
@item ignore-case
@itemx icase
Use case-insensitive regular expression. Use case-insensitive regular expression.
@opindex regex, @command{pam_regex} option
@item regex=@var{string} @item regex=@var{string}
The user name must match the given regular expression. This The user name must match the given regular expression. This
option is mandatory. The default expression flavor is option is mandatory. The default expression flavor is
``basic, case-sensitive'', but this can be changed using other ``basic, case-sensitive'', but this can be changed using other
options (see above). options (see above).
@opindex sense, @command{pam_regex} option
@item sense=@{allow|deny@} @item sense=@{allow|deny@}
What to do if user name matches the regexp. Default is @samp{allow}. What to do if user name matches the regexp. Default is @samp{allow}.
@opindex use_authtok, @command{pam_regex} option
@item use_authtok @item use_authtok
Do not prompt the user for password, take it from the saved Do not prompt the user for password, take it from the saved
authentication tokens. This option is useful when @command{pam_fshadow} authentication tokens instead. This option is useful when
is used as a non-first module in a stack of authentication modules. @command{pam_fshadow} is used as a non-first module in a stack of
authentication modules.
@item user=@var{string} @item user=@var{string}
Upon successful matching, return set PAM user name to @var{string}. Upon successful matching, set @acronym{PAM} user name to @var{string}.
@end table @end table
@ -289,30 +322,31 @@ is used as a non-first module in a stack of authentication modules.
httpd auth required pam_regex.so sense=deny regex=.*@@.* httpd auth required pam_regex.so sense=deny regex=.*@@.*
@end smallexample @end smallexample
@noindent This example denies login for users whose login names contain the
this example denies login for users whose login names contain the
@samp{@@} character. @samp{@@} character.
@node log, sql, regex, Top @node log, sql, regex, Top
@chapter Log arbitrary messages to syslog. @chapter Log arbitrary messages to syslog.
The @command{pam_log} logs is a diagnostic tool. It works as the @prindex pam_log
shell @command{echo} command, outputting its arguments to the The @command{pam_log} module is a diagnostic tool. It works
@command{syslog}. The module can be used in any PAM service similarly to the shell @command{echo} command, outputting its
stack. arguments to the @command{syslog}. The module can be used in any PAM
service stack.
Before logging, each argument is subject to @dfn{variable Before logging, each command line argument is subject to @dfn{variable
substitiution}. During this phase, any occurrence of substitiution}. During this phase, any occurrence of
@code{$@var{variable}} is substituted by the value of @var{variable}. @code{$@var{variable}} is substituted by the value of @var{variable}.
If the @var{variable} is not defined, emtpy string is substituted If the @var{variable} is not defined, emtpy string is substituted
instead. The shell-style default values are also supported: the instead. A limited support for the shell-style default values is
notation @code{$@{@var{variable}:-@var{value}@}} expands to the value available: namely, the notation
of @var{variable} if it is set, and to @var{value} otherwise. @code{$@{@var{variable}:-@var{value}@}} expands to the value of
@var{variable} if it is set, and to @var{value} otherwise.
Supported variables are: The supported variables are:
@multitable @columnfractions .30 .50 @multitable @columnfractions .30 .50
@headitem Variable name @tab PAM variable @headitem Variable name @tab @acronym{PAM} variable
@item service @tab PAM_SERVICE @item service @tab PAM_SERVICE
@item user @tab PAM_USER @item user @tab PAM_USER
@item tty @tab PAM_TTY @item tty @tab PAM_TTY
@ -322,8 +356,8 @@ of @var{variable} if it is set, and to @var{value} otherwise.
@item password @tab PAM_AUTHTOK @item password @tab PAM_AUTHTOK
@end multitable @end multitable
In order to be discerned from the arguments, all @command{pam_log}'s In order to be discerned from arguments, all @command{pam_log}'s
options begin with a dash (@samp{-}). They must precede the options begin with a dash (@samp{-}). They must precede any
non-option arguments. If the first non-option argument happens to non-option arguments. If the first non-option argument happens to
begin with a dash, you can inhibit its special handling by placing begin with a dash, you can inhibit its special handling by placing
@samp{--} before it. @samp{--} before it.
@ -331,15 +365,19 @@ begin with a dash, you can inhibit its special handling by placing
The following table lists all the supported options: The following table lists all the supported options:
@table @option @table @option
@opindex -debug, @command{pam_log} option
@item -debug[=@var{level}] @item -debug[=@var{level}]
Similar to @option{debug} in other modules (@pxref{Intro}). Similar to @option{debug} in other modules (@pxref{Intro}).
@opindex -no-open, @command{pam_log} option
@item -no-open @item -no-open
Reserved for future use. Reserved for future use.
@opindex -waitdebug, @command{pam_log} option
@item -waitdebug[=@var{interval}] @item -waitdebug[=@var{interval}]
Similar to @option{waitdebug} in other modules (@pxref{Intro}). Similar to @option{waitdebug} in other modules (@pxref{Intro}).
@opindex -pri, @command{pam_regex} option
@item -pri=@var{facility}.@var{priority} @item -pri=@var{facility}.@var{priority}
Requests to send log messages to the given syslog facility and Requests to send log messages to the given syslog facility and
priority. The @var{facility} part can be any of: @samp{user}, priority. The @var{facility} part can be any of: @samp{user},
@ -355,6 +393,7 @@ priority. The @var{facility} part can be any of: @samp{user},
the following defaults are used: @var{facility}=@code{authpriv}, the following defaults are used: @var{facility}=@code{authpriv},
@var{priority}=@code{info}. @var{priority}=@code{info}.
@opindex -tag, @command{pam_log} option
@item -tag=@var{label} @item -tag=@var{label}
Use @var{label} as the syslog tag, instead of the module name. Use @var{label} as the syslog tag, instead of the module name.
@end table @end table
@ -375,10 +414,14 @@ cvs session required pam_permit.so
@node sql, Reporting Bugs, log, Top @node sql, Reporting Bugs, log, Top
@chapter Simple SQL authentication. @chapter Simple SQL authentication.
The package provides two modules for SQL authentication: @prindex pam_pgsql
@prindex pam_mysql
@cindex MySQL, using for authentication
@cindex PostreSQL, using for authentication
The package provides two modules for @acronym{SQL} authentication:
@command{pam_mysql}, for MySQL and @command{pam_pgsql} for @command{pam_mysql}, for MySQL and @command{pam_pgsql} for
PostgreSQL. Both modules share the same set of options and provide PostgreSQL. Both modules share the same set of options and provide
similar functionality. To authenticate the user, the module connects similar functionality. To authenticate a user, each module connects
to the database and issues a query which should return the user to the database and issues a query which should return the user
password. Then the obtained password is compared with the password. Then the obtained password is compared with the
authentication token, using a preconfigured algorithm. If it matches, authentication token, using a preconfigured algorithm. If it matches,
@ -387,42 +430,64 @@ the user is authenticated successfully.
The options, common for both modules are: The options, common for both modules are:
@table @option @table @option
@opindex use_authtok, @command{pam_mysql} option
@opindex use_authtok, @command{pam_pgsql} option
@item use_authtok @item use_authtok
Do not prompt the user for password, take it from the saved Do not prompt the user for password, take it from the saved
authentication tokens. This option is useful when this module is authentication tokens. This option is useful when this module is
not the first in the stack of authentication modules. not the first in the stack of authentication modules.
@opindex config, @command{pam_pgsql} option
@opindex config, @command{pam_mysql} option
@item config=@var{file} @item config=@var{file}
Read SQL access credentials from the given @var{file}. Read SQL access credentials from the given @var{file}.
@end table @end table
@cindex configuration file, @command{pam_pgsql}
@cindex configuration file, @command{pam_mysql}
The configuration file has a simple line-oriented syntax. Empty The configuration file has a simple line-oriented syntax. Empty
lines and lines beginning with @samp{#} are ignored. Nonempty lines lines and lines beginning with @samp{#} are ignored. Nonempty lines
consist of the keyword and its value, separated by any amount of the consist of a keyword and its value, separated by any amount of
white space. white space.
The keywords, common for both modules are: The keywords, common for both modules are:
@table @code @table @code
@opindex host, @command{pam_mysql} configuration variable
@opindex host, @command{pam_pgsql} configuration variable
@item host @var{hostname} @item host @var{hostname}
Defines the host where the database is running. Defines the host where the database is running.
@opindex port, @command{pam_mysql} configuration variable
@opindex port, @command{pam_pgsql} configuration variable
@item port @var{number} @item port @var{number}
Defines the SQL port number. Defines the SQL port number.
@opindex db, @command{pam_mysql} configuration variable
@opindex db, @command{pam_pgsql} configuration variable
@item db @var{database} @item db @var{database}
Sets the database name. Sets the database name.
@opindex login, @command{pam_mysql} configuration variable
@opindex login, @command{pam_pgsql} configuration variable
@item login @var{string} @item login @var{string}
Sets the SQL user name. Sets the SQL user name.
@opindex pass, @command{pam_mysql} configuration variable
@opindex pass, @command{pam_pgsql} configuration variable
@item pass @var{password} @item pass @var{password}
Sets the SQL user password Sets the SQL user password
@opindex query, @command{pam_mysql} configuration variable
@opindex query, @command{pam_pgsql} configuration variable
@item query @var{query} @item query @var{query}
Defines the query used to obtain the user's password from the Defines the query used to obtain the user's password from the
database. The query can contain the following meta-characters: database. The query can contain the following meta-characters:
@cindex meta-characters in @acronym{SQL} queries
@cindex u, %u, a meta-character
@cindex p, %p, a meta-character
@cindex %, %%, a meta-character
@multitable @columnfractions .15 .40 @multitable @columnfractions .15 .40
@headitem Meta-char @tab Replaced by @headitem Meta-char @tab Replaced by
@item %u @tab User name @item %u @tab User name
@ -435,6 +500,7 @@ database. The query can contain the following meta-characters:
Variables, specific for @command{pam_pgsql}: Variables, specific for @command{pam_pgsql}:
@table @code @table @code
@opindex allow-plaintext-pass, @command{pam_pgsql} configuration variable
@item allow-plaintext-pass @var{bool} @item allow-plaintext-pass @var{bool}
The returned password can be plaintext. Without this option, it is The returned password can be plaintext. Without this option, it is
supposed to be encrypted using the system @code{crypt} function. supposed to be encrypted using the system @code{crypt} function.
@ -443,10 +509,12 @@ supposed to be encrypted using the system @code{crypt} function.
Variables, specific for @command{pam_mysql}: Variables, specific for @command{pam_mysql}:
@table @code @table @code
@opindex allow-mysql-pass, @command{pam_mysql} configuration variable
@item allow-mysql-pass @var{bool} @item allow-mysql-pass @var{bool}
The returned password can be encrypted using MySQL @code{password} The returned password can be encrypted using MySQL @code{password}
function. function.
@opindex allow-plaintext-pass, @command{pam_mysql} configuration variable
@item allow-plaintext-pass @var{bool} @item allow-plaintext-pass @var{bool}
The returned password can be plaintext. The returned password can be plaintext.
@end table @end table