1 .\" Copyright (c) 2003 - 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_ccache.3 22071 2007-11-14 20:04:50Z lha $
43 .Nm krb5_cc_clear_mcred ,
45 .Nm krb5_cc_copy_cache ,
47 .Nm krb5_cc_default_name ,
49 .Nm krb5_cc_end_seq_get ,
51 .Nm krb5_cc_get_full_name ,
52 .Nm krb5_cc_get_name ,
54 .Nm krb5_cc_get_prefix_ops ,
55 .Nm krb5_cc_get_principal ,
56 .Nm krb5_cc_get_type ,
57 .Nm krb5_cc_get_version ,
58 .Nm krb5_cc_initialize ,
59 .Nm krb5_cc_next_cred ,
60 .Nm krb5_cc_next_cred_match ,
61 .Nm krb5_cc_new_unique ,
62 .Nm krb5_cc_register ,
63 .Nm krb5_cc_remove_cred ,
65 .Nm krb5_cc_retrieve_cred ,
66 .Nm krb5_cc_set_default_name ,
67 .Nm krb5_cc_set_flags ,
68 .Nm krb5_cc_start_seq_get ,
69 .Nm krb5_cc_store_cred
70 .Nd mange credential cache
72 Kerberos 5 Library (libkrb5, -lkrb5)
76 .Li "struct krb5_ccache;"
78 .Li "struct krb5_cc_cursor;"
80 .Li "struct krb5_cc_ops;"
82 .Li "struct krb5_cc_ops *krb5_fcc_ops;"
84 .Li "struct krb5_cc_ops *krb5_mcc_ops;"
87 .Fo krb5_cc_clear_mcred
88 .Fa "krb5_creds *mcred"
92 .Fa "krb5_context context"
96 .Fo krb5_cc_copy_cache
97 .Fa "krb5_context context"
98 .Fa "const krb5_ccache from"
103 .Fa "krb5_context context"
104 .Fa "krb5_ccache *id"
107 .Fo krb5_cc_default_name
108 .Fa "krb5_context context"
112 .Fa "krb5_context context"
116 .Fo krb5_cc_end_seq_get
117 .Fa "krb5_context context"
118 .Fa "const krb5_ccache id"
119 .Fa "krb5_cc_cursor *cursor"
123 .Fa "krb5_context context"
124 .Fa "const krb5_cc_ops *ops"
125 .Fa "krb5_ccache *id"
128 .Fo krb5_cc_get_full_name
129 .Fa "krb5_context context"
135 .Fa "krb5_context context"
139 .Fo krb5_cc_get_principal
140 .Fa "krb5_context context"
142 .Fa "krb5_principal *principal"
146 .Fa "krb5_context context"
149 .Ft "const krb5_cc_ops *"
151 .Fa "krb5_context context"
154 .Ft "const krb5_cc_ops *"
155 .Fo krb5_cc_get_prefix_ops
156 .Fa "krb5_context context"
157 .Fa "const char *prefix"
160 .Fo krb5_cc_get_version
161 .Fa "krb5_context context"
162 .Fa "const krb5_ccache id"
165 .Fo krb5_cc_initialize
166 .Fa "krb5_context context"
168 .Fa "krb5_principal primary_principal"
172 .Fa "krb5_context context"
173 .Fa "const krb5_cc_ops *ops"
174 .Fa "krb5_boolean override"
178 .Fa "krb5_context context"
179 .Fa "const char *name"
180 .Fa "krb5_ccache *id"
183 .Fo krb5_cc_retrieve_cred
184 .Fa "krb5_context context"
186 .Fa "krb5_flags whichfields"
187 .Fa "const krb5_creds *mcreds"
188 .Fa "krb5_creds *creds"
191 .Fo krb5_cc_remove_cred
192 .Fa "krb5_context context"
194 .Fa "krb5_flags which"
195 .Fa "krb5_creds *cred"
198 .Fo krb5_cc_set_default_name
199 .Fa "krb5_context context"
200 .Fa "const char *name"
203 .Fo krb5_cc_start_seq_get
204 .Fa "krb5_context context"
205 .Fa "const krb5_ccache id"
206 .Fa "krb5_cc_cursor *cursor"
209 .Fo krb5_cc_store_cred
210 .Fa "krb5_context context"
212 .Fa "krb5_creds *creds"
215 .Fo krb5_cc_set_flags
216 .Fa "krb5_context context"
217 .Fa "krb5_cc_set_flags id"
218 .Fa "krb5_flags flags"
221 .Fo krb5_cc_next_cred
222 .Fa "krb5_context context"
223 .Fa "const krb5_ccache id"
224 .Fa "krb5_cc_cursor *cursor"
225 .Fa "krb5_creds *creds"
228 .Fo krb5_cc_next_cred_match
229 .Fa "krb5_context context"
230 .Fa "const krb5_ccache id"
231 .Fa "krb5_cc_cursor *cursor"
232 .Fa "krb5_creds *creds"
233 .Fa "krb5_flags whichfields"
234 .Fa "const krb5_creds *mcreds"
237 .Fo krb5_cc_new_unique
238 .Fa "krb5_context context"
239 .Fa "const char *type"
240 .Fa "const char *hint"
241 .Fa "krb5_ccache *id"
246 structure holds a Kerberos credential cache.
250 structure holds current position in a credential cache when
251 iterating over the cache.
255 structure holds a set of operations that can me preformed on a
258 There is no component inside
263 that is directly referable.
267 holds a Kerberos credential, see manpage for
270 .Fn krb5_cc_default_name
272 .Fn krb5_cc_set_default_name
273 gets and sets the default name for the
277 opens the default credential cache in
279 Return 0 or an error code.
282 generates a new credential cache of type
286 Return 0 or an error code.
287 The Heimdal version of this function also runs
288 .Fn krb5_cc_initialize
289 on the credential cache, but since the MIT version doesn't, portable
290 code must call krb5_cc_initialize.
292 .Fn krb5_cc_new_unique
293 generates a new unique credential cache of
299 the library chooses the default credential cache type.
304 is a string that the credential cache type can use to base the name of
305 the credential on, this is to make it easier for the user to
306 differentiate the credentials.
307 The returned credential cache
309 should be freed using
312 .Fn krb5_cc_destroy .
313 Returns 0 or an error code.
316 finds and allocates a credential cache in
318 from the specification in
320 If the credential cache name doesn't contain any colon (:), interpret it as a
322 Return 0 or an error code.
324 .Fn krb5_cc_initialize
325 creates a new credential cache in
328 .Fa primary_principal .
329 Return 0 or an error code.
332 stops using the credential cache
334 and frees the related resources.
335 Return 0 or an error code.
337 removes the credential cache
338 and closes (by calling
341 Return 0 or an error code.
343 .Fn krb5_cc_copy_cache
344 copys the contents of
349 .Fn krb5_cc_get_full_name
350 returns the complete resolvable name of the credential cache
357 Returns 0 or an error, on error
363 returns the name of the credential cache
366 .Fn krb5_cc_get_principal
367 returns the principal of
371 Return 0 or an error code.
374 returns the type of the credential cache
378 returns the ops of the credential cache
381 .Fn krb5_cc_get_version
382 returns the version of
386 Adds a new credential cache type with operations
388 overwriting any existing one if
390 Return an error code or 0.
392 .Fn krb5_cc_get_prefix_ops
393 Get the cc ops that is registered in
401 .Fn krb5_cc_remove_cred
402 removes the credential identified by
408 .Fn krb5_cc_store_cred
411 in the credential cache
413 Return 0 or an error code.
415 .Fn krb5_cc_set_flags
421 .Fn krb5_cc_clear_mcred
424 argument so it is reset and can be used with
425 .Fa krb5_cc_retrieve_cred .
427 .Fn krb5_cc_retrieve_cred ,
428 retrieves the credential identified by
437 should be freed using
438 .Fn krb5_free_cred_contents .
439 Return 0 or an error code.
441 .Fn krb5_cc_start_seq_get
444 structure to be used for iteration over the credential cache.
446 .Fn krb5_cc_next_cred
447 retrieves the next cred pointed to by
454 Return 0 or an error code.
456 .Fn krb5_cc_next_cred_match
458 .Fn krb5_cc_next_cred
459 except that it will only return creds matching
464 .Xr krb5_compare_creds 3 . )
466 .Fn krb5_cc_end_seq_get
470 This is a minimalistic version of
477 main (int argc, char **argv)
479 krb5_context context;
480 krb5_cc_cursor cursor;
485 if (krb5_init_context (&context) != 0)
486 errx(1, "krb5_context");
488 ret = krb5_cc_default (context, &id);
490 krb5_err(context, 1, ret, "krb5_cc_default");
492 ret = krb5_cc_start_seq_get(context, id, &cursor);
494 krb5_err(context, 1, ret, "krb5_cc_start_seq_get");
496 while((ret = krb5_cc_next_cred(context, id, &cursor, &creds)) == 0){
499 krb5_unparse_name_short(context, creds.server, &principal);
500 printf("principal: %s\\n", principal);
502 krb5_free_cred_contents (context, &creds);
504 ret = krb5_cc_end_seq_get(context, id, &cursor);
506 krb5_err(context, 1, ret, "krb5_cc_end_seq_get");
508 krb5_cc_close(context, id);
510 krb5_free_context(context);