cde/lib/pam/libpam/pam_appl.h

   1 /* $XConsortium: pam_appl.h /main/5 1996/05/09 04:24:28 drk $ */
   2 /*
   3  * Copyright (c) 1992-1995, by Sun Microsystems, Inc.
   4  * All rights reserved.
   5  */
   6
   7 #ifndef _PAM_APPL_H
   8 #define _PAM_APPL_H
   9
  10 #pragma ident   "@(#)pam_appl.h 1.45    96/02/15 SMI"   /* PAM 2.6 */
  11
  12 #include <pwd.h>
  13
  14 #ifdef  __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 /* Generic PAM errors */
  19 #define PAM_SUCCESS             0       /* Normal function return */
  20 #define PAM_OPEN_ERR            1       /* Dlopen failure */
  21 #define PAM_SYMBOL_ERR          2       /* Symbol not found */
  22 #define PAM_SERVICE_ERR         3       /* Error in underlying service module */
  23 #define PAM_SYSTEM_ERR          4       /* System error */
  24 #define PAM_BUF_ERR             5       /* Memory buffer error */
  25 #define PAM_CONV_ERR            6       /* Conversation failure */
  26 #define PAM_PERM_DENIED         7       /* Permission denied */
  27
  28 /* Errors returned by pam_authenticate, pam_acct_mgmt(), and pam_setcred() */
  29 #define PAM_MAXTRIES            8       /* Maximum number of tries exceeded */
  30 #define PAM_AUTH_ERR            9       /* Authentication failure */
  31 #define PAM_NEW_AUTHTOK_REQD    10      /* Get new auth token from the user */
  32 #define PAM_AUTHTOKEN_REQD      PAM_NEW_AUTHTOK_REQD /* backward compatible */
  33 #define PAM_CRED_INSUFFICIENT   11      /* can not access auth data b/c */
  34                                         /* of insufficient credentials  */
  35 #define PAM_AUTHINFO_UNAVAIL    12      /* Can not retrieve auth information */
  36 #define PAM_USER_UNKNOWN        13      /* No account present for user */
  37
  38 /* Errors returned by pam_setcred() */
  39 #define PAM_CRED_UNAVAIL        14      /* can not retrieve user credentials */
  40 #define PAM_CRED_EXPIRED        15      /* user credentials expired */
  41 #define PAM_CRED_ERR            16      /* failure setting user credentials */
  42
  43 /* Errors returned by pam_acct_mgmt() */
  44 #define PAM_ACCT_EXPIRED        17      /* user account has expired */
  45 #define PAM_AUTHTOK_EXPIRED     18      /* Password expired and no longer */
  46                                         /* usable */
  47
  48 /* Errors returned by pam_open/close_session() */
  49 #define PAM_SESSION_ERR         19      /* can not make/remove entry for */
  50                                         /* specified session */
  51
  52 /* Errors returned by pam_chauthtok() */
  53 #define PAM_AUTHTOK_ERR           20    /* Authentication token */
  54                                         /*   manipulation error */
  55 #define PAM_AUTHTOK_RECOVERY_ERR  21    /* Old authentication token */
  56                                         /*   cannot be recovered */
  57 #define PAM_AUTHTOK_LOCK_BUSY     22    /* Authentication token */
  58                                         /*   lock busy */
  59 #define PAM_AUTHTOK_DISABLE_AGING 23    /* Authentication token aging */
  60                                         /*   is disabled */
  61
  62 /* Errors returned by pam_get_data */
  63 #define PAM_NO_MODULE_DATA      24      /* module data not found */
  64
  65 /* Errors returned by modules */
  66 #define PAM_IGNORE              25      /* ignore module */
  67
  68 #define PAM_ABORT               26      /* General PAM failure */
  69 #define PAM_TRY_AGAIN           27      /* Unable to update password */
  70                                         /* Try again another time */
  71
  72 /*
  73  * XXX: Make sure that PAM_TOTAL_ERRNUM = 28 in pam_impl.h
  74  */
  75
  76 /*
  77  * structure pam_message is used to pass prompt, error message,
  78  * or any text information from scheme to application/user.
  79  */
  80
  81 struct pam_message {
  82         int msg_style;          /* Msg_style - see below */
  83         char *msg;              /* Message string */
  84 };
  85
  86 /*
  87  * msg_style defines the interaction style between the
  88  * scheme and the application.
  89  */
  90 #define PAM_PROMPT_ECHO_OFF     1       /* Echo off when getting response */
  91 #define PAM_PROMPT_ECHO_ON      2       /* Echo on when getting response */
  92 #define PAM_ERROR_MSG           3       /* Error message */
  93 #define PAM_TEXT_INFO           4       /* Textual information */
  94
  95 /* max # of authentication token attributes */
  96 #define PAM_MAX_NUM_ATTR        10
  97
  98 /* max size (in chars) of an authentication token attribute */
  99 #define PAM_MAX_ATTR_SIZE       80
 100
 101 /*
 102  * max # of messages passed to the application through the
 103  * conversation function call
 104  */
 105 #define PAM_MAX_NUM_MSG 32
 106
 107 /*
 108  * max size (in chars) of each messages passed to the application
 109  * through the conversation function call
 110  */
 111 #define PAM_MAX_MSG_SIZE        512
 112
 113 /*
 114  * max size (in chars) of each response passed from the application
 115  * through the conversation function call
 116  */
 117 #define PAM_MAX_RESP_SIZE       512
 118
 119 /*
 120  * structure pam_response is used by the scheme to get the user's
 121  * response back from the application/user.
 122  */
 123
 124 struct pam_response {
 125         char *resp;             /* Response string */
 126         int resp_retcode;       /* Return code - for future use */
 127 };
 128
 129 /*
 130  * structure pam_conv is used by authentication applications for passing
 131  * call back function pointers and application data pointers to the scheme
 132  */
 133 struct pam_conv {
 134         int (*conv)(int, struct pam_message **,
 135             struct pam_response **, void *);
 136         void *appdata_ptr;              /* Application data ptr */
 137 };
 138
 139 /* the pam handle */
 140 typedef struct pam_handle pam_handle_t;
 141
 142 /*
 143  * pam_start() is called to initiate an authentication exchange
 144  * with PAM.
 145  */
 146 extern int
 147 pam_start(
 148         const char *service_name,               /* Service Name */
 149         const char *user,                       /* User Name */
 150         const struct pam_conv *pam_conv,        /* Conversation structure */
 151         pam_handle_t **pamh             /* Address to store handle */
 152 );
 153
 154 /*
 155  * pam_end() is called to end an authentication exchange with PAM.
 156  */
 157 extern int
 158 pam_end(
 159         pam_handle_t *pamh,             /* handle from pam_start() */
 160         int status                      /* the final status value that */
 161                                         /* gets passed to cleanup functions */
 162 );
 163
 164 /*
 165  * pam_set_item is called to store an object in PAM handle.
 166  */
 167 extern int
 168 pam_set_item(
 169         pam_handle_t *pamh,             /* PAM handle */
 170         int item_type,                  /* Type of object - see below */
 171         const void *item                /* Address of place to put pointer */
 172                                         /*   to object */
 173 );
 174
 175 /*
 176  * pam_get_item is called to retrieve an object from the static data area
 177  */
 178 extern int
 179 pam_get_item(
 180         const pam_handle_t *pamh,       /* PAM handle */
 181         int item_type,                  /* Type of object - see below */
 182         void ** item                    /* Address of place to put pointer */
 183                                         /*   to object */
 184 );
 185
 186 /* Items supported by pam_[sg]et_item() calls */
 187 #define PAM_SERVICE     1               /* The program/service name */
 188 #define PAM_USER        2               /* The user name */
 189 #define PAM_TTY         3               /* The tty name */
 190 #define PAM_RHOST       4               /* The remote host name */
 191 #define PAM_CONV        5               /* The conversation structure */
 192 #define PAM_AUTHTOK     6               /* The authentication token */
 193 #define PAM_OLDAUTHTOK  7               /* Old authentication token */
 194 #define PAM_RUSER       8               /* The remote user name */
 195 #define PAM_USER_PROMPT 9               /* The user prompt */
 196
 197 /*
 198  * pam_get_user is called to retrieve the user name (PAM_USER). If PAM_USER
 199  * is not set then this call will prompt for the user name using the
 200  * conversation function. This function should only be used by modules, not
 201  * applications.
 202  */
 203
 204 extern int
 205 pam_get_user(
 206         pam_handle_t *pamh,             /* PAM handle */
 207         char **user,                    /* User Name */
 208         const char *prompt              /* Prompt */
 209 );
 210
 211 /*
 212  * pam_set_data is used to create module specific data, and
 213  * to optionally add a cleanup handler that gets called by pam_end.
 214  *
 215  */
 216 extern int
 217 pam_set_data(
 218         pam_handle_t *pamh,             /* PAM handle */
 219         const char *module_data_name,   /* unique module data name */
 220         const void *data,               /* the module specific data */
 221         void (*cleanup)(pam_handle_t *pamh, void *data, int pam_end_status)
 222 );
 223
 224 /*
 225  * get module specific data set by pam_set_scheme_data.
 226  * returns PAM_NO_MODULE_DATA if specified module data was not found.
 227  */
 228 extern int
 229 pam_get_data(
 230         const pam_handle_t *pamh,
 231         const char *module_data_name,
 232         void **data
 233 );
 234
 235 /*
 236  * PAM equivalent to strerror();
 237  */
 238 extern char *
 239 pam_strerror(
 240         pam_handle_t *pamh,     /* pam handle */
 241         int errnum              /* error number */
 242 );
 243
 244 /* general flag for pam_* functions */
 245 #define PAM_SILENT      0x80000000
 246
 247 /*
 248  * pam_authenticate is called to authenticate the current user.
 249  */
 250 extern int
 251 pam_authenticate(
 252         pam_handle_t *pamh,
 253         int flags
 254 );
 255
 256 /*
 257  * Flags for pam_authenticate
 258  */
 259
 260 #define PAM_DISALLOW_NULL_AUTHTOK 2     /* The password must be non-null */
 261
 262 /*
 263  * pam_acct_mgmt is called to perform account management processing
 264  */
 265 extern int
 266 pam_acct_mgmt(
 267         pam_handle_t *pamh,
 268         int flags
 269 );
 270
 271 /*
 272  * pam_open_session is called to note the initiation of new session in the
 273  * appropriate administrative data bases.
 274  */
 275 extern int
 276 pam_open_session(
 277         pam_handle_t *pamh,
 278         int flags
 279 );
 280
 281 /*
 282  * pam_close_session records the termination of a session.
 283  */
 284 extern int
 285 pam_close_session(
 286         pam_handle_t    *pamh,
 287         int             flags
 288 );
 289
 290 /* pam_setcred is called to set the credentials of the current user */
 291 extern int
 292 pam_setcred(
 293         pam_handle_t *pamh,
 294         int flags
 295 );
 296
 297 /* flags for pam_setcred() */
 298 #define PAM_ESTABLISH_CRED      1       /* set scheme specific user id */
 299 #define PAM_DELETE_CRED         2       /* unset scheme specific user id */
 300 #define PAM_REINITIALIZE_CRED   4       /* reinitialize user credentials */
 301                                         /* (after a password has changed */
 302 #define PAM_REFRESH_CRED        8       /* extend lifetime of credentials */
 303
 304 /* pam_chauthtok is called to change authentication token */
 305
 306 extern int
 307 pam_chauthtok(
 308         pam_handle_t    *pamh,
 309         int             flags
 310 );
 311
 312 /*
 313  * Be careful - there are flags defined for pam_sm_chauthtok() in
 314  * pam_modules.h also.
 315  */
 316 #define PAM_CHANGE_EXPIRED_AUTHTOK      4 /* update expired passwords only */
 317
 318 #ifdef  __cplusplus
 319 }
 320 #endif
 321
 322 #endif /* _PAM_APPL_H */