2 * Copyright (c) 1997 - 2008 Kungliga Tekniska Högskolan
3 * (Royal Institute of Technology, Stockholm, Sweden).
6 * Portions Copyright (c) 2009 Apple Inc. All rights reserved.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in the
17 * documentation and/or other materials provided with the distribution.
19 * 3. Neither the name of the Institute nor the names of its contributors
20 * may be used to endorse or promote products derived from this software
21 * without specific prior written permission.
23 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
27 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 #include "krb5_locl.h"
39 * @page krb5_ccache_intro The credential cache functions
40 * @section section_krb5_ccache Kerberos credential caches
42 * krb5_ccache structure holds a Kerberos credential cache.
44 * Heimdal support the follow types of credential caches:
47 * Store the credential in a database
49 * Store the credential in memory
51 * Store the credential in memory
53 * A credential cache server based solution for Mac OS X
55 * A credential cache server based solution for all platforms
59 * This is a minimalistic version of klist:
64 main (int argc, char **argv)
67 krb5_cc_cursor cursor;
72 if (krb5_init_context (&context) != 0)
73 errx(1, "krb5_context");
75 ret = krb5_cc_default (context, &id);
77 krb5_err(context, 1, ret, "krb5_cc_default");
79 ret = krb5_cc_start_seq_get(context, id, &cursor);
81 krb5_err(context, 1, ret, "krb5_cc_start_seq_get");
83 while((ret = krb5_cc_next_cred(context, id, &cursor, &creds)) == 0){
86 krb5_unparse_name(context, creds.server, &principal);
87 printf("principal: %s\\n", principal);
89 krb5_free_cred_contents (context, &creds);
91 ret = krb5_cc_end_seq_get(context, id, &cursor);
93 krb5_err(context, 1, ret, "krb5_cc_end_seq_get");
95 krb5_cc_close(context, id);
97 krb5_free_context(context);
104 * Add a new ccache type with operations `ops', overwriting any
105 * existing one if `override'.
107 * @param context a Keberos context
108 * @param ops type of plugin symbol
109 * @param override flag to select if the registration is to overide
110 * an existing ops with the same name.
112 * @return Return an error code or 0, see krb5_get_error_message().
114 * @ingroup krb5_ccache
117 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
118 krb5_cc_register(krb5_context context
,
119 const krb5_cc_ops
*ops
,
120 krb5_boolean override
)
124 for(i
= 0; i
< context
->num_cc_ops
&& context
->cc_ops
[i
]->prefix
; i
++) {
125 if(strcmp(context
->cc_ops
[i
]->prefix
, ops
->prefix
) == 0) {
127 krb5_set_error_message(context
,
129 N_("cache type %s already exists", "type"),
131 return KRB5_CC_TYPE_EXISTS
;
136 if(i
== context
->num_cc_ops
) {
137 const krb5_cc_ops
**o
= realloc(context
->cc_ops
,
138 (context
->num_cc_ops
+ 1) *
139 sizeof(context
->cc_ops
[0]));
141 krb5_set_error_message(context
, KRB5_CC_NOMEM
,
142 N_("malloc: out of memory", ""));
143 return KRB5_CC_NOMEM
;
146 context
->cc_ops
[context
->num_cc_ops
] = NULL
;
147 context
->num_cc_ops
++;
149 context
->cc_ops
[i
] = ops
;
154 * Allocate the memory for a `id' and the that function table to
155 * `ops'. Returns 0 or and error code.
159 _krb5_cc_allocate(krb5_context context
,
160 const krb5_cc_ops
*ops
,
165 p
= malloc (sizeof(*p
));
167 krb5_set_error_message(context
, KRB5_CC_NOMEM
,
168 N_("malloc: out of memory", ""));
169 return KRB5_CC_NOMEM
;
178 * Allocate memory for a new ccache in `id' with operations `ops'
179 * and name `residual'. Return 0 or an error code.
182 static krb5_error_code
183 allocate_ccache (krb5_context context
,
184 const krb5_cc_ops
*ops
,
185 const char *residual
,
189 #ifdef KRB5_USE_PATH_TOKENS
190 char * exp_residual
= NULL
;
192 ret
= _krb5_expand_path_tokens(context
, residual
, &exp_residual
);
196 residual
= exp_residual
;
199 ret
= _krb5_cc_allocate(context
, ops
, id
);
201 #ifdef KRB5_USE_PATH_TOKENS
208 ret
= (*id
)->ops
->resolve(context
, id
, residual
);
214 #ifdef KRB5_USE_PATH_TOKENS
223 is_possible_path_name(const char * name
)
227 if ((colon
= strchr(name
, ':')) == NULL
)
231 /* <drive letter>:\path\to\cache ? */
233 if (colon
== name
+ 1 &&
234 strchr(colon
+ 1, ':') == NULL
)
242 * Find and allocate a ccache in `id' from the specification in `residual'.
243 * If the ccache name doesn't contain any colon, interpret it as a file name.
245 * @param context a Keberos context.
246 * @param name string name of a credential cache.
247 * @param id return pointer to a found credential cache.
249 * @return Return 0 or an error code. In case of an error, id is set
250 * to NULL, see krb5_get_error_message().
252 * @ingroup krb5_ccache
256 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
257 krb5_cc_resolve(krb5_context context
,
265 for(i
= 0; i
< context
->num_cc_ops
&& context
->cc_ops
[i
]->prefix
; i
++) {
266 size_t prefix_len
= strlen(context
->cc_ops
[i
]->prefix
);
268 if(strncmp(context
->cc_ops
[i
]->prefix
, name
, prefix_len
) == 0
269 && name
[prefix_len
] == ':') {
270 return allocate_ccache (context
, context
->cc_ops
[i
],
271 name
+ prefix_len
+ 1,
275 if (is_possible_path_name(name
))
276 return allocate_ccache (context
, &krb5_fcc_ops
, name
, id
);
278 krb5_set_error_message(context
, KRB5_CC_UNKNOWN_TYPE
,
279 N_("unknown ccache type %s", "name"), name
);
280 return KRB5_CC_UNKNOWN_TYPE
;
285 * Generates a new unique ccache of `type` in `id'. If `type' is NULL,
286 * the library chooses the default credential cache type. The supplied
287 * `hint' (that can be NULL) is a string that the credential cache
288 * type can use to base the name of the credential on, this is to make
289 * it easier for the user to differentiate the credentials.
291 * @return Return an error code or 0, see krb5_get_error_message().
293 * @ingroup krb5_ccache
296 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
297 krb5_cc_new_unique(krb5_context context
, const char *type
,
298 const char *hint
, krb5_ccache
*id
)
300 const krb5_cc_ops
*ops
;
303 ops
= krb5_cc_get_prefix_ops(context
, type
);
305 krb5_set_error_message(context
, KRB5_CC_UNKNOWN_TYPE
,
306 "Credential cache type %s is unknown", type
);
307 return KRB5_CC_UNKNOWN_TYPE
;
310 ret
= _krb5_cc_allocate(context
, ops
, id
);
313 ret
= (*id
)->ops
->gen_new(context
, id
);
322 * Return the name of the ccache `id'
324 * @ingroup krb5_ccache
328 KRB5_LIB_FUNCTION
const char* KRB5_LIB_CALL
329 krb5_cc_get_name(krb5_context context
,
332 return id
->ops
->get_name(context
, id
);
336 * Return the type of the ccache `id'.
338 * @ingroup krb5_ccache
342 KRB5_LIB_FUNCTION
const char* KRB5_LIB_CALL
343 krb5_cc_get_type(krb5_context context
,
346 return id
->ops
->prefix
;
350 * Return the complete resolvable name the cache
352 * @param context a Keberos context
353 * @param id return pointer to a found credential cache
354 * @param str the returned name of a credential cache, free with krb5_xfree()
356 * @return Returns 0 or an error (and then *str is set to NULL).
358 * @ingroup krb5_ccache
362 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
363 krb5_cc_get_full_name(krb5_context context
,
367 const char *type
, *name
;
371 type
= krb5_cc_get_type(context
, id
);
373 krb5_set_error_message(context
, KRB5_CC_UNKNOWN_TYPE
,
374 "cache have no name of type");
375 return KRB5_CC_UNKNOWN_TYPE
;
378 name
= krb5_cc_get_name(context
, id
);
380 krb5_set_error_message(context
, KRB5_CC_BADNAME
,
381 "cache of type %s have no name", type
);
382 return KRB5_CC_BADNAME
;
385 if (asprintf(str
, "%s:%s", type
, name
) == -1) {
386 krb5_set_error_message(context
, ENOMEM
, N_("malloc: out of memory", ""));
394 * Return krb5_cc_ops of a the ccache `id'.
396 * @ingroup krb5_ccache
401 krb5_cc_get_ops(krb5_context context
, krb5_ccache id
)
407 * Expand variables in `str' into `res'
411 _krb5_expand_default_cc_name(krb5_context context
, const char *str
, char **res
)
413 return _krb5_expand_path_tokens(context
, str
, res
);
417 * Return non-zero if envirnoment that will determine default krb5cc
422 environment_changed(krb5_context context
)
426 /* if the cc name was set, don't change it */
427 if (context
->default_cc_name_set
)
430 /* XXX performance: always ask KCM/API if default name has changed */
431 if (context
->default_cc_name
&&
432 (strncmp(context
->default_cc_name
, "KCM:", 4) == 0 ||
433 strncmp(context
->default_cc_name
, "API:", 4) == 0))
439 e
= getenv("KRB5CCNAME");
441 if (context
->default_cc_name_env
) {
442 free(context
->default_cc_name_env
);
443 context
->default_cc_name_env
= NULL
;
447 if (context
->default_cc_name_env
== NULL
)
449 if (strcmp(e
, context
->default_cc_name_env
) != 0)
456 * Switch the default default credential cache for a specific
457 * credcache type (and name for some implementations).
459 * @return Return an error code or 0, see krb5_get_error_message().
461 * @ingroup krb5_ccache
464 krb5_error_code KRB5_LIB_FUNCTION
465 krb5_cc_switch(krb5_context context
, krb5_ccache id
)
468 if (id
->ops
->set_default
== NULL
)
471 return (*id
->ops
->set_default
)(context
, id
);
475 * Return true if the default credential cache support switch
477 * @ingroup krb5_ccache
480 krb5_boolean KRB5_LIB_FUNCTION
481 krb5_cc_support_switch(krb5_context context
, const char *type
)
483 const krb5_cc_ops
*ops
;
485 ops
= krb5_cc_get_prefix_ops(context
, type
);
486 if (ops
&& ops
->set_default
)
492 * Set the default cc name for `context' to `name'.
494 * @ingroup krb5_ccache
497 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
498 krb5_cc_set_default_name(krb5_context context
, const char *name
)
500 krb5_error_code ret
= 0;
501 char *p
= NULL
, *exp_p
= NULL
;
504 const char *e
= NULL
;
507 e
= getenv("KRB5CCNAME");
510 if (context
->default_cc_name_env
)
511 free(context
->default_cc_name_env
);
512 context
->default_cc_name_env
= strdup(e
);
516 e
= krb5_config_get_string(context
, NULL
, "libdefaults",
517 "default_cc_name", NULL
);
519 ret
= _krb5_expand_default_cc_name(context
, e
, &p
);
524 const krb5_cc_ops
*ops
= KRB5_DEFAULT_CCTYPE
;
525 e
= krb5_config_get_string(context
, NULL
, "libdefaults",
526 "default_cc_type", NULL
);
528 ops
= krb5_cc_get_prefix_ops(context
, e
);
530 krb5_set_error_message(context
,
531 KRB5_CC_UNKNOWN_TYPE
,
532 "Credential cache type %s "
534 return KRB5_CC_UNKNOWN_TYPE
;
537 ret
= (*ops
->get_default_name
)(context
, &p
);
542 context
->default_cc_name_set
= 0;
545 context
->default_cc_name_set
= 1;
549 krb5_set_error_message(context
, ENOMEM
, N_("malloc: out of memory", ""));
553 ret
= _krb5_expand_path_tokens(context
, p
, &exp_p
);
558 if (context
->default_cc_name
)
559 free(context
->default_cc_name
);
561 context
->default_cc_name
= exp_p
;
567 * Return a pointer to a context static string containing the default
570 * @return String to the default credential cache name.
572 * @ingroup krb5_ccache
576 KRB5_LIB_FUNCTION
const char* KRB5_LIB_CALL
577 krb5_cc_default_name(krb5_context context
)
579 if (context
->default_cc_name
== NULL
|| environment_changed(context
))
580 krb5_cc_set_default_name(context
, NULL
);
582 return context
->default_cc_name
;
586 * Open the default ccache in `id'.
588 * @return Return an error code or 0, see krb5_get_error_message().
590 * @ingroup krb5_ccache
594 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
595 krb5_cc_default(krb5_context context
,
598 const char *p
= krb5_cc_default_name(context
);
601 krb5_set_error_message(context
, ENOMEM
, N_("malloc: out of memory", ""));
604 return krb5_cc_resolve(context
, p
, id
);
608 * Create a new ccache in `id' for `primary_principal'.
610 * @return Return an error code or 0, see krb5_get_error_message().
612 * @ingroup krb5_ccache
616 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
617 krb5_cc_initialize(krb5_context context
,
619 krb5_principal primary_principal
)
621 return (*id
->ops
->init
)(context
, id
, primary_principal
);
626 * Remove the ccache `id'.
628 * @return Return an error code or 0, see krb5_get_error_message().
630 * @ingroup krb5_ccache
634 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
635 krb5_cc_destroy(krb5_context context
,
640 ret
= (*id
->ops
->destroy
)(context
, id
);
641 krb5_cc_close (context
, id
);
646 * Stop using the ccache `id' and free the related resources.
648 * @return Return an error code or 0, see krb5_get_error_message().
650 * @ingroup krb5_ccache
654 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
655 krb5_cc_close(krb5_context context
,
659 ret
= (*id
->ops
->close
)(context
, id
);
665 * Store `creds' in the ccache `id'.
667 * @return Return an error code or 0, see krb5_get_error_message().
669 * @ingroup krb5_ccache
673 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
674 krb5_cc_store_cred(krb5_context context
,
678 return (*id
->ops
->store
)(context
, id
, creds
);
682 * Retrieve the credential identified by `mcreds' (and `whichfields')
683 * from `id' in `creds'. 'creds' must be free by the caller using
684 * krb5_free_cred_contents.
686 * @param context A Kerberos 5 context
687 * @param id a Kerberos 5 credential cache
688 * @param whichfields what fields to use for matching credentials, same
689 * flags as whichfields in krb5_compare_creds()
690 * @param mcreds template credential to use for comparing
691 * @param creds returned credential, free with krb5_free_cred_contents()
693 * @return Return an error code or 0, see krb5_get_error_message().
695 * @ingroup krb5_ccache
699 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
700 krb5_cc_retrieve_cred(krb5_context context
,
702 krb5_flags whichfields
,
703 const krb5_creds
*mcreds
,
707 krb5_cc_cursor cursor
;
709 if (id
->ops
->retrieve
!= NULL
) {
710 return (*id
->ops
->retrieve
)(context
, id
, whichfields
,
714 ret
= krb5_cc_start_seq_get(context
, id
, &cursor
);
717 while((ret
= krb5_cc_next_cred(context
, id
, &cursor
, creds
)) == 0){
718 if(krb5_compare_creds(context
, whichfields
, mcreds
, creds
)){
722 krb5_free_cred_contents (context
, creds
);
724 krb5_cc_end_seq_get(context
, id
, &cursor
);
729 * Return the principal of `id' in `principal'.
731 * @return Return an error code or 0, see krb5_get_error_message().
733 * @ingroup krb5_ccache
737 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
738 krb5_cc_get_principal(krb5_context context
,
740 krb5_principal
*principal
)
742 return (*id
->ops
->get_princ
)(context
, id
, principal
);
746 * Start iterating over `id', `cursor' is initialized to the
747 * beginning. Caller must free the cursor with krb5_cc_end_seq_get().
749 * @return Return an error code or 0, see krb5_get_error_message().
751 * @ingroup krb5_ccache
755 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
756 krb5_cc_start_seq_get (krb5_context context
,
757 const krb5_ccache id
,
758 krb5_cc_cursor
*cursor
)
760 return (*id
->ops
->get_first
)(context
, id
, cursor
);
764 * Retrieve the next cred pointed to by (`id', `cursor') in `creds'
765 * and advance `cursor'.
767 * @return Return an error code or 0, see krb5_get_error_message().
769 * @ingroup krb5_ccache
773 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
774 krb5_cc_next_cred (krb5_context context
,
775 const krb5_ccache id
,
776 krb5_cc_cursor
*cursor
,
779 return (*id
->ops
->get_next
)(context
, id
, cursor
, creds
);
783 * Destroy the cursor `cursor'.
785 * @ingroup krb5_ccache
789 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
790 krb5_cc_end_seq_get (krb5_context context
,
791 const krb5_ccache id
,
792 krb5_cc_cursor
*cursor
)
794 return (*id
->ops
->end_get
)(context
, id
, cursor
);
798 * Remove the credential identified by `cred', `which' from `id'.
800 * @ingroup krb5_ccache
804 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
805 krb5_cc_remove_cred(krb5_context context
,
810 if(id
->ops
->remove_cred
== NULL
) {
811 krb5_set_error_message(context
,
813 "ccache %s does not support remove_cred",
815 return EACCES
; /* XXX */
817 return (*id
->ops
->remove_cred
)(context
, id
, which
, cred
);
821 * Set the flags of `id' to `flags'.
823 * @ingroup krb5_ccache
827 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
828 krb5_cc_set_flags(krb5_context context
,
832 return (*id
->ops
->set_flags
)(context
, id
, flags
);
836 * Get the flags of `id', store them in `flags'.
838 * @ingroup krb5_ccache
841 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
842 krb5_cc_get_flags(krb5_context context
,
851 * Copy the contents of `from' to `to' if the given match function
854 * @param context A Kerberos 5 context.
855 * @param from the cache to copy data from.
856 * @param to the cache to copy data to.
857 * @param match a match function that should return TRUE if cred argument should be copied, if NULL, all credentials are copied.
858 * @param matchctx context passed to match function.
859 * @param matched set to true if there was a credential that matched, may be NULL.
861 * @return Return an error code or 0, see krb5_get_error_message().
863 * @ingroup krb5_ccache
866 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
867 krb5_cc_copy_match_f(krb5_context context
,
868 const krb5_ccache from
,
870 krb5_boolean (*match
)(krb5_context
, void *, const krb5_creds
*),
872 unsigned int *matched
)
875 krb5_cc_cursor cursor
;
877 krb5_principal princ
;
882 ret
= krb5_cc_get_principal(context
, from
, &princ
);
885 ret
= krb5_cc_initialize(context
, to
, princ
);
887 krb5_free_principal(context
, princ
);
890 ret
= krb5_cc_start_seq_get(context
, from
, &cursor
);
892 krb5_free_principal(context
, princ
);
896 while ((ret
= krb5_cc_next_cred(context
, from
, &cursor
, &cred
)) == 0) {
897 if (match
== NULL
|| (*match
)(context
, matchctx
, &cred
) == 0) {
900 ret
= krb5_cc_store_cred(context
, to
, &cred
);
904 krb5_free_cred_contents(context
, &cred
);
906 krb5_cc_end_seq_get(context
, from
, &cursor
);
907 krb5_free_principal(context
, princ
);
908 if (ret
== KRB5_CC_END
)
914 * Just like krb5_cc_copy_match_f(), but copy everything.
916 * @ingroup @krb5_ccache
919 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
920 krb5_cc_copy_cache(krb5_context context
,
921 const krb5_ccache from
,
924 return krb5_cc_copy_match_f(context
, from
, to
, NULL
, NULL
, NULL
);
928 * Return the version of `id'.
930 * @ingroup krb5_ccache
934 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
935 krb5_cc_get_version(krb5_context context
,
936 const krb5_ccache id
)
938 if(id
->ops
->get_version
)
939 return (*id
->ops
->get_version
)(context
, id
);
945 * Clear `mcreds' so it can be used with krb5_cc_retrieve_cred
947 * @ingroup krb5_ccache
951 KRB5_LIB_FUNCTION
void KRB5_LIB_CALL
952 krb5_cc_clear_mcred(krb5_creds
*mcred
)
954 memset(mcred
, 0, sizeof(*mcred
));
958 * Get the cc ops that is registered in `context' to handle the
959 * prefix. prefix can be a complete credential cache name or a
960 * prefix, the function will only use part up to the first colon (:)
961 * if there is one. If prefix the argument is NULL, the default ccache
962 * implemtation is returned.
964 * @return Returns NULL if ops not found.
966 * @ingroup krb5_ccache
971 krb5_cc_get_prefix_ops(krb5_context context
, const char *prefix
)
977 return KRB5_DEFAULT_CCTYPE
;
978 if (prefix
[0] == '/')
979 return &krb5_fcc_ops
;
983 krb5_set_error_message(context
, ENOMEM
, N_("malloc: out of memory", ""));
990 for(i
= 0; i
< context
->num_cc_ops
&& context
->cc_ops
[i
]->prefix
; i
++) {
991 if(strcmp(context
->cc_ops
[i
]->prefix
, p
) == 0) {
993 return context
->cc_ops
[i
];
1000 struct krb5_cc_cache_cursor_data
{
1001 const krb5_cc_ops
*ops
;
1002 krb5_cc_cursor cursor
;
1006 * Start iterating over all caches of specified type. See also
1007 * krb5_cccol_cursor_new().
1009 * @param context A Kerberos 5 context
1010 * @param type optional type to iterate over, if NULL, the default cache is used.
1011 * @param cursor cursor should be freed with krb5_cc_cache_end_seq_get().
1013 * @return Return an error code or 0, see krb5_get_error_message().
1015 * @ingroup krb5_ccache
1019 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1020 krb5_cc_cache_get_first (krb5_context context
,
1022 krb5_cc_cache_cursor
*cursor
)
1024 const krb5_cc_ops
*ops
;
1025 krb5_error_code ret
;
1028 type
= krb5_cc_default_name(context
);
1030 ops
= krb5_cc_get_prefix_ops(context
, type
);
1032 krb5_set_error_message(context
, KRB5_CC_UNKNOWN_TYPE
,
1033 "Unknown type \"%s\" when iterating "
1034 "trying to iterate the credential caches", type
);
1035 return KRB5_CC_UNKNOWN_TYPE
;
1038 if (ops
->get_cache_first
== NULL
) {
1039 krb5_set_error_message(context
, KRB5_CC_NOSUPP
,
1040 N_("Credential cache type %s doesn't support "
1041 "iterations over caches", "type"),
1043 return KRB5_CC_NOSUPP
;
1046 *cursor
= calloc(1, sizeof(**cursor
));
1047 if (*cursor
== NULL
) {
1048 krb5_set_error_message(context
, ENOMEM
, N_("malloc: out of memory", ""));
1052 (*cursor
)->ops
= ops
;
1054 ret
= ops
->get_cache_first(context
, &(*cursor
)->cursor
);
1063 * Retrieve the next cache pointed to by (`cursor') in `id'
1064 * and advance `cursor'.
1066 * @param context A Kerberos 5 context
1067 * @param cursor the iterator cursor, returned by krb5_cc_cache_get_first()
1068 * @param id next ccache
1070 * @return Return 0 or an error code. Returns KRB5_CC_END when the end
1071 * of caches is reached, see krb5_get_error_message().
1073 * @ingroup krb5_ccache
1077 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1078 krb5_cc_cache_next (krb5_context context
,
1079 krb5_cc_cache_cursor cursor
,
1082 return cursor
->ops
->get_cache_next(context
, cursor
->cursor
, id
);
1086 * Destroy the cursor `cursor'.
1088 * @return Return an error code or 0, see krb5_get_error_message().
1090 * @ingroup krb5_ccache
1094 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1095 krb5_cc_cache_end_seq_get (krb5_context context
,
1096 krb5_cc_cache_cursor cursor
)
1098 krb5_error_code ret
;
1099 ret
= cursor
->ops
->end_cache_get(context
, cursor
->cursor
);
1106 * Search for a matching credential cache that have the
1107 * `principal' as the default principal. On success, `id' needs to be
1108 * freed with krb5_cc_close() or krb5_cc_destroy().
1110 * @param context A Kerberos 5 context
1111 * @param client The principal to search for
1112 * @param id the returned credential cache
1114 * @return On failure, error code is returned and `id' is set to NULL.
1116 * @ingroup krb5_ccache
1120 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1121 krb5_cc_cache_match (krb5_context context
,
1122 krb5_principal client
,
1125 krb5_cccol_cursor cursor
;
1126 krb5_error_code ret
;
1127 krb5_ccache cache
= NULL
;
1131 ret
= krb5_cccol_cursor_new (context
, &cursor
);
1135 while (krb5_cccol_cursor_next (context
, cursor
, &cache
) == 0 && cache
!= NULL
) {
1136 krb5_principal principal
;
1138 ret
= krb5_cc_get_principal(context
, cache
, &principal
);
1142 match
= krb5_principal_compare(context
, principal
, client
);
1143 krb5_free_principal(context
, principal
);
1148 krb5_cc_close(context
, cache
);
1152 krb5_cccol_cursor_free(context
, &cursor
);
1154 if (cache
== NULL
) {
1157 krb5_unparse_name(context
, client
, &str
);
1159 krb5_set_error_message(context
, KRB5_CC_NOTFOUND
,
1160 N_("Principal %s not found in any "
1161 "credential cache", ""),
1162 str
? str
: "<out of memory>");
1165 return KRB5_CC_NOTFOUND
;
1173 * Move the content from one credential cache to another. The
1174 * operation is an atomic switch.
1176 * @param context a Keberos context
1177 * @param from the credential cache to move the content from
1178 * @param to the credential cache to move the content to
1180 * @return On sucess, from is freed. On failure, error code is
1181 * returned and from and to are both still allocated, see krb5_get_error_message().
1183 * @ingroup krb5_ccache
1187 krb5_cc_move(krb5_context context
, krb5_ccache from
, krb5_ccache to
)
1189 krb5_error_code ret
;
1191 if (strcmp(from
->ops
->prefix
, to
->ops
->prefix
) != 0) {
1192 krb5_set_error_message(context
, KRB5_CC_NOSUPP
,
1193 N_("Moving credentials between diffrent "
1194 "types not yet supported", ""));
1195 return KRB5_CC_NOSUPP
;
1198 ret
= (*to
->ops
->move
)(context
, from
, to
);
1200 memset(from
, 0, sizeof(*from
));
1206 #define KRB5_CONF_NAME "krb5_ccache_conf_data"
1207 #define KRB5_REALM_NAME "X-CACHECONF:"
1209 static krb5_error_code
1210 build_conf_principals(krb5_context context
, krb5_ccache id
,
1211 krb5_const_principal principal
,
1212 const char *name
, krb5_creds
*cred
)
1214 krb5_principal client
;
1215 krb5_error_code ret
;
1218 memset(cred
, 0, sizeof(*cred
));
1220 ret
= krb5_cc_get_principal(context
, id
, &client
);
1225 ret
= krb5_unparse_name(context
, principal
, &pname
);
1230 ret
= krb5_make_principal(context
, &cred
->server
,
1232 KRB5_CONF_NAME
, name
, pname
, NULL
);
1235 krb5_free_principal(context
, client
);
1238 ret
= krb5_copy_principal(context
, client
, &cred
->client
);
1239 krb5_free_principal(context
, client
);
1244 * Return TRUE (non zero) if the principal is a configuration
1245 * principal (generated part of krb5_cc_set_config()). Returns FALSE
1246 * (zero) if not a configuration principal.
1248 * @param context a Keberos context
1249 * @param principal principal to check if it a configuration principal
1251 * @ingroup krb5_ccache
1254 KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL
1255 krb5_is_config_principal(krb5_context context
,
1256 krb5_const_principal principal
)
1258 if (strcmp(principal
->realm
, KRB5_REALM_NAME
) != 0)
1261 if (principal
->name
.name_string
.len
== 0 ||
1262 strcmp(principal
->name
.name_string
.val
[0], KRB5_CONF_NAME
) != 0)
1269 * Store some configuration for the credential cache in the cache.
1270 * Existing configuration under the same name is over-written.
1272 * @param context a Keberos context
1273 * @param id the credential cache to store the data for
1274 * @param principal configuration for a specific principal, if
1275 * NULL, global for the whole cache.
1276 * @param name name under which the configuraion is stored.
1277 * @param data data to store, if NULL, configure is removed.
1279 * @ingroup krb5_ccache
1282 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1283 krb5_cc_set_config(krb5_context context
, krb5_ccache id
,
1284 krb5_const_principal principal
,
1285 const char *name
, krb5_data
*data
)
1287 krb5_error_code ret
;
1290 ret
= build_conf_principals(context
, id
, principal
, name
, &cred
);
1294 /* Remove old configuration */
1295 ret
= krb5_cc_remove_cred(context
, id
, 0, &cred
);
1296 if (ret
&& ret
!= KRB5_CC_NOTFOUND
)
1300 /* not that anyone care when this expire */
1301 cred
.times
.authtime
= time(NULL
);
1302 cred
.times
.endtime
= cred
.times
.authtime
+ 3600 * 24 * 30;
1304 ret
= krb5_data_copy(&cred
.ticket
, data
->data
, data
->length
);
1308 ret
= krb5_cc_store_cred(context
, id
, &cred
);
1312 krb5_free_cred_contents (context
, &cred
);
1317 * Get some configuration for the credential cache in the cache.
1319 * @param context a Keberos context
1320 * @param id the credential cache to store the data for
1321 * @param principal configuration for a specific principal, if
1322 * NULL, global for the whole cache.
1323 * @param name name under which the configuraion is stored.
1324 * @param data data to fetched, free with krb5_data_free()
1326 * @ingroup krb5_ccache
1330 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1331 krb5_cc_get_config(krb5_context context
, krb5_ccache id
,
1332 krb5_const_principal principal
,
1333 const char *name
, krb5_data
*data
)
1335 krb5_creds mcred
, cred
;
1336 krb5_error_code ret
;
1338 memset(&cred
, 0, sizeof(cred
));
1339 krb5_data_zero(data
);
1341 ret
= build_conf_principals(context
, id
, principal
, name
, &mcred
);
1345 ret
= krb5_cc_retrieve_cred(context
, id
, 0, &mcred
, &cred
);
1349 ret
= krb5_data_copy(data
, cred
.ticket
.data
, cred
.ticket
.length
);
1352 krb5_free_cred_contents (context
, &cred
);
1353 krb5_free_cred_contents (context
, &mcred
);
1361 struct krb5_cccol_cursor_data
{
1363 krb5_cc_cache_cursor cursor
;
1367 * Get a new cache interation cursor that will interate over all
1368 * credentials caches independent of type.
1370 * @param context a Keberos context
1371 * @param cursor passed into krb5_cccol_cursor_next() and free with krb5_cccol_cursor_free().
1373 * @return Returns 0 or and error code, see krb5_get_error_message().
1375 * @ingroup krb5_ccache
1378 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1379 krb5_cccol_cursor_new(krb5_context context
, krb5_cccol_cursor
*cursor
)
1381 *cursor
= calloc(1, sizeof(**cursor
));
1382 if (*cursor
== NULL
) {
1383 krb5_set_error_message(context
, ENOMEM
, N_("malloc: out of memory", ""));
1387 (*cursor
)->cursor
= NULL
;
1393 * Get next credential cache from the iteration.
1395 * @param context A Kerberos 5 context
1396 * @param cursor the iteration cursor
1397 * @param cache the returned cursor, pointer is set to NULL on failure
1398 * and a cache on success. The returned cache needs to be freed
1399 * with krb5_cc_close() or destroyed with krb5_cc_destroy().
1400 * MIT Kerberos behavies slightly diffrent and sets cache to NULL
1401 * when all caches are iterated over and return 0.
1403 * @return Return 0 or and error, KRB5_CC_END is returned at the end
1404 * of iteration. See krb5_get_error_message().
1406 * @ingroup krb5_ccache
1410 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1411 krb5_cccol_cursor_next(krb5_context context
, krb5_cccol_cursor cursor
,
1414 krb5_error_code ret
;
1418 while (cursor
->idx
< context
->num_cc_ops
) {
1420 if (cursor
->cursor
== NULL
) {
1421 ret
= krb5_cc_cache_get_first (context
,
1422 context
->cc_ops
[cursor
->idx
]->prefix
,
1429 ret
= krb5_cc_cache_next(context
, cursor
->cursor
, cache
);
1433 krb5_cc_cache_end_seq_get(context
, cursor
->cursor
);
1434 cursor
->cursor
= NULL
;
1435 if (ret
!= KRB5_CC_END
)
1440 if (cursor
->idx
>= context
->num_cc_ops
) {
1441 krb5_set_error_message(context
, KRB5_CC_END
,
1442 N_("Reached end of credential caches", ""));
1450 * End an iteration and free all resources, can be done before end is reached.
1452 * @param context A Kerberos 5 context
1453 * @param cursor the iteration cursor to be freed.
1455 * @return Return 0 or and error, KRB5_CC_END is returned at the end
1456 * of iteration. See krb5_get_error_message().
1458 * @ingroup krb5_ccache
1461 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1462 krb5_cccol_cursor_free(krb5_context context
, krb5_cccol_cursor
*cursor
)
1464 krb5_cccol_cursor c
= *cursor
;
1469 krb5_cc_cache_end_seq_get(context
, c
->cursor
);
1476 * Return the last time the credential cache was modified.
1478 * @param context A Kerberos 5 context
1479 * @param id The credential cache to probe
1480 * @param mtime the last modification time, set to 0 on error.
1482 * @return Return 0 or and error. See krb5_get_error_message().
1484 * @ingroup krb5_ccache
1488 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1489 krb5_cc_last_change_time(krb5_context context
,
1491 krb5_timestamp
*mtime
)
1494 return (*id
->ops
->lastchange
)(context
, id
, mtime
);
1498 * Return the last modfication time for a cache collection. The query
1499 * can be limited to a specific cache type. If the function return 0
1500 * and mtime is 0, there was no credentials in the caches.
1502 * @param context A Kerberos 5 context
1503 * @param type The credential cache to probe, if NULL, all type are traversed.
1504 * @param mtime the last modification time, set to 0 on error.
1506 * @return Return 0 or and error. See krb5_get_error_message().
1508 * @ingroup krb5_ccache
1511 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1512 krb5_cccol_last_change_time(krb5_context context
,
1514 krb5_timestamp
*mtime
)
1516 krb5_cccol_cursor cursor
;
1517 krb5_error_code ret
;
1519 krb5_timestamp t
= 0;
1523 ret
= krb5_cccol_cursor_new (context
, &cursor
);
1527 while (krb5_cccol_cursor_next(context
, cursor
, &id
) == 0 && id
!= NULL
) {
1529 if (type
&& strcmp(krb5_cc_get_type(context
, id
), type
) != 0)
1532 ret
= krb5_cc_last_change_time(context
, id
, &t
);
1533 krb5_cc_close(context
, id
);
1540 krb5_cccol_cursor_free(context
, &cursor
);
1545 * Return a friendly name on credential cache. Free the result with krb5_xfree().
1547 * @return Return an error code or 0, see krb5_get_error_message().
1549 * @ingroup krb5_ccache
1552 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1553 krb5_cc_get_friendly_name(krb5_context context
,
1557 krb5_error_code ret
;
1560 ret
= krb5_cc_get_config(context
, id
, NULL
, "FriendlyName", &data
);
1562 krb5_principal principal
;
1563 ret
= krb5_cc_get_principal(context
, id
, &principal
);
1566 ret
= krb5_unparse_name(context
, principal
, name
);
1567 krb5_free_principal(context
, principal
);
1569 ret
= asprintf(name
, "%.*s", (int)data
.length
, (char *)data
.data
);
1570 krb5_data_free(&data
);
1573 krb5_set_error_message(context
, ret
, N_("malloc: out of memory", ""));
1582 * Set the friendly name on credential cache.
1584 * @return Return an error code or 0, see krb5_get_error_message().
1586 * @ingroup krb5_ccache
1589 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1590 krb5_cc_set_friendly_name(krb5_context context
,
1596 data
.data
= rk_UNCONST(name
);
1597 data
.length
= strlen(name
);
1599 return krb5_cc_set_config(context
, id
, NULL
, "FriendlyName", &data
);
1603 * Get the lifetime of the initial ticket in the cache
1605 * Get the lifetime of the initial ticket in the cache, if the initial
1606 * ticket was not found, the error code KRB5_CC_END is returned.
1608 * @param context A Kerberos 5 context.
1609 * @param id a credential cache
1610 * @param t the relative lifetime of the initial ticket
1612 * @return Return an error code or 0, see krb5_get_error_message().
1614 * @ingroup krb5_ccache
1617 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
1618 krb5_cc_get_lifetime(krb5_context context
, krb5_ccache id
, time_t *t
)
1620 krb5_cc_cursor cursor
;
1621 krb5_error_code ret
;
1628 ret
= krb5_cc_start_seq_get(context
, id
, &cursor
);
1632 while ((ret
= krb5_cc_next_cred(context
, id
, &cursor
, &cred
)) == 0) {
1633 if (cred
.flags
.b
.initial
) {
1634 if (now
< cred
.times
.endtime
)
1635 *t
= cred
.times
.endtime
- now
;
1636 krb5_free_cred_contents(context
, &cred
);
1639 krb5_free_cred_contents(context
, &cred
);
1642 krb5_cc_end_seq_get(context
, id
, &cursor
);
1648 * Set the time offset betwen the client and the KDC
1650 * If the backend doesn't support KDC offset, use the context global setting.
1652 * @param context A Kerberos 5 context.
1653 * @param id a credential cache
1654 * @param offset the offset in seconds
1656 * @return Return an error code or 0, see krb5_get_error_message().
1658 * @ingroup krb5_ccache
1662 krb5_cc_set_kdc_offset(krb5_context context
, krb5_ccache id
, krb5_deltat offset
)
1664 if (id
->ops
->set_kdc_offset
== NULL
) {
1665 context
->kdc_sec_offset
= offset
;
1666 context
->kdc_usec_offset
= 0;
1669 return (*id
->ops
->set_kdc_offset
)(context
, id
, offset
);
1673 * Get the time offset betwen the client and the KDC
1675 * If the backend doesn't support KDC offset, use the context global setting.
1677 * @param context A Kerberos 5 context.
1678 * @param id a credential cache
1679 * @param offset the offset in seconds
1681 * @return Return an error code or 0, see krb5_get_error_message().
1683 * @ingroup krb5_ccache
1687 krb5_cc_get_kdc_offset(krb5_context context
, krb5_ccache id
, krb5_deltat
*offset
)
1689 if (id
->ops
->get_kdc_offset
== NULL
) {
1690 *offset
= context
->kdc_sec_offset
;
1693 return (*id
->ops
->get_kdc_offset
)(context
, id
, offset
);