1pam_sm_authenticate(3PAM) PAM Library Functions pam_sm_authenticate(3PAM)
2
3
4
6 pam_sm_authenticate - service provider implementation for pam_authenti‐
7 cate
8
10 cc [ flag... ] file... -lpam [ library... ]
11 #include <security/pam_appl.h>
12 #include <security/pam_modules.h>
13
14
15 int pam_sm_authenticate(pam_handle_t *pamh, int flags,
16 int argc, const char **argv);
17
18
20 In response to a call to pam_authenticate(3PAM), the PAM framework
21 calls pam_sm_authenticate() from the modules listed in the pam.conf(4)
22 file. The authentication provider supplies the back-end functionality
23 for this interface function.
24
25
26 The pam_sm_authenticate() function is called to verify the identity of
27 the current user. The user is usually required to enter a password or
28 similar authentication token depending upon the authentication scheme
29 configured within the system. The user in question is specified by a
30 prior call to pam_start(), and is referenced by the authentication han‐
31 dle pamh.
32
33
34 If the user is unknown to the authentication service, the service mod‐
35 ule should mask this error and continue to prompt the user for a pass‐
36 word. It should then return the error, PAM_USER_UNKNOWN.
37
38
39 The following flag may be passed in to pam_sm_authenticate():
40
41 PAM_SILENT The authentication service should not gen‐
42 erate any messages.
43
44
45 PAM_DISALLOW_NULL_AUTHTOK The authentication service should return
46
47
48 PAM_AUTH_ERR The user has a null authentication token.
49
50
51
52 The argc argument represents the number of module options passed in
53 from the configuration file pam.conf(4). argv specifies the module
54 options, which are interpreted and processed by the authentication ser‐
55 vice. Please refer to the specific module man pages for the various
56 available options. If any unknown option is passed in, the module
57 should log the error and ignore the option.
58
59
60 Before returning, pam_sm_authenticate() should call pam_get_item() and
61 retrieve PAM_AUTHTOK. If it has not been set before and the value is
62 NULL, pam_sm_authenticate() should set it to the password entered by
63 the user using pam_set_item().
64
65
66 An authentication module may save the authentication status (success or
67 reason for failure) as state in the authentication handle using
68 pam_set_data(3PAM). This information is intended for use by pam_set‐
69 cred().
70
72 Upon successful completion, PAM_SUCCESS must be returned. In addition,
73 the following values may be returned:
74
75 PAM_MAXTRIES Maximum number of authentication attempts
76 exceeded.
77
78
79 PAM_AUTH_ERR Authentication failure.
80
81
82 PAM_CRED_INSUFFICIENT Cannot access authentication data due to
83 insufficient credentials.
84
85
86 PAM_AUTHINFO_UNAVAIL Underlying authentication service can not
87 retrieve authentication information.
88
89
90 PAM_USER_UNKNOWN User not known to underlying authentication
91 module.
92
93
94 PAM_IGNORE Ignore underlying authentication module
95 regardless of whether the control flag is
96 required,optional, or sufficient1.
97
98
100 See attributes(5) for description of the following attributes:
101
102
103
104
105 ┌─────────────────────────────┬─────────────────────────────┐
106 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
107 ├─────────────────────────────┼─────────────────────────────┤
108 │Interface Stability │ Stable │
109 ├─────────────────────────────┼─────────────────────────────┤
110 │MT-Level │MT-Safe with exceptions │
111 └─────────────────────────────┴─────────────────────────────┘
112
114 pam(3PAM), pam_authenticate(3PAM), pam_get_item(3PAM),
115 pam_set_data(3PAM), pam_set_item(3PAM), pam_setcred(3PAM),
116 pam_start(3PAM), libpam(3LIB), pam.conf(4), attributes(5)
117
119 Modules should not retry the authentication in the event of a failure.
120 Applications handle authentication retries and maintain the retry
121 count. To limit the number of retries, the module can return a PAM_MAX‐
122 TRIES error.
123
124
125 The interfaces in libpam are MT-Safe only if each thread within the
126 multithreaded application uses its own PAM handle.
127
128
129 If the PAM_REPOSITORY item_type is set and a service module does not
130 recognize the type, the service module does not process any informa‐
131 tion, and returns PAM_IGNORE. If the PAM_REPOSITORY item_type is not
132 set, a service module performs its default action.
133
134
135
136SunOS 5.11 27 Jan 2005 pam_sm_authenticate(3PAM)