cde/lib/pam/libpam/pam_appl.h

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