xref: /illumos-gate/usr/src/lib/libpam/pam_appl.h (revision 38603a20)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef _PAM_APPL_H
27 #define	_PAM_APPL_H
28 
29 #include <sys/types.h>
30 
31 #ifdef	__cplusplus
32 extern "C" {
33 #endif
34 
35 /* Generic PAM errors */
36 #define	PAM_SUCCESS		0	/* Normal function return */
37 #define	PAM_OPEN_ERR		1	/* Dlopen failure */
38 #define	PAM_SYMBOL_ERR		2	/* Symbol not found */
39 #define	PAM_SERVICE_ERR		3	/* Error in underlying service module */
40 #define	PAM_SYSTEM_ERR		4	/* System error */
41 #define	PAM_BUF_ERR		5	/* Memory buffer error */
42 #define	PAM_CONV_ERR		6	/* Conversation failure */
43 #define	PAM_PERM_DENIED		7	/* Permission denied */
44 
45 /* Errors returned by pam_authenticate, pam_acct_mgmt(), and pam_setcred() */
46 #define	PAM_MAXTRIES		8	/* Maximum number of tries exceeded */
47 #define	PAM_AUTH_ERR		9	/* Authentication failure */
48 #define	PAM_NEW_AUTHTOK_REQD	10	/* Get new auth token from the user */
49 #define	PAM_CRED_INSUFFICIENT	11	/* can not access auth data b/c */
50 					/* of insufficient credentials  */
51 #define	PAM_AUTHINFO_UNAVAIL	12	/* Can not retrieve auth information */
52 #define	PAM_USER_UNKNOWN	13	/* No account present for user */
53 
54 /* Errors returned by pam_setcred() */
55 #define	PAM_CRED_UNAVAIL	14	/* can not retrieve user credentials */
56 #define	PAM_CRED_EXPIRED	15	/* user credentials expired */
57 #define	PAM_CRED_ERR		16	/* failure setting user credentials */
58 
59 /* Errors returned by pam_acct_mgmt() */
60 #define	PAM_ACCT_EXPIRED	17	/* user account has expired */
61 #define	PAM_AUTHTOK_EXPIRED 	18	/* Password expired and no longer */
62 					/* usable */
63 
64 /* Errors returned by pam_open/close_session() */
65 #define	PAM_SESSION_ERR		19	/* can not make/remove entry for */
66 					/* specified session */
67 
68 /* Errors returned by pam_chauthtok() */
69 #define	PAM_AUTHTOK_ERR		  20	/* Authentication token */
70 					/*   manipulation error */
71 #define	PAM_AUTHTOK_RECOVERY_ERR  21	/* Old authentication token */
72 					/*   cannot be recovered */
73 #define	PAM_AUTHTOK_LOCK_BUSY	  22	/* Authentication token */
74 					/*   lock busy */
75 #define	PAM_AUTHTOK_DISABLE_AGING 23	/* Authentication token aging */
76 					/*   is disabled */
77 
78 /* Errors returned by pam_get_data */
79 #define	PAM_NO_MODULE_DATA	24	/* module data not found */
80 
81 /* Errors returned by modules */
82 #define	PAM_IGNORE		25	/* ignore module */
83 
84 #define	PAM_ABORT		26	/* General PAM failure */
85 #define	PAM_TRY_AGAIN		27	/* Unable to update password */
86 					/* Try again another time */
87 #define	PAM_TOTAL_ERRNUM	28
88 
89 /*
90  * structure pam_message is used to pass prompt, error message,
91  * or any text information from scheme to application/user.
92  */
93 
94 struct pam_message {
95 	int msg_style;		/* Msg_style - see below */
96 	char *msg; 		/* Message string */
97 };
98 
99 /*
100  * msg_style defines the interaction style between the
101  * scheme and the application.
102  */
103 #define	PAM_PROMPT_ECHO_OFF	1	/* Echo off when getting response */
104 #define	PAM_PROMPT_ECHO_ON	2 	/* Echo on when getting response */
105 #define	PAM_ERROR_MSG		3	/* Error message */
106 #define	PAM_TEXT_INFO		4	/* Textual information */
107 
108 /*
109  * max # of messages passed to the application through the
110  * conversation function call
111  */
112 #define	PAM_MAX_NUM_MSG	32
113 
114 /*
115  * max size (in chars) of each messages passed to the application
116  * through the conversation function call
117  */
118 #define	PAM_MAX_MSG_SIZE	512
119 
120 /*
121  * max size (in chars) of each response passed from the application
122  * through the conversation function call
123  */
124 #define	PAM_MAX_RESP_SIZE	512
125 
126 /*
127  * structure pam_response is used by the scheme to get the user's
128  * response back from the application/user.
129  */
130 
131 struct pam_response {
132 	char *resp;		/* Response string */
133 	int resp_retcode;	/* Return code - for future use */
134 };
135 
136 /*
137  * structure pam_conv is used by authentication applications for passing
138  * call back function pointers and application data pointers to the scheme
139  */
140 struct pam_conv {
141 	int (*conv)(int, struct pam_message **,
142 	    struct pam_response **, void *);
143 	void *appdata_ptr;		/* Application data ptr */
144 };
145 
146 /* the pam handle */
147 typedef struct pam_handle pam_handle_t;
148 
149 /*
150  * pam_start() is called to initiate an authentication exchange
151  * with PAM.
152  */
153 extern int
154 pam_start(
155 	const char *service_name,		/* Service Name */
156 	const char *user,			/* User Name */
157 	const struct pam_conv *pam_conv,	/* Conversation structure */
158 	pam_handle_t **pamh		/* Address to store handle */
159 );
160 
161 /*
162  * pam_end() is called to end an authentication exchange with PAM.
163  */
164 extern int
165 pam_end(
166 	pam_handle_t *pamh,		/* handle from pam_start() */
167 	int status			/* the final status value that */
168 					/* gets passed to cleanup functions */
169 );
170 
171 /*
172  * pam_set_item is called to store an object in PAM handle.
173  */
174 extern int
175 pam_set_item(
176 	pam_handle_t *pamh,		/* PAM handle */
177 	int item_type, 			/* Type of object - see below */
178 	const void *item		/* Address of place to put pointer */
179 					/*   to object */
180 );
181 
182 /*
183  * pam_get_item is called to retrieve an object from the static data area
184  */
185 extern int
186 pam_get_item(
187 	const pam_handle_t *pamh, 	/* PAM handle */
188 	int item_type, 			/* Type of object - see below */
189 	void **	item			/* Address of place to put pointer */
190 					/*   to object */
191 );
192 
193 /* Items supported by pam_[sg]et_item() calls */
194 #define	PAM_SERVICE	1		/* The program/service name */
195 #define	PAM_USER	2		/* The user name */
196 #define	PAM_TTY		3		/* The tty name */
197 #define	PAM_RHOST	4		/* The remote host name */
198 #define	PAM_CONV	5		/* The conversation structure */
199 #define	PAM_AUTHTOK	6		/* The authentication token */
200 #define	PAM_OLDAUTHTOK	7		/* Old authentication token */
201 #define	PAM_RUSER	8		/* The remote user name */
202 #define	PAM_USER_PROMPT	9		/* The user prompt */
203 #define	PAM_REPOSITORY	10		/* The repository to be updated */
204 #define	PAM_RESOURCE	11		/* Resource management info */
205 #define	PAM_AUSER	12		/* The authenticated user name */
206 
207 /* pam repository structure */
208 
209 struct pam_repository {
210 	char   *type;		/* Repository type, e.g., files, nis, ldap */
211 	void   *scope;		/* Optional scope information */
212 	size_t  scope_len;	/* length of scope inforamtion */
213 };
214 
215 typedef struct pam_repository pam_repository_t;
216 
217 /*
218  * pam_get_user is called to retrieve the user name (PAM_USER). If PAM_USER
219  * is not set then this call will prompt for the user name using the
220  * conversation function. This function should only be used by modules, not
221  * applications.
222  */
223 
224 extern int
225 pam_get_user(
226 	pam_handle_t *pamh,		/* PAM handle */
227 	char **user, 			/* User Name */
228 	const char *prompt		/* Prompt */
229 );
230 
231 /*
232  * PAM equivalent to strerror();
233  */
234 extern const char *
235 pam_strerror(
236 	pam_handle_t *pamh,	/* pam handle */
237 	int errnum		/* error number */
238 );
239 
240 /* general flag for pam_* functions */
241 #define	PAM_SILENT	0x80000000
242 
243 /*
244  * pam_authenticate is called to authenticate the current user.
245  */
246 extern int
247 pam_authenticate(
248 	pam_handle_t *pamh,
249 	int flags
250 );
251 
252 /*
253  * Flags for pam_authenticate
254  */
255 
256 #define	PAM_DISALLOW_NULL_AUTHTOK 0x1	/* The password must be non-null */
257 
258 /*
259  * pam_acct_mgmt is called to perform account management processing
260  */
261 extern int
262 pam_acct_mgmt(
263 	pam_handle_t *pamh,
264 	int flags
265 );
266 
267 /*
268  * pam_open_session is called to note the initiation of new session in the
269  * appropriate administrative data bases.
270  */
271 extern int
272 pam_open_session(
273 	pam_handle_t *pamh,
274 	int flags
275 );
276 
277 /*
278  * pam_close_session records the termination of a session.
279  */
280 extern int
281 pam_close_session(
282 	pam_handle_t	*pamh,
283 	int		flags
284 );
285 
286 /* pam_setcred is called to set the credentials of the current user */
287 extern int
288 pam_setcred(
289 	pam_handle_t *pamh,
290 	int flags
291 );
292 
293 /* flags for pam_setcred() */
294 #define	PAM_ESTABLISH_CRED	0x1	/* set scheme specific user id */
295 #define	PAM_DELETE_CRED		0x2	/* unset scheme specific user id */
296 #define	PAM_REINITIALIZE_CRED	0x4	/* reinitialize user credentials */
297 					/* (after a password has changed */
298 #define	PAM_REFRESH_CRED	0x8	/* extend lifetime of credentials */
299 
300 /* pam_chauthtok is called to change authentication token */
301 
302 extern int
303 pam_chauthtok(
304 	pam_handle_t	*pamh,
305 	int		flags
306 );
307 
308 /*
309  * Be careful - there are flags defined for pam_sm_chauthtok() in
310  * pam_modules.h also:
311  * PAM_PRELIM_CHECK	0x1
312  * PAM_UPDATE_AUTHTOK	0x2
313  */
314 #define	PAM_CHANGE_EXPIRED_AUTHTOK	0x4 /* update expired passwords only */
315 #define	PAM_NO_AUTHTOK_CHECK		0x8 /* bypass password strength tests */
316 
317 /* pam_putenv is called to add environment variables to the PAM handle */
318 
319 extern int
320 pam_putenv(
321 	pam_handle_t	*pamh,
322 	const char	*name_value
323 );
324 
325 /* pam_getenv is called to retrieve an env variable from the PAM handle */
326 
327 extern char *
328 pam_getenv(
329 	pam_handle_t	*pamh,
330 	const char	*name
331 );
332 
333 /* pam_getenvlist is called to retrieve all env variables from the PAM handle */
334 
335 extern char **
336 pam_getenvlist(
337 	pam_handle_t	*pamh
338 );
339 
340 #ifdef	__cplusplus
341 }
342 #endif
343 
344 #endif /* _PAM_APPL_H */
345