Currently, getting an initial ticket for a user involves many function calls, especially when a full set of features including password expiration and challenge preauthentication is desired. In order to solve this problem, a new api is proposed. typedef struct _krb5_prompt { char *prompt; int hidden; krb5_data *reply; } krb5_prompt; typedef int (*krb5_prompter_fct)(krb5_context context, void *data, const char *banner, int num_prompts, krb5_prompt prompts[]); typedef struct _krb5_get_init_creds_opt { krb5_flags flags; krb5_deltat tkt_life; krb5_deltat renew_life; int forwardable; int proxiable; krb5_enctype *etype_list; int etype_list_length; krb5_address **address_list; /* XXX the next three should not be used, as they may be removed later */ krb5_preauthtype *preauth_list; int preauth_list_length; krb5_data *salt; } krb5_get_init_creds_opt; #define KRB5_GET_INIT_CREDS_OPT_TKT_LIFE 0x0001 #define KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE 0x0002 #define KRB5_GET_INIT_CREDS_OPT_FORWARDABLE 0x0004 #define KRB5_GET_INIT_CREDS_OPT_PROXIABLE 0x0008 #define KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST 0x0010 #define KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST 0x0020 #define KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST 0x0040 #define KRB5_GET_INIT_CREDS_OPT_SALT 0x0080 void krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt); void krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt, krb5_deltat tkt_life); void krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt, krb5_deltat renew_life); void krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt, int forwardable); void krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt, int proxiable); void krb5_get_init_creds_opt_set_etype_list(krb5_get_init_creds_opt *opt, krb5_enctype *etype_list, int etype_list_length); void krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt, krb5_address **addresses); void krb5_get_init_creds_opt_set_preauth_list(krb5_get_init_creds_opt *opt, krb5_preauthtype *preauth_list, int preauth_list_length); void krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt, krb5_data *salt); krb5_error_code krb5_get_init_creds_password(krb5_context context, krb5_creds *creds, krb5_principal client, char *password, krb5_prompter_fct prompter, void *data, krb5_deltat start_time, char *in_tkt_service, krb5_get_init_creds_opt *options); This function will attempt to acquire an initial ticket. The function will perform whatever tasks are necessary to do so. This may include changing an expired password, preauthentication. The arguments divide into two types. Some arguments are basically invariant and arbitrary across all initial tickets, and if not specified are determined by configuration or library defaults. Some arguments are different for each execution or application, and if not specified can be determined correctly from system configuration or environment. The former arguments are contained in a structure whose pointer is passed to the function. A bitmask specifies which elements of the structure should be used. In most cases, a NULL pointer can be used. The latter arguments are specified as individual arguments to the function. If a pointer to a credential is specified, the initial credential is filled in. If the caller only wishes to do a simple password check and will not be doing any other kerberos functions, then a NULL pointer may be specified, and the credential will be destroyed. If the client name is non-NULL, the initial ticket requested will be for that principal. Otherwise, the principal will be the the username specified by the USER environment variable, or if the USER environment variable is not set, the username corresponding to the real user id of the caller. If the password is non-NULL, then this string is used as the password. Otherwise, the prompter function will be used to prompt the user for the password. If a prompter function is non-NULL, it will be used if additional user input is required, such as if the user's password has expired and needs to be changed, or if input preauthentication is necessary. If no function is specified and input is required, then the login will fail. The context argument is the same as that passed to krb5_login. The data argument is passed unmodified to the prompter function and is intended to be used to pass application data (such as a display handle) to the prompter function. The banner argument, if non-NULL, will indicate what sort of input is expected from the user (for example, "Password has expired and must be changed" or "Enter Activcard response for challenge 012345678"), and should be displayed accordingly. The num_prompts argument indicates the number of values which should be prompted for. If num_prompts == 0, then the banner contains an informational message which should be displayed to the user. The prompts argument contains an array describing the values for which the user should be prompted. The prompt member indicates the prompt for each value ("Enter new password"/"Enter it again", or "Challenge response"). The hidden member is nonzero if the response should not be displayed back to the user. The reply member is a pointer to krb5_data structure which has already been allocated. The prompter should fill in the structure with the NUL-terminated response from the user. If the response data does not fit, or if any other error occurs, then the prompter function should return a non-zero value which will be returned by the krb5_get_init_creds function. Otherwise, zero should be returned. The library function krb5_prompter_posix() implements a prompter using a posix terminal for user in. This function does not use the data argument. If the start_time is zero, then the requested ticket will be valid beginning immediately. Otherwise, the start_time indicates how far in the future the ticket should be postdated. If the in_tkt_service name is non-NULL, that principal name will be used as the server name for the initial ticket request. The realm of the name specified will be ignored and will be set to the realm of the client name. If no in_tkt_service name is specified, krbtgt/CLIENT-REALM@CLIENT-REALM will be used. For the rest of arguments, a configuration or library default will be used if no value is specified in the options structure. If a tkt_life is specified, that will be the lifetime of the ticket. The library default is 10 hours; there is no configuration variable (there should be, but it's not there now). If a renew_life is specified and non-zero, then the RENEWABLE option on the ticket will be set, and the value of the argument will be the the renewable lifetime. The configuration variable [libdefaults] "renew_lifetime" is the renewable lifetime if none is passed in. The library default is not to set the RENEWABLE option. If forwardable is specified, the FORWARDABLE option on the ticket will be set if and only if forwardable is non-zero. The configuration variable [libdefaults] "forwardable" is used if no value is passed in. The option will be set if and only if the variable is "y", "yes", "true", "t", "1", or "on", case insensitive. The library default is not to set the FORWARDABLE option. If proxiable is specified, the PROXIABLE option on the ticket will be set if and only if proxiable is non-zero. The configuration variable [libdefaults] "proxiable" is used if no value is passed in. The option will be set if and only if the variable is "y", "yes", "true", "t", "1", or "on", case insensitive. The library default is not to set the PROXIABLE option. If etype_list is specified, it will be used as the list of desired encryption algorithms in the request. The configuration variable [libdefaults] "default_tkt_enctypes" is used if no value is passed in. The library default is "des-cbc-md5 des-cbc-crc". If address_list is specified, it will be used as the list of addresses for which the ticket will be valid. The library default is to use all local non-loopback addresses. There is no configuration variable. If preauth_list is specified, it names preauth data types which will be included in the request. The library default is to interact with the kdc to determine the required preauth types. There is no configuration variable. If salt is specified, it specifies the salt which will be used when converting the password to a key. The library default is to interact with the kdc to determine the correct salt. There is no configuration variable. ================================================================ typedef struct _krb5_verify_init_creds_opt { krb5_flags flags; int ap_req_nofail; } krb5_verify_init_creds_opt; #define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL 0x0001 void krb5_verify_init_creds_opt_init(krb5_init_creds_opt *options); void krb5_verify_init_creds_opt_set_ap_req_nofail(krb5_init_creds_opt *options, int ap_req_nofail); krb5_error_code krb5_verify_init_creds(krb5_context context, krb5_creds *creds, krb5_principal ap_req_server, krb5_keytab ap_req_keytab, krb5_ccache *ccache, krb5_verify_init_creds_opt *options); This function will use the initial ticket in creds to make an AP_REQ and verify it to insure that the AS_REP has not been spoofed. If the ap_req_server name is non-NULL, then this service name will be used for the AP_REQ; otherwise, the default host key (host/hostname.domain@LOCAL-REALM) will be used. If ap_req_keytab is non-NULL, the service key for the verification will be read from that keytab; otherwise, the service key will be read from the default keytab. If the service of the ticket in creds is the same as the service name for the AP_REQ, then this ticket will be used directly. If the ticket is a tgt, then it will be used to obtain credentials for the service. Otherwise, the verification will fail, and return an error. Other failures of the AP_REQ verification may or may not be considered errors, as described below. If a pointer to a credential cache handle is specified, and the handle is NULL, a credential cache handle referring to all credentials obtained in the course of verifying the user will be returned. In order to avoid potential setuid race conditions and other problems related to file system access, this handle will refer to a memory credential cache. If the handle is non-NULL, then the credentials will be added to the existing ccache. If the caller only wishes to verify the password and will not be doing any other kerberos functions, then a NULL pointer may be specified, and the credentials will be deleted before the function returns. If ap_req_nofail is specified, then failures of the AP_REQ verification are considered errors if and only if ap_req_nofail is non-zero. Whether or not AP_REQ validation is performed and what failures mean depends on these inputs: A) The appropriate keytab exists and contains the named key. B) An AP_REQ request to the kdc succeeds, and the resulting AP_REQ can be decrypted and verified. C) The administrator has specified in a configuration file that AP_REQ validation must succeed. This is basically a paranoid bit, and can be overridden by the application based on a command line flag or other application-specific info. This flag is especially useful if the admin is concerned that DNS might be spoofed while determining the host/FQDN name. The configuration variable [libdefaults] "verify_ap_req_nofail" is used if no value is passed in. The library default is not to set this option. Initial ticket verification will succeed if and only if: - A && B or - !A && !C ================================================================ For illustrative purposes, here's the invocations I expect some programs will use. Of course, error checking needs to be added. kinit: /* Fill in client from the command line || existing ccache, and, start_time, and options.{tkt_life,renew_life,forwardable,proxiable} from the command line. Some or all may remain unset. */ krb5_get_init_creds(context, &creds, client, krb5_initial_prompter_posix, NULL, start_time, NULL, &options); krb5_cc_store_cred(context, ccache, &creds); krb5_free_cred_contents(context, &creds); login: krb5_get_init_creds(context, &creds, client, krb5_initial_prompter_posix, NULL, 0, NULL, NULL); krb5_verify_init_creds(context, &creds, NULL, NULL, &vcc, NULL); /* setuid */ krb5_cc_store_cred(context, ccache, &creds); krb5_cc_copy(context, vcc, ccache); krb5_free_cred_contents(context, &creds); krb5_cc_destroy(context, vcc); xdm: krb5_get_initial_creds(context, &creds, client, krb5_initial_prompter_xt, (void *) &xtstuff, 0, NULL, NULL); krb5_verify_init_creds(context, &creds, NULL, NULL, &vcc, NULL); /* setuid */ krb5_cc_store_cred(context, ccache, &creds); krb5_free_cred_contents(context, &creds); krb5_cc_copy(context, vcc, ccache); krb5_cc_destroy(context, vcc); passwd: krb5_init_creds_opt_init(&options); krb5_init_creds_opt_set_tkt_life = 300; krb5_get_initial_creds(context, &creds, client, krb5_initial_prompter_posix, NULL, 0, "kadmin/changepw", &options); /* change password */ krb5_free_cred_contents(context, &creds); pop3d (simple password validator when no user interation possible): krb5_get_initial_creds(context, &creds, client, NULL, NULL, 0, NULL, NULL); krb5_verify_init_creds(context, &creds, NULL, NULL, &vcc, NULL); krb5_cc_destroy(context, vcc); ================================================================ password expiration has a subtlety. When a password expires and is changed, there is a delay between when the master gets the new key (immediately), and the slaves (propogation interval). So, when getting an in_tkt, if the password is expired, the request should be reissued to the master (this kind of sucks if you have SAM, oh well). If this says expired, too, then the password should be changed, and then the initial ticket request should be issued to the master again. If the master times out, then a message that the password has expired and cannot be changed due to the master being unreachable should be displayed. ================================================================ get_init_creds reads config stuff from: [libdefaults] varname1 = defvalue REALM = { varname1 = value varname2 = value } typedef struct _krb5_get_init_creds_opt { krb5_flags flags; krb5_deltat tkt_life; /* varname = "ticket_lifetime" */ krb5_deltat renew_life; /* varname = "renew_lifetime" */ int forwardable; /* varname = "forwardable" */ int proxiable; /* varname = "proxiable" */ krb5_enctype *etype_list; /* varname = "default_tkt_enctypes" */ int etype_list_length; krb5_address **address_list; /* no varname */ krb5_preauthtype *preauth_list; /* no varname */ int preauth_list_length; krb5_data *salt; } krb5_get_init_creds_opt;