doc/api/keytab.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 are all be atomic.  Every routine that acquires
   5 a non-sharable resource releases it before it returns.
   6
   7 All keytab types support multiple concurrent sequential scans.
   8
   9 The order of values returned from \funcname{krb5_kt_next_entry} is
  10 unspecified.
  11
  12 Although the ``right thing'' should happen if the program aborts
  13 abnormally, a close routine, \funcname{krb5_kt_free_entry},  is provided
  14 for freeing resources, etc.  People should use the close routine when
  15 they are finished.
  16
  17 \begin{funcdecl}{krb5_kt_register}{krb5_error_code}{\funcinout}
  18 \funcarg{krb5_context}{context}
  19 \funcin
  20 \funcarg{krb5_kt_ops *}{ops}
  21 \end{funcdecl}
  22
  23
  24 Adds a new ticket cache type to the set recognized by
  25 \funcname{krb5_kt_resolve}.
  26 Requires that a keytab type named \funcparam{ops{\ptsto}prefix} is not
  27 yet known.
  28
  29 An error is returned if \funcparam{ops{\ptsto}prefix} is already known.
  30
  31 \begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcinout}
  32 \funcarg{krb5_context}{context}
  33 \funcin
  34 \funcarg{const char *}{string_name}
  35 \funcout
  36 \funcarg{krb5_keytab *}{id}
  37 \end{funcdecl}
  38
  39 Fills in \funcparam{*id} with a handle identifying the keytab with name
  40 ``string_name''.  The keytab is not opened.
  41 Requires that \funcparam{string_name} be of the form ``type:residual'' and
  42 ``type'' is a type known to the library.
  43
  44 Errors: badly formatted name.
  45
  46 \begin{funcdecl}{krb5_kt_default_name}{krb5_error_code}{\funcinout}
  47 \funcarg{krb5_context}{context}
  48 \funcin
  49 \funcarg{char *}{name}
  50 \funcarg{int}{namesize}
  51 \end{funcdecl}
  52
  53 \funcparam{name} is filled in with the first \funcparam{namesize} bytes of
  54 the name of the default keytab.
  55 If the name is shorter than \funcparam{namesize}, then the remainder of
  56 \funcparam{name} will be zeroed.
  57
  58
  59 \begin{funcdecl}{krb5_kt_default}{krb5_error_code}{\funcinout}
  60 \funcarg{krb5_context}{context}
  61 \funcin
  62 \funcarg{krb5_keytab *}{id}
  63 \end{funcdecl}
  64
  65 Fills in \funcparam{id} with a handle identifying the default keytab.
  66
  67 \begin{funcdecl}{krb5_kt_read_service_key}{krb5_error_code}{\funcinout}
  68 \funcarg{krb5_context}{context}
  69 \funcin
  70 \funcarg{krb5_pointer}{keyprocarg}
  71 \funcarg{krb5_principal}{principal}
  72 \funcarg{krb5_kvno}{vno}
  73 \funcarg{krb5_keytype}{keytype}
  74 \funcout
  75 \funcarg{krb5_keyblock **}{key}
  76 \end{funcdecl}
  77
  78 If \funcname{keyprocarg} is not NULL, it is taken to be a
  79 \datatype{char *} denoting the name of a keytab.  Otherwise, the default
  80 keytab will be used.
  81 The keytab is opened and searched for the entry identified by
  82 \funcparam{principal}, \funcparam{keytype}, and \funcparam{vno},
  83 returning the resulting key
  84 in \funcparam{*key} or returning an error code if it is not found.
  85
  86 \funcname{krb5_free_keyblock} should be called on \funcparam{*key} when
  87 the caller is finished with the key.
  88
  89 Returns an error code if the entry is not found.
  90
  91 \begin{funcdecl}{krb5_kt_add_entry}{krb5_error_code}{\funcinout}
  92 \funcarg{krb5_context}{context}
  93 \funcin
  94 \funcarg{krb5_keytab}{id}
  95 \funcarg{krb5_keytab_entry *}{entry}
  96 \end{funcdecl}
  97
  98 Calls the keytab-specific add routine \funcname{krb5_kt_add_internal}
  99 with the same function arguments.  If this routine is not available,
 100 then KRB5_KT_NOWRITE is returned.
 101
 102 \begin{funcdecl}{krb5_kt_remove_entry}{krb5_error_code}{\funcinout}
 103 \funcarg{krb5_context}{context}
 104 \funcin
 105 \funcarg{krb5_keytab}{id}
 106 \funcarg{krb5_keytab_entry *}{entry}
 107 \end{funcdecl}
 108
 109 Calls the keytab-specific remove routine
 110 \funcname{krb5_kt_remove_internal} with the same function arguments.
 111 If this routine is not available, then KRB5_KT_NOWRITE is returned.
 112
 113 \begin{funcdecl}{krb5_kt_get_name}{krb5_error_code}{\funcinout}
 114 \funcarg{krb5_context}{context}
 115 \funcarg{krb5_keytab}{id}
 116 \funcout
 117 \funcarg{char *}{name}
 118 \funcin
 119 \funcarg{unsigned int}{namesize}
 120 \end{funcdecl}
 121
 122 \funcarg{name} is filled in with the first \funcparam{namesize} bytes of
 123 the name of the keytab identified by \funcname{id}.
 124 If the name is shorter than \funcparam{namesize}, then \funcarg{name}
 125 will be null-terminated.
 126
 127 \begin{funcdecl}{krb5_kt_close}{krb5_error_code}{\funcinout}
 128 \funcarg{krb5_context}{context}
 129 \funcarg{krb5_keytab}{id}
 130 \end{funcdecl}
 131
 132 Closes the keytab identified by \funcparam{id} and invalidates
 133 \funcparam{id}, and releases any other resources acquired during use of
 134 the key table.
 135
 136 Requires that \funcparam{id} identifies a keytab.
 137
 138 \begin{funcdecl}{krb5_kt_get_entry}{krb5_error_code}{\funcinout}
 139 \funcarg{krb5_context}{context}
 140 \funcarg{krb5_keytab}{id}
 141 \funcin
 142 \funcarg{krb5_principal}{principal}
 143 \funcarg{krb5_kvno}{vno}
 144 \funcarg{krb5_keytype}{keytype}
 145 \funcout
 146 \funcarg{krb5_keytab_entry *}{entry}
 147 \end{funcdecl}
 148
 149 \begin{sloppypar}
 150 Searches the keytab identified by \funcparam{id} for an entry whose
 151 principal matches \funcparam{principal}, whose keytype matches
 152 \funcparam{keytype}, and
 153 whose key version number matches \funcparam{vno}.  If \funcparam{vno} is
 154 zero, the first entry whose principal matches is returned.
 155 \end{sloppypar}
 156
 157 Returns an error code if no suitable entry is found.  If an entry is
 158 found, the entry is returned in \funcparam{*entry}; its contents should
 159 be deallocated by calling \funcname{krb5_kt_free_entry} when no longer
 160 needed.
 161
 162 \begin{funcdecl}{krb5_kt_free_entry}{krb5_error_code}{\funcinout}
 163 \funcarg{krb5_context}{context}
 164 \funcarg{krb5_keytab_entry *}{entry}
 165 \end{funcdecl}
 166
 167 Releases all storage allocated for \funcparam{entry}, which must point
 168 to a structure previously filled in by \funcname{krb5_kt_get_entry} or
 169 \funcname{krb5_kt_next_entry}.
 170
 171 \begin{funcdecl}{krb5_kt_start_seq_get}{krb5_error_code}{\funcinout}
 172 \funcarg{krb5_context}{context}
 173 \funcarg{krb5_keytab}{id}
 174 \funcout
 175 \funcarg{krb5_kt_cursor *}{cursor}
 176 \end{funcdecl}
 177
 178 Prepares to read sequentially every key in the keytab identified by
 179 \funcparam{id}.
 180 \funcparam{cursor} is filled in with a cursor to be used in calls to
 181 \funcname{krb5_kt_next_entry}.
 182
 183 \begin{funcdecl}{krb5_kt_next_entry}{krb5_error_code}{\funcinout}
 184 \funcarg{krb5_context}{context}
 185 \funcarg{krb5_keytab}{id}
 186 \funcout
 187 \funcarg{krb5_keytab_entry *}{entry}
 188 \funcinout
 189 \funcarg{krb5_kt_cursor *}{cursor}
 190 \end{funcdecl}
 191
 192 Fetches the ``next'' entry in the keytab, returning it in
 193 \funcparam{*entry}, and updates \funcparam{*cursor} for the next
 194 request.  If the keytab changes during the sequential get, an error is
 195 guaranteed.  \funcparam{*entry} should be freed after use by calling
 196 \funcname{krb5_kt_free_entry}.
 197
 198 Requires that \funcparam{id} identifies a valid keytab.  and
 199 \funcparam{*cursor} be a cursor returned by
 200 \funcname{krb5_kt_start_seq_get} or a subsequent call to
 201 \funcname{krb5_kt_next_entry}.
 202
 203 Errors: error code if no more cache entries or if the keytab changes.
 204
 205 \begin{funcdecl}{krb5_kt_end_seq_get}{krb5_error_code}{\funcinout}
 206 \funcarg{krb5_context}{context}
 207 \funcarg{krb5_keytab}{id}
 208 \funcarg{krb5_kt_cursor *}{cursor}
 209 \end{funcdecl}
 210
 211 Finishes sequential processing mode and invalidates \funcparam{cursor},
 212 which must never be re-used after this call.
 213
 214 Requires that \funcparam{id} identifies a valid keytab  and
 215 \funcparam{*cursor} be a cursor returned by
 216 \funcname{krb5_kt_start_seq_get} or a subsequent call to
 217 \funcname{krb5_kt_next_entry}.
 218
 219 May return error code if \funcparam{cursor} is invalid.
 220
 221