From: John Kohl <jtkohl@mit.edu>
Date: Mon, 4 Jun 1990 14:01:30 +0000 (+0000)
Subject: add functions from librc.spec
X-Git-Tag: krb5-1.0-alpha2~417
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=11e5eee5b940593ae2dfbafc55fbc245f9628630;p=krb5.git

add functions from librc.spec

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@994 dc483132-0cff-0310-8789-dd5450dbe970
---

diff --git a/doc/api/rcache.tex b/doc/api/rcache.tex
index 06cf1d98c..5d49116cb 100644
--- a/doc/api/rcache.tex
+++ b/doc/api/rcache.tex
@@ -2,3 +2,145 @@ The replay cache functions deal with verifying that AP_REQ's do not
 contain duplicate authenticators; the storage must be non-volatile for
 the site-determined validity period of authenticators.
 
+Each replay cache has a string ``name'' associated with it.  The use of
+this name is dependent on the underlying caching strategy (for
+file-based things, it would be a cache file name).  The
+caching strategy should use non-volatile storage so that replay
+integrity can be maintained across system failures.
+
+\subsubsection{Per-type functions}
+The following entry points must be implemented for each type of
+credentials cache.
+
+\begin{funcdecl}{krb5_rc_initialize}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\funcarg{krb5_deltat}{auth_lifespan}
+\end{funcdecl}
+
+Creates/refreshes the replay cache identified by \funcparam{id} and sets its
+authenticator lifespan to \funcparam{auth_lifespan}.  If the 
+replay cache already exists, its contents are destroyed.
+
+Errors: permission errors, system errors
+
+\begin{funcdecl}{krb5_rc_recover}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+Attempts to recover the replay cache \funcparam{id}, (presumably after a
+system crash or server restart).
+
+Errors: error indicating that no cache was found to recover
+
+\begin{funcdecl}{krb5_rc_destroy}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+
+Destroys the replay cache \funcparam{id}.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+Errors: permission errors.
+
+\begin{funcdecl}{krb5_rc_close}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+
+Closes the replay cache \funcparam{id}, invalidates \funcparam{id},
+and releases any other resources acquired during use of the replay cache.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+Errors: permission errors
+
+\begin{funcdecl}{krb5_rc_store}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\funcarg{krb5_tkt_authent *}{tkt_auth}
+\end{funcdecl}
+Stores \funcparam{tkt_auth} in the replay cache \funcparam{id}.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+Returns KRB5KRB_AP_ERR_REPEAT if \funcparam{tkt_auth} is already in the
+cache.  May also return permission errors, storage failure errors.
+
+\begin{funcdecl}{krb5_rc_expunge}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+Removes all expired replay information (i.e. those entries which are
+older than then authenticator lifespan of the cache) from the cache
+\funcparam{id}.  Requires that \funcparam{id} identifies a valid replay
+cache.
+
+Errors: permission errors.
+
+\begin{funcdecl}{krb5_rc_get_lifespan}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\funcout
+\funcarg{krb5_deltat *}{auth_lifespan}
+\end{funcdecl}
+Fills in \funcparam{auth_lifespan} with the lifespan of
+the cache \funcparam{id}.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+\begin{funcdecl}{krb5_rc_resolve}{krb5_error_code}{\funcinout}
+\funcarg{krb5_rcache}{id}
+\funcin
+\funcarg{char *}{name}
+\end{funcdecl}
+
+Initializes private data attached to \funcparam{id}.  This function MUST
+be called before the other per-replay cache functions.
+
+Requires that \funcparam{id} points to allocated space, with an
+initialized \funcparam{id{\ptsto}ops} field.
+
+Returns:  allocation errors.
+
+
+\begin{funcdecl}{krb5_rc_get_name}{char *}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+
+Returns the name (excluding the type) of the rcache \funcparam{id}.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+\subsubsection{Glue functions}
+The following functions are implemented in the base library and serve to
+glue together the various types of replay caches.
+
+\begin{funcdecl}{krb5_rc_resolve_full}{krb5_error_code}{\funcinout}
+\funcarg{krb5_rcache *}{id}
+\funcin
+\funcarg{char *}{string_name}
+\end{funcdecl}
+
+\funcparam{id} is filled in to identify a replay cache which
+corresponds to the name in \funcparam{string_name}.  The cache is not opened.
+Requires that \funcparam{string_name} be of the form ``type:residual''
+and that ``type'' is a type known to the library.
+
+Errors: error if cannot resolve name.
+
+\begin{funcdecl}{krb5_rc_register_type}{krb5_error_code}{\funcin}
+\funcarg{krb5_rc_ops *}{ops}
+\end{funcdecl}
+Adds a new replay cache type implemented and identified by
+\funcparam{ops} to the set recognized by
+\funcname{krb5_rc_resolve}.  Requires that a ticket cache type named
+\funcparam{ops{\ptsto}prefix} is not yet known.
+
+
+\begin{funcdecl}{krb5_rc_default_name}{char *}{\funcvoid}
+\end{funcdecl}
+Returns  the name of the default replay cache; this may be equivalent to
+\funcnamenoparens{getenv}({\tt "KRB5RCACHE"}) with an appropriate fallback.
+
+\begin{funcdecl}{krb5_rc_default_type}{char *}{\funcvoid}
+\end{funcdecl}
+
+Returns the type of the default replay cache.
+
+\begin{funcdecl}{krb5_rc_default}{krb5_error_code}{\funcinout}
+\funcarg{krb5_rcache *}{id}
+\end{funcdecl}
+Equivalent to \funcnamenoparens{krb5_rc_resolve_full}(\funcparam{id},
+\funcnamenoparens{strcat}(\funcnamenoparens{strcat}(\funcname{krb5_rc_default_type},``:''),
+\funcname{krb5_rc_default_name})) (except of course you can't do the
+strcat's with the return values\ldots).
diff --git a/doc/implement/rcache-i.tex b/doc/implement/rcache-i.tex
index 06cf1d98c..5d49116cb 100644
--- a/doc/implement/rcache-i.tex
+++ b/doc/implement/rcache-i.tex
@@ -2,3 +2,145 @@ The replay cache functions deal with verifying that AP_REQ's do not
 contain duplicate authenticators; the storage must be non-volatile for
 the site-determined validity period of authenticators.
 
+Each replay cache has a string ``name'' associated with it.  The use of
+this name is dependent on the underlying caching strategy (for
+file-based things, it would be a cache file name).  The
+caching strategy should use non-volatile storage so that replay
+integrity can be maintained across system failures.
+
+\subsubsection{Per-type functions}
+The following entry points must be implemented for each type of
+credentials cache.
+
+\begin{funcdecl}{krb5_rc_initialize}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\funcarg{krb5_deltat}{auth_lifespan}
+\end{funcdecl}
+
+Creates/refreshes the replay cache identified by \funcparam{id} and sets its
+authenticator lifespan to \funcparam{auth_lifespan}.  If the 
+replay cache already exists, its contents are destroyed.
+
+Errors: permission errors, system errors
+
+\begin{funcdecl}{krb5_rc_recover}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+Attempts to recover the replay cache \funcparam{id}, (presumably after a
+system crash or server restart).
+
+Errors: error indicating that no cache was found to recover
+
+\begin{funcdecl}{krb5_rc_destroy}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+
+Destroys the replay cache \funcparam{id}.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+Errors: permission errors.
+
+\begin{funcdecl}{krb5_rc_close}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+
+Closes the replay cache \funcparam{id}, invalidates \funcparam{id},
+and releases any other resources acquired during use of the replay cache.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+Errors: permission errors
+
+\begin{funcdecl}{krb5_rc_store}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\funcarg{krb5_tkt_authent *}{tkt_auth}
+\end{funcdecl}
+Stores \funcparam{tkt_auth} in the replay cache \funcparam{id}.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+Returns KRB5KRB_AP_ERR_REPEAT if \funcparam{tkt_auth} is already in the
+cache.  May also return permission errors, storage failure errors.
+
+\begin{funcdecl}{krb5_rc_expunge}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+Removes all expired replay information (i.e. those entries which are
+older than then authenticator lifespan of the cache) from the cache
+\funcparam{id}.  Requires that \funcparam{id} identifies a valid replay
+cache.
+
+Errors: permission errors.
+
+\begin{funcdecl}{krb5_rc_get_lifespan}{krb5_error_code}{\funcin}
+\funcarg{krb5_rcache}{id}
+\funcout
+\funcarg{krb5_deltat *}{auth_lifespan}
+\end{funcdecl}
+Fills in \funcparam{auth_lifespan} with the lifespan of
+the cache \funcparam{id}.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+\begin{funcdecl}{krb5_rc_resolve}{krb5_error_code}{\funcinout}
+\funcarg{krb5_rcache}{id}
+\funcin
+\funcarg{char *}{name}
+\end{funcdecl}
+
+Initializes private data attached to \funcparam{id}.  This function MUST
+be called before the other per-replay cache functions.
+
+Requires that \funcparam{id} points to allocated space, with an
+initialized \funcparam{id{\ptsto}ops} field.
+
+Returns:  allocation errors.
+
+
+\begin{funcdecl}{krb5_rc_get_name}{char *}{\funcin}
+\funcarg{krb5_rcache}{id}
+\end{funcdecl}
+
+Returns the name (excluding the type) of the rcache \funcparam{id}.
+Requires that \funcparam{id} identifies a valid replay cache.
+
+\subsubsection{Glue functions}
+The following functions are implemented in the base library and serve to
+glue together the various types of replay caches.
+
+\begin{funcdecl}{krb5_rc_resolve_full}{krb5_error_code}{\funcinout}
+\funcarg{krb5_rcache *}{id}
+\funcin
+\funcarg{char *}{string_name}
+\end{funcdecl}
+
+\funcparam{id} is filled in to identify a replay cache which
+corresponds to the name in \funcparam{string_name}.  The cache is not opened.
+Requires that \funcparam{string_name} be of the form ``type:residual''
+and that ``type'' is a type known to the library.
+
+Errors: error if cannot resolve name.
+
+\begin{funcdecl}{krb5_rc_register_type}{krb5_error_code}{\funcin}
+\funcarg{krb5_rc_ops *}{ops}
+\end{funcdecl}
+Adds a new replay cache type implemented and identified by
+\funcparam{ops} to the set recognized by
+\funcname{krb5_rc_resolve}.  Requires that a ticket cache type named
+\funcparam{ops{\ptsto}prefix} is not yet known.
+
+
+\begin{funcdecl}{krb5_rc_default_name}{char *}{\funcvoid}
+\end{funcdecl}
+Returns  the name of the default replay cache; this may be equivalent to
+\funcnamenoparens{getenv}({\tt "KRB5RCACHE"}) with an appropriate fallback.
+
+\begin{funcdecl}{krb5_rc_default_type}{char *}{\funcvoid}
+\end{funcdecl}
+
+Returns the type of the default replay cache.
+
+\begin{funcdecl}{krb5_rc_default}{krb5_error_code}{\funcinout}
+\funcarg{krb5_rcache *}{id}
+\end{funcdecl}
+Equivalent to \funcnamenoparens{krb5_rc_resolve_full}(\funcparam{id},
+\funcnamenoparens{strcat}(\funcnamenoparens{strcat}(\funcname{krb5_rc_default_type},``:''),
+\funcname{krb5_rc_default_name})) (except of course you can't do the
+strcat's with the return values\ldots).