'\" te
.\"  Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PAM_SAMPLE 5 "Apr 4, 2007"
.SH NAME
pam_sample \- a sample PAM module
.SH SYNOPSIS
.LP
.nf
\fB/usr/lib/security/pam_sample.so.1\fR
.fi

.SH DESCRIPTION
.sp
.LP
The SAMPLE service module for \fBPAM\fR is divided into four components:
authentication, account management, password management, and session
management. The sample module is a shared object that is dynamically loaded to
provide the necessary functionality.
.SH SAMPLE AUTHENTICATION COMPONENT
.sp
.LP
The SAMPLE authentication module provides functions to test the \fBPAM\fR
framework functionality using the \fBpam_sm_authenticate\fR(3PAM) call. The
SAMPLE module implementation of the \fBpam_sm_authenticate\fR(3PAM) function
compares the user entered password with the password set in the
\fBpam.conf\fR(4) file, or the string "test" if a default test password has not
been set. The following options can be passed in to the SAMPLE Authentication
module:
.sp
.ne 2
.na
\fB\fBdebug\fR \fR
.ad
.RS 20n
Syslog debugging information at the \fBLOG_DEBUG\fR level.
.RE

.sp
.ne 2
.na
\fB\fBpass=newone\fR \fR
.ad
.RS 20n
Sets the password to be "newone".
.RE

.sp
.ne 2
.na
\fB\fBfirst_pass_good\fR \fR
.ad
.RS 20n
The first password is always good when used with the use_first_pass or
try_first_pass option.
.RE

.sp
.ne 2
.na
\fB\fBfirst_pass_bad\fR \fR
.ad
.RS 20n
The first password is always bad when used with the use_first_pass or
try_first_pass option.
.RE

.sp
.ne 2
.na
\fB\fBalways_fail\fR \fR
.ad
.RS 20n
Always returns \fBPAM_AUTH_ERR.\fR
.RE

.sp
.ne 2
.na
\fB\fBalways_succeed\fR \fR
.ad
.RS 20n
Always returns \fBPAM_SUCCESS.\fR
.RE

.sp
.ne 2
.na
\fB\fBalways_ignore\fR \fR
.ad
.RS 20n
Always returns \fBPAM_IGNORE.\fR
.RE

.sp
.ne 2
.na
\fB\fBuse_first_pass\fR \fR
.ad
.RS 20n
Use the user's initial password (entered when the user is authenticated to the
first authentication module in the stack) to authenticate with the SAMPLE
module. If the passwords do not match, or if this is the first authentication
module in the stack, quit and do not prompt the user for a password. It is
recommended that this option only be used if the SAMPLE authentication module
is designated as \fIoptional\fR in the \fBpam.conf\fR configuration file.
.RE

.sp
.ne 2
.na
\fB\fBtry_first_pass\fR \fR
.ad
.RS 20n
Use the user's initial password (entered when the user is authenticated to the
first authentication module in the stack) to authenticate with the SAMPLE
module. If the passwords do not match, or if this is the first authentication
module in the stack, prompt the user for a password.
.sp
The SAMPLE module \fBpam_sm_setcred\fR(3PAM) function always returns
\fBPAM_SUCCESS.\fR
.RE

.SH SAMPLE ACCOUNT MANAGEMENT COMPONENT
.sp
.LP
The SAMPLE Account Management Component implements a simple access control
scheme that limits machine access to a list of authorized users. The list of
authorized users is supplied as option arguments to the entry for the SAMPLE
account management \fBPAM\fR module in the \fBpam.conf\fR file. Note that the
module always permits access to the root super user.
.sp
.LP
The option field syntax to limit access is shown below: allow=
\fIname[,name]\fR allow= \fIname\fR \fI[allow=name]\fR
.sp
.LP
The example \fBpam.conf\fR show below permits only larry to \fBlogin\fR
directly. \fBrlogin\fR is allowed only for don and larry. Once a user is logged
in, the user can use \fBsu\fR if the user are sam or eric.
.sp

.sp
.TS
l l l l l
l l l l l .
login	account	require	pam_sample.so.1	allow=larry
dtlogin	account	require	pam_sample.so.1	allow=larry
rlogin	account	require	pam_sample.so.1	allow=don allow=larry
su	account	require	pam_sample.so.1	allow=sam,eric
.TE

.sp
.LP
The debug and nowarn options are also supported.
.SH SAMPLE PASSWORD MANAGEMENT COMPONENT
.sp
.LP
The SAMPLE Password Management Component function (
\fBpam_sm_chauthtok\fR(3PAM)), always returns \fBPAM_SUCCESS.\fR
.SH SAMPLE SESSION MANAGEMENT COMPONENT
.sp
.LP
The SAMPLE Session Management Component functions (
\fBpam_sm_open_session\fR(3PAM), \fBpam_sm_close_session\fR(3PAM)) always
return \fBPAM_SUCCESS.\fR
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT Level	MT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
\fBpam\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), \fBpam_sm_chauthtok\fR(3PAM),
\fBpam_sm_close_session\fR(3PAM), \fBpam_sm_open_session\fR(3PAM),
\fBpam_sm_setcred\fR(3PAM), \fBlibpam\fR(3LIB), \fBpam.conf\fR(4),
\fBattributes\fR(5)
.SH WARNINGS
.sp
.LP
This module should never be used outside of a closed debug environment. The
examples of the \fBuse_first_pass\fR and \fBtry_first_pass\fR options are
obsolete for all other Solaris delivered PAM service modules
.SH NOTES
.sp
.LP
The interfaces in \fBlibpam()\fR are MT-Safe only if each thread within the
multi-threaded application uses its own \fBPAM\fR handle.