next up previous contents index
Next: Free functions Up: libkrb5.a functions Previous: Replay cache functions   Contents   Index

Key table functions

The key table functions deal with storing and retrieving service keys for use by unattended services which participate in authentication exchanges.

Keytab routines are all be atomic. Every routine that acquires a non-sharable resource releases it before it returns.

All keytab types support multiple concurrent sequential scans.

The order of values returned from krb5_kt_next_entry is unspecified.

Although the ``right thing'' should happen if the program aborts abnormally, a close routine, krb5_kt_free_entry, is provided for freeing resources, etc. People should use the close routine when they are finished.


\begin{funcdecl}{krb5_kt_register}{krb5_error_code}{\funcinout}
\funcarg{krb5_context}{context}
\funcin
\funcarg{krb5_kt_ops *}{ops}
\end{funcdecl}

Adds a new ticket cache type to the set recognized by krb5_kt_resolve. Requires that a keytab type named opsprefix is not yet known.

An error is returned if opsprefix is already known.


\begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcinout}
\funcarg{krb5_con...
...g{const char *}{string_name}
\funcout
\funcarg{krb5_keytab *}{id}
\end{funcdecl}

Fills in *id with a handle identifying the keytab with name ``string_name''. The keytab is not opened. Requires that string_name be of the form ``type:residual'' and ``type'' is a type known to the library.

Errors: badly formatted name.


\begin{funcdecl}{krb5_kt_default_name}{krb5_error_code}{\funcinout}
\funcarg{krb...
...}{context}
\funcin
\funcarg{char *}{name}
\funcarg{int}{namesize}
\end{funcdecl}

name is filled in with the first namesize bytes of the name of the default keytab. If the name is shorter than namesize, then the remainder of name will be zeroed.


\begin{funcdecl}{krb5_kt_default}{krb5_error_code}{\funcinout}
\funcarg{krb5_context}{context}
\funcin
\funcarg{krb5_keytab *}{id}
\end{funcdecl}

Fills in id with a handle identifying the default keytab.


\begin{funcdecl}{krb5_kt_read_service_key}{krb5_error_code}{\funcinout}
\funcarg...
...g{krb5_keytype}{keytype}
\funcout
\funcarg{krb5_keyblock **}{key}
\end{funcdecl}

If keyprocarg is not NULL, it is taken to be a char * denoting the name of a keytab. Otherwise, the default keytab will be used. The keytab is opened and searched for the entry identified by principal, keytype, and vno, returning the resulting key in *key or returning an error code if it is not found.

krb5_free_keyblock should be called on *key when the caller is finished with the key.

Returns an error code if the entry is not found.


\begin{funcdecl}{krb5_kt_add_entry}{krb5_error_code}{\funcinout}
\funcarg{krb5_c...
...in
\funcarg{krb5_keytab}{id}
\funcarg{krb5_keytab_entry *}{entry}
\end{funcdecl}

Calls the keytab-specific add routine krb5_kt_add_internal with the same function arguments. If this routine is not available, then KRB5_KT_NOWRITE is returned.


\begin{funcdecl}{krb5_kt_remove_entry}{krb5_error_code}{\funcinout}
\funcarg{krb...
...in
\funcarg{krb5_keytab}{id}
\funcarg{krb5_keytab_entry *}{entry}
\end{funcdecl}

Calls the keytab-specific remove routine krb5_kt_remove_internal with the same function arguments. If this routine is not available, then KRB5_KT_NOWRITE is returned.


\begin{funcdecl}{krb5_kt_get_name}{krb5_error_code}{\funcinout}
\funcarg{krb5_co...
...t
\funcarg{char *}{name}
\funcin
\funcarg{unsigned int}{namesize}
\end{funcdecl}

name is filled in with the first namesize bytes of the name of the keytab identified by id. If the name is shorter than namesize, then name will be null-terminated.


\begin{funcdecl}{krb5_kt_close}{krb5_error_code}{\funcinout}
\funcarg{krb5_context}{context}
\funcarg{krb5_keytab}{id}
\end{funcdecl}

Closes the keytab identified by id and invalidates id, and releases any other resources acquired during use of the key table.

Requires that id identifies a keytab.


\begin{funcdecl}{krb5_kt_get_entry}{krb5_error_code}{\funcinout}
\funcarg{krb5_c...
...5_keytype}{keytype}
\funcout
\funcarg{krb5_keytab_entry *}{entry}
\end{funcdecl}

Searches the keytab identified by id for an entry whose principal matches principal, whose keytype matches keytype, and whose key version number matches vno. If vno is zero, the first entry whose principal matches is returned.

Returns an error code if no suitable entry is found. If an entry is found, the entry is returned in *entry; its contents should be deallocated by calling krb5_kt_free_entry when no longer needed.


\begin{funcdecl}{krb5_kt_free_entry}{krb5_error_code}{\funcinout}
\funcarg{krb5_context}{context}
\funcarg{krb5_keytab_entry *}{entry}
\end{funcdecl}

Releases all storage allocated for entry, which must point to a structure previously filled in by krb5_kt_get_entry or krb5_kt_next_entry.


\begin{funcdecl}{krb5_kt_start_seq_get}{krb5_error_code}{\funcinout}
\funcarg{kr...
...carg{krb5_keytab}{id}
\funcout
\funcarg{krb5_kt_cursor *}{cursor}
\end{funcdecl}

Prepares to read sequentially every key in the keytab identified by id. cursor is filled in with a cursor to be used in calls to krb5_kt_next_entry.


\begin{funcdecl}{krb5_kt_next_entry}{krb5_error_code}{\funcinout}
\funcarg{krb5_...
...tab_entry *}{entry}
\funcinout
\funcarg{krb5_kt_cursor *}{cursor}
\end{funcdecl}

Fetches the ``next'' entry in the keytab, returning it in *entry, and updates *cursor for the next request. If the keytab changes during the sequential get, an error is guaranteed. *entry should be freed after use by calling krb5_kt_free_entry.

Requires that id identifies a valid keytab. and *cursor be a cursor returned by krb5_kt_start_seq_get or a subsequent call to krb5_kt_next_entry.

Errors: error code if no more cache entries or if the keytab changes.


\begin{funcdecl}{krb5_kt_end_seq_get}{krb5_error_code}{\funcinout}
\funcarg{krb5...
...ext}
\funcarg{krb5_keytab}{id}
\funcarg{krb5_kt_cursor *}{cursor}
\end{funcdecl}

Finishes sequential processing mode and invalidates cursor, which must never be re-used after this call.

Requires that id identifies a valid keytab and *cursor be a cursor returned by krb5_kt_start_seq_get or a subsequent call to krb5_kt_next_entry.

May return error code if cursor is invalid.


next up previous contents index
Next: Free functions Up: libkrb5.a functions Previous: Replay cache functions   Contents   Index
Autobuild 2009-09-05