--- /dev/null
+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 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;
+
+
git.samba.org / samba.git / blobdiff