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

NAME

6       pam_sm_authenticate - service provider implementation for pam_authenti‐
7       cate
8

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUES

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

ATTRIBUTES

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

SEE ALSO

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

NOTES

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)
Impressum