usr/src/lib/libpam/pam_appl.h

   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 */