doc/implement/rcache-i.tex

   1 The replay cache functions deal with verifying that AP_REQ's do not
   2 contain duplicate authenticators; the storage must be non-volatile for
   3 the site-determined validity period of authenticators.
   4
   5 Each replay cache has a string {\bf name} associated with it.  The use of
   6 this name is dependent on the underlying caching strategy (for
   7 file-based things, it would be a cache file name).  The
   8 caching strategy should use non-volatile storage so that replay
   9 integrity can be maintained across system failures.
  10
  11 \subsubsection{The krb5_rc_ops structure}
  12 In order to implement a new replay cache type, the programmer should
  13 declare a {\bf krb5_rc_ops} structure, and fill in the elements of the
  14 structure appropriately, by implementing each of the replay cache
  15 functions for the new replay cache type.
  16
  17 The prefix element specifies the prefix {bf name} of the the new replay
  18 cache type.  For example, if the prefix {\bf name} is ``dfl'', then if the
  19 program calls \funcname{krb5_rc_resolve} with a credential cache name
  20 such as ``dfl:host'', then \funcname{krb5_rc_resolve}
  21 will call the resolve function (as defined by the {\bf krb5_rc_ops}
  22 structure where the prefix element is ``dfl'') and pass it the
  23 argument ``host''.
  24
  25 Before a new replay cache type can be recognized by
  26 \funcname{krb5_rc_resolve}, it must be registered with the Kerberos
  27 library by calling \funcname{krb5_rc_register}.
  28
  29 \begin{verbatim}
  30 typedef struct _krb5_rc_ops {
  31     char *type;
  32     krb5_error_code (*init)((krb5_rcache,krb5_deltat));
  33     krb5_error_code (*recover)((krb5_rcache));
  34     krb5_error_code (*destroy)((krb5_rcache));
  35     krb5_error_code (*close)((krb5_rcache));
  36     krb5_error_code (*store)((krb5_rcache,krb5_donot_replay *));
  37     krb5_error_code (*expunge)((krb5_rcache));
  38     krb5_error_code (*get_span)((krb5_rcache,krb5_deltat *));
  39     char *(*get_name)((krb5_rcache));
  40     krb5_error_code (*resolve)((krb5_rcache, char *));
  41 } krb5_rc_ops;
  42 \end{verbatim}
  43
  44
  45 \subsubsection{Per-type functions}
  46 The following entry points must be implemented for each type of
  47 replay cache.
  48
  49 \begin{funcdecl}{init}{krb5_error_code}{\funcin}
  50 \funcarg{krb5_rcache}{id}
  51 \funcarg{krb5_deltat}{auth_lifespan}
  52 \end{funcdecl}
  53
  54 Creates/refreshes the replay cache identified by \funcparam{id} and sets its
  55 authenticator lifespan to \funcparam{auth_lifespan}.  If the
  56 replay cache already exists, its contents are destroyed.
  57
  58 %Errors: permission errors, system errors
  59
  60 \begin{funcdecl}{recover}{krb5_error_code}{\funcin}
  61 \funcarg{krb5_rcache}{id}
  62 \end{funcdecl}
  63 Attempts to recover the replay cache \funcparam{id}, (presumably after a
  64 system crash or server restart).
  65
  66 %Errors: error indicating that no cache was found to recover
  67
  68 \begin{funcdecl}{destroy}{krb5_error_code}{\funcin}
  69 \funcarg{krb5_rcache}{id}
  70 \end{funcdecl}
  71
  72 Destroys the replay cache \funcparam{id}.
  73 Requires that \funcparam{id} identifies a valid replay cache.
  74
  75 %Errors: permission errors.
  76
  77 \begin{funcdecl}{close}{krb5_error_code}{\funcin}
  78 \funcarg{krb5_rcache}{id}
  79 \end{funcdecl}
  80
  81 Closes the replay cache \funcparam{id}, invalidates \funcparam{id},
  82 and releases any other resources acquired during use of the replay cache.
  83 Requires that \funcparam{id} identifies a valid replay cache.
  84
  85 %Errors: permission errors
  86
  87 \begin{funcdecl}{store}{krb5_error_code}{\funcin}
  88 \funcarg{krb5_rcache}{id}
  89 \funcarg{krb5_donot_replay *}{rep}
  90 \end{funcdecl}
  91 Stores \funcparam{rep} in the replay cache \funcparam{id}.
  92 Requires that \funcparam{id} identifies a valid replay cache.
  93
  94 Returns KRB5KRB_AP_ERR_REPEAT if \funcparam{rep} is already in the
  95 cache.  May also return permission errors, storage failure errors.
  96
  97 \begin{funcdecl}{expunge}{krb5_error_code}{\funcin}
  98 \funcarg{krb5_rcache}{id}
  99 \end{funcdecl}
 100 Removes all expired replay information (i.e. those entries which are
 101 older than then authenticator lifespan of the cache) from the cache
 102 \funcparam{id}.  Requires that \funcparam{id} identifies a valid replay
 103 cache.
 104
 105 %Errors: permission errors.
 106
 107 \begin{funcdecl}{get_span}{krb5_error_code}{\funcin}
 108 \funcarg{krb5_rcache}{id}
 109 \funcout
 110 \funcarg{krb5_deltat *}{auth_lifespan}
 111 \end{funcdecl}
 112 Fills in \funcparam{auth_lifespan} with the lifespan of
 113 the cache \funcparam{id}.
 114 Requires that \funcparam{id} identifies a valid replay cache.
 115
 116 \begin{funcdecl}{resolve}{krb5_error_code}{\funcinout}
 117 \funcarg{krb5_rcache}{id}
 118 \funcin
 119 \funcarg{char *}{name}
 120 \end{funcdecl}
 121
 122 Initializes private data attached to \funcparam{id}.  This function MUST
 123 be called before the other per-replay cache functions.
 124
 125 Requires that \funcparam{id} points to allocated space, with an
 126 initialized \funcparam{id{\ptsto}ops} field.
 127
 128 Since \funcname{resolve} allocates memory,
 129 \funcname{close} must be called to free the allocated memory,
 130 even if neither \funcname{init} or
 131 \funcname{recover} were successfully called by the application.
 132
 133 %Returns:  allocation errors.
 134
 135
 136 \begin{funcdecl}{krb5_rc_get_name}{char *}{\funcin}
 137 \funcarg{krb5_rcache}{id}
 138 \end{funcdecl}
 139
 140 Returns the name (excluding the type) of the rcache \funcparam{id}.
 141 Requires that \funcparam{id} identifies a valid replay cache.
 142