/crypto/heimdal/doc/init-creds

  1Currently, getting an initial ticket for a user involves many function
  2calls, especially when a full set of features including password
  3expiration and challenge preauthentication is desired.  In order to
  4solve this problem, a new api is proposed.
  5
  6typedef struct _krb5_prompt {
  7    char *prompt;
  8    int hidden;
  9    krb5_data *reply;
 10} krb5_prompt;
 11
 12typedef int (*krb5_prompter_fct)(krb5_context context,
 13				 void *data,
 14				 const char *banner,
 15				 int num_prompts,
 16				 krb5_prompt prompts[]);
 17
 18typedef struct _krb5_get_init_creds_opt {
 19    krb5_flags flags;
 20    krb5_deltat tkt_life;
 21    krb5_deltat renew_life;
 22    int forwardable;
 23    int proxiable;
 24    krb5_enctype *etype_list;
 25    int etype_list_length;
 26    krb5_address **address_list;
 27	/* XXX the next three should not be used, as they may be
 28	removed later */
 29    krb5_preauthtype *preauth_list;
 30    int preauth_list_length;
 31    krb5_data *salt;
 32} krb5_get_init_creds_opt;
 33
 34#define KRB5_GET_INIT_CREDS_OPT_TKT_LIFE	0x0001
 35#define KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE	0x0002
 36#define KRB5_GET_INIT_CREDS_OPT_FORWARDABLE	0x0004
 37#define KRB5_GET_INIT_CREDS_OPT_PROXIABLE	0x0008
 38#define KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST	0x0010
 39#define KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST	0x0020
 40#define KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST	0x0040
 41#define KRB5_GET_INIT_CREDS_OPT_SALT		0x0080
 42
 43void krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt);
 44
 45void krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt,
 46					  krb5_deltat tkt_life);
 47void krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt,
 48					    krb5_deltat renew_life);
 49void krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt,
 50					     int forwardable);
 51void krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt,
 52					   int proxiable);
 53void krb5_get_init_creds_opt_set_etype_list(krb5_get_init_creds_opt *opt,
 54					    krb5_enctype *etype_list,
 55					    int etype_list_length);
 56void krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt,
 57					      krb5_address **addresses);
 58void krb5_get_init_creds_opt_set_preauth_list(krb5_get_init_creds_opt *opt,
 59					      krb5_preauthtype *preauth_list,
 60					      int preauth_list_length);
 61void krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt,
 62				      krb5_data *salt);
 63
 64krb5_error_code
 65krb5_get_init_creds_password(krb5_context context,
 66			     krb5_creds *creds,
 67			     krb5_principal client,
 68			     char *password,
 69			     krb5_prompter_fct prompter,
 70			     void *data,
 71			     krb5_deltat start_time,
 72			     char *in_tkt_service,
 73			     krb5_get_init_creds_opt *options);
 74
 75This function will attempt to acquire an initial ticket.  The function
 76will perform whatever tasks are necessary to do so.  This may include
 77changing an expired password, preauthentication.
 78
 79The arguments divide into two types.  Some arguments are basically
 80invariant and arbitrary across all initial tickets, and if not
 81specified are determined by configuration or library defaults.  Some
 82arguments are different for each execution or application, and if not
 83specified can be determined correctly from system configuration or
 84environment.  The former arguments are contained in a structure whose
 85pointer is passed to the function.  A bitmask specifies which elements
 86of the structure should be used.  In most cases, a NULL pointer can be
 87used.  The latter arguments are specified as individual arguments to
 88the function.
 89
 90If a pointer to a credential is specified, the initial credential is
 91filled in.  If the caller only wishes to do a simple password check
 92and will not be doing any other kerberos functions, then a NULL
 93pointer may be specified, and the credential will be destroyed.
 94
 95If the client name is non-NULL, the initial ticket requested will be
 96for that principal.  Otherwise, the principal will be the username
 97specified by the USER environment variable, or if the USER environment
 98variable is not set, the username corresponding to the real user id of
 99the caller.
100
101If the password is non-NULL, then this string is used as the password.
102Otherwise, the prompter function will be used to prompt the user for
103the password.
104
105If a prompter function is non-NULL, it will be used if additional user
106input is required, such as if the user's password has expired and
107needs to be changed, or if input preauthentication is necessary.  If
108no function is specified and input is required, then the login will
109fail.
110
111	The context argument is the same as that passed to krb5_login.
112	The data argument is passed unmodified to the prompter
113	function and is intended to be used to pass application data
114	(such as a display handle) to the prompter function.
115
116	The banner argument, if non-NULL, will indicate what sort of
117	input is expected from the user (for example, "Password has
118	expired and must be changed" or "Enter Activcard response for
119	challenge 012345678"), and should be displayed accordingly.
120	
121	The num_prompts argument indicates the number of values which
122	should be prompted for.  If num_prompts == 0, then the banner
123	contains an informational message which should be displayed to
124	the user.
125
126	The prompts argument contains an array describing the values
127	for which the user should be prompted.  The prompt member
128	indicates the prompt for each value ("Enter new
129	password"/"Enter it again", or "Challenge response").  The
130	hidden member is nonzero if the response should not be
131	displayed back to the user.  The reply member is a pointer to
132	krb5_data structure which has already been allocated.  The
133	prompter should fill in the structure with the NUL-terminated
134	response from the user.
135
136	If the response data does not fit, or if any other error
137	occurs, then the prompter function should return a non-zero
138	value which will be returned by the krb5_get_init_creds
139	function. Otherwise, zero should be returned.
140
141	The library function krb5_prompter_posix() implements
142	a prompter using a posix terminal for user in.  This function
143	does not use the data argument.
144
145If the start_time is zero, then the requested ticket will be valid
146beginning immediately.  Otherwise, the start_time indicates how far in
147the future the ticket should be postdated.
148
149If the in_tkt_service name is non-NULL, that principal name will be
150used as the server name for the initial ticket request.  The realm of
151the name specified will be ignored and will be set to the realm of the
152client name.  If no in_tkt_service name is specified,
153krbtgt/CLIENT-REALM@CLIENT-REALM will be used.
154
155For the rest of arguments, a configuration or library default will be
156used if no value is specified in the options structure.
157
158If a tkt_life is specified, that will be the lifetime of the ticket.
159The library default is 10 hours; there is no configuration variable
160(there should be, but it's not there now).
161
162If a renew_life is specified and non-zero, then the RENEWABLE option
163on the ticket will be set, and the value of the argument will be the
164the renewable lifetime.  The configuration variable [libdefaults]
165"renew_lifetime" is the renewable lifetime if none is passed in.  The
166library default is not to set the RENEWABLE option.
167
168If forwardable is specified, the FORWARDABLE option on the ticket will
169be set if and only if forwardable is non-zero.  The configuration
170variable [libdefaults] "forwardable" is used if no value is passed in.
171The option will be set if and only if the variable is "y", "yes",
172"true", "t", "1", or "on", case insensitive.  The library default is
173not to set the FORWARDABLE option.
174
175If proxiable is specified, the PROXIABLE option on the ticket will be
176set if and only if proxiable is non-zero.  The configuration variable
177[libdefaults] "proxiable" is used if no value is passed in.  The
178option will be set if and only if the variable is "y", "yes", "true",
179"t", "1", or "on", case insensitive.  The library default is not to
180set the PROXIABLE option.
181
182If etype_list is specified, it will be used as the list of desired
183encryption algorithms in the request.  The configuration variable
184[libdefaults] "default_tkt_enctypes" is used if no value is passed in.
185The library default is "des-cbc-md5 des-cbc-crc".
186
187If address_list is specified, it will be used as the list of addresses
188for which the ticket will be valid.  The library default is to use all
189local non-loopback addresses.  There is no configuration variable.
190
191If preauth_list is specified, it names preauth data types which will
192be included in the request.  The library default is to interact with
193the kdc to determine the required preauth types.  There is no
194configuration variable.
195
196If salt is specified, it specifies the salt which will be used when
197converting the password to a key.  The library default is to interact
198with the kdc to determine the correct salt.  There is no configuration
199variable.
200
201================================================================
202
203typedef struct _krb5_verify_init_creds_opt {
204    krb5_flags flags;
205    int ap_req_nofail;
206} krb5_verify_init_creds_opt;
207
208#define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL	0x0001
209
210void krb5_verify_init_creds_opt_init(krb5_init_creds_opt *options);
211void krb5_verify_init_creds_opt_set_ap_req_nofail(krb5_init_creds_opt *options,
212						  int ap_req_nofail);
213
214krb5_error_code
215krb5_verify_init_creds(krb5_context context,
216		       krb5_creds *creds,
217		       krb5_principal ap_req_server,
218		       krb5_keytab ap_req_keytab,
219		       krb5_ccache *ccache,
220		       krb5_verify_init_creds_opt *options);
221
222This function will use the initial ticket in creds to make an AP_REQ
223and verify it to insure that the AS_REP has not been spoofed.
224
225If the ap_req_server name is non-NULL, then this service name will be
226used for the AP_REQ; otherwise, the default host key
227(host/hostname.domain@LOCAL-REALM) will be used.
228
229If ap_req_keytab is non-NULL, the service key for the verification
230will be read from that keytab; otherwise, the service key will be read
231from the default keytab. 
232
233If the service of the ticket in creds is the same as the service name
234for the AP_REQ, then this ticket will be used directly.  If the ticket
235is a tgt, then it will be used to obtain credentials for the service.
236Otherwise, the verification will fail, and return an error.
237
238Other failures of the AP_REQ verification may or may not be considered
239errors, as described below.
240
241If a pointer to a credential cache handle is specified, and the handle
242is NULL, a credential cache handle referring to all credentials
243obtained in the course of verifying the user will be returned.  In
244order to avoid potential setuid race conditions and other problems
245related to file system access, this handle will refer to a memory
246credential cache.  If the handle is non-NULL, then the credentials
247will be added to the existing ccache.  If the caller only wishes to
248verify the password and will not be doing any other kerberos
249functions, then a NULL pointer may be specified, and the credentials
250will be deleted before the function returns.
251
252If ap_req_nofail is specified, then failures of the AP_REQ
253verification are considered errors if and only if ap_req_nofail is
254non-zero.
255
256Whether or not AP_REQ validation is performed and what failures mean
257depends on these inputs:
258
259 A) The appropriate keytab exists and contains the named key.
260
261 B) An AP_REQ request to the kdc succeeds, and the resulting AP_REQ
262can be decrypted and verified.
263
264 C) The administrator has specified in a configuration file that
265AP_REQ validation must succeed.  This is basically a paranoid bit, and
266can be overridden by the application based on a command line flag or
267other application-specific info.  This flag is especially useful if
268the admin is concerned that DNS might be spoofed while determining the
269host/FQDN name.  The configuration variable [libdefaults]
270"verify_ap_req_nofail" is used if no value is passed in.  The library
271default is not to set this option.
272
273Initial ticket verification will succeed if and only if:
274
275 - A && B    or
276 - !A && !C
277
278================================================================
279
280For illustrative purposes, here's the invocations I expect some
281programs will use.  Of course, error checking needs to be added.
282
283kinit:
284
285    /* Fill in client from the command line || existing ccache, and,
286       start_time, and options.{tkt_life,renew_life,forwardable,proxiable}
287       from the command line.  Some or all may remain unset. */
288
289    krb5_get_init_creds(context, &creds, client,
290			krb5_initial_prompter_posix, NULL,
291			start_time, NULL, &options);
292    krb5_cc_store_cred(context, ccache, &creds);
293    krb5_free_cred_contents(context, &creds);
294
295login:
296
297    krb5_get_init_creds(context, &creds, client,
298			krb5_initial_prompter_posix, NULL,
299			0, NULL, NULL);
300    krb5_verify_init_creds(context, &creds, NULL, NULL, &vcc, NULL);
301    /* setuid */
302    krb5_cc_store_cred(context, ccache, &creds);
303    krb5_cc_copy(context, vcc, ccache);
304    krb5_free_cred_contents(context, &creds);
305    krb5_cc_destroy(context, vcc);
306
307xdm:
308
309    krb5_get_initial_creds(context, &creds, client,
310			   krb5_initial_prompter_xt, (void *) &xtstuff,
311			   0, NULL, NULL);
312    krb5_verify_init_creds(context, &creds, NULL, NULL, &vcc, NULL);
313    /* setuid */
314    krb5_cc_store_cred(context, ccache, &creds);
315    krb5_free_cred_contents(context, &creds);
316    krb5_cc_copy(context, vcc, ccache);
317    krb5_cc_destroy(context, vcc);
318
319passwd:
320
321    krb5_init_creds_opt_init(&options);
322    krb5_init_creds_opt_set_tkt_life = 300;
323    krb5_get_initial_creds(context, &creds, client,
324			   krb5_initial_prompter_posix, NULL,
325			   0, "kadmin/changepw", &options);
326    /* change password */
327    krb5_free_cred_contents(context, &creds);
328
329pop3d (simple password validator when no user interation possible):
330
331    krb5_get_initial_creds(context, &creds, client,
332			   NULL, NULL, 0, NULL, NULL);
333    krb5_verify_init_creds(context, &creds, NULL, NULL, &vcc, NULL);
334    krb5_cc_destroy(context, vcc);
335
336================================================================
337
338password expiration has a subtlety.  When a password expires and is
339changed, there is a delay between when the master gets the new key
340(immediately), and the slaves (propogation interval).  So, when
341getting an in_tkt, if the password is expired, the request should be
342reissued to the master (this kind of sucks if you have SAM, oh well).
343If this says expired, too, then the password should be changed, and
344then the initial ticket request should be issued to the master again.
345If the master times out, then a message that the password has expired
346and cannot be changed due to the master being unreachable should be
347displayed.
348
349================================================================
350
351get_init_creds reads config stuff from:
352
353[libdefaults]
354	varname1 = defvalue
355	REALM = {
356		varname1 = value
357		varname2 = value
358	}
359
360typedef struct _krb5_get_init_creds_opt {
361    krb5_flags flags;
362    krb5_deltat tkt_life;	/* varname = "ticket_lifetime" */
363    krb5_deltat renew_life;	/* varname = "renew_lifetime" */
364    int forwardable;		/* varname = "forwardable" */
365    int proxiable;		/* varname = "proxiable" */
366    krb5_enctype *etype_list;	/* varname = "default_tkt_enctypes" */
367    int etype_list_length;
368    krb5_address **address_list; /* no varname */
369    krb5_preauthtype *preauth_list; /* no varname */
370    int preauth_list_length;
371    krb5_data *salt;
372} krb5_get_init_creds_opt;
373
374