October 19, 2005 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

```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

    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)