1 .\" Copyright (c) 2001 - 2005 Kungliga Tekniska Högskolan
2 .\" (Royal Institute of Technology, Stockholm, Sweden).
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
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.
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.
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
32 .\" $Id: krb5_keytab.3 22071 2007-11-14 20:04:50Z lha $
39 .Nm krb5_keytab_entry ,
41 .Nm krb5_kt_add_entry ,
44 .Nm krb5_kt_copy_entry_contents ,
46 .Nm krb5_kt_default_modify_name ,
47 .Nm krb5_kt_default_name ,
48 .Nm krb5_kt_end_seq_get ,
49 .Nm krb5_kt_free_entry ,
50 .Nm krb5_kt_get_entry ,
51 .Nm krb5_kt_get_name ,
52 .Nm krb5_kt_get_type ,
53 .Nm krb5_kt_next_entry ,
54 .Nm krb5_kt_read_service_key ,
55 .Nm krb5_kt_register ,
56 .Nm krb5_kt_remove_entry ,
58 .Nm krb5_kt_start_seq_get
59 .Nd manage keytab (key storage) files
61 Kerberos 5 Library (libkrb5, -lkrb5)
67 .Fa "krb5_context context"
69 .Fa "krb5_keytab_entry *entry"
73 .Fa "krb5_context context"
78 .Fa "krb5_context context"
79 .Fa "krb5_keytab_entry *entry"
80 .Fa "krb5_const_principal principal"
82 .Fa "krb5_enctype enctype"
85 .Fo krb5_kt_copy_entry_contents
86 .Fa "krb5_context context"
87 .Fa "const krb5_keytab_entry *in"
88 .Fa "krb5_keytab_entry *out"
92 .Fa "krb5_context context"
96 .Fo krb5_kt_default_modify_name
97 .Fa "krb5_context context"
102 .Fo krb5_kt_default_name
103 .Fa "krb5_context context"
105 .Fa "size_t namesize"
108 .Fo krb5_kt_end_seq_get
109 .Fa "krb5_context context"
111 .Fa "krb5_kt_cursor *cursor"
114 .Fo krb5_kt_free_entry
115 .Fa "krb5_context context"
116 .Fa "krb5_keytab_entry *entry"
119 .Fo krb5_kt_get_entry
120 .Fa "krb5_context context"
122 .Fa "krb5_const_principal principal"
124 .Fa "krb5_enctype enctype"
125 .Fa "krb5_keytab_entry *entry"
129 .Fa "krb5_context context"
130 .Fa "krb5_keytab keytab"
132 .Fa "size_t namesize"
136 .Fa "krb5_context context"
137 .Fa "krb5_keytab keytab"
139 .Fa "size_t prefixsize"
142 .Fo krb5_kt_next_entry
143 .Fa "krb5_context context"
145 .Fa "krb5_keytab_entry *entry"
146 .Fa "krb5_kt_cursor *cursor"
149 .Fo krb5_kt_read_service_key
150 .Fa "krb5_context context"
151 .Fa "krb5_pointer keyprocarg"
152 .Fa "krb5_principal principal"
154 .Fa "krb5_enctype enctype"
155 .Fa "krb5_keyblock **key"
159 .Fa "krb5_context context"
160 .Fa "const krb5_kt_ops *ops"
163 .Fo krb5_kt_remove_entry
164 .Fa "krb5_context context"
166 .Fa "krb5_keytab_entry *entry"
170 .Fa "krb5_context context"
171 .Fa "const char *name"
172 .Fa "krb5_keytab *id"
175 .Fo krb5_kt_start_seq_get
176 .Fa "krb5_context context"
178 .Fa "krb5_kt_cursor *cursor"
181 A keytab name is on the form
185 part is specific to each keytab-type.
187 When a keytab-name is resolved, the type is matched with an internal
188 list of keytab types. If there is no matching keytab type,
189 the default keytab is used. The current default type is
191 The default value can be changed in the configuration file
193 by setting the variable
194 .Li [defaults]default_keytab_name .
196 The keytab types that are implemented in Heimdal
200 store the keytab in a file, the type's name is
202 The residual part is a filename.
203 For compatibility with other Kerberos implemtation
209 has the same format as
212 have a format that is compatible with older versions of MIT kerberos
213 and SUN's Java based installation. They store a truncted kvno, so
214 when the knvo excess 255, they are truncted in this format.
216 store the keytab in a
219 .Pa /usr/afs/etc/KeyFile ) ,
222 The residual part is a filename.
224 the keytab is a Kerberos 4
226 that is on-the-fly converted to a keytab. The type's name is
228 The residual part is a filename.
230 The keytab is stored in a memory segment. This allows sensitive and/or
231 temporary data not to be stored on disk. The type's name is
235 keytab is referenced counted by and opened by the residual name, so two
236 handles can point to the same memory area.
237 When the last user closes the entry, it disappears.
240 .Nm krb5_keytab_entry
241 holds all data for an entry in a keytab file, like principal name,
242 key-type, key, key-version number, etc.
244 holds the current position that is used when iterating through a
246 .Fn krb5_kt_start_seq_get ,
247 .Fn krb5_kt_next_entry ,
249 .Fn krb5_kt_end_seq_get .
252 contains the different operations that can be done to a keytab. This
253 structure is normally only used when doing a new keytab-type
257 is the equivalent of an
259 on keytab. Resolve the keytab name in
263 Returns 0 or an error. The opposite of
269 frees all resources allocated to the keytab, even on failure.
270 Returns 0 or an error.
275 to the default keytab.
276 Returns 0 or an error.
278 .Fn krb5_kt_default_modify_name
279 copies the name of the default modify keytab into
281 Return 0 or KRB5_CONFIG_NOTENUFSPACE if
285 .Fn krb5_kt_default_name
286 copies the name of the default keytab into
288 Return 0 or KRB5_CONFIG_NOTENUFSPACE if
292 .Fn krb5_kt_add_entry
298 is returned if the keytab is a readonly keytab.
301 compares the passed in
313 might be 0 which acts as a wildcard. Return TRUE if they compare the
314 same, FALSE otherwise.
316 .Fn krb5_kt_copy_entry_contents
317 copies the contents of
321 Returns 0 or an error.
324 retrieves the name of the keytab
329 Returns 0 or an error.
332 retrieves the type of the keytab
334 and store the prefix/name for type of the keytab into
337 The prefix will have the maximum length of
338 .Dv KRB5_KT_PREFIX_MAX_LEN
339 (including terminating
341 Returns 0 or an error.
343 .Fn krb5_kt_free_entry
344 frees the contents of
347 .Fn krb5_kt_start_seq_get
350 to point at the beginning of
352 Returns 0 or an error.
354 .Fn krb5_kt_next_entry
355 gets the next entry from
361 On success the returne entry must be freed with
362 .Fn krb5_kt_free_entry .
363 Returns 0 or an error.
365 .Fn krb5_kt_end_seq_get
366 releases all resources associated with
369 .Fn krb5_kt_get_entry
370 retrieves the keytab entry for
378 When comparing an entry in the keytab to determine a match, the
381 is used, so the wildcard rules applies to the argument of
384 On success the returne entry must be freed with
385 .Fn krb5_kt_free_entry .
386 Returns 0 or an error.
388 .Fn krb5_kt_read_service_key
389 reads the key identified by
395 (the system default keytab if
400 is the same argument as to
403 .Fn krb5_kt_resolve .
406 will be used, so the same wildcard rules applies
408 .Fn krb5_kt_read_service_key .
409 On success the returned key must be freed with
410 .Fa krb5_free_keyblock .
411 Returns 0 or an error.
413 .Fn krb5_kt_remove_entry
418 When comparing an entry in the keytab to determine a match, the
421 is use, so the wildcard rules applies to the argument of
422 .Fn krb5_kt_remove_entry .
425 if not entry matched or another error.
428 registers a new keytab type
430 Returns 0 or an error.
432 This is a minimalistic version of
437 main (int argc, char **argv)
439 krb5_context context;
441 krb5_kt_cursor cursor;
442 krb5_keytab_entry entry;
446 if (krb5_init_context (&context) != 0)
447 errx(1, "krb5_context");
449 ret = krb5_kt_default (context, &keytab);
451 krb5_err(context, 1, ret, "krb5_kt_default");
453 ret = krb5_kt_start_seq_get(context, keytab, &cursor);
455 krb5_err(context, 1, ret, "krb5_kt_start_seq_get");
456 while((ret = krb5_kt_next_entry(context, keytab, &entry, &cursor)) == 0){
457 krb5_unparse_name_short(context, entry.principal, &principal);
458 printf("principal: %s\\n", principal);
460 krb5_kt_free_entry(context, &entry);
462 ret = krb5_kt_end_seq_get(context, keytab, &cursor);
464 krb5_err(context, 1, ret, "krb5_kt_end_seq_get");
465 ret = krb5_kt_close(context, keytab);
467 krb5_err(context, 1, ret, "krb5_kt_close");
468 krb5_free_context(context);
473 Heimdal stored the ticket flags in machine bit-field order before
474 Heimdal 0.7. The behavior is possible to change in with the option
475 .Li [libdefaults]fcc-mit-ticketflags .
476 Heimdal 0.7 also code to detech that ticket flags was in the wrong
477 order and correct them. This matters when doing delegation in GSS-API
478 because the client code looks at the flag to determin if it is possible
479 to do delegation if the user requested it.