KRB5_CCACHE(3)

NAME
krb5_ccache, krb5_cc_cursor, krb5_cc_ops, krb5_fcc_ops, krb5_mcc_ops, krb5_cc_clear_mcred, krb5_cc_close, krb5_cc_copy_cache, krb5_cc_default, krb5_cc_default_name, krb5_cc_destroy, krb5_cc_end_seq_get, krb5_cc_gen_new, krb5_cc_get_full_name, krb5_cc_get_name, krb5_cc_get_ops, krb5_cc_get_prefix_ops, krb5_cc_get_principal, krb5_cc_get_type, krb5_cc_get_version, krb5_cc_initialize, krb5_cc_next_cred, krb5_cc_next_cred_match, krb5_cc_new_unique, krb5_cc_register, krb5_cc_remove_cred, krb5_cc_resolve, krb5_cc_retrieve_cred, krb5_cc_set_default_name, krb5_cc_set_flags, krb5_cc_start_seq_get, krb5_cc_store_cred - mange credential cache

LIBRARY
Kerberos 5 Library (libkrb5, -lkrb5)

SYNOPSIS
#include <krb5.h>

struct krb5_ccache;

struct krb5_cc_cursor;

struct krb5_cc_ops;

struct krb5_cc_ops *krb5_fcc_ops;

struct krb5_cc_ops *krb5_mcc_ops;

void
krb5_cc_clear_mcred(krb5_creds *mcred);
krb5_error_code
krb5_cc_close(krb5_context context, krb5_ccache id);
krb5_error_code
krb5_cc_copy_cache(krb5_context context, const krb5_ccache from, krb5_ccache to);
krb5_error_code
krb5_cc_default(krb5_context context, krb5_ccache *id);
const char *
krb5_cc_default_name(krb5_context context);
krb5_error_code
krb5_cc_destroy(krb5_context context, krb5_ccache id);
krb5_error_code
krb5_cc_end_seq_get(krb5_context context, const krb5_ccache id, krb5_cc_cursor *cursor);
krb5_error_code
krb5_cc_gen_new(krb5_context context, const krb5_cc_ops *ops, krb5_ccache *id);
krb5_error_code
krb5_cc_get_full_name(krb5_context context, krb5_ccache id, char **str);
const char *
krb5_cc_get_name(krb5_context context, krb5_ccache id);
krb5_error_code
krb5_cc_get_principal(krb5_context context, krb5_ccache id, krb5_principal *principal);
const char *
krb5_cc_get_type(krb5_context context, krb5_ccache id);
const krb5_cc_ops *
krb5_cc_get_ops(krb5_context context, krb5_ccache id);
const krb5_cc_ops *
krb5_cc_get_prefix_ops(krb5_context context, const char *prefix);
krb5_error_code
krb5_cc_get_version(krb5_context context, const krb5_ccache id);
krb5_error_code
krb5_cc_initialize(krb5_context context, krb5_ccache id, krb5_principal primary_principal);
krb5_error_code
krb5_cc_register(krb5_context context, const krb5_cc_ops *ops, krb5_boolean override);
krb5_error_code
krb5_cc_resolve(krb5_context context, const char *name, krb5_ccache *id);
krb5_error_code
krb5_cc_retrieve_cred(krb5_context context, krb5_ccache id, krb5_flags whichfields, const krb5_creds *mcreds, krb5_creds *creds);
krb5_error_code
krb5_cc_remove_cred(krb5_context context, krb5_ccache id, krb5_flags which, krb5_creds *cred);
krb5_error_code
krb5_cc_set_default_name(krb5_context context, const char *name);
krb5_error_code
krb5_cc_start_seq_get(krb5_context context, const krb5_ccache id, krb5_cc_cursor *cursor);
krb5_error_code
krb5_cc_store_cred(krb5_context context, krb5_ccache id, krb5_creds *creds);
krb5_error_code
krb5_cc_set_flags(krb5_context context, krb5_cc_set_flags id, krb5_flags flags);
krb5_error_code
krb5_cc_next_cred(krb5_context context, const krb5_ccache id, krb5_cc_cursor *cursor, krb5_creds *creds);
krb5_error_code
krb5_cc_next_cred_match(krb5_context context, const krb5_ccache id, krb5_cc_cursor *cursor, krb5_creds *creds, krb5_flags whichfields, const krb5_creds *mcreds);
krb5_error_code
krb5_cc_new_unique(krb5_context context, const char *type, const char *hint, krb5_ccache *id);

DESCRIPTION
The krb5_ccache structure holds a Kerberos credential cache.

The krb5_cc_cursor structure holds current position in a credential cache when iterating over the cache.

The krb5_cc_ops structure holds a set of operations that can me preformed on a credential cache.

There is no component inside krb5_ccache, krb5_cc_cursor nor krb5_fcc_ops that is directly referable.

The krb5_creds holds a Kerberos credential, see manpage for krb5_creds(3).

krb5_cc_default_name() and krb5_cc_set_default_name() gets and sets the default name for the context.

krb5_cc_default() opens the default credential cache in id. Return 0 or an error code.

krb5_cc_gen_new() generates a new credential cache of type ops in id. Return 0 or an error code. The Heimdal version of this function also runs krb5_cc_initialize() on the credential cache, but since the MIT version doesn't, portable code must call krb5_cc_initialize.

krb5_cc_new_unique() generates a new unique credential cache of type in id. If type is NULL, the library chooses the default credential cache type. The supplied hint (that can be NULL) is a string that the credential cache type can use to base the name of the credential on, this is to make it easier for the user to differentiate the credentials. The returned credential cache id should be freed using krb5_cc_close() or krb5_cc_destroy(). Returns 0 or an error code.

krb5_cc_resolve() finds and allocates a credential cache in id from the specification in residual. If the credential cache name doesn't contain any colon (:), interpret it as a file name. Return 0 or an error code.

krb5_cc_initialize() creates a new credential cache in id for primary_principal. Return 0 or an error code.

krb5_cc_close() stops using the credential cache id and frees the related resources. Return 0 or an error code. krb5_cc_destroy() removes the credential cache and closes (by calling krb5_cc_close()) id. Return 0 or an error code.

krb5_cc_copy_cache() copys the contents of from to to.

krb5_cc_get_full_name() returns the complete resolvable name of the credential cache id in str. str should be freed with free(3). Returns 0 or an error, on error *str is set to NULL.

krb5_cc_get_name() returns the name of the credential cache id.

krb5_cc_get_principal() returns the principal of id in principal. Return 0 or an error code.

krb5_cc_get_type() returns the type of the credential cache id.

krb5_cc_get_ops() returns the ops of the credential cache id.

krb5_cc_get_version() returns the version of id.

krb5_cc_register() Adds a new credential cache type with operations ops, overwriting any existing one if override. Return an error code or 0.

krb5_cc_get_prefix_ops() Get the cc ops that is registered in context to handle the prefix. Returns NULL if ops not found.

krb5_cc_remove_cred() removes the credential identified by (cred, which) from id.

krb5_cc_store_cred() stores creds in the credential cache id. Return 0 or an error code.

krb5_cc_set_flags() sets the flags of id to flags.

krb5_cc_clear_mcred() clears the mcreds argument so it is reset and can be used with krb5_cc_retrieve_cred.

krb5_cc_retrieve_cred(), retrieves the credential identified by mcreds (and whichfields) from id in creds. creds should be freed using krb5_free_cred_contents(). Return 0 or an error code.

krb5_cc_start_seq_get() initiates the krb5_cc_cursor structure to be used for iteration over the credential cache.

krb5_cc_next_cred() retrieves the next cred pointed to by (id, cursor) in creds, and advance cursor. Return 0 or an error code.

krb5_cc_next_cred_match() is similar to krb5_cc_next_cred() except that it will only return creds matching whichfields and mcreds (as interpreted by krb5_compare_creds(3).)

krb5_cc_end_seq_get() Destroys the cursor cursor.

EXAMPLE
This is a minimalistic version of klist.

    #include <krb5.h>
    int
    main (int argc, char **argv)
    {
        krb5_context context;
        krb5_cc_cursor cursor;
        krb5_error_code ret;
        krb5_ccache id;
        krb5_creds creds;
        if (krb5_init_context (&context) != 0)
    	errx(1, "krb5_context");
        ret = krb5_cc_default (context, &id);
        if (ret)
    	krb5_err(context, 1, ret, "krb5_cc_default");
        ret = krb5_cc_start_seq_get(context, id, &cursor);
        if (ret)
    	krb5_err(context, 1, ret, "krb5_cc_start_seq_get");
        while((ret = krb5_cc_next_cred(context, id, &cursor, &creds)) == 0){
            char *principal;
    	krb5_unparse_name_short(context, creds.server, &principal);
    	printf("principal: %s\n", principal);
    	free(principal);
    	krb5_free_cred_contents (context, &creds);
        }
        ret = krb5_cc_end_seq_get(context, id, &cursor);
        if (ret)
    	krb5_err(context, 1, ret, "krb5_cc_end_seq_get");
        krb5_cc_close(context, id);
        krb5_free_context(context);
        return 0;
    }

SEE ALSO
krb5(3), krb5.conf(5), kerberos(8)