'\" te
.\" Copyright (c) 2008, 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_UNIX_AUTH 7 "August 19, 2023"
.SH NAME
pam_unix_auth \- PAM authentication module for UNIX
.SH SYNOPSIS
.nf
\fBpam_unix_auth.so.1\fR
.fi

.SH DESCRIPTION
The \fBpam_unix_auth\fR module implements \fBpam_sm_authenticate\fR(3PAM), which
provides functionality to the PAM authentication stack. It provides functions
that use \fBcrypt\fR(3C) to verify that the password contained in the \fBPAM\fR
item \fBPAM_AUTHTOK\fR is the correct password for the user specified in the
item \fBPAM_USER\fR. If \fBPAM_REPOSITORY\fR is specified, then user's password
is fetched from that repository. Otherwise, the default \fBnsswitch.conf\fR(5)
repository is searched for that user.
.sp
.LP
For accounts in the name services which support automatic account locking, the
account may be configured to be automatically locked (see \fBuser_attr\fR(5)
and \fBpolicy.conf\fR(5)) after multiple failed login attempts.  For accounts
that are configured for automatic locking, if authentication failure is to be
returned, the failed login counter is incremented upon each failure. If the
number of successive failures equals or exceeds \fBRETRIES\fR as defined in
\fBlogin\fR(1), the account is locked and \fBPAM_MAXTRIES\fR is returned.
Currently, only the "files" repository (see \fBpasswd\fR(5) and
\fBshadow\fR(5)) supports automatic account locking. A successful
authentication by this module clears the failed login counter and reports the
number of failed attempts since the last successful authentication.
.sp
.LP
Authentication service modules must implement both \fBpam_sm_authenticate()\fR
and \fBpam_sm_setcred()\fR. To allow the authentication portion of UNIX
authentication to be replaced, \fBpam_sm_setcred()\fR in this module always
returns \fBPAM_IGNORE\fR. This module should be stacked with
\fBpam_unix_cred\fR(7) to ensure a successful return from
\fBpam_setcred\fR(3PAM).
.sp
.LP
The following options can be passed to the module:
.sp
.ne 2
.na
\fB\fBnowarn\fR\fR
.ad
.sp .6
.RS 4n
Turn off warning messages.
.RE

.sp
.ne 2
.na
\fB\fBserver_policy\fR\fR
.ad
.sp .6
.RS 4n
If the account authority for the user, as specified by \fBPAM_USER\fR, is a
server, do not apply the UNIX policy from the \fBpasswd\fR entry in the name
service switch.
.RE

.sp
.ne 2
.na
\fB\fBnolock\fR\fR
.ad
.sp .6
.RS 4n
Regardless of the automatic account locking setting for the account, do not
lock the account, increment or clear the failed login count. The \fBnolock\fR
option allows for exempting account locking on a per service basis.
.RE

.SH ERRORS
The following error codes are returned from \fBpam_sm_authenticate()\fR:
.sp
.ne 2
.na
\fB\fBPAM_AUTH_ERR\fR\fR
.ad
.sp .6
.RS 4n
Authentication failure.
.RE

.sp
.ne 2
.na
\fB\fBPAM_BUF_ERR\fR\fR
.ad
.sp .6
.RS 4n
Memory buffer error.
.RE

.sp
.ne 2
.na
\fB\fBPAM_IGNORE\fR\fR
.ad
.sp .6
.RS 4n
Ignores module, not participating in result.
.RE

.sp
.ne 2
.na
\fB\fBPAM_MAXTRIES\fR\fR
.ad
.sp .6
.RS 4n
Maximum number of retries exceeded.
.RE

.sp
.ne 2
.na
\fB\fBPAM_PERM_DENIED\fR\fR
.ad
.sp .6
.RS 4n
Permission denied.
.RE

.sp
.ne 2
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.sp .6
.RS 4n
Successfully obtains authentication token.
.RE

.sp
.ne 2
.na
\fB\fBPAM_SYSTEM_ERR\fR\fR
.ad
.sp .6
.RS 4n
System error.
.RE

.sp
.ne 2
.na
\fB\fBPAM_USER_UNKNOWN\fR\fR
.ad
.sp .6
.RS 4n
No account present for user.
.RE

.sp
.LP
The following error codes are returned from \fBpam_sm_setcred()\fR:
.sp
.ne 2
.na
\fB\fBPAM_IGNORE\fR\fR
.ad
.sp .6
.RS 4n
Ignores this module regardless of the control flag.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

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

.SH SEE ALSO
.BR login (1),
.BR passwd (1),
.BR crypt (3C),
.BR syslog (3C),
.BR libpam (3LIB),
.BR pam (3PAM),
.BR pam_setcred (3PAM),
.BR pam_sm_authenticate (3PAM),
.BR pam_sm_setcred (3PAM),
.BR nsswitch.conf (5),
.BR pam.conf (5),
.BR passwd (5),
.BR policy.conf (5),
.BR shadow (5),
.BR user_attr (5),
.BR attributes (7),
.BR pam_authtok_check (7),
.BR pam_authtok_get (7),
.BR pam_authtok_store (7),
.BR pam_dhkeys (7),
.BR pam_passwd_auth (7),
.BR pam_unix_account (7),
.BR pam_unix_cred (7),
.BR pam_unix_session (7),
.SH NOTES
The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
multi-threaded application uses its own \fBPAM\fR handle.
.sp
.LP
The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is
provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7),
\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7),
\fBpam_passwd_auth\fR(7), \fBpam_setcred\fR(3PAM), \fBpam_unix_account\fR(7),
\fBpam_unix_cred\fR(7), \fBpam_unix_session\fR(7).
.sp
.LP
If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is set and a service module does
not recognize the type, the service module does not process any information,
and returns \fBPAM_IGNORE\fR. If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is
not set, a service module performs its default action.