1PAM(3) Linux-PAM Manual PAM(3)
2
6 pam - Pluggable Authentication Modules Library
7
9 #include <security/pam_appl.h>
10 #include <security/pam_modules.h>
12 #include <security/pam_ext.h>
14
16 PAM is a system of libraries that handle the authentication tasks of
17 applications (services) on the system. The library provides a stable
18 general interface (Application Programming Interface - API) that
19 privilege granting programs (such as login(1) and su(1)) defer to to
20 perform standard authentication tasks.
21 Initialization and Cleanup
23 The pam_start(3) function creates the PAM context and initiates the PAM
24 transaction. It is the first of the PAM functions that needs to be
25 called by an application. The transaction state is contained entirely
26 within the structure identified by this handle, so it is possible to
27 have multiple transactions in parallel. But it is not possible to use
28 the same handle for different transactions, a new one is needed for
29 every new context.
30 The pam_end(3) function terminates the PAM transaction and is the last
32 function an application should call in the PAM context. Upon return the
33 handle pamh is no longer valid and all memory associated with it will
34 be invalid. It can be called at any time to terminate a PAM
35 transaction.
36 Authentication
38 The pam_authenticate(3) function is used to authenticate the user. The
39 user is required to provide an authentication token depending upon the
40 authentication service, usually this is a password, but could also be a
41 finger print.
42 The pam_setcred(3) function manages the user's credentials.
44 Account Management
46 The pam_acct_mgmt(3) function is used to determine if the user's
47 account is valid. It checks for authentication token and account
48 expiration and verifies access restrictions. It is typically called
49 after the user has been authenticated.
50 Password Management
52 The pam_chauthtok(3) function is used to change the authentication
53 token for a given user on request or because the token has expired.
54 Session Management
56 The pam_open_session(3) function sets up a user session for a
57 previously successful authenticated user. The session should later be
58 terminated with a call to pam_close_session(3).
59 Conversation
61 The PAM library uses an application-defined callback to allow a direct
62 communication between a loaded module and the application. This
63 callback is specified by the struct pam_conv passed to pam_start(3) at
64 the start of the transaction. See pam_conv(3) for details.
65 Data Objects
67 The pam_set_item(3) and pam_get_item(3) functions allows applications
68 and PAM service modules to set and retrieve PAM information.
69 The pam_get_user(3) function is the preferred method to obtain the
71 username.
72 The pam_set_data(3) and pam_get_data(3) functions allows PAM service
74 modules to set and retrieve free-form data from one invocation to
75 another.
76 Environment and Error Management
78 The pam_putenv(3), pam_getenv(3) and pam_getenvlist(3) functions are
79 for maintaining a set of private environment variables.
80 The pam_strerror(3) function returns a pointer to a string describing
82 the given PAM error code.
83
85 The following return codes are known by PAM:
86 PAM_ABORT
88 Critical error, immediate abort.
89 PAM_ACCT_EXPIRED
91 User account has expired.
92 PAM_AUTHINFO_UNAVAIL
94 Authentication service cannot retrieve authentication info.
95 PAM_AUTHTOK_DISABLE_AGING
97 Authentication token aging disabled.
98 PAM_AUTHTOK_ERR
100 Authentication token manipulation error.
101 PAM_AUTHTOK_EXPIRED
103 Authentication token expired.
104 PAM_AUTHTOK_LOCK_BUSY
106 Authentication token lock busy.
107 PAM_AUTHTOK_RECOVERY_ERR
109 Authentication information cannot be recovered.
110 PAM_AUTH_ERR
112 Authentication failure.
113 PAM_BUF_ERR
115 Memory buffer error.
116 PAM_CONV_ERR
118 Conversation failure.
119 PAM_CRED_ERR
121 Failure setting user credentials.
122 PAM_CRED_EXPIRED
124 User credentials expired.
125 PAM_CRED_INSUFFICIENT
127 Insufficient credentials to access authentication data.
128 PAM_CRED_UNAVAIL
130 Authentication service cannot retrieve user credentials.
131 PAM_IGNORE
133 The return value should be ignored by PAM dispatch.
134 PAM_MAXTRIES
136 Have exhausted maximum number of retries for service.
137 PAM_MODULE_UNKNOWN
139 Module is unknown.
140 PAM_NEW_AUTHTOK_REQD
142 Authentication token is no longer valid; new one required.
143 PAM_NO_MODULE_DATA
145 No module specific data is present.
146 PAM_OPEN_ERR
148 Failed to load module.
149 PAM_PERM_DENIED
151 Permission denied.
152 PAM_SERVICE_ERR
154 Error in service module.
155 PAM_SESSION_ERR
157 Cannot make/remove an entry for the specified session.
158 PAM_SUCCESS
160 Success.
161 PAM_SYMBOL_ERR
163 Symbol not found.
164 PAM_SYSTEM_ERR
166 System error.
167 PAM_TRY_AGAIN
169 Failed preliminary check by password service.
170 PAM_USER_UNKNOWN
172 User not known to the underlying authentication module.
173
175 pam_acct_mgmt(3), pam_authenticate(3), pam_chauthtok(3),
176 pam_close_session(3), pam_conv(3), pam_end(3), pam_get_data(3),
177 pam_getenv(3), pam_getenvlist(3), pam_get_item(3), pam_get_user(3),
178 pam_open_session(3), pam_putenv(3), pam_set_data(3), pam_set_item(3),
179 pam_setcred(3), pam_start(3), pam_strerror(3)
180
182 The libpam interfaces are only thread-safe if each thread within the
183 multithreaded application uses its own PAM handle.
184Linux-PAM Manual 09/03/2021 PAM(3)