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