The credentials cache functions (some of which are macros which call to
specific types of credentials caches) deal with storing credentials
(tickets, session keys, and other identifying information) in a
semi-permanent store for later use by different programs.

\subsubsection{Per-type functions}
The following entry points must be implemented for each type of
credentials cache; however, applications are not expected to have a need
to call either \funcname{krb5_cc_resolve_internal} or
\funcname{krb5_cc_gennew_internal}.


\begin{funcdecl}{krb5_cc_resolve_internal}{krb5_error_code}{\funcout}
\funcarg{krb5_ccache *}{id}
\funcin
\funcarg{char *}{residual}
\end{funcdecl}

Creates a credentials cache named by \funcparam{residual} (which may be
interpreted differently by each type of ccache).  The cache is not
opened, but the cache name is held in reserve.

\begin{funcdecl}{krb5_cc_gennew_internal}{krb5_error_code}{\funcout}
\funcarg{krb5_ccache *}{id}
\end{funcdecl}

Creates a new credentials cache whose name is guaranteed to be
unique.  The cache is not opened. \funcparam{*id} is
filled in with a \datatype{krb5_ccache} which may be used in subsequent
calls to ccache functions.

\begin{funcdecl}{krb5_cc_initialize}{krb5_error_code}{\funcinout}
\funcarg{krb5_ccache}{id}
\funcin
\funcarg{krb5_principal}{primary_principal}
\end{funcdecl}

Creates/refreshes a credentials cache identified by \funcparam{id} with
primary principal set to \funcparam{primary_principal}.
If the credentials cache already exists, its contents are destroyed.

Errors:  permission errors, system errors.

Modifies: cache identified by \funcparam{id}.

\begin{funcdecl}{krb5_cc_destroy}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{id}
\end{funcdecl}

Destroys the credentials cache identified by \funcparam{id}, invalidates
\funcparam{id}, and releases any other resources acquired during use of
the credentials cache.  Requires that \funcparam{id} identifies a valid
credentials cache.  After return, \funcparam{id} must not be used unless
it is first reinitialized.

Errors:  permission errors.

\begin{funcdecl}{krb5_cc_close}{krb5_error_code}{\funcinout}
\funcarg{krb5_ccache}{id}
\end{funcdecl}

Closes the credentials cache \funcparam{id}, invalidates \funcparam{id},
and releases any other resources acquired during use of the credentials
cache.  Requires that \funcparam{id} identifies a valid credentials
cache.  After return, \funcparam{id} must not be used unless it is first
reinitialized.


\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{id}
\funcarg{krb5_credentials *}{creds}
\end{funcdecl}

Stores \funcparam{creds} in the cache \funcparam{id}, tagged with
\funcparam{creds{\ptsto}client}.
Requires that \funcparam{id} identifies a valid credentials cache.

Errors: permission errors, storage failure errors.

\begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{id}
\funcarg{krb5_flags}{whichfields}
\funcarg{krb5_credentials *}{mcreds}
\funcout
\funcarg{krb5_credentials *}{creds}
\end{funcdecl}

Searches the cache \funcparam{id} for credentials matching
\funcparam{mcreds}.  The fields which are to be matched are specified by
set bits in \funcparam{whichfields}, and always include the principal
name \funcparam{mcreds{\ptsto}server}.
Requires that \funcparam{id} identifies a valid credentials cache.

If at least one match is found, one of the matching credentials is
returned in \funcparam{*creds}. XXX free the return creds?

Errors: error code if no matches found.

\begin{funcdecl}{krb5_cc_get_principal}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{id}
\funcarg{krb5_principal *}{principal}
\end{funcdecl}

Retrieves the primary principal of the credentials cache (as
set by the \funcname{krb5_cc_initialize} request)
The primary principal is filled into \funcparam{*principal}; the caller
should release this memory by calling \funcname{krb5_free_principal} on
\funcparam{*principal} when finished.

Requires that \funcparam{id} identifies a valid credentials cache.

\begin{funcdecl}{krb5_cc_start_seq_get}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{id}
\funcout
\funcarg{krb5_cc_cursor *}{cursor}
\end{funcdecl}

Prepares to sequentially read every set of cached credentials.
Requires that \funcparam{id} identifies a valid credentials cache opened by
\funcname{krb5_cc_open}.
\funcparam{cursor} is filled in with a cursor to be used in calls to
\funcname{krb5_cc_next_cred}.

\begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{id}
\funcout
\funcarg{krb5_credentials *}{creds}
\funcinout
\funcarg{krb5_cc_cursor *}{cursor}
\end{funcdecl}

Fetches the next entry from \funcparam{id}, returning its values in
\funcparam{*creds}, and updates \funcparam{*cursor} for the next request.
Requires that \funcparam{id} identifies a valid credentials cache and
\funcparam{*cursor} be a cursor returned by
\funcname{krb5_cc_start_seq_get} or a subsequent call to
\funcname{krb5_cc_next_cred}.

Errors: error code if no more cache entries.

\begin{funcdecl}{krb5_cc_end_seq_get}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{id}
\funcarg{krb5_cc_cursor *}{cursor}
\end{funcdecl}

Finishes sequential processing mode and invalidates \funcparam{*cursor}.
\funcparam{*cursor} must never be re-used after this call.

Requires that \funcparam{id} identifies a valid credentials cache and
\funcparam{*cursor} be a cursor returned by
\funcname{krb5_cc_start_seq_get} or a subsequent call to
\funcname{krb5_cc_next_cred}.

Errors: may return error code if \funcparam{*cursor} is invalid.


\begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{id}
\funcarg{krb5_flags}{which}
\funcarg{krb5_credentials *}{cred}
\end{funcdecl}

Removes any credentials from \funcparam{id} which match the principal
name {cred{\ptsto}server} and the fields in \funcparam{cred} masked by
\funcparam{which}.
Requires that \funcparam{id} identifies a valid credentials cache.

Errors: returns error code if nothing matches; returns error code if
couldn't delete.

\begin{funcdecl}{krb5_cc_set_flags}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{id}
\funcarg{krb5_flags}{flags}
\end{funcdecl}

Sets the flags on the cache \funcparam{id} to \funcparam{flags}.  Useful
flags are defined in {\tt <krb5/ccache.h>}.


\subsubsection{Glue functions}
The following functions are implemented in the base library and serve to
glue together the various types of credentials caches.


\begin{funcdecl}{krb5_cc_resolve}{krb5_error_code}{\funcin}
\funcarg{char *}{string_name}
\funcout
\funcarg{krb5_ccache *}{id}
\end{funcdecl}

Fills in \funcparam{id} with a ccache identifier which corresponds to
the name in \funcparam{string_name}.  The cache is left unopened.

Requires that \funcparam{string_name} be of the form ``type:residual'' and
``type'' is a type known to the library.

\begin{funcdecl}{krb5_cc_generate_new}{krb5_error_code}{\funcin}
\funcarg{krb5_cc_ops *}{ops}
\funcout
\funcarg{krb5_ccache *}{id}
\end{funcdecl}


Fills in \funcparam{id} with a unique ccache identifier of a type defined by
\funcparam{ops}.  The cache is left unopened.

\begin{funcdecl}{krb5_cc_register}{krb5_error_code}{\funcin}
\funcarg{krb5_cc_ops *}{ops}
\funcarg{krb5_boolean}{override}
\end{funcdecl}

Adds a new cache type identified and implemented by \funcparam{ops} to
the set recognized by \funcname{krb5_cc_resolve}.
If \funcparam{override} is FALSE, a ticket cache type named
\funcparam{ops{\ptsto}prefix} must not be known.

\begin{funcdecl}{krb5_cc_get_name}{char *}{\funcin}
\funcarg{krb5_ccache}{id}
\end{funcdecl}

Returns the name of the ccache denoted by \funcparam{id}.

\begin{funcdecl}{krb5_cc_default_name}{char *}{\funcvoid}
\end{funcdecl}

Returns the name of the default credentials cache; this may be equivalent to
\funcnamenoparens{getenv}({\tt "KRB5CCACHE"}) with an appropriate fallback.

\begin{funcdecl}{krb5_cc_default}{krb5_error_code}{\funcout}
\funcarg{krb5_ccache *}{ccache}
\end{funcdecl}

Equivalent to
\funcnamenoparens{krb5_cc_resolve}(\funcname{krb5_cc_default_name},
\funcparam{ccache}).