Move kadmin and ktutil to /usr/bin.
[heimdal.git] / lib / krb5 / krb5_get_init_creds.3
blob764efb47e441720ff749420cccb313207c7f6ff1
1 .\" Copyright (c) 2003 - 2007 Kungliga Tekniska Högskolan
2 .\" (Royal Institute of Technology, Stockholm, Sweden).
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\"
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\"
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\"
16 .\" 3. Neither the name of the Institute nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" $Id$
33 .\"
34 .Dd Sep  16, 2006
35 .Dt KRB5_GET_INIT_CREDS 3
36 .Os HEIMDAL
37 .Sh NAME
38 .Nm krb5_get_init_creds ,
39 .Nm krb5_get_init_creds_keytab ,
40 .Nm krb5_get_init_creds_opt ,
41 .Nm krb5_get_init_creds_opt_alloc ,
42 .Nm krb5_get_init_creds_opt_free ,
43 .Nm krb5_get_init_creds_opt_init ,
44 .Nm krb5_get_init_creds_opt_set_address_list ,
45 .Nm krb5_get_init_creds_opt_set_addressless ,
46 .Nm krb5_get_init_creds_opt_set_anonymous ,
47 .Nm krb5_get_init_creds_opt_set_default_flags ,
48 .Nm krb5_get_init_creds_opt_set_etype_list ,
49 .Nm krb5_get_init_creds_opt_set_forwardable ,
50 .Nm krb5_get_init_creds_opt_set_pa_password ,
51 .Nm krb5_get_init_creds_opt_set_paq_request ,
52 .Nm krb5_get_init_creds_opt_set_preauth_list ,
53 .Nm krb5_get_init_creds_opt_set_proxiable ,
54 .Nm krb5_get_init_creds_opt_set_renew_life ,
55 .Nm krb5_get_init_creds_opt_set_salt ,
56 .Nm krb5_get_init_creds_opt_set_tkt_life ,
57 .Nm krb5_get_init_creds_opt_set_canonicalize ,
58 .Nm krb5_get_init_creds_opt_set_win2k ,
59 .Nm krb5_get_init_creds_password ,
60 .Nm krb5_prompt ,
61 .Nm krb5_prompter_posix
62 .Nd Kerberos 5 initial authentication functions
63 .Sh LIBRARY
64 Kerberos 5 Library (libkrb5, -lkrb5)
65 .Sh SYNOPSIS
66 .In krb5.h
67 .Pp
68 .Ft krb5_get_init_creds_opt;
69 .Pp
70 .Ft krb5_error_code
71 .Fo krb5_get_init_creds_opt_alloc
72 .Fa "krb5_context context"
73 .Fa "krb5_get_init_creds_opt **opt"
74 .Fc
75 .Ft void
76 .Fo krb5_get_init_creds_opt_free
77 .Fa "krb5_context context"
78 .Fa "krb5_get_init_creds_opt *opt"
79 .Fc
80 .Ft void
81 .Fo krb5_get_init_creds_opt_init
82 .Fa "krb5_get_init_creds_opt *opt"
83 .Fc
84 .Ft void
85 .Fo krb5_get_init_creds_opt_set_address_list
86 .Fa "krb5_get_init_creds_opt *opt"
87 .Fa "krb5_addresses *addresses"
88 .Fc
89 .Ft void
90 .Fo krb5_get_init_creds_opt_set_addressless
91 .Fa "krb5_get_init_creds_opt *opt"
92 .Fa "krb5_boolean addressless"
93 .Fc
94 .Ft void
95 .Fo krb5_get_init_creds_opt_set_anonymous
96 .Fa "krb5_get_init_creds_opt *opt"
97 .Fa "int anonymous"
98 .Fc
99 .Ft void
100 .Fo krb5_get_init_creds_opt_set_default_flags
101 .Fa "krb5_context context"
102 .Fa "const char *appname"
103 .Fa "krb5_const_realm realm"
104 .Fa "krb5_get_init_creds_opt *opt"
106 .Ft void
107 .Fo krb5_get_init_creds_opt_set_etype_list
108 .Fa "krb5_get_init_creds_opt *opt"
109 .Fa "krb5_enctype *etype_list"
110 .Fa "int etype_list_length"
112 .Ft void
113 .Fo krb5_get_init_creds_opt_set_forwardable
114 .Fa "krb5_get_init_creds_opt *opt"
115 .Fa "int forwardable"
117 .Ft krb5_error_code
118 .Fo krb5_get_init_creds_opt_set_pa_password
119 .Fa "krb5_context context"
120 .Fa "krb5_get_init_creds_opt *opt"
121 .Fa "const char *password"
122 .Fa "krb5_s2k_proc key_proc"
124 .Ft krb5_error_code
125 .Fo krb5_get_init_creds_opt_set_paq_request
126 .Fa "krb5_context context"
127 .Fa "krb5_get_init_creds_opt *opt"
128 .Fa "krb5_boolean req_pac"
130 .Ft krb5_error_code
131 .Fo krb5_get_init_creds_opt_set_pkinit
132 .Fa "krb5_context context"
133 .Fa "krb5_get_init_creds_opt *opt"
134 .Fa "const char *cert_file"
135 .Fa "const char *key_file"
136 .Fa "const char *x509_anchors"
137 .Fa "int flags"
138 .Fa "char *password"
140 .Ft void
141 .Fo krb5_get_init_creds_opt_set_preauth_list
142 .Fa "krb5_get_init_creds_opt *opt"
143 .Fa "krb5_preauthtype *preauth_list"
144 .Fa "int preauth_list_length"
146 .Ft void
147 .Fo krb5_get_init_creds_opt_set_proxiable
148 .Fa "krb5_get_init_creds_opt *opt"
149 .Fa "int proxiable"
151 .Ft void
152 .Fo krb5_get_init_creds_opt_set_renew_life
153 .Fa "krb5_get_init_creds_opt *opt"
154 .Fa "krb5_deltat renew_life"
156 .Ft void
157 .Fo krb5_get_init_creds_opt_set_salt
158 .Fa "krb5_get_init_creds_opt *opt"
159 .Fa "krb5_data *salt"
161 .Ft void
162 .Fo krb5_get_init_creds_opt_set_tkt_life
163 .Fa "krb5_get_init_creds_opt *opt"
164 .Fa "krb5_deltat tkt_life"
166 .Ft krb5_error_code
167 .Fo krb5_get_init_creds_opt_set_canonicalize
168 .Fa "krb5_context context"
169 .Fa "krb5_get_init_creds_opt *opt"
170 .Fa "krb5_boolean req"
172 .Ft krb5_error_code
173 .Fo krb5_get_init_creds_opt_set_win2k
174 .Fa "krb5_context context"
175 .Fa "krb5_get_init_creds_opt *opt"
176 .Fa "krb5_boolean req"
178 .Ft krb5_error_code
179 .Fo krb5_get_init_creds
180 .Fa "krb5_context context"
181 .Fa "krb5_creds *creds"
182 .Fa "krb5_principal client"
183 .Fa "krb5_prompter_fct prompter"
184 .Fa "void *prompter_data"
185 .Fa "krb5_deltat start_time"
186 .Fa "const char *in_tkt_service"
187 .Fa "krb5_get_init_creds_opt *options"
189 .Ft krb5_error_code
190 .Fo krb5_get_init_creds_password
191 .Fa "krb5_context context"
192 .Fa "krb5_creds *creds"
193 .Fa "krb5_principal client"
194 .Fa "const char *password"
195 .Fa "krb5_prompter_fct prompter"
196 .Fa "void *prompter_data"
197 .Fa "krb5_deltat start_time"
198 .Fa "const char *in_tkt_service"
199 .Fa "krb5_get_init_creds_opt *in_options"
201 .Ft krb5_error_code
202 .Fo krb5_get_init_creds_keytab
203 .Fa "krb5_context context"
204 .Fa "krb5_creds *creds"
205 .Fa "krb5_principal client"
206 .Fa "krb5_keytab keytab"
207 .Fa "krb5_deltat start_time"
208 .Fa "const char *in_tkt_service"
209 .Fa "krb5_get_init_creds_opt *options"
211 .Ft int
212 .Fo krb5_prompter_posix
213 .Fa "krb5_context context"
214 .Fa "void *data"
215 .Fa "const char *name"
216 .Fa "const char *banner"
217 .Fa "int num_prompts"
218 .Fa "krb5_prompt prompts[]"
220 .Sh DESCRIPTION
221 Getting initial credential ticket for a principal.
222 That may include changing an expired password, and doing preauthentication.
223 This interface that replaces the deprecated
224 .Fa krb5_in_tkt
226 .Fa krb5_in_cred
227 functions.
229 If you only want to verify a username and password, consider using
230 .Xr krb5_verify_user 3
231 instead, since it also verifies that initial credentials with using a
232 keytab to make sure the response was from the KDC.
234 First a
235 .Li krb5_get_init_creds_opt
236 structure is initialized
237 with
238 .Fn krb5_get_init_creds_opt_alloc
240 .Fn krb5_get_init_creds_opt_init .
241 .Fn krb5_get_init_creds_opt_alloc
242 allocates a extendible structures that needs to be freed with
243 .Fn krb5_get_init_creds_opt_free .
244 The structure may be modified by any of the
245 .Fn krb5_get_init_creds_opt_set
246 functions to change request parameters and authentication information.
248 If the caller want to use the default options,
249 .Dv NULL
250 can be passed instead.
252 The the actual request to the KDC is done by any of the
253 .Fn krb5_get_init_creds ,
254 .Fn krb5_get_init_creds_password ,
256 .Fn krb5_get_init_creds_keytab
257 functions.
258 .Fn krb5_get_init_creds
259 is the least specialized function and can, with the right in data,
260 behave like the latter two.
261 The latter two are there for compatibility with older releases and
262 they are slightly easier to use.
264 .Li krb5_prompt
265 is a structure containing the following elements:
266 .Bd -literal
267 typedef struct {
268     const char *prompt;
269     int hidden;
270     krb5_data *reply;
271     krb5_prompt_type type
272 } krb5_prompt;
275 .Fa prompt
276 is the prompt that should shown to the user
278 .Fa hidden
279 is set, the prompter function shouldn't echo the output to the display
280 device.
281 .Fa reply
282 must be preallocated; it will not be allocated by the prompter
283 function.
284 Possible values for the
285 .Fa type
286 element are:
288 .Bl -tag -width Ds -compact -offset indent
289 .It KRB5_PROMPT_TYPE_PASSWORD
290 .It KRB5_PROMPT_TYPE_NEW_PASSWORD
291 .It KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN
292 .It KRB5_PROMPT_TYPE_PREAUTH
293 .It KRB5_PROMPT_TYPE_INFO
296 .Fn krb5_prompter_posix
297 is the default prompter function in a POSIX environment.
298 It matches the
299 .Fa krb5_prompter_fct
300 and can be used in the
301 .Fa krb5_get_init_creds
302 functions.
303 .Fn krb5_prompter_posix
304 doesn't require
305 .Fa prompter_data.
307 If the
308 .Fa start_time
309 is zero, then the requested ticket will be valid
310 beginning immediately.
311 Otherwise, the
312 .Fa start_time
313 indicates how far in the future the ticket should be postdated.
315 If the
316 .Fa in_tkt_service
317 name is
318 .Dv non-NULL ,
319 that principal name will be
320 used as the server name for the initial ticket request.
321 The realm of the name specified will be ignored and will be set to the
322 realm of the client name.
323 If no in_tkt_service name is specified,
324 krbtgt/CLIENT-REALM@CLIENT-REALM will be used.
326 For the rest of arguments, a configuration or library default will be
327 used if no value is specified in the options structure.
329 .Fn krb5_get_init_creds_opt_set_address_list
330 sets the list of
331 .Fa addresses
332 that is should be stored in the ticket.
334 .Fn krb5_get_init_creds_opt_set_addressless
335 controls if the ticket is requested with addresses or not,
336 .Fn krb5_get_init_creds_opt_set_address_list
337 overrides this option.
339 .Fn krb5_get_init_creds_opt_set_anonymous
340 make the request anonymous if the
341 .Fa anonymous
342 parameter is non-zero.
344 .Fn krb5_get_init_creds_opt_set_default_flags
345 sets the default flags using the configuration file.
347 .Fn krb5_get_init_creds_opt_set_etype_list
348 set a list of enctypes that the client is willing to support in the
349 request.
351 .Fn krb5_get_init_creds_opt_set_forwardable
352 request a forwardable ticket.
354 .Fn krb5_get_init_creds_opt_set_pa_password
355 set the
356 .Fa password
358 .Fa key_proc
359 that is going to be used to get a new ticket.
360 .Fa password
362 .Fa key_proc
363 can be
364 .Dv NULL
365 if the caller wants to use the default values.
366 If the
367 .Fa password
368 is unset and needed, the user will be prompted for it.
370 .Fn krb5_get_init_creds_opt_set_paq_request
371 sets the password that is going to be used to get a new ticket.
373 .Fn krb5_get_init_creds_opt_set_preauth_list
374 sets the list of client-supported preauth types.
376 .Fn krb5_get_init_creds_opt_set_proxiable
377 makes the request proxiable.
379 .Fn krb5_get_init_creds_opt_set_renew_life
380 sets the requested renewable lifetime.
382 .Fn krb5_get_init_creds_opt_set_salt
383 sets the salt that is going to be used in the request.
385 .Fn krb5_get_init_creds_opt_set_tkt_life
386 sets requested ticket lifetime.
388 .Fn krb5_get_init_creds_opt_set_canonicalize
389 requests that the KDC canonicalize the client pricipal if possible.
391 .Fn krb5_get_init_creds_opt_set_win2k
392 turns on compatibility with Windows 2000.
393 .Sh SEE ALSO
394 .Xr krb5 3 ,
395 .Xr krb5_creds 3 ,
396 .Xr krb5_verify_user 3 ,
397 .Xr krb5.conf 5 ,
398 .Xr kerberos 8