/crypto/heimdal/doc/init-creds
https://bitbucket.org/freebsd/freebsd-head/ · #! · 374 lines · 305 code · 69 blank · 0 comment · 0 complexity · ec6dd12a276cdb3199833b3873d32ddc MD5 · raw file
- 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;