375 lines
15 KiB
Plaintext
375 lines
15 KiB
Plaintext
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;
|
|
|
|
|