doc/implement/keytab-i.tex

   1 The key table functions deal with storing and retrieving service keys
   2 for use by unattended services which participate in authentication exchanges.
   3
   4 Keytab routines should all be atomic.  Before a routine returns it
   5 must make sure that all non-sharable resources it acquires are
   6 released and in a consistent state.  For example, an implementation is not
   7 allowed to leave a file open for writing or to have a lock on a file.
   8
   9 Note that all keytab implementations must support multiple concurrent
  10 sequential scans.  Another detail to note is that
  11 the order of values returned from \funcname{get_next} is
  12 unspecified and may be sorted to the implementor's convenience.
  13
  14 \subsubsection{The krb5_kt_ops structure}
  15 In order to implement a new key table type, the programmer should
  16 declare a {\bf krb5_kt_ops} structure, and fill in the elements of the
  17 structure appropriately, by implementing each of the key table
  18 functions for the new key table type.
  19
  20 In order to reduce the size of binary programs when static linking is
  21 used, it is common to provide two \datatype{krb5_kt_ops} structures for
  22 each key table type, one for reading only in which the pointers to the
  23 add and delete functions are zero, and one for reading and writing.
  24
  25 \begin{verbatim}
  26 typedef struct _krb5_kt_ops {
  27         char *prefix;
  28         /* routines always present */
  29         krb5_error_code (*resolve)((char *,
  30                                           krb5_keytab *));
  31         krb5_error_code (*get_name)((krb5_keytab,
  32                                           char *,
  33                                           int));
  34         krb5_error_code (*close)((krb5_keytab));
  35         krb5_error_code (*get)((krb5_keytab,
  36                                           krb5_principal,
  37                                           krb5_kvno,
  38                                           krb5_keytab_entry *));
  39         krb5_error_code (*start_seq_get)((krb5_keytab,
  40                                           krb5_kt_cursor *));
  41         krb5_error_code (*get_next)((krb5_keytab,
  42                                           krb5_keytab_entry *,
  43                                           krb5_kt_cursor *));
  44         krb5_error_code (*end_get)((krb5_keytab,
  45                                           krb5_kt_cursor *));
  46         /* routines to be included on extended version (write routines) */
  47         krb5_error_code (*add)((krb5_keytab,
  48                                           krb5_keytab_entry *));
  49         krb5_error_code (*remove)((krb5_keytab,
  50                                           krb5_keytab_entry *));
  51 } krb5_kt_ops;
  52 \end{verbatim}
  53
  54 \subsubsection{Per-type functions that are always present}
  55 The following entry points must be implemented for each type of
  56 key table.  However, \funcname{resolve}, \funcname{remove} and
  57 \funcname{add} are only called by the key table glue code.
  58 They are not called directly by the application.
  59
  60  however, application programs are not expected to call
  61 \funcname{resolve}, \funcname{remove},
  62 or \funcname{add} directly.
  63
  64 \begin{funcdecl}{resolve}{krb5_error_code}{\funcin}
  65 \funcarg{char *}{residual}
  66 \funcout
  67 \funcarg{krb5_keytab *}{id}
  68 \end{funcdecl}
  69
  70 Fills in \funcparam{*id} with a handle identifying the keytab with name
  71 ``residual''.  The interpretation of ``residual'' is dependent on the
  72 type of keytab.
  73
  74 \begin{funcdecl}{get_name}{krb5_error_code}{\funcin}
  75 \funcarg{krb5_keytab}{id}
  76 \funcout
  77 \funcarg{char *}{name}
  78 \funcin
  79 \funcarg{int}{namesize}
  80 \end{funcdecl}
  81
  82 \funcarg{name} is filled in with the first \funcparam{namesize} bytes of
  83 the name of the keytab identified by \funcname{id}.
  84 If the name is shorter than \funcparam{namesize}, then \funcarg{name}
  85 will be null-terminated.
  86
  87 \begin{funcdecl}{close}{krb5_error_code}{\funcin}
  88 \funcarg{krb5_keytab}{id}
  89 \end{funcdecl}
  90
  91 Closes the keytab identified by \funcparam{id} and invalidates
  92 \funcparam{id}, and releases any other resources acquired during use of
  93 the key table.
  94
  95 Requires that \funcparam{id} identifies a valid credentials cache.
  96
  97 \begin{funcdecl}{get}{krb5_error_code}{\funcin}
  98 \funcarg{krb5_keytab}{id}
  99 \funcarg{krb5_principal}{principal}
 100 \funcarg{krb5_kvno}{vno}
 101 \funcout
 102 \funcarg{krb5_keytab_entry *}{entry}
 103 \end{funcdecl}
 104
 105 Searches the keytab identified by \funcparam{id} for an entry whose
 106 principal matches \funcparam{principal} and
 107 whose key version number matches \funcparam{vno}.  If \funcparam{vno} is
 108 zero, the first entry whose principal matches is returned.
 109
 110 %Errors:
 111 This routine should return an error code if no suitable entry is
 112 found.  If an entry is found, the entry is returned in
 113 \funcparam{*entry}; its contents should be deallocated by calling
 114 \funcname{close} when no longer needed.
 115
 116 \begin{funcdecl}{close}{krb5_error_code}{\funcinout}
 117 \funcarg{krb5_keytab_entry *}{entry}
 118 \end{funcdecl}
 119
 120 Releases all storage allocated for \funcparam{entry}, which must point
 121 to a structure previously filled in by \funcname{get} or
 122 \funcname{get_next}.
 123
 124 \begin{funcdecl}{start_seq_get}{krb5_error_code}{\funcin}
 125 \funcarg{krb5_keytab}{id}
 126 \funcout
 127 \funcarg{krb5_kt_cursor *}{cursor}
 128 \end{funcdecl}
 129
 130 Prepares to read sequentially every key in the keytab identified by
 131 \funcparam{id}.
 132 \funcparam{cursor} is filled in with a cursor to be used in calls to
 133 \funcname{get_next}.
 134
 135 \begin{funcdecl}{get_next}{krb5_error_code}{\funcin}
 136 \funcarg{krb5_keytab}{id}
 137 \funcout
 138 \funcarg{krb5_keytab_entry *}{entry}
 139 \funcinout
 140 \funcarg{krb5_kt_cursor}{cursor}
 141 \end{funcdecl}
 142
 143 Fetches the ``next'' entry in the keytab, returning it in
 144 \funcparam{*entry}, and updates \funcparam{*cursor} for the next
 145 request.  If the keytab changes during the sequential get, an error
 146 must be
 147 %Errors:
 148 guaranteed.  \funcparam{*entry} should be freed after use by
 149 calling
 150 \funcname{close}.
 151
 152 Requires that \funcparam{id} identifies a valid credentials cache.  and
 153 \funcparam{*cursor} be a cursor returned by
 154 \funcname{start_seq_get} or a subsequent call to
 155 \funcname{get_next}.
 156
 157 %Errors: error code if no more cache entries or if the keytab changes.
 158
 159 \begin{funcdecl}{end_get}{krb5_error_code}{\funcin}
 160 \funcarg{krb5_keytab}{id}
 161 \funcarg{krb5_kt_cursor *}{cursor}
 162 \end{funcdecl}
 163
 164 Finishes sequential processing mode and invalidates \funcparam{cursor},
 165 which must never be re-used after this call.
 166
 167 Requires that \funcparam{id} identifies a valid credentials cache.  and
 168 \funcparam{*cursor} be a cursor returned by
 169 \funcname{start_seq_get} or a subsequent call to
 170 \funcname{get_next}.
 171
 172 %Errors: May return error code if \funcparam{cursor} is invalid.
 173
 174 \subsubsection{Per-type functions to be included for write routines}
 175
 176 \begin{funcdecl}{add}{krb5_error_code}{\funcin}
 177 \funcarg{krb5_keytab}{id}
 178 \funcarg{krb5_keytab_entry *}{entry}
 179 \end{funcdecl}
 180
 181 Stores \funcparam{entry} in the keytab \funcparam{id}.
 182 Fails if the entry already exists.
 183
 184 This operation must, within the constraints of the operating system, not
 185 return until it can verify that the write has completed succesfully.
 186 For example, in a UNIX file-based implementation, this routine (or the part
 187 of the underlying implementation that it calls) would be responsible for
 188 doing an \funcname{fsync} on the file before returning.
 189
 190 %Errors:
 191 This routine should return an error code if \funcparam{entry} is
 192 already present in the keytab or if the key could not be stored (quota
 193 problem, etc).
 194
 195 \begin{funcdecl}{remove}{krb5_error_code}{\funcin}
 196 \funcarg{krb5_keytab}{id}
 197 \funcarg{krb5_keytab_entry *}{entry}
 198 \end{funcdecl}
 199
 200 Searches the keytab \funcparam{id} for an entry that exactly matches
 201 \funcparam{entry}.  If one is found, it is removed from the keytab.
 202
 203 %Errors: Returns an error code if not found.
 204