1 .\" Copyright (c) 2001 - 2003 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,v 1.9 2003/04/16 13:58:16 lha Exp $
39 .Nm krb5_keytab_entry ,
41 .Nm krb5_kt_add_entry ,
44 .Nm krb5_kt_copy_entry_contents ,
46 .Nm krb5_kt_default_name ,
47 .Nm krb5_kt_end_seq_get ,
48 .Nm krb5_kt_free_entry ,
49 .Nm krb5_kt_get_entry ,
50 .Nm krb5_kt_get_name ,
51 .Nm krb5_kt_get_type ,
52 .Nm krb5_kt_next_entry ,
53 .Nm krb5_kt_read_service_key ,
54 .Nm krb5_kt_register ,
55 .Nm krb5_kt_remove_entry ,
57 .Nm krb5_kt_start_seq_get
58 .Nd manage keytab (key storage) files
60 Kerberos 5 Library (libkrb5, -lkrb5)
66 .Fa "krb5_context context"
68 .Fa "krb5_keytab_entry *entry"
72 .Fa "krb5_context context"
77 .Fa "krb5_context context"
78 .Fa "krb5_keytab_entry *entry"
79 .Fa "krb5_const_principal principal"
81 .Fa "krb5_enctype enctype"
84 .Fo krb5_kt_copy_entry_contents
85 .Fa "krb5_context context"
86 .Fa "const krb5_keytab_entry *in"
87 .Fa "krb5_keytab_entry *out"
91 .Fa "krb5_context context"
95 .Fo krb5_kt_default_name
96 .Fa "krb5_context context"
101 .Fo krb5_kt_end_seq_get
102 .Fa "krb5_context context"
104 .Fa "krb5_kt_cursor *cursor"
107 .Fo krb5_kt_free_entry
108 .Fa "krb5_context context"
109 .Fa "krb5_keytab_entry *entry"
112 .Fo krb5_kt_get_entry
113 .Fa "krb5_context context"
115 .Fa "krb5_const_principal principal"
117 .Fa "krb5_enctype enctype"
118 .Fa "krb5_keytab_entry *entry"
122 .Fa "krb5_context context"
123 .Fa "krb5_keytab keytab"
125 .Fa "size_t namesize"
129 .Fa "krb5_context context"
130 .Fa "krb5_keytab keytab"
132 .Fa "size_t prefixsize"
135 .Fo krb5_kt_next_entry
136 .Fa "krb5_context context"
138 .Fa "krb5_keytab_entry *entry"
139 .Fa "krb5_kt_cursor *cursor"
142 .Fo krb5_kt_read_service_key
143 .Fa "krb5_context context"
144 .Fa "krb5_pointer keyprocarg"
145 .Fa "krb5_principal principal"
147 .Fa "krb5_enctype enctype"
148 .Fa "krb5_keyblock **key"
152 .Fa "krb5_context context"
153 .Fa "const krb5_kt_ops *ops"
156 .Fo krb5_kt_remove_entry
157 .Fa "krb5_context context"
159 .Fa "krb5_keytab_entry *entry"
163 .Fa "krb5_context context"
164 .Fa "const char *name"
165 .Fa "krb5_keytab *id"
168 .Fo krb5_kt_start_seq_get
169 .Fa "krb5_context context"
171 .Fa "krb5_kt_cursor *cursor"
174 A keytab name is on the form
178 part is specific to each keytab-type.
180 When a keytab-name is resolved, the type is matched with an internal
181 list of keytab types. If there is no matching keytab type,
182 the default keytab is used. The current default type is
184 The default value can be changed in the configuration file
186 by setting the variable
187 .Li [defaults]default_keytab_name .
189 The keytab types that are implemented in Heimdal
193 store the keytab in a file, the type's name is
195 The residual part is a filename.
197 store the keytab in a
200 .Pa /usr/afs/etc/KeyFile ) ,
203 The residual part is a filename.
205 the keytab is a Kerberos 4
207 that is on-the-fly converted to a keytab. The type's name is
209 The residual part is a filename.
211 The keytab is stored in a memory segment. This allows sensitive and/or
212 temporary data not to be stored on disk. The type's name is
214 There are no residual part, the only pointer back to the keytab is the
217 .Fn krb5_kt_resolve .
220 .Nm krb5_keytab_entry
221 holds all data for an entry in a keytab file, like principal name,
222 key-type, key, key-version number, etc.
224 holds the current position that is used when iterating through a
226 .Fn krb5_kt_start_seq_get ,
227 .Fn krb5_kt_next_entry ,
229 .Fn krb5_kt_end_seq_get .
232 contains the different operations that can be done to a keytab. This
233 structure is normally only used when doing a new keytab-type
237 is the equivalent of an
239 on keytab. Resolve the keytab name in
243 Returns 0 or an error. The opposite of
248 frees all resources allocated to the keytab.
253 to the default keytab.
254 Returns 0 or an error.
256 .Fn krb5_kt_default_name
257 copy the name of the default keytab into
259 Return 0 or KRB5_CONFIG_NOTENUFSPACE if
263 .Fn krb5_kt_add_entry
269 is returned if the keytab is a readonly keytab.
272 compares the passed in
284 might be 0 which acts as a wildcard. Return TRUE if they compare the
285 same, FALSE otherwise.
287 .Fn krb5_kt_copy_entry_contents
288 copies the contents of
292 Returns 0 or an error.
295 retrieves the name of the keytab
300 Returns 0 or an error.
303 retrieves the type of the keytab
305 and store the prefix/name for type of the keytab into
308 The prefix will have the maximum length of
309 .Dv KRB5_KT_PREFIX_MAX_LEN
310 (including terminating
312 Returns 0 or an error.
314 .Fn krb5_kt_free_entry
315 frees the contents of
318 .Fn krb5_kt_start_seq_get
321 to point at the beginning of
323 Returns 0 or an error.
325 .Fn krb5_kt_next_entry
326 gets the next entry from
332 Returns 0 or an error.
334 .Fn krb5_kt_end_seq_get
335 releases all resources associated with
338 .Fn krb5_kt_get_entry
339 retrieves the keytab entry for
347 Returns 0 or an error.
349 .Fn krb5_kt_read_service_key
350 reads the key identified by
356 (the default if == NULL) into
358 Returns 0 or an error.
360 .Fn krb5_kt_remove_entry
365 Returns 0 or an error.
368 registers a new keytab type
370 Returns 0 or an error.
372 This is a minimalistic version of
377 main (int argc, char **argv)
379 krb5_context context;
381 krb5_kt_cursor cursor;
382 krb5_keytab_entry entry;
386 if (krb5_init_context (&context) != 0)
387 errx(1, "krb5_context");
389 ret = krb5_kt_default (context, &keytab);
391 krb5_err(context, 1, ret, "krb5_kt_default");
393 ret = krb5_kt_start_seq_get(context, keytab, &cursor);
395 krb5_err(context, 1, ret, "krb5_kt_start_seq_get");
396 while((ret = krb5_kt_next_entry(context, keytab, &entry, &cursor)) == 0){
397 krb5_unparse_name_short(context, entry.principal, &principal);
398 printf("principal: %s\\n", principal);
400 krb5_kt_free_entry(context, &entry);
402 ret = krb5_kt_end_seq_get(context, keytab, &cursor);
404 krb5_err(context, 1, ret, "krb5_kt_end_seq_get");
405 krb5_free_context(context);