1.\" Generated from pam_authenticate.c by gendoc.pl
2.Dd June 27, 2023
3.Dt PAM_AUTHENTICATE 3
4.Os
5.Sh NAME
6.Nm pam_authenticate
7.Nd perform authentication within the PAM framework
8.Sh SYNOPSIS
9.In sys/types.h
10.In security/pam_appl.h
11.Ft "int"
12.Fn pam_authenticate "pam_handle_t *pamh" "int flags"
13.Sh DESCRIPTION
14The
15.Fn pam_authenticate
16function attempts to authenticate the user
17associated with the pam context specified by the
18.Fa pamh
19argument.
20.Pp
21The application is free to call
22.Fn pam_authenticate
23as many times as it
24wishes, but some modules may maintain an internal retry counter and
25return
26.Dv PAM_MAXTRIES
27when it exceeds some preset or hardcoded limit.
28.Pp
29The
30.Fa flags
31argument is the binary or of zero or more of the following
32values:
33.Bl -tag -width 18n
34.It Dv PAM_SILENT
35Do not emit any messages.
36.It Dv PAM_DISALLOW_NULL_AUTHTOK
37Fail if the user's authentication token is null.
38.El
39.Pp
40If any other bits are set,
41.Fn pam_authenticate
42will return
43.Dv PAM_BAD_CONSTANT .
44.Sh RETURN VALUES
45The
46.Fn pam_authenticate
47function returns one of the following values:
48.Bl -tag -width 18n
49.It Bq Er PAM_SUCCESS
50Success.
51.It Bq Er PAM_ABORT
52General failure.
53.It Bq Er PAM_AUTHINFO_UNAVAIL
54Authentication information is unavailable.
55.It Bq Er PAM_AUTH_ERR
56Authentication error.
57.It Bq Er PAM_BAD_CONSTANT
58Bad constant.
59.It Bq Er PAM_BUF_ERR
60Memory buffer error.
61.It Bq Er PAM_CONV_ERR
62Conversation failure.
63.It Bq Er PAM_CRED_INSUFFICIENT
64Insufficient credentials.
65.It Bq Er PAM_MAXTRIES
66Maximum number of tries exceeded.
67.It Bq Er PAM_PERM_DENIED
68Permission denied.
69.It Bq Er PAM_SERVICE_ERR
70Error in service module.
71.It Bq Er PAM_SYSTEM_ERR
72System error.
73.It Bq Er PAM_USER_UNKNOWN
74Unknown user.
75.El
76.Sh SEE ALSO
77.Xr pam 3 ,
78.Xr pam_strerror 3
79.Sh STANDARDS
80.Rs
81.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
82.%D "June 1997"
83.Re
84.Sh AUTHORS
85The
86.Fn pam_authenticate
87function and this manual page were
88developed for the
89.Fx
90Project by ThinkSec AS and Network Associates Laboratories, the
91Security Research Division of Network Associates, Inc.\& under
92DARPA/SPAWAR contract N66001-01-C-8035
93.Pq Dq CBOSS ,
94as part of the DARPA CHATS research program.
95.Pp
96The OpenPAM library is maintained by
97.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .
98