Vendor import of OpenPAM Cinchona.

50 files changed, 813 insertions, 99 deletions

diff --git a/contrib/openpam/HISTORY b/contrib/openpam/HISTORY
index f191f24..740ca6f 100644
--- a/contrib/openpam/HISTORY
+++ b/contrib/openpam/HISTORY
@@ -1,4 +1,35 @@
 ============================================================================
+OpenPAM Cinchona						2002-04-08
+
+ - ENHANCE: Improved documentation for several API functions.
+
+ - BUGFIX: Fix bug in pam_set_data() that would result in corruption
+   of the module data list.
+
+ - BUGFIX: Allocate the correct amount of memory for the environment
+   list in pam_putenv().
+
+ - ENHANCE: Change pam_get_authtok()'s prototype so the caller can
+   specify what token it wants.  Also introduce PAM_OLDAUTHTOK_PROMPT.
+
+ - BUGFIX: Plug memory leak in pam_get_user() / pam_get_authtok(), and
+   reduce differences between these very similar functions.
+
+ - ENHANCE: Check flags carefully in pam_authenticate() and
+   pam_chauthtok().
+
+ - BUGFIX: Fix bugs in portability code; libpam now builds on NetBSD.
+
+ - ENHANCE: In pam_get_authtok(), if PAM_OLDAUTHTOK is set, we're
+   asked for PAM_AUTHTOK, and we have to prompt the user, prompt her
+   twice and compare the responses.
+
+ - ENHANCE: Add openpam_{borrow,restore}_cred(), for temporarily
+   switching to user credentials.
+
+ - ENHANCE: Add openpam_free_data(), a generic cleanup function for
+   pam_set_data() consumers.
+============================================================================
 OpenPAM	Centaury						2002-03-14
 
  - BUGFIX: Add missing #include <string.h> to openpam_log.c.
@@ -16,7 +47,7 @@ OpenPAM	Centaury						2002-03-14
 
  - ENHANCE: Suppress debugging logs, unless compiled with -DDEBUG.
 ============================================================================
-OpenPAM Celandine 2002-03-05
+OpenPAM Celandine						2002-03-05
 
  - BUGFIX: PAM_TRY_AGAIN is a valid return value for pam_chauthtok().
 
@@ -83,4 +114,4 @@ OpenPAM	Calamite						2002-02-09
 
 First (beta) release.
 ============================================================================
-$P4: //depot/projects/openpam/HISTORY#6 $
+$P4: //depot/projects/openpam/HISTORY#8 $
diff --git a/contrib/openpam/MANIFEST b/contrib/openpam/MANIFEST
index af31041..647b1b4 100644
--- a/contrib/openpam/MANIFEST
+++ b/contrib/openpam/MANIFEST
@@ -13,8 +13,11 @@ bin/su/Makefile
 bin/su/su.c
 doc/Makefile
 doc/man/Makefile
+doc/man/openpam_borrow_cred.3
+doc/man/openpam_free_data.3
 doc/man/openpam_get_option.3
 doc/man/openpam_log.3
+doc/man/openpam_restore_cred.3
 doc/man/openpam_set_option.3
 doc/man/openpam_ttyconv.3
 doc/man/pam.3
@@ -55,13 +58,16 @@ include/security/pam_constants.h
 include/security/pam_modules.h
 include/security/pam_types.h
 lib/Makefile
+lib/openpam_borrow_cred.c
 lib/openpam_dispatch.c
 lib/openpam_dynamic.c
 lib/openpam_findenv.c
+lib/openpam_free_data.c
 lib/openpam_get_option.c
 lib/openpam_impl.h
 lib/openpam_load.c
 lib/openpam_log.c
+lib/openpam_restore_cred.c
 lib/openpam_set_option.c
 lib/openpam_static.c
 lib/openpam_ttyconv.c
diff --git a/contrib/openpam/README b/contrib/openpam/README
index 24923aa..8837965 100644
--- a/contrib/openpam/README
+++ b/contrib/openpam/README
@@ -13,18 +13,14 @@ These are some of OpenPAM's features:
      paper and in OSF-RFC 86.0; this corresponds to the full XSSO API
      except for mappings and secondary authentication.
 
-   - Extends the API with several useful and time-saving functions:
-     pam_error(), pam_get_authtok(), pam_info(), pam_prompt(),
-     pam_setenv(), pam_verror(), pam_vinfo(), pam_vprompt()
-
-   - Offers a number of time-saving convenience functions:
-     openpam_log(), openpam_ttyconv().
+   - Extends the API with several useful and time-saving functions.
 
    - Performs strict checking of return values from service modules.
 
    - Reads configuration from /etc/pam.d/, /usr/local/etc/pam.d/ and
      /etc/pam.conf, in that order; this will be made configurable in a
-     future release.Please direct bug reports and inquiries to
-     openpam@thinksec.com.
+     future release.
+
+Please direct bug reports and inquiries to openpam@thinksec.com.
 
-$P4: //depot/projects/openpam/README#2 $
+$P4: //depot/projects/openpam/README#3 $
diff --git a/contrib/openpam/RELNOTES b/contrib/openpam/RELNOTES
index 7912cc7..42d62d6 100644
--- a/contrib/openpam/RELNOTES
+++ b/contrib/openpam/RELNOTES
@@ -1,19 +1,25 @@
 
-		  Release notes for OpenPAM Centaury
+		  Release notes for OpenPAM Cinchona
 		  ==================================
 
 This is a beta release.
 
 The library itself is complete.  Documentation exists in the form of
-man pages for the library functions, though some pages are still
+man pages for the library functions, though a few pages are still
 incomplete.
 
-This release is incorporated into FreeBSD-CURRENT as of 2002-03-14.
-It has not been tested on any other OS, though it should build and run
-with minimal tweaks on NetBSD and OpenBSD.
+This release is incorporated into FreeBSD-CURRENT as of 2002-04-08.
+It has also been successfully built on NetBSD, and should build with
+minimal or no changes on OpenBSD.  It has not been tested on any other
+OS.
 
 Known issues:
 
   - The documentation is still incomplete.
 
-$P4: //depot/projects/openpam/RELNOTES#6 $
+  - It should be possible to create incomplete modules without
+    recourse to placeholders or elaborate preprocessor tricks.  This
+    is made difficult by the requirement that it should be possible to
+    link modules statically.
+
+$P4: //depot/projects/openpam/RELNOTES#8 $
diff --git a/contrib/openpam/doc/man/Makefile b/contrib/openpam/doc/man/Makefile
index dfaf03a..8192df2 100644
--- a/contrib/openpam/doc/man/Makefile
+++ b/contrib/openpam/doc/man/Makefile
@@ -31,12 +31,15 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 #
-# $P4: //depot/projects/openpam/doc/man/Makefile#5 $
+# $P4: //depot/projects/openpam/doc/man/Makefile#6 $
 #
 
 MAN		 =
+MAN		+= openpam_borrow_cred.3
+MAN		+= openpam_free_data.3
 MAN		+= openpam_get_option.3
 MAN		+= openpam_log.3
+MAN		+= openpam_restore_cred.3
 MAN		+= openpam_set_option.3
 MAN		+= openpam_ttyconv.3
 MAN		+= pam.3
diff --git a/contrib/openpam/doc/man/openpam_borrow_cred.3 b/contrib/openpam/doc/man/openpam_borrow_cred.3
new file mode 100644
index 0000000..b83e14a
--- /dev/null
+++ b/contrib/openpam/doc/man/openpam_borrow_cred.3
@@ -0,0 +1,89 @@
+.\"-
+.\" Copyright (c) 2002 Networks Associates Technology, Inc.
+.\" All rights reserved.
+.\"
+.\" This software was 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.
+.\"
+.\" $P4: //depot/projects/openpam/doc/man/openpam_borrow_cred.3#1 $
+.\"
+.Dd April 8, 2002
+.Dt OPENPAM_BORROW_CRED 3
+.Os
+.Sh NAME
+.Nm openpam_borrow_cred
+.Nd temporarily borrow user credentials
+.Sh LIBRARY
+.Lb libpam
+.Sh SYNOPSIS
+.In security/pam_appl.h
+.Ft int
+.Fn openpam_borrow_cred "pam_handle_t *pamh" "const struct passwd *pwd"
+.Sh DESCRIPTION
+The
+.Nm
+function saves the current credentials and
+switches to those of the user specified by its
+.Va pwd
+argument.  The
+affected credentials are the effective UID, the effective GID, and the
+group access list.  The original credentials can be restored using
+.Xr openpam_restore_cred 3 .
+.Pp
+.Sh RETURN VALUES
+The
+.Nm
+function returns one of the following values:
+.Bl -tag -width 18n
+.It Bq Er PAM_BUF_ERR
+Memory buffer error.
+.It Bq Er PAM_PERM_DENIED
+Permission denied.
+.It Bq Er PAM_SYSTEM_ERR
+System error.
+.El
+.Sh SEE ALSO
+.Xr openpam_restore_cred 3 ,
+.Xr pam 3 ,
+.Xr pam_strerror 3 ,
+.Xr setegid 3 ,
+.Xr seteuid 3 ,
+.Xr setgroups 3
+.Sh STANDARDS
+The
+.Nm
+function is an OpenPAM extension.
+.Sh AUTHORS
+The
+.Nm
+function and this manual page 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
+.Pq Dq CBOSS ,
+as part of the DARPA CHATS research program.
diff --git a/contrib/openpam/doc/man/openpam_free_data.3 b/contrib/openpam/doc/man/openpam_free_data.3
new file mode 100644
index 0000000..b34d98d
--- /dev/null
+++ b/contrib/openpam/doc/man/openpam_free_data.3
@@ -0,0 +1,72 @@
+.\"-
+.\" Copyright (c) 2002 Networks Associates Technology, Inc.
+.\" All rights reserved.
+.\"
+.\" This software was 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.
+.\"
+.\" $P4: //depot/projects/openpam/doc/man/openpam_free_data.3#1 $
+.\"
+.Dd April 8, 2002
+.Dt OPENPAM_FREE_DATA 3
+.Os
+.Sh NAME
+.Nm openpam_free_data
+.Nd generic cleanup function
+.Sh LIBRARY
+.Lb libpam
+.Sh SYNOPSIS
+.In security/pam_appl.h
+.Ft void
+.Fn openpam_free_data "pam_handle_t *pamh" "void *data" "int status"
+.Sh DESCRIPTION
+The
+.Nm
+is a cleanup function suitable for passing to
+.Xr pam_set_data 3 .
+It simply releases the data by passing its
+.Va data
+argument to
+.Xr free 3 .
+.Sh SEE ALSO
+.Xr free 3 ,
+.Xr pam 3 ,
+.Xr pam_set_data 3
+.Sh STANDARDS
+The
+.Nm
+function is an OpenPAM extension.
+.Sh AUTHORS
+The
+.Nm
+function and this manual page 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
+.Pq Dq CBOSS ,
+as part of the DARPA CHATS research program.
diff --git a/contrib/openpam/doc/man/openpam_get_option.3 b/contrib/openpam/doc/man/openpam_get_option.3
index a66f1ac..06295d2 100644
--- a/contrib/openpam/doc/man/openpam_get_option.3
+++ b/contrib/openpam/doc/man/openpam_get_option.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/openpam_get_option.3#4 $
+.\" $P4: //depot/projects/openpam/doc/man/openpam_get_option.3#5 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt OPENPAM_GET_OPTION 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/openpam_log.3 b/contrib/openpam/doc/man/openpam_log.3
index 1352866..1b3d6e2 100644
--- a/contrib/openpam/doc/man/openpam_log.3
+++ b/contrib/openpam/doc/man/openpam_log.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/openpam_log.3#5 $
+.\" $P4: //depot/projects/openpam/doc/man/openpam_log.3#6 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt OPENPAM_LOG 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/openpam_restore_cred.3 b/contrib/openpam/doc/man/openpam_restore_cred.3
new file mode 100644
index 0000000..6f293a1
--- /dev/null
+++ b/contrib/openpam/doc/man/openpam_restore_cred.3
@@ -0,0 +1,82 @@
+.\"-
+.\" Copyright (c) 2002 Networks Associates Technology, Inc.
+.\" All rights reserved.
+.\"
+.\" This software was 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.
+.\"
+.\" $P4: //depot/projects/openpam/doc/man/openpam_restore_cred.3#1 $
+.\"
+.Dd April 8, 2002
+.Dt OPENPAM_RESTORE_CRED 3
+.Os
+.Sh NAME
+.Nm openpam_restore_cred
+.Nd restore credentials
+.Sh LIBRARY
+.Lb libpam
+.Sh SYNOPSIS
+.In security/pam_appl.h
+.Ft int
+.Fn openpam_restore_cred "pam_handle_t *pamh"
+.Sh DESCRIPTION
+The
+.Nm
+function restores the credentials saved by
+.Xr openpam_borrow_cred 3 .
+.Pp
+.Sh RETURN VALUES
+The
+.Nm
+function returns one of the following values:
+.Bl -tag -width 18n
+.It Bq Er PAM_NO_MODULE_DATA
+Module data not found.
+.It Bq Er PAM_SYSTEM_ERR
+System error.
+.El
+.Sh SEE ALSO
+.Xr openpam_borrow_cred 3 ,
+.Xr pam 3 ,
+.Xr pam_strerror 3 ,
+.Xr setegid 3 ,
+.Xr seteuid 3 ,
+.Xr setgroups 3
+.Sh STANDARDS
+The
+.Nm
+function is an OpenPAM extension.
+.Sh AUTHORS
+The
+.Nm
+function and this manual page 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
+.Pq Dq CBOSS ,
+as part of the DARPA CHATS research program.
diff --git a/contrib/openpam/doc/man/openpam_set_option.3 b/contrib/openpam/doc/man/openpam_set_option.3
index f0644cd..6643ee7 100644
--- a/contrib/openpam/doc/man/openpam_set_option.3
+++ b/contrib/openpam/doc/man/openpam_set_option.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/openpam_set_option.3#4 $
+.\" $P4: //depot/projects/openpam/doc/man/openpam_set_option.3#5 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt OPENPAM_SET_OPTION 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/openpam_ttyconv.3 b/contrib/openpam/doc/man/openpam_ttyconv.3
index 1a244fc..df9b1c9 100644
--- a/contrib/openpam/doc/man/openpam_ttyconv.3
+++ b/contrib/openpam/doc/man/openpam_ttyconv.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/openpam_ttyconv.3#5 $
+.\" $P4: //depot/projects/openpam/doc/man/openpam_ttyconv.3#6 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt OPENPAM_TTYCONV 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam.3 b/contrib/openpam/doc/man/pam.3
index d5e3be8..e754d8b 100644
--- a/contrib/openpam/doc/man/pam.3
+++ b/contrib/openpam/doc/man/pam.3
@@ -31,12 +31,15 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam.3#11 $
+.\" $P4: //depot/projects/openpam/doc/man/pam.3#12 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM 3
 .Os
 .Sh NAME
+.Nm openpam_borrow_cred ,
+.Nm openpam_free_data ,
+.Nm openpam_restore_cred ,
 .Nm pam_acct_mgmt ,
 .Nm pam_authenticate ,
 .Nm pam_chauthtok ,
@@ -68,6 +71,12 @@
 .Sh SYNOPSIS
 .In security/pam_appl.h
 .Ft int
+.Fn openpam_borrow_cred "pam_handle_t *pamh" "const struct passwd *pwd"
+.Ft void
+.Fn openpam_free_data "pam_handle_t *pamh" "void *data" "int status"
+.Ft int
+.Fn openpam_restore_cred "pam_handle_t *pamh"
+.Ft int
 .Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags"
 .Ft int
 .Fn pam_authenticate "pam_handle_t *pamh" "int flags"
@@ -80,7 +89,7 @@
 .Ft int
 .Fn pam_error "pam_handle_t *pamh" "const char *fmt" "..."
 .Ft int
-.Fn pam_get_authtok "pam_handle_t *pamh" "const char **authtok" "const char *prompt"
+.Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt"
 .Ft int
 .Fn pam_get_data "pam_handle_t *pamh" "const char *module_data_name" "const void **data"
 .Ft int
@@ -185,6 +194,9 @@ Try again.
 Unknown user.
 .El
 .Sh SEE ALSO
+.Xr openpam_borrow_cred 3 ,
+.Xr openpam_free_data 3 ,
+.Xr openpam_restore_cred 3 ,
 .Xr pam_acct_mgmt 3 ,
 .Xr pam_authenticate 3 ,
 .Xr pam_chauthtok 3 ,
diff --git a/contrib/openpam/doc/man/pam_acct_mgmt.3 b/contrib/openpam/doc/man/pam_acct_mgmt.3
index f514ca3..c73909b 100644
--- a/contrib/openpam/doc/man/pam_acct_mgmt.3
+++ b/contrib/openpam/doc/man/pam_acct_mgmt.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_acct_mgmt.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_acct_mgmt.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_ACCT_MGMT 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_authenticate.3 b/contrib/openpam/doc/man/pam_authenticate.3
index a1d40fa..5a8ee56 100644
--- a/contrib/openpam/doc/man/pam_authenticate.3
+++ b/contrib/openpam/doc/man/pam_authenticate.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_authenticate.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_authenticate.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_AUTHENTICATE 3
 .Os
 .Sh NAME
@@ -46,7 +46,31 @@
 .Ft int
 .Fn pam_authenticate "pam_handle_t *pamh" "int flags"
 .Sh DESCRIPTION
-No description available.
+The
+.Nm
+function attempts to authenticate the user
+associated with the pam context specified by the
+.Va pamh
+argument.
+.Pp
+The application is free to call
+.Nm
+as many times as it
+wishes, but some modules may maintain an internal retry counter and
+return
+.Dv PAM_MAXTRIES
+when it exceeds some preset or hardcoded limit.
+.Pp
+The
+.Va flags
+argument is the binary or of zero or more of the following
+values:
+.Pp
+.Bd -literal
+	=PAM_SILENT
+		Do not emit any messages.
+	=PAM_DISALLOW_NULL_AUTHTOK
+		Fail if the user's authentication token is null.
 .Sh RETURN VALUES
 The
 .Nm
diff --git a/contrib/openpam/doc/man/pam_chauthtok.3 b/contrib/openpam/doc/man/pam_chauthtok.3
index a4bd920..8525d6d 100644
--- a/contrib/openpam/doc/man/pam_chauthtok.3
+++ b/contrib/openpam/doc/man/pam_chauthtok.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_chauthtok.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_chauthtok.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_CHAUTHTOK 3
 .Os
 .Sh NAME
@@ -46,7 +46,23 @@
 .Ft int
 .Fn pam_chauthtok "pam_handle_t *pamh" "int flags"
 .Sh DESCRIPTION
-No description available.
+The
+.Nm
+function attempts to change the authentication token
+for the user associated with the pam context specified by the
+.Va pamh
+argument.
+.Pp
+The
+.Va flags
+argument is the binary or of zero or more of the following
+values:
+.Pp
+.Bd -literal
+	=PAM_SILENT
+		Do not emit any messages.
+	=PAM_CHANGE_EXPIRED_AUTHTOK
+		Change only those authentication tokens that have expired.
 .Sh RETURN VALUES
 The
 .Nm
diff --git a/contrib/openpam/doc/man/pam_close_session.3 b/contrib/openpam/doc/man/pam_close_session.3
index 2e01eb4..54f7a7d 100644
--- a/contrib/openpam/doc/man/pam_close_session.3
+++ b/contrib/openpam/doc/man/pam_close_session.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_close_session.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_close_session.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_CLOSE_SESSION 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_end.3 b/contrib/openpam/doc/man/pam_end.3
index f559015..b4a88fc 100644
--- a/contrib/openpam/doc/man/pam_end.3
+++ b/contrib/openpam/doc/man/pam_end.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_end.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_end.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_END 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_error.3 b/contrib/openpam/doc/man/pam_error.3
index 5fe3dc7..e68dcf8 100644
--- a/contrib/openpam/doc/man/pam_error.3
+++ b/contrib/openpam/doc/man/pam_error.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_error.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_error.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_ERROR 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_get_authtok.3 b/contrib/openpam/doc/man/pam_get_authtok.3
index 296c900..a582991 100644
--- a/contrib/openpam/doc/man/pam_get_authtok.3
+++ b/contrib/openpam/doc/man/pam_get_authtok.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_get_authtok.3#10 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_get_authtok.3#11 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_GET_AUTHTOK 3
 .Os
 .Sh NAME
@@ -44,9 +44,66 @@
 .Sh SYNOPSIS
 .In security/pam_appl.h
 .Ft int
-.Fn pam_get_authtok "pam_handle_t *pamh" "const char **authtok" "const char *prompt"
+.Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt"
 .Sh DESCRIPTION
-No description available.
+The
+.Nm
+function returns the cached authentication token,
+or prompts the user if no token is currently cached.  Either way, a
+pointer to the authentication token is stored in the location pointed
+to by the
+.Va authtok
+argument.
+.Pp
+The
+.Va item
+argument must have one of the following values:
+.Pp
+.Bd -literal
+	=PAM_AUTHTOK
+		Returns the current authentication token, or the new token
+		when changing authentication tokens.
+	=PAM_OLDAUTHTOK
+		Returns the previous authentication token when changing
+		authentication tokens.
+
+.Ed
+The
+.Va prompt
+argument specifies a prompt to use if no token is cached.
+.Ed
+If it is
+.Dv NULL ,
+the
+.Dv PAM_AUTHTOK_PROMPT
+or
+.Dv PAM_OLDAUTHTOK_PROMPT
+item,
+.Ed
+as appropriate, will be used.  If that item is also
+.Dv NULL ,
+a hardcoded
+.Ed
+default prompt will be used.
+
+.Ed
+If
+.Va item
+is set to
+.Dv PAM_AUTHTOK
+and there is a non-null
+.Dv PAM_OLDAUTHTOK
+.Ed
+item,
+.Nm
+will ask the user to confirm the new token by
+.Ed
+retyping it.  If there is a mismatch,
+.Nm
+will return
+.Ed
+.Dv PAM_TRY_AGAIN .
+
 .Sh RETURN VALUES
 The
 .Nm
@@ -58,9 +115,13 @@ Memory buffer error.
 Conversation failure.
 .It Bq Er PAM_SYSTEM_ERR
 System error.
+.It Bq Er PAM_TRY_AGAIN
+Try again.
 .El
 .Sh SEE ALSO
 .Xr pam 3 ,
+.Xr pam_get_item 3 ,
+.Xr pam_get_user 3 ,
 .Xr pam_strerror 3
 .Sh STANDARDS
 The
diff --git a/contrib/openpam/doc/man/pam_get_data.3 b/contrib/openpam/doc/man/pam_get_data.3
index c5e3637..1a59578 100644
--- a/contrib/openpam/doc/man/pam_get_data.3
+++ b/contrib/openpam/doc/man/pam_get_data.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_get_data.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_get_data.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_GET_DATA 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_get_item.3 b/contrib/openpam/doc/man/pam_get_item.3
index 37f3a28..33cee1e 100644
--- a/contrib/openpam/doc/man/pam_get_item.3
+++ b/contrib/openpam/doc/man/pam_get_item.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_get_item.3#10 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_get_item.3#11 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_GET_ITEM 3
 .Os
 .Sh NAME
@@ -85,6 +85,9 @@ name to authenticate as.
 .It Dv PAM_AUTHTOK_PROMPT
 The prompt to use when asking the applicant for an
 authentication token.
+.It Dv PAM_OLDAUTHTOK_PROMPT
+The prompt to use when asking the applicant for an
+expired authentication token prior to changing it.
 .El
 See
 .Xr pam_start 3
diff --git a/contrib/openpam/doc/man/pam_get_user.3 b/contrib/openpam/doc/man/pam_get_user.3
index 15c967a..e6aba14 100644
--- a/contrib/openpam/doc/man/pam_get_user.3
+++ b/contrib/openpam/doc/man/pam_get_user.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_get_user.3#10 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_get_user.3#11 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_GET_USER 3
 .Os
 .Sh NAME
@@ -46,7 +46,31 @@
 .Ft int
 .Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt"
 .Sh DESCRIPTION
-No description available.
+The
+.Nm
+function returns the name of the target user, as
+specified to
+.Xr pam_start 3 .
+If no user was specified, nor set using
+.Xr pam_set_item 3 ,
+.Nm
+will prompt for a user name.  Either way,
+a pointer to the user name is stored in the location pointed to by the
+.Va user
+argument.
+.Pp
+The
+.Va prompt
+argument specifies a prompt to use if no user name is
+cached.  If it is
+.Dv NULL ,
+the
+.Dv PAM_USER_PROMPT
+will be used.  If that
+item is also
+.Dv NULL ,
+a hardcoded default prompt will be used.
+.Pp
 .Sh RETURN VALUES
 The
 .Nm
@@ -61,6 +85,10 @@ System error.
 .El
 .Sh SEE ALSO
 .Xr pam 3 ,
+.Xr pam_get_authtok 3 ,
+.Xr pam_get_item 3 ,
+.Xr pam_set_item 3 ,
+.Xr pam_start 3 ,
 .Xr pam_strerror 3
 .Sh STANDARDS
 .Rs
diff --git a/contrib/openpam/doc/man/pam_getenv.3 b/contrib/openpam/doc/man/pam_getenv.3
index e4d0578..3c7cc61 100644
--- a/contrib/openpam/doc/man/pam_getenv.3
+++ b/contrib/openpam/doc/man/pam_getenv.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_getenv.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_getenv.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_GETENV 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_getenvlist.3 b/contrib/openpam/doc/man/pam_getenvlist.3
index b4042d1..46147a6 100644
--- a/contrib/openpam/doc/man/pam_getenvlist.3
+++ b/contrib/openpam/doc/man/pam_getenvlist.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_getenvlist.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_getenvlist.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_GETENVLIST 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_info.3 b/contrib/openpam/doc/man/pam_info.3
index 6806123..99237cc 100644
--- a/contrib/openpam/doc/man/pam_info.3
+++ b/contrib/openpam/doc/man/pam_info.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_info.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_info.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_INFO 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_open_session.3 b/contrib/openpam/doc/man/pam_open_session.3
index cdb56c7..872ebca 100644
--- a/contrib/openpam/doc/man/pam_open_session.3
+++ b/contrib/openpam/doc/man/pam_open_session.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_open_session.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_open_session.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_OPEN_SESSION 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_prompt.3 b/contrib/openpam/doc/man/pam_prompt.3
index 7a902ea..18a8273 100644
--- a/contrib/openpam/doc/man/pam_prompt.3
+++ b/contrib/openpam/doc/man/pam_prompt.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_prompt.3#10 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_prompt.3#11 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_PROMPT 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_putenv.3 b/contrib/openpam/doc/man/pam_putenv.3
index 8186f49..254ed80 100644
--- a/contrib/openpam/doc/man/pam_putenv.3
+++ b/contrib/openpam/doc/man/pam_putenv.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_putenv.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_putenv.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_PUTENV 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_set_data.3 b/contrib/openpam/doc/man/pam_set_data.3
index 2e08b14..1d325e3 100644
--- a/contrib/openpam/doc/man/pam_set_data.3
+++ b/contrib/openpam/doc/man/pam_set_data.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_set_data.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_set_data.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SET_DATA 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_set_item.3 b/contrib/openpam/doc/man/pam_set_item.3
index be16aae..99d4f5e 100644
--- a/contrib/openpam/doc/man/pam_set_item.3
+++ b/contrib/openpam/doc/man/pam_set_item.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_set_item.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_set_item.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SET_ITEM 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_setcred.3 b/contrib/openpam/doc/man/pam_setcred.3
index c4a1461..8055f9a 100644
--- a/contrib/openpam/doc/man/pam_setcred.3
+++ b/contrib/openpam/doc/man/pam_setcred.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_setcred.3#10 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_setcred.3#11 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SETCRED 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_setenv.3 b/contrib/openpam/doc/man/pam_setenv.3
index 7cd07b2..5c942b9 100644
--- a/contrib/openpam/doc/man/pam_setenv.3
+++ b/contrib/openpam/doc/man/pam_setenv.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_setenv.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_setenv.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SETENV 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_sm_acct_mgmt.3 b/contrib/openpam/doc/man/pam_sm_acct_mgmt.3
index a43bf58..cdfe7e1 100644
--- a/contrib/openpam/doc/man/pam_sm_acct_mgmt.3
+++ b/contrib/openpam/doc/man/pam_sm_acct_mgmt.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_sm_acct_mgmt.3#5 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_sm_acct_mgmt.3#6 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SM_ACCT_MGMT 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_sm_authenticate.3 b/contrib/openpam/doc/man/pam_sm_authenticate.3
index 350be4b..e8254c7 100644
--- a/contrib/openpam/doc/man/pam_sm_authenticate.3
+++ b/contrib/openpam/doc/man/pam_sm_authenticate.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_sm_authenticate.3#5 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_sm_authenticate.3#6 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SM_AUTHENTICATE 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_sm_chauthtok.3 b/contrib/openpam/doc/man/pam_sm_chauthtok.3
index cb907ab..11291c7 100644
--- a/contrib/openpam/doc/man/pam_sm_chauthtok.3
+++ b/contrib/openpam/doc/man/pam_sm_chauthtok.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_sm_chauthtok.3#5 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_sm_chauthtok.3#6 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SM_CHAUTHTOK 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_sm_close_session.3 b/contrib/openpam/doc/man/pam_sm_close_session.3
index 11e1378..bc7e982 100644
--- a/contrib/openpam/doc/man/pam_sm_close_session.3
+++ b/contrib/openpam/doc/man/pam_sm_close_session.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_sm_close_session.3#5 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_sm_close_session.3#6 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SM_CLOSE_SESSION 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_sm_open_session.3 b/contrib/openpam/doc/man/pam_sm_open_session.3
index 8cb2b01..796eb08 100644
--- a/contrib/openpam/doc/man/pam_sm_open_session.3
+++ b/contrib/openpam/doc/man/pam_sm_open_session.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_sm_open_session.3#5 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_sm_open_session.3#6 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SM_OPEN_SESSION 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_sm_setcred.3 b/contrib/openpam/doc/man/pam_sm_setcred.3
index 736022b..adaac06 100644
--- a/contrib/openpam/doc/man/pam_sm_setcred.3
+++ b/contrib/openpam/doc/man/pam_sm_setcred.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_sm_setcred.3#5 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_sm_setcred.3#6 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_SM_SETCRED 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_start.3 b/contrib/openpam/doc/man/pam_start.3
index 004a4a1..913ac03 100644
--- a/contrib/openpam/doc/man/pam_start.3
+++ b/contrib/openpam/doc/man/pam_start.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_start.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_start.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_START 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_strerror.3 b/contrib/openpam/doc/man/pam_strerror.3
index f50a1ce..993e32e 100644
--- a/contrib/openpam/doc/man/pam_strerror.3
+++ b/contrib/openpam/doc/man/pam_strerror.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_strerror.3#9 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_strerror.3#10 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_STRERROR 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_verror.3 b/contrib/openpam/doc/man/pam_verror.3
index 4043769..f71381c 100644
--- a/contrib/openpam/doc/man/pam_verror.3
+++ b/contrib/openpam/doc/man/pam_verror.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_verror.3#7 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_verror.3#8 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_VERROR 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_vinfo.3 b/contrib/openpam/doc/man/pam_vinfo.3
index d757218..8a2ba09 100644
--- a/contrib/openpam/doc/man/pam_vinfo.3
+++ b/contrib/openpam/doc/man/pam_vinfo.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_vinfo.3#7 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_vinfo.3#8 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_VINFO 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/doc/man/pam_vprompt.3 b/contrib/openpam/doc/man/pam_vprompt.3
index 9ff0b28..dd31d06 100644
--- a/contrib/openpam/doc/man/pam_vprompt.3
+++ b/contrib/openpam/doc/man/pam_vprompt.3
@@ -31,9 +31,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $P4: //depot/projects/openpam/doc/man/pam_vprompt.3#7 $
+.\" $P4: //depot/projects/openpam/doc/man/pam_vprompt.3#8 $
 .\"
-.Dd March 7, 2002
+.Dd April 8, 2002
 .Dt PAM_VPROMPT 3
 .Os
 .Sh NAME
diff --git a/contrib/openpam/include/security/openpam.h b/contrib/openpam/include/security/openpam.h
index b001398..214401a 100644
--- a/contrib/openpam/include/security/openpam.h
+++ b/contrib/openpam/include/security/openpam.h
@@ -31,7 +31,7 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * $P4: //depot/projects/openpam/include/security/openpam.h#14 $
+ * $P4: //depot/projects/openpam/include/security/openpam.h#15 $
  */
 
 #ifndef _SECURITY_OPENPAM_H_INCLUDED
@@ -46,14 +46,28 @@
 extern "C" {
 #endif
 
+struct passwd;
+
 /*
  * API extensions
  */
+int
+openpam_borrow_cred(pam_handle_t *_pamh,
+	const struct passwd *_pwd);
+
+void
+openpam_free_data(pam_handle_t *_pamh,
+	void *_data,
+	int _status);
+
 const char *
 openpam_get_option(pam_handle_t *_pamh,
 	const char *_option);
 
 int
+openpam_restore_cred(pam_handle_t *_pamh);
+
+int
 openpam_set_option(pam_handle_t *_pamh,
 	const char *_option,
 	const char *_value);
diff --git a/contrib/openpam/lib/Makefile b/contrib/openpam/lib/Makefile
index d9f38c3..f2fb006 100644
--- a/contrib/openpam/lib/Makefile
+++ b/contrib/openpam/lib/Makefile
@@ -31,7 +31,7 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 #
-# $P4: //depot/projects/openpam/lib/Makefile#12 $
+# $P4: //depot/projects/openpam/lib/Makefile#13 $
 #
 
 LIB		 = pam
@@ -44,12 +44,15 @@ CFLAGS		+= -I${.CURDIR}/../include
 CFLAGS		+= -DLIB_MAJ=${SHLIB_MAJOR}
 
 SRCS		 =
+SRCS		+= openpam_borrow_cred.c
 SRCS		+= openpam_dispatch.c
 SRCS		+= openpam_dynamic.c
 SRCS		+= openpam_findenv.c
+SRCS		+= openpam_free_data.c
 SRCS		+= openpam_get_option.c
 SRCS		+= openpam_load.c
 SRCS		+= openpam_log.c
+SRCS		+= openpam_restore_cred.c
 SRCS		+= openpam_set_option.c
 SRCS		+= openpam_static.c
 SRCS		+= openpam_ttyconv.c
diff --git a/contrib/openpam/lib/openpam_borrow_cred.c b/contrib/openpam/lib/openpam_borrow_cred.c
new file mode 100644
index 0000000..87aed86
--- /dev/null
+++ b/contrib/openpam/lib/openpam_borrow_cred.c
@@ -0,0 +1,105 @@
+/*-
+ * Copyright (c) 2002 Networks Associates Technology, Inc.
+ * All rights reserved.
+ *
+ * This software was 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.
+ *
+ * $P4: //depot/projects/openpam/lib/openpam_borrow_cred.c#1 $
+ */
+
+#include <sys/param.h>
+
+#include <pwd.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+#include <security/pam_appl.h>
+
+#include "openpam_impl.h"
+
+/*
+ * OpenPAM extension
+ *
+ * Temporarily borrow user credentials
+ */
+
+int
+openpam_borrow_cred(pam_handle_t *pamh,
+	const struct passwd *pwd)
+{
+	struct pam_saved_cred *scred;
+	int r;
+
+	if (geteuid() != 0)
+		return (PAM_PERM_DENIED);
+	scred = calloc(1, sizeof *scred);
+	if (scred == NULL)
+		return (PAM_BUF_ERR);
+	scred->euid = geteuid();
+	scred->egid = getegid();
+	r = getgroups(NGROUPS_MAX, scred->groups);
+	if (r == -1) {
+		free(scred);
+		return (PAM_SYSTEM_ERR);
+	}
+	scred->ngroups = r;
+	r = pam_set_data(pamh, PAM_SAVED_CRED, scred, &openpam_free_data);
+	if (r != PAM_SUCCESS) {
+		free(scred);
+		return (r);
+	}
+	if (initgroups(pwd->pw_name, pwd->pw_gid) == -1 ||
+	      setegid(pwd->pw_gid) == -1 || seteuid(pwd->pw_uid) == -1) {
+		openpam_restore_cred(pamh);
+		return (PAM_SYSTEM_ERR);
+	}
+	return (PAM_SUCCESS);
+}
+
+/*
+ * Error codes:
+ *
+ *	=pam_set_data
+ *	PAM_SYSTEM_ERR
+ *	PAM_BUF_ERR
+ *	PAM_PERM_DENIED
+ */
+
+/**
+ * The =openpam_borrow_cred function saves the current credentials and
+ * switches to those of the user specified by its =pwd argument.  The
+ * affected credentials are the effective UID, the effective GID, and the
+ * group access list.  The original credentials can be restored using
+ * =openpam_restore_cred.
+ *
+ * >setegid
+ * >seteuid
+ * >setgroups
+ */
diff --git a/contrib/openpam/lib/openpam_free_data.c b/contrib/openpam/lib/openpam_free_data.c
new file mode 100644
index 0000000..6c71266
--- /dev/null
+++ b/contrib/openpam/lib/openpam_free_data.c
@@ -0,0 +1,67 @@
+/*-
+ * Copyright (c) 2002 Networks Associates Technology, Inc.
+ * All rights reserved.
+ *
+ * This software was 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.
+ *
+ * $P4: //depot/projects/openpam/lib/openpam_free_data.c#1 $
+ */
+
+#include <stdlib.h>
+#include <string.h>
+
+#include <security/pam_appl.h>
+
+#include "openpam_impl.h"
+
+/*
+ * OpenPAM extension
+ *
+ * Generic cleanup function
+ */
+
+void
+openpam_free_data(pam_handle_t *pamh, void *data, int status)
+{
+	/* silence compiler warnings */
+	pamh = pamh;
+	status = status;
+	free(data);
+}
+
+/*
+ * Error codes:
+ */
+
+/**
+ * The =openpam_free_data is a cleanup function suitable for passing to
+ * =pam_set_data.  It simply releases the data by passing its =data
+ * argument to =free.
+ */
diff --git a/contrib/openpam/lib/openpam_impl.h b/contrib/openpam/lib/openpam_impl.h
index 8300b0f..a9b011e 100644
--- a/contrib/openpam/lib/openpam_impl.h
+++ b/contrib/openpam/lib/openpam_impl.h
@@ -31,7 +31,7 @@
  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  *
- * $P4: //depot/projects/openpam/lib/openpam_impl.h#11 $
+ * $P4: //depot/projects/openpam/lib/openpam_impl.h#12 $
  */
 
 #ifndef _OPENPAM_IMPL_H_INCLUDED
@@ -93,6 +93,16 @@ struct pam_handle {
 	int		 env_size;
 };
 
+#ifdef NGROUPS_MAX
+#define PAM_SAVED_CRED "pam_saved_cred"
+struct pam_saved_cred {
+	uid_t	 euid;
+	gid_t	 egid;
+	gid_t	 groups[NGROUPS_MAX];
+	int	 ngroups;
+};
+#endif
+
 #define PAM_OTHER	"other"
 
 int		openpam_dispatch(pam_handle_t *, int, int);
diff --git a/contrib/openpam/lib/openpam_restore_cred.c b/contrib/openpam/lib/openpam_restore_cred.c
new file mode 100644
index 0000000..05c3b10
--- /dev/null
+++ b/contrib/openpam/lib/openpam_restore_cred.c
@@ -0,0 +1,86 @@
+/*-
+ * Copyright (c) 2002 Networks Associates Technology, Inc.
+ * All rights reserved.
+ *
+ * This software was 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.
+ *
+ * $P4: //depot/projects/openpam/lib/openpam_restore_cred.c#1 $
+ */
+
+#include <sys/param.h>
+
+#include <pwd.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+#include <security/pam_appl.h>
+
+#include "openpam_impl.h"
+
+/*
+ * OpenPAM extension
+ *
+ * Restore credentials
+ */
+
+int
+openpam_restore_cred(pam_handle_t *pamh)
+{
+	struct pam_saved_cred *scred;
+	int r;
+
+	r = pam_get_data(pamh, PAM_SAVED_CRED, (const void **)&scred);
+	if (r != PAM_SUCCESS)
+		return (r);
+	if (scred == NULL)
+		return (PAM_SYSTEM_ERR);
+	if (seteuid(scred->euid) == -1 ||
+	    setgroups(scred->ngroups, scred->groups) == -1 ||
+	    setegid(scred->egid) == -1)
+		return (PAM_SYSTEM_ERR);
+	pam_set_data(pamh, PAM_SAVED_CRED, NULL, NULL);
+	return (PAM_SUCCESS);
+}
+
+/*
+ * Error codes:
+ *
+ *	=pam_get_data
+ *	PAM_SYSTEM_ERR
+ */
+
+/**
+ * The =openpam_restore_cred function restores the credentials saved by
+ * =openpam_borrow_cred.
+ *
+ * >setegid
+ * >seteuid
+ * >setgroups
+ */