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