From b310c90b693e962c147f8863d9aec96423d949ba Mon Sep 17 00:00:00 2001
From: John Kohl <jtkohl@mit.edu>
Date: Mon, 4 Jun 1990 10:13:04 +0000
Subject: [PATCH] first-cut (not proofread) ccache funcs

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@988 dc483132-0cff-0310-8789-dd5450dbe970
---
 doc/api/ccache.tex         | 224 +++++++++++++++++++++++++++++++++++++
 doc/implement/ccache-i.tex | 224 +++++++++++++++++++++++++++++++++++++
 2 files changed, 448 insertions(+)

diff --git a/doc/api/ccache.tex b/doc/api/ccache.tex
index 33addc51d..110f42987 100644
--- a/doc/api/ccache.tex
+++ b/doc/api/ccache.tex
@@ -3,3 +3,227 @@ 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_error_code}{krb5_cc_resolve_internal}{\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_error_code}{krb5_cc_gennew_internal}{\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}.
+Requires that the credentials cache exist.
+
+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} identify a valid credentials cache.
+
+
+\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} identify 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} identify 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} identify 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} identify 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} identify 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} identify 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} identify 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}.
+
+
+\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
+{\funcfont getenv}({\tt "KRB5CCACHE"}) with an appropriate fallback.
+
+\begin{funcdecl}{krb5_cc_default }{krb5_error_code}{\funcout}
+\funcarg{krb5_ccache *}{ccache}
+\end{funcdecl}
+
+Equivalent to {\funcfont krb5_cc_resolve}({\funcfont
+krb5_cc_default_name}(), \funcparam{ccache}).
+
diff --git a/doc/implement/ccache-i.tex b/doc/implement/ccache-i.tex
index 33addc51d..110f42987 100644
--- a/doc/implement/ccache-i.tex
+++ b/doc/implement/ccache-i.tex
@@ -3,3 +3,227 @@ 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_error_code}{krb5_cc_resolve_internal}{\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_error_code}{krb5_cc_gennew_internal}{\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}.
+Requires that the credentials cache exist.
+
+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} identify a valid credentials cache.
+
+
+\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} identify 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} identify 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} identify 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} identify 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} identify 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} identify 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} identify 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}.
+
+
+\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
+{\funcfont getenv}({\tt "KRB5CCACHE"}) with an appropriate fallback.
+
+\begin{funcdecl}{krb5_cc_default }{krb5_error_code}{\funcout}
+\funcarg{krb5_ccache *}{ccache}
+\end{funcdecl}
+
+Equivalent to {\funcfont krb5_cc_resolve}({\funcfont
+krb5_cc_default_name}(), \funcparam{ccache}).
+
-- 
2.26.2