1pam_authenticate(3PAM)       PAM Library Functions      pam_authenticate(3PAM)
2
3
4

NAME

6       pam_authenticate - perform authentication within the PAM framework
7

SYNOPSIS

9       cc [ flag ... ] file ... -lpam [ library ... ]
10       #include <security/pam_appl.h>
11
12
13       int pam_authenticate(pam_handle_t *pamh, int flags);
14
15

DESCRIPTION

17       The  pam_authenticate()  function is called to authenticate the current
18       user. The user is usually required  to  enter  a  password  or  similar
19       authentication  token depending upon the authentication service config‐
20       ured within the system. The user in question should have been specified
21       by a prior call to pam_start() or pam_set_item().
22
23
24       The following flags may be set in the flags field:
25
26       PAM_SILENT                   Authentication service should not generate
27                                    any messages.
28
29
30       PAM_DISALLOW_NULL_AUTHTOK    The authentication service  should  return
31                                    PAM_AUTH_ERR   if  the  user  has  a  null
32                                    authentication token.
33
34

RETURN VALUES

36       Upon successful completion,  PAM_SUCCESS is returned.  In  addition  to
37       the  error  return  values described in pam(3PAM), the following values
38       may be returned:
39
40       PAM_AUTH_ERR             Authentication failure.
41
42
43       PAM_CRED_INSUFFICIENT    Cannot  access  authentication  data  due   to
44                                insufficient credentials.
45
46
47       PAM_AUTHINFO_UNAVAIL     Underlying   authentication   service   cannot
48                                retrieve authentication information.
49
50
51       PAM_USER_UNKNOWN         User not known to the  underlying  authentica‐
52                                tion module.
53
54
55       PAM_MAXTRIES             An  authentication  service  has  maintained a
56                                retry count which has been reached. No further
57                                retries should be attempted.
58
59

ATTRIBUTES

61       See attributes(5) for description of the following attributes:
62
63
64
65
66       ┌─────────────────────────────┬─────────────────────────────┐
67       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
68       ├─────────────────────────────┼─────────────────────────────┤
69       │Interface Stability          │ Stable                      │
70       ├─────────────────────────────┼─────────────────────────────┤
71       │MT-Level                     │MT-Safe with exceptions      │
72       └─────────────────────────────┴─────────────────────────────┘
73

SEE ALSO

75       pam(3PAM),    pam_open_session(3PAM),    pam_set_item(3PAM),   pam_set‐
76       cred(3PAM), pam_start(3PAM), libpam(3LIB), attributes(5)
77

NOTES

79       In the case of authentication failures due to an incorrect username  or
80       password,  it  is  the  responsibility  of  the  application  to  retry
81       pam_authenticate() and to maintain the retry count.  An  authentication
82       service  module  may  implement  an  internal retry count and return an
83       error PAM_MAXTRIES if the module  does  not  want  the  application  to
84       retry.
85
86
87       If  the   PAM  framework cannot load the authentication module, then it
88       will return  PAM_ABORT. This indicates  a  serious  failure,  and   the
89       application should not attempt to retry the authentication.
90
91
92       For security reasons, the location of authentication failures is hidden
93       from the user.   Thus, if several authentication services  are  stacked
94       and  a  single service fails, pam_authenticate() requires that the user
95       re-authenticate each of the services.
96
97
98       A null authentication token in the authentication database will  result
99       in successful authentication unless PAM_DISALLOW_NULL_AUTHTOK was spec‐
100       ified. In such cases, there will be no prompt to the user to  enter  an
101       authentication token.
102
103
104       The  interfaces  in   libpam are MT-Safe only if each thread within the
105       multithreaded application uses its own  PAM handle.
106
107
108
109SunOS 5.11                        27 Jan 2005           pam_authenticate(3PAM)