Unleashed v1.4
[unleashed.git] / share / man / man5 / pam_sample.5
blob38f313607f034aca1c2d169f1f72272bc37c0d95
1 '\" te
2 .\"  Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH PAM_SAMPLE 5 "Apr 4, 2007"
7 .SH NAME
8 pam_sample \- a sample PAM module
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/lib/security/pam_sample.so.1\fR
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 The SAMPLE service module for \fBPAM\fR is divided into four components:
19 authentication, account management, password management, and session
20 management. The sample module is a shared object that is dynamically loaded to
21 provide the necessary functionality.
22 .SH SAMPLE AUTHENTICATION COMPONENT
23 .sp
24 .LP
25 The SAMPLE authentication module provides functions to test the \fBPAM\fR
26 framework functionality using the \fBpam_sm_authenticate\fR(3PAM) call. The
27 SAMPLE module implementation of the \fBpam_sm_authenticate\fR(3PAM) function
28 compares the user entered password with the password set in the
29 \fBpam.conf\fR(4) file, or the string "test" if a default test password has not
30 been set. The following options can be passed in to the SAMPLE Authentication
31 module:
32 .sp
33 .ne 2
34 .na
35 \fB\fBdebug\fR \fR
36 .ad
37 .RS 20n
38 Syslog debugging information at the \fBLOG_DEBUG\fR level.
39 .RE
41 .sp
42 .ne 2
43 .na
44 \fB\fBpass=newone\fR \fR
45 .ad
46 .RS 20n
47 Sets the password to be "newone".
48 .RE
50 .sp
51 .ne 2
52 .na
53 \fB\fBfirst_pass_good\fR \fR
54 .ad
55 .RS 20n
56 The first password is always good when used with the use_first_pass or
57 try_first_pass option.
58 .RE
60 .sp
61 .ne 2
62 .na
63 \fB\fBfirst_pass_bad\fR \fR
64 .ad
65 .RS 20n
66 The first password is always bad when used with the use_first_pass or
67 try_first_pass option.
68 .RE
70 .sp
71 .ne 2
72 .na
73 \fB\fBalways_fail\fR \fR
74 .ad
75 .RS 20n
76 Always returns \fBPAM_AUTH_ERR.\fR
77 .RE
79 .sp
80 .ne 2
81 .na
82 \fB\fBalways_succeed\fR \fR
83 .ad
84 .RS 20n
85 Always returns \fBPAM_SUCCESS.\fR
86 .RE
88 .sp
89 .ne 2
90 .na
91 \fB\fBalways_ignore\fR \fR
92 .ad
93 .RS 20n
94 Always returns \fBPAM_IGNORE.\fR
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fB\fBuse_first_pass\fR \fR
102 .RS 20n
103 Use the user's initial password (entered when the user is authenticated to the
104 first authentication module in the stack) to authenticate with the SAMPLE
105 module. If the passwords do not match, or if this is the first authentication
106 module in the stack, quit and do not prompt the user for a password. It is
107 recommended that this option only be used if the SAMPLE authentication module
108 is designated as \fIoptional\fR in the \fBpam.conf\fR configuration file.
112 .ne 2
114 \fB\fBtry_first_pass\fR \fR
116 .RS 20n
117 Use the user's initial password (entered when the user is authenticated to the
118 first authentication module in the stack) to authenticate with the SAMPLE
119 module. If the passwords do not match, or if this is the first authentication
120 module in the stack, prompt the user for a password.
122 The SAMPLE module \fBpam_sm_setcred\fR(3PAM) function always returns
123 \fBPAM_SUCCESS.\fR
126 .SH SAMPLE ACCOUNT MANAGEMENT COMPONENT
129 The SAMPLE Account Management Component implements a simple access control
130 scheme that limits machine access to a list of authorized users. The list of
131 authorized users is supplied as option arguments to the entry for the SAMPLE
132 account management \fBPAM\fR module in the \fBpam.conf\fR file. Note that the
133 module always permits access to the root super user.
136 The option field syntax to limit access is shown below: allow=
137 \fIname[,name]\fR allow= \fIname\fR \fI[allow=name]\fR
140 The example \fBpam.conf\fR show below permits only larry to \fBlogin\fR
141 directly. \fBrlogin\fR is allowed only for don and larry. Once a user is logged
142 in, the user can use \fBsu\fR if the user are sam or eric.
147 l l l l l
148 l l l l l .
149 login   account require pam_sample.so.1 allow=larry
150 dtlogin account require pam_sample.so.1 allow=larry
151 rlogin  account require pam_sample.so.1 allow=don allow=larry
152 su      account require pam_sample.so.1 allow=sam,eric
157 The debug and nowarn options are also supported.
158 .SH SAMPLE PASSWORD MANAGEMENT COMPONENT
161 The SAMPLE Password Management Component function (
162 \fBpam_sm_chauthtok\fR(3PAM)), always returns \fBPAM_SUCCESS.\fR
163 .SH SAMPLE SESSION MANAGEMENT COMPONENT
166 The SAMPLE Session Management Component functions (
167 \fBpam_sm_open_session\fR(3PAM), \fBpam_sm_close_session\fR(3PAM)) always
168 return \fBPAM_SUCCESS.\fR
169 .SH ATTRIBUTES
172 See \fBattributes\fR(5) for description of the following attributes:
177 box;
178 c | c
179 l | l .
180 ATTRIBUTE TYPE  ATTRIBUTE VALUE
182 MT Level        MT-Safe with exceptions
185 .SH SEE ALSO
188 \fBpam\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), \fBpam_sm_chauthtok\fR(3PAM),
189 \fBpam_sm_close_session\fR(3PAM), \fBpam_sm_open_session\fR(3PAM),
190 \fBpam_sm_setcred\fR(3PAM), \fBlibpam\fR(3LIB), \fBpam.conf\fR(4),
191 \fBattributes\fR(5)
192 .SH WARNINGS
195 This module should never be used outside of a closed debug environment. The
196 examples of the \fBuse_first_pass\fR and \fBtry_first_pass\fR options are
197 obsolete for all other Solaris delivered PAM service modules
198 .SH NOTES
201 The interfaces in \fBlibpam()\fR are MT-Safe only if each thread within the
202 multi-threaded application uses its own \fBPAM\fR handle.