usr/src/man/man5/pam_sample.5

   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
  14
  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
  40
  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
  49
  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
  59
  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
  69
  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
  78
  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
  87
  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
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBuse_first_pass\fR \fR
 101 .ad
 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.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBtry_first_pass\fR \fR
 115 .ad
 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.
 121 .sp
 122 The SAMPLE module \fBpam_sm_setcred\fR(3PAM) function always returns
 123 \fBPAM_SUCCESS.\fR
 124 .RE
 125
 126 .SH SAMPLE ACCOUNT MANAGEMENT COMPONENT
 127 .sp
 128 .LP
 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.
 134 .sp
 135 .LP
 136 The option field syntax to limit access is shown below: allow=
 137 \fIname[,name]\fR allow= \fIname\fR \fI[allow=name]\fR
 138 .sp
 139 .LP
 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.
 143 .sp
 144
 145 .sp
 146 .TS
 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
 153 .TE
 154
 155 .sp
 156 .LP
 157 The debug and nowarn options are also supported.
 158 .SH SAMPLE PASSWORD MANAGEMENT COMPONENT
 159 .sp
 160 .LP
 161 The SAMPLE Password Management Component function (
 162 \fBpam_sm_chauthtok\fR(3PAM)), always returns \fBPAM_SUCCESS.\fR
 163 .SH SAMPLE SESSION MANAGEMENT COMPONENT
 164 .sp
 165 .LP
 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
 170 .sp
 171 .LP
 172 See \fBattributes\fR(5) for description of the following attributes:
 173 .sp
 174
 175 .sp
 176 .TS
 177 box;
 178 c | c
 179 l | l .
 180 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 181 _
 182 MT Level        MT-Safe with exceptions
 183 .TE
 184
 185 .SH SEE ALSO
 186 .sp
 187 .LP
 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
 193 .sp
 194 .LP
 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
 199 .sp
 200 .LP
 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.