d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
680ca73945
freebsd-dev/lib/libpam/modules/pam_exec/pam_exec.8

172 lines
5.2 KiB
Groff
Raw Normal View History

Export the PAM environment to the child process instead of the "normal" environment list, which may be unsafe and / or sensitive. Sponsored by: DARPA, NAI Labs
2003-02-06 12:40:58 +00:00
.\" Copyright (c) 2001,2003 Networks Associates Technology, Inc.
Changes to the expose_password functionality: - Implement use_first_pass, allowing expose_password to be used by other service functions than pam_auth() without prompting a second time. - Don't prompt for a password during pam_setcred(). PR: 238041 MFC after: 3 weeks
2019-06-30 14:46:15 +00:00
.\" Copyright (c) 2017-2019 Dag-Erling Smørgrav
Add support for Linux-PAM's badly named expose_authtok option. Submitted by: Thomas Munro <munro@ip9.org> MFC after: 1 week Differential Revision: D16171
2018-08-14 00:14:17 +00:00
.\" Copyright (c) 2018 Thomas Munro
Just to show that PAM can do almost anything from the ridiculous to the obscene, or - as they say in New York - sophisticated, add pam_echo(8) and pam_exec(8) to our ever-lengthening roster of PAM modules. Sponsored by: DARPA, NAI Labs.
2002-05-23 22:03:06 +00:00
.\" All rights reserved.
.\"
.\" Portions of this software were developed for the FreeBSD Project by
.\" ThinkSec AS and NAI Labs, the Security Research Division of Network
.\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
.\" ("CBOSS"), as part of the DARPA CHATS research program.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote
.\" products derived from this software without specific prior written
.\" permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
Changes to the expose_password functionality: - Implement use_first_pass, allowing expose_password to be used by other service functions than pam_auth() without prompting a second time. - Don't prompt for a password during pam_setcred(). PR: 238041 MFC after: 3 weeks
2019-06-30 14:46:15 +00:00
.Dd May 24, 2019
Just to show that PAM can do almost anything from the ridiculous to the obscene, or - as they say in New York - sophisticated, add pam_echo(8) and pam_exec(8) to our ever-lengthening roster of PAM modules. Sponsored by: DARPA, NAI Labs.
2002-05-23 22:03:06 +00:00
.Dt PAM_EXEC 8
.Os
.Sh NAME
.Nm pam_exec
.Nd Exec PAM module
.Sh SYNOPSIS
.Op Ar service-name
.Ar module-type
.Ar control-flag
.Pa pam_exec
.Op Ar arguments
.Sh DESCRIPTION
Use program exit status as pam_exec return code (optional) pam_exec(8) now accepts a new option "return_prog_exit_status". When set, the program exit status is used as the pam_exec return code. It allows the program to tell why the step failed (eg. user unknown). However, if it exits with a code not allowed by the calling PAM service module function (see $PAM_SM_FUNC below), a warning is logged and PAM_SERVICE_ERR is returned. The following changes are related to this new feature but they apply no matter if the "return_prog_exit_status" option is set or not. The environment passed to the program is extended: o $PAM_SM_FUNC contains the name of the PAM service module function (eg. pam_sm_authenticate). o All valid PAM return codes' numerical values are available through variables named after the return code name. For instance, $PAM_SUCCESS, $PAM_USER_UNKNOWN or $PAM_PERM_DENIED. pam_exec return code better reflects what went on: o If the program exits with !0, the return code is now PAM_PERM_DENIED, not PAM_SYSTEM_ERR. o If the program fails because of a signal (WIFSIGNALED) or doesn't terminate normally (!WIFEXITED), the return code is now PAM_SERVICE_ERR, not PAM_SYSTEM_ERR. o If a syscall in pam_exec fails, the return code remains PAM_SYSTEM_ERR. waitpid(2) is called in a loop. If it returns because of EINTR, do it again. Before, it would return PAM_SYSTEM_ERR without waiting for the child to exit. Several log messages now include the PAM service module function name. The man page is updated accordingly. Reviewed by: gleb@, des@ Sponsored by: Yakaz (http://www.yakaz.com) MFC after: 2 weeks
2012-03-26 12:18:15 +00:00
The exec service module for PAM executes the program designated by
its first argument if no options are specified, with its remaining
arguments as command-line arguments.
If options are specified, the program and its arguments follow the last
option or
.Cm --
if the program name conflicts with an option name.
.Pp
The following options may be passed before the program and its
arguments:
Add options to capture stdout and / or stderr and pass the output on to the user. There is currently no buffering, so the result may be somewhat unpredictable if the conversation function adds a newline, like openpam_ttyconv() does. Clean up and simplify the environment handling code, which triggered an inexplicable bug on some systems. MFC after: 2 weeks
2017-03-22 13:16:04 +00:00
.Bl -tag -width indent
.It Cm capture_stderr
Capture text printed by the program to its standard error stream and
pass it to the conversation function as error messages.
No attempt is made at buffering the text, so results may vary.
.It Cm capture_stdout
Capture text printed by the program to its standard output stream and
pass it to the conversation function as informational messages.
No attempt is made at buffering the text, so results may vary.
.It Cm debug
Ignored for compatibility reasons.
.It Cm no_warn
Ignored for compatibility reasons.
Use program exit status as pam_exec return code (optional) pam_exec(8) now accepts a new option "return_prog_exit_status". When set, the program exit status is used as the pam_exec return code. It allows the program to tell why the step failed (eg. user unknown). However, if it exits with a code not allowed by the calling PAM service module function (see $PAM_SM_FUNC below), a warning is logged and PAM_SERVICE_ERR is returned. The following changes are related to this new feature but they apply no matter if the "return_prog_exit_status" option is set or not. The environment passed to the program is extended: o $PAM_SM_FUNC contains the name of the PAM service module function (eg. pam_sm_authenticate). o All valid PAM return codes' numerical values are available through variables named after the return code name. For instance, $PAM_SUCCESS, $PAM_USER_UNKNOWN or $PAM_PERM_DENIED. pam_exec return code better reflects what went on: o If the program exits with !0, the return code is now PAM_PERM_DENIED, not PAM_SYSTEM_ERR. o If the program fails because of a signal (WIFSIGNALED) or doesn't terminate normally (!WIFEXITED), the return code is now PAM_SERVICE_ERR, not PAM_SYSTEM_ERR. o If a syscall in pam_exec fails, the return code remains PAM_SYSTEM_ERR. waitpid(2) is called in a loop. If it returns because of EINTR, do it again. Before, it would return PAM_SYSTEM_ERR without waiting for the child to exit. Several log messages now include the PAM service module function name. The man page is updated accordingly. Reviewed by: gleb@, des@ Sponsored by: Yakaz (http://www.yakaz.com) MFC after: 2 weeks
2012-03-26 12:18:15 +00:00
.It Cm return_prog_exit_status
Use the program exit status as the return code of the pam_sm_* function.
It must be a valid return value for this function.
Add support for Linux-PAM's badly named expose_authtok option. Submitted by: Thomas Munro <munro@ip9.org> MFC after: 1 week Differential Revision: D16171
2018-08-14 00:14:17 +00:00
.It Cm expose_authtok
For full Linux-PAM compatibility, add a trailing NUL character when passing the authentication token to the external program. Approved by: re (kib) Submitted by: Thomas Munro <munro@ip9.org> MFC after: 1 week Differential Revision: D16950
2018-09-04 10:51:41 +00:00
Write the authentication token to the program's standard input stream,
followed by a NUL character.
Changes to the expose_password functionality: - Implement use_first_pass, allowing expose_password to be used by other service functions than pam_auth() without prompting a second time. - Don't prompt for a password during pam_setcred(). PR: 238041 MFC after: 3 weeks
2019-06-30 14:46:15 +00:00
Ignored for
.Fn pam_sm_setcred .
.It Cm use_first_pass
If
.Cm expose_authtok
was specified, do not prompt for an authentication token if one is not
already available.
Use program exit status as pam_exec return code (optional) pam_exec(8) now accepts a new option "return_prog_exit_status". When set, the program exit status is used as the pam_exec return code. It allows the program to tell why the step failed (eg. user unknown). However, if it exits with a code not allowed by the calling PAM service module function (see $PAM_SM_FUNC below), a warning is logged and PAM_SERVICE_ERR is returned. The following changes are related to this new feature but they apply no matter if the "return_prog_exit_status" option is set or not. The environment passed to the program is extended: o $PAM_SM_FUNC contains the name of the PAM service module function (eg. pam_sm_authenticate). o All valid PAM return codes' numerical values are available through variables named after the return code name. For instance, $PAM_SUCCESS, $PAM_USER_UNKNOWN or $PAM_PERM_DENIED. pam_exec return code better reflects what went on: o If the program exits with !0, the return code is now PAM_PERM_DENIED, not PAM_SYSTEM_ERR. o If the program fails because of a signal (WIFSIGNALED) or doesn't terminate normally (!WIFEXITED), the return code is now PAM_SERVICE_ERR, not PAM_SYSTEM_ERR. o If a syscall in pam_exec fails, the return code remains PAM_SYSTEM_ERR. waitpid(2) is called in a loop. If it returns because of EINTR, do it again. Before, it would return PAM_SYSTEM_ERR without waiting for the child to exit. Several log messages now include the PAM service module function name. The man page is updated accordingly. Reviewed by: gleb@, des@ Sponsored by: Yakaz (http://www.yakaz.com) MFC after: 2 weeks
2012-03-26 12:18:15 +00:00
.It Cm --
Stop options parsing;
program and its arguments follow.
.El
.Pp
Export the PAM environment to the child process instead of the "normal" environment list, which may be unsafe and / or sensitive. Sponsored by: DARPA, NAI Labs
2003-02-06 12:40:58 +00:00
The child's environment is set to the current PAM environment list,
as returned by
.Xr pam_getenvlist 3 .
In addition to the PAM environment, export a handful of useful PAM items. Suggested by: Ed Maste <emaste@phaedrus.sandvine.ca>
2005-02-01 10:37:07 +00:00
In addition, the following PAM items are exported as environment
variables:
.Ev PAM_RHOST ,
.Ev PAM_RUSER ,
.Ev PAM_SERVICE ,
Use program exit status as pam_exec return code (optional) pam_exec(8) now accepts a new option "return_prog_exit_status". When set, the program exit status is used as the pam_exec return code. It allows the program to tell why the step failed (eg. user unknown). However, if it exits with a code not allowed by the calling PAM service module function (see $PAM_SM_FUNC below), a warning is logged and PAM_SERVICE_ERR is returned. The following changes are related to this new feature but they apply no matter if the "return_prog_exit_status" option is set or not. The environment passed to the program is extended: o $PAM_SM_FUNC contains the name of the PAM service module function (eg. pam_sm_authenticate). o All valid PAM return codes' numerical values are available through variables named after the return code name. For instance, $PAM_SUCCESS, $PAM_USER_UNKNOWN or $PAM_PERM_DENIED. pam_exec return code better reflects what went on: o If the program exits with !0, the return code is now PAM_PERM_DENIED, not PAM_SYSTEM_ERR. o If the program fails because of a signal (WIFSIGNALED) or doesn't terminate normally (!WIFEXITED), the return code is now PAM_SERVICE_ERR, not PAM_SYSTEM_ERR. o If a syscall in pam_exec fails, the return code remains PAM_SYSTEM_ERR. waitpid(2) is called in a loop. If it returns because of EINTR, do it again. Before, it would return PAM_SYSTEM_ERR without waiting for the child to exit. Several log messages now include the PAM service module function name. The man page is updated accordingly. Reviewed by: gleb@, des@ Sponsored by: Yakaz (http://www.yakaz.com) MFC after: 2 weeks
2012-03-26 12:18:15 +00:00
.Ev PAM_SM_FUNC ,
.Ev PAM_TTY
In addition to the PAM environment, export a handful of useful PAM items. Suggested by: Ed Maste <emaste@phaedrus.sandvine.ca>
2005-02-01 10:37:07 +00:00
and
.Ev PAM_USER .
Use program exit status as pam_exec return code (optional) pam_exec(8) now accepts a new option "return_prog_exit_status". When set, the program exit status is used as the pam_exec return code. It allows the program to tell why the step failed (eg. user unknown). However, if it exits with a code not allowed by the calling PAM service module function (see $PAM_SM_FUNC below), a warning is logged and PAM_SERVICE_ERR is returned. The following changes are related to this new feature but they apply no matter if the "return_prog_exit_status" option is set or not. The environment passed to the program is extended: o $PAM_SM_FUNC contains the name of the PAM service module function (eg. pam_sm_authenticate). o All valid PAM return codes' numerical values are available through variables named after the return code name. For instance, $PAM_SUCCESS, $PAM_USER_UNKNOWN or $PAM_PERM_DENIED. pam_exec return code better reflects what went on: o If the program exits with !0, the return code is now PAM_PERM_DENIED, not PAM_SYSTEM_ERR. o If the program fails because of a signal (WIFSIGNALED) or doesn't terminate normally (!WIFEXITED), the return code is now PAM_SERVICE_ERR, not PAM_SYSTEM_ERR. o If a syscall in pam_exec fails, the return code remains PAM_SYSTEM_ERR. waitpid(2) is called in a loop. If it returns because of EINTR, do it again. Before, it would return PAM_SYSTEM_ERR without waiting for the child to exit. Several log messages now include the PAM service module function name. The man page is updated accordingly. Reviewed by: gleb@, des@ Sponsored by: Yakaz (http://www.yakaz.com) MFC after: 2 weeks
2012-03-26 12:18:15 +00:00
.Pp
The
.Ev PAM_SM_FUNC
variable contains the name of the PAM service module function being
called.
It may be:
.Bl -dash -offset indent -compact
.It
pam_sm_acct_mgmt
.It
pam_sm_authenticate
.It
pam_sm_chauthtok
.It
pam_sm_close_session
.It
pam_sm_open_session
.It
pam_sm_setcred
.El
.Pp
If
.Cm return_prog_exit_status
is not set (default), the
.Ev PAM_SM_FUNC
function returns
.Er PAM_SUCCESS
if the program exit status is 0,
.Er PAM_PERM_DENIED
otherwise.
.Pp
If
.Cm return_prog_exit_status
is set, the program exit status is used.
It should be
.Er PAM_SUCCESS
or one of the error codes allowed by the calling
.Ev PAM_SM_FUNC
function.
The valid codes are documented in each function man page.
If the exit status is not a valid return code,
.Er PAM_SERVICE_ERR
is returned.
Each valid codes numerical value is available as an environment variable
(eg.\&
.Ev PAM_SUCESS ,
.Ev PAM_USER_UNKNOWN ,
etc).
This is useful in shell scripts for instance.
Just to show that PAM can do almost anything from the ridiculous to the obscene, or - as they say in New York - sophisticated, add pam_echo(8) and pam_exec(8) to our ever-lengthening roster of PAM modules. Sponsored by: DARPA, NAI Labs.
2002-05-23 22:03:06 +00:00
.Sh SEE ALSO
In addition to the PAM environment, export a handful of useful PAM items. Suggested by: Ed Maste <emaste@phaedrus.sandvine.ca>
2005-02-01 10:37:07 +00:00
.Xr pam_get_item 3 ,
Assorted markup fixes. Approved by: re
2005-06-15 19:04:04 +00:00
.Xr pam.conf 5 ,
Use program exit status as pam_exec return code (optional) pam_exec(8) now accepts a new option "return_prog_exit_status". When set, the program exit status is used as the pam_exec return code. It allows the program to tell why the step failed (eg. user unknown). However, if it exits with a code not allowed by the calling PAM service module function (see $PAM_SM_FUNC below), a warning is logged and PAM_SERVICE_ERR is returned. The following changes are related to this new feature but they apply no matter if the "return_prog_exit_status" option is set or not. The environment passed to the program is extended: o $PAM_SM_FUNC contains the name of the PAM service module function (eg. pam_sm_authenticate). o All valid PAM return codes' numerical values are available through variables named after the return code name. For instance, $PAM_SUCCESS, $PAM_USER_UNKNOWN or $PAM_PERM_DENIED. pam_exec return code better reflects what went on: o If the program exits with !0, the return code is now PAM_PERM_DENIED, not PAM_SYSTEM_ERR. o If the program fails because of a signal (WIFSIGNALED) or doesn't terminate normally (!WIFEXITED), the return code is now PAM_SERVICE_ERR, not PAM_SYSTEM_ERR. o If a syscall in pam_exec fails, the return code remains PAM_SYSTEM_ERR. waitpid(2) is called in a loop. If it returns because of EINTR, do it again. Before, it would return PAM_SYSTEM_ERR without waiting for the child to exit. Several log messages now include the PAM service module function name. The man page is updated accordingly. Reviewed by: gleb@, des@ Sponsored by: Yakaz (http://www.yakaz.com) MFC after: 2 weeks
2012-03-26 12:18:15 +00:00
.Xr pam 8 ,
.Xr pam_sm_acct_mgmt 8 ,
.Xr pam_sm_authenticate 8 ,
Fixes to man8 groff mandoc style, usage mistakes, or typos. PR: 168016 Submitted by: Nobuyuki Koganemaru Approved by: gjb MFC after: 3 days
2012-05-24 02:24:03 +00:00
.Xr pam_sm_chauthtok 8 ,
Use program exit status as pam_exec return code (optional) pam_exec(8) now accepts a new option "return_prog_exit_status". When set, the program exit status is used as the pam_exec return code. It allows the program to tell why the step failed (eg. user unknown). However, if it exits with a code not allowed by the calling PAM service module function (see $PAM_SM_FUNC below), a warning is logged and PAM_SERVICE_ERR is returned. The following changes are related to this new feature but they apply no matter if the "return_prog_exit_status" option is set or not. The environment passed to the program is extended: o $PAM_SM_FUNC contains the name of the PAM service module function (eg. pam_sm_authenticate). o All valid PAM return codes' numerical values are available through variables named after the return code name. For instance, $PAM_SUCCESS, $PAM_USER_UNKNOWN or $PAM_PERM_DENIED. pam_exec return code better reflects what went on: o If the program exits with !0, the return code is now PAM_PERM_DENIED, not PAM_SYSTEM_ERR. o If the program fails because of a signal (WIFSIGNALED) or doesn't terminate normally (!WIFEXITED), the return code is now PAM_SERVICE_ERR, not PAM_SYSTEM_ERR. o If a syscall in pam_exec fails, the return code remains PAM_SYSTEM_ERR. waitpid(2) is called in a loop. If it returns because of EINTR, do it again. Before, it would return PAM_SYSTEM_ERR without waiting for the child to exit. Several log messages now include the PAM service module function name. The man page is updated accordingly. Reviewed by: gleb@, des@ Sponsored by: Yakaz (http://www.yakaz.com) MFC after: 2 weeks
2012-03-26 12:18:15 +00:00
.Xr pam_sm_close_session 8 ,
.Xr pam_sm_open_session 8 ,
Fixes to man8 groff mandoc style, usage mistakes, or typos. PR: 168016 Submitted by: Nobuyuki Koganemaru Approved by: gjb MFC after: 3 days
2012-05-24 02:24:03 +00:00
.Xr pam_sm_setcred 8
Just to show that PAM can do almost anything from the ridiculous to the obscene, or - as they say in New York - sophisticated, add pam_echo(8) and pam_exec(8) to our ever-lengthening roster of PAM modules. Sponsored by: DARPA, NAI Labs.
2002-05-23 22:03:06 +00:00
.Sh AUTHORS
The
.Nm
module and this manual page were developed for the
.Fx
Project by
ThinkSec AS and NAI Labs, the Security Research Division of Network
Mechanically kill hard sentence breaks.
2004-07-02 23:52:20 +00:00
Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
Just to show that PAM can do almost anything from the ridiculous to the obscene, or - as they say in New York - sophisticated, add pam_echo(8) and pam_exec(8) to our ever-lengthening roster of PAM modules. Sponsored by: DARPA, NAI Labs.
2002-05-23 22:03:06 +00:00
.Pq Dq CBOSS ,
as part of the DARPA CHATS research program.
Reference in New Issue Copy Permalink