diff options
Diffstat (limited to 'doc/api')
| -rw-r--r-- | doc/api/ChangeLog | 12 | ||||
| -rw-r--r-- | doc/api/ccache.tex | 60 | ||||
| -rw-r--r-- | doc/api/free.tex | 265 | ||||
| -rw-r--r-- | doc/api/keytab.tex | 62 | ||||
| -rw-r--r-- | doc/api/rcache.tex | 35 |
5 files changed, 395 insertions, 39 deletions
diff --git a/doc/api/ChangeLog b/doc/api/ChangeLog index fd43aaf45..831c3f270 100644 --- a/doc/api/ChangeLog +++ b/doc/api/ChangeLog @@ -1,6 +1,16 @@ +Sun Apr 30 15:37:31 1995 Ezra Peisach <epeisach@kangaroo.mit.edu> + + * rcache.tex: Update to current API specs. + + * ccache.tex: Update to current API specs. + + * keytab.tex: Update to current API specs. + + * free.tex: Finished first version. + Tue Apr 18 10:42:03 1995 Ezra Peisach <epeisach@kangaroo.mit.edu> - * intro.tex spell checked + * intro.tex: spell checked Tue Apr 11 14:21:21 1995 Ezra Peisach (epeisach@kangaroo.mit.edu) diff --git a/doc/api/ccache.tex b/doc/api/ccache.tex index e85a77444..8f2fd25ca 100644 --- a/doc/api/ccache.tex +++ b/doc/api/ccache.tex @@ -3,7 +3,9 @@ specific types of credentials caches) deal with storing credentials (tickets, session keys, and other identifying information) in a semi-permanent store for later use by different programs. -\begin{funcdecl}{krb5_cc_resolve}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_resolve}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{char *}{string_name} \funcout \funcarg{krb5_ccache *}{id} @@ -15,7 +17,9 @@ the name in \funcparam{string_name}. Requires that \funcparam{string_name} be of the form ``type:residual'' and ``type'' is a type known to the library. -\begin{funcdecl}{krb5_cc_generate_new}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_generate_new}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_cc_ops *}{ops} \funcout \funcarg{krb5_ccache *}{id} @@ -25,7 +29,9 @@ Requires that \funcparam{string_name} be of the form ``type:residual'' and Fills in \funcparam{id} with a unique ccache identifier of a type defined by \funcparam{ops}. The cache is left unopened. -\begin{funcdecl}{krb5_cc_register}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_register}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_cc_ops *}{ops} \funcarg{krb5_boolean}{override} \end{funcdecl} @@ -35,19 +41,24 @@ the set recognized by \funcname{krb5_cc_resolve}. If \funcparam{override} is FALSE, a ticket cache type named \funcparam{ops{\ptsto}prefix} must not be known. -\begin{funcdecl}{krb5_cc_get_name}{char *}{\funcin} +\begin{funcdecl}{krb5_cc_get_name}{char *}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_ccache}{id} \end{funcdecl} Returns the name of the ccache denoted by \funcparam{id}. -\begin{funcdecl}{krb5_cc_default_name}{char *}{\funcvoid} +\begin{funcdecl}{krb5_cc_default_name}{char *}{\funcinout} +\funcarg{krb5_context}{context} \end{funcdecl} Returns the name of the default credentials cache; this may be equivalent to \funcnamenoparens{getenv}({\tt "KRB5CCACHE"}) with an appropriate fallback. -\begin{funcdecl}{krb5_cc_default}{krb5_error_code}{\funcout} +\begin{funcdecl}{krb5_cc_default}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcout \funcarg{krb5_ccache *}{ccache} \end{funcdecl} @@ -56,6 +67,7 @@ Equivalent to \funcparam{ccache}). \begin{funcdecl}{krb5_cc_initialize}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_ccache}{id} \funcin \funcarg{krb5_principal}{primary_principal} @@ -69,7 +81,8 @@ Errors: permission errors, system errors. Modifies: cache identified by \funcparam{id}. -\begin{funcdecl}{krb5_cc_destroy}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_destroy}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_ccache}{id} \end{funcdecl} @@ -83,6 +96,7 @@ it is first reinitialized using \funcname{krb5_cc_resolve} or Errors: permission errors. \begin{funcdecl}{krb5_cc_close}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_ccache}{id} \end{funcdecl} @@ -94,7 +108,9 @@ acquired during use of the credentials cache. Requires that \funcname{krb5_cc_resolve} or \funcname{krb5_cc_generate_new}. -\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_ccache}{id} \funcarg{krb5_creds *}{creds} \end{funcdecl} @@ -105,7 +121,9 @@ Requires that \funcparam{id} identifies a valid credentials cache. Errors: permission errors, storage failure errors. -\begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_ccache}{id} \funcarg{krb5_flags}{whichfields} \funcarg{krb5_creds *}{mcreds} @@ -125,7 +143,9 @@ returned in \funcparam{*creds}. The credentials should be freed using Errors: error code if no matches found. -\begin{funcdecl}{krb5_cc_get_principal}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_get_principal}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_ccache}{id} \funcarg{krb5_principal *}{principal} \end{funcdecl} @@ -138,7 +158,8 @@ should release this memory by calling \funcname{krb5_free_principal} on Requires that \funcparam{id} identifies a valid credentials cache. -\begin{funcdecl}{krb5_cc_start_seq_get}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_start_seq_get}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_ccache}{id} \funcout \funcarg{krb5_cc_cursor *}{cursor} @@ -148,7 +169,8 @@ Prepares to sequentially read every set of cached credentials. \funcparam{cursor} is filled in with a cursor to be used in calls to \funcname{krb5_cc_next_cred}. -\begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_ccache}{id} \funcout \funcarg{krb5_creds *}{creds} @@ -165,7 +187,8 @@ Requires that \funcparam{id} identifies a valid credentials cache and Errors: error code if no more cache entries. -\begin{funcdecl}{krb5_cc_end_seq_get}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_end_seq_get}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_ccache}{id} \funcarg{krb5_cc_cursor *}{cursor} \end{funcdecl} @@ -181,7 +204,9 @@ Requires that \funcparam{id} identifies a valid credentials cache and Errors: may return error code if \funcparam{*cursor} is invalid. -\begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_ccache}{id} \funcarg{krb5_flags}{which} \funcarg{krb5_creds *}{cred} @@ -195,12 +220,15 @@ Requires that \funcparam{id} identifies a valid credentials cache. Errors: returns error code if nothing matches; returns error code if couldn't delete. -\begin{funcdecl}{krb5_cc_set_flags}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_cc_set_flags}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_ccache}{id} +\funcin \funcarg{krb5_flags}{flags} \end{funcdecl} Sets the flags on the cache \funcparam{id} to \funcparam{flags}. Useful -flags are defined in {\tt <krb5/ccache.h>}. +flags are defined in {\tt <krb5.h>}. + diff --git a/doc/api/free.tex b/doc/api/free.tex new file mode 100644 index 000000000..da0b85e75 --- /dev/null +++ b/doc/api/free.tex @@ -0,0 +1,265 @@ +The free functions deal with deallocation of memory that has been +allocated by various routines. It is recommended that the developer use +these routines as they will know about the contents of the structures. + +\begin{funcdecl}{krb5_auth_con_free}{krb5_auth_con_free}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_auth_context *}{auth_context} +\end{funcdecl} + +Frees the auth_context \funcparam{auth_context} returned by +\funcname{krb5_auth_con_init}. + +\begin{funcdecl}{krb5_free_context}{void}{\funcinout} +\funcarg{krb5_context}{context} +\end{funcdecl} + +Frees the context returned by \funcname{krb5_init_context}. Internally +calls \funcname{krb5_os_free_context}. + +\begin{funcdecl}{krb5_free_princial}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_principal}{val} +\end{funcdecl} + +Frees the pwd_data \funcparam{val} that has been allocated from +\funcname{krb5_copy_principal}. + +\begin{funcdecl}{krb5_free_authenticator}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_authenticator *}{val} +\end{funcdecl} + +Frees the authenticator \funcparam{val}, including the pointer +\funcparam{val}. + +\begin{funcdecl}{krb5_free_authenticator_contents}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_authenticator *}{val} +\end{funcdecl} + +Frees the authenticator contents of \funcparam{val}. The pointer +\funcparam{val} is not freed. + + +\begin{funcdecl}{krb5_free_addresses}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_address **}{val} +\end{funcdecl} + +Frees the series of addresses \funcparam{*val} that have been allocated from +\funcname{krb5_copy_addresses}. + +\begin{funcdecl}{krb5_free_address}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_address *}{val} +\end{funcdecl} + +Frees the address \funcparam{val}. + +\begin{funcdecl}{krb5_free_authdata}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_authdata **}{val} +\end{funcdecl} + +Frees the authdata structure pointed to by \funcparam{val} that has been +allocated from +\funcname{krb5_copy_authdata}. + +\begin{funcdecl}{krb5_free_enc_tkt_part}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_enc_tkt_part *}{val} +\end{funcdecl} + +Frees \funcparam{val} that has been allocated from +\funcname{krb5_enc_tkt_part} and \funcname{krb5_decrypt_tkt_part}. + +\begin{funcdecl}{krb5_free_ticket}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_ticket *}{val} +\end{funcdecl} + +Frees the ticket \funcparam{val} that has been allocated from +\funcname{krb5_copy_ticket} and other routines. + +\begin{funcdecl}{krb5_free_tickets}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_ticket **}{val} +\end{funcdecl} + +Frees the tickets pointed to by \funcparam{val}. + +\begin{funcdecl}{krb5_free_kdc_req}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_kdc_req *}{val} +\end{funcdecl} + +Frees the kdc_req \funcparam{val} and all substructures. The pointer +\funcparam{val} is freed as well. + +\begin{funcdecl}{krb5_free_kdc_rep}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_kdc_rep *}{val} +\end{funcdecl} + +Frees the kdc_rep \funcparam{val} that has been allocated from +\funcname{krb5_get_in_tkt}. + +\begin{funcdecl}{krb5_free_kdc_rep_part}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_enc_kdc_rep_part *}{val} +\end{funcdecl} + +Frees the kdc_rep_part \funcparam{val}. + +\begin{funcdecl}{krb5_free_error}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_error *}{val} +\end{funcdecl} + +Frees the error \funcparam{val} that has been allocated from +\funcname{krb5_read_error} or \funcname{krb5_sendauth}. + +\begin{funcdecl}{krb5_free_ap_req}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_ap_req *}{val} +\end{funcdecl} + +Frees the ap_req \funcparam{val}. + +\begin{funcdecl}{krb5_free_ap_rep}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_ap_rep *}{val} +\end{funcdecl} + +Frees the ap_rep \funcparam{val}. + +\begin{funcdecl}{krb5_free_safe}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_safe *}{val} +\end{funcdecl} + +Frees the safe application data \funcparam{val} that is allocated with +\funcparam{decode_krb5_safe}. + + +\begin{funcdecl}{krb5_free_priv}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_priv *}{val} +\end{funcdecl} + +Frees the private data \funcparam{val} that has been allocated from +\funcname{decode_krb5_priv}. + +\begin{funcdecl}{krb5_free_priv_enc_part}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_priv_enc_part *}{val} +\end{funcdecl} + +Frees the private encoded part \funcparam{val} that has been allocated from +\funcname{decode_krb5_enc_priv_part}. + +\begin{funcdecl}{krb5_free_cred}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_cred *}{val} +\end{funcdecl} + +Frees the credential \funcparam{val}. + +\begin{funcdecl}{krb5_free_creds}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_creds *}{val} +\end{funcdecl} + +Calls \funcname{krb5_free_cred_contents} with \funcparam{val} as the +argument. \funcparam{val} is freed as well. + +\begin{funcdecl}{krb5_free_cred_contents}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_creds *}{val} +\end{funcdecl} + +The function zeros out the session key stored in the credential and then +frees the credentials structures. The argument \funcparam{val} is +{\bf not} freed. + + +\begin{funcdecl}{krb5_free_cred_enc_part}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_cred_enc_part *}{val} +\end{funcdecl} + +Frees the addresses and ticket_info elements of +\funcparam{val}. \funcparam{val} is {\bf not} freed by this routine. + +\begin{funcdecl}{krb5_free_checksum}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_checksum *}{val} +\end{funcdecl} + +The checksum and the pointer \funcparam{val} are both freed. + +\begin{funcdecl}{krb5_free_keyblock}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_keyblock *}{val} +\end{funcdecl} + +The keyblock contents of \funcparam{val} are zeroed and the memory +freed. The pointer \funcparam{val} is freed as well. + +\begin{funcdecl}{krb5_free_pa_data}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_pa_data **}{val} +\end{funcdecl} + +Frees the contents of \funcparam{*val}. \funcparam{val} is freed as +well. + +\begin{funcdecl}{krb5_free_ap_rep_enc_part}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_ap_rep_enc_part *}{val} +\end{funcdecl} + +Frees the subkey keyblock (if set) as well as \funcparam{val} that has +been allocated from \funcname{krb5_rd_rep} or \funcname{krb5_send_auth}. + +\begin{funcdecl}{krb5_free_tkt_authent}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_tkt_authent *}{val} +\end{funcdecl} + +Frees the ticket and authenticator portions of \funcparam{val}. The +pointer \funcparam{val} is freed as well. + +\begin{funcdecl}{krb5_free_pwd_data}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{passwd_pwd_data *}{val} +\end{funcdecl} + +Frees the pwd_data \funcparam{val} that has been allocated from +\funcname{decode_krb5_pwd_data}. + +\begin{funcdecl}{krb5_free_pwd_sequences}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{passwd_phrase_element **}{val} +\end{funcdecl} + +Frees the passwd_phrase_element \funcparam{val}. This is usually called +from \funcname{krb5_free_pwd_data}. + +\begin{funcdecl}{krb5_free_realm_tree}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_principal *}{realms} +\end{funcdecl} + +Frees the realms tree \funcparam{realms} returned by +\funcname{krb5_walk_realm_tree}. + +\begin{funcdecl}{krb5_free_tgt_creds}{void}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_creds **}{tgts} +\end{funcdecl} + +Frees the TGT credentials \funcparam{tgts} returned by +\funcname{krb5_get_cred_from_kdc}. + diff --git a/doc/api/keytab.tex b/doc/api/keytab.tex index c642b17eb..740c9de07 100644 --- a/doc/api/keytab.tex +++ b/doc/api/keytab.tex @@ -14,7 +14,9 @@ abnormally, a close routine, \funcname{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}{\funcin} +\begin{funcdecl}{krb5_kt_register}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_kt_ops *}{ops} \end{funcdecl} @@ -26,7 +28,9 @@ yet known. An error is returned if \funcparam{ops{\ptsto}prefix} is already known. -\begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{const char *}{string_name} \funcout \funcarg{krb5_keytab *}{id} @@ -39,7 +43,9 @@ Requires that \funcparam{string_name} be of the form ``type:residual'' and Errors: badly formatted name. -\begin{funcdecl}{krb5_kt_default_name}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_kt_default_name}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{char *}{name} \funcarg{int}{namesize} \end{funcdecl} @@ -50,13 +56,17 @@ If the name is shorter than \funcparam{namesize}, then the remainder of \funcparam{name} will be zeroed. -\begin{funcdecl}{krb5_kt_default}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_kt_default}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_keytab *}{id} \end{funcdecl} -Fills in \funcparam{id} with a handle identifying the default keytab. +Fills in \funcparam{id} with a handle identifying the default keytab. -\begin{funcdecl}{krb5_kt_read_service_key}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_kt_read_service_key}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_pointer}{keyprocarg} \funcarg{krb5_principal}{principal} \funcarg{krb5_kvno}{vno} @@ -65,9 +75,6 @@ Fills in \funcparam{id} with a handle identifying the default keytab. \funcarg{krb5_keyblock **}{key} \end{funcdecl} -This function is suitable for use as a parameter to -\funcname{krb5_rd_req}. - If \funcname{keyprocarg} is not NULL, it is taken to be a \datatype{char *} denoting the name of a keytab. Otherwise, the default keytab will be used. @@ -81,7 +88,9 @@ 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}{\funcin} +\begin{funcdecl}{krb5_kt_add_entry}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_keytab}{id} \funcarg{krb5_keytab_entry *}{entry} \end{funcdecl} @@ -90,7 +99,9 @@ Calls the keytab-specific add routine \funcname{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}{\funcin} +\begin{funcdecl}{krb5_kt_remove_entry}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_keytab}{id} \funcarg{krb5_keytab_entry *}{entry} \end{funcdecl} @@ -99,7 +110,8 @@ Calls the keytab-specific remove routine \funcname{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}{\funcin} +\begin{funcdecl}{krb5_kt_get_name}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_keytab}{id} \funcout \funcarg{char *}{name} @@ -112,7 +124,8 @@ the name of the keytab identified by \funcname{id}. If the name is shorter than \funcparam{namesize}, then \funcarg{name} will be null-terminated. -\begin{funcdecl}{krb5_kt_close}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_kt_close}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_keytab}{id} \end{funcdecl} @@ -120,10 +133,12 @@ Closes the keytab identified by \funcparam{id} and invalidates \funcparam{id}, and releases any other resources acquired during use of the key table. -Requires that \funcparam{id} identifies a valid credentials cache. +Requires that \funcparam{id} identifies a keytab. -\begin{funcdecl}{krb5_kt_get_entry}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_kt_get_entry}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_keytab}{id} +\funcin \funcarg{krb5_principal}{principal} \funcarg{krb5_kvno}{vno} \funcarg{krb5_keytype}{keytype} @@ -131,11 +146,13 @@ Requires that \funcparam{id} identifies a valid credentials cache. \funcarg{krb5_keytab_entry *}{entry} \end{funcdecl} +\begin{sloppypar} Searches the keytab identified by \funcparam{id} for an entry whose principal matches \funcparam{principal}, whose keytype matches \funcparam{keytype}, and whose key version number matches \funcparam{vno}. If \funcparam{vno} is zero, the first entry whose principal matches is returned. +\end{sloppypar} Returns an error code if no suitable entry is found. If an entry is found, the entry is returned in \funcparam{*entry}; its contents should @@ -143,6 +160,7 @@ be deallocated by calling \funcname{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} @@ -150,7 +168,8 @@ Releases all storage allocated for \funcparam{entry}, which must point to a structure previously filled in by \funcname{krb5_kt_get_entry} or \funcname{krb5_kt_next_entry}. -\begin{funcdecl}{krb5_kt_start_seq_get}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_kt_start_seq_get}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_keytab}{id} \funcout \funcarg{krb5_kt_cursor *}{cursor} @@ -161,7 +180,8 @@ Prepares to read sequentially every key in the keytab identified by \funcparam{cursor} is filled in with a cursor to be used in calls to \funcname{krb5_kt_next_entry}. -\begin{funcdecl}{krb5_kt_next_entry}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_kt_next_entry}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_keytab}{id} \funcout \funcarg{krb5_keytab_entry *}{entry} @@ -175,14 +195,15 @@ request. If the keytab changes during the sequential get, an error is guaranteed. \funcparam{*entry} should be freed after use by calling \funcname{krb5_kt_free_entry}. -Requires that \funcparam{id} identifies a valid credentials cache. and +Requires that \funcparam{id} identifies a valid keytab. and \funcparam{*cursor} be a cursor returned by \funcname{krb5_kt_start_seq_get} or a subsequent call to \funcname{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}{\funcin} +\begin{funcdecl}{krb5_kt_end_seq_get}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_keytab}{id} \funcarg{krb5_kt_cursor *}{cursor} \end{funcdecl} @@ -190,10 +211,11 @@ Errors: error code if no more cache entries or if the keytab changes. Finishes sequential processing mode and invalidates \funcparam{cursor}, which must never be re-used after this call. -Requires that \funcparam{id} identifies a valid credentials cache. and +Requires that \funcparam{id} identifies a valid keytab and \funcparam{*cursor} be a cursor returned by \funcname{krb5_kt_start_seq_get} or a subsequent call to \funcname{krb5_kt_next_entry}. May return error code if \funcparam{cursor} is invalid. + diff --git a/doc/api/rcache.tex b/doc/api/rcache.tex index b9ef1977a..55347cb7c 100644 --- a/doc/api/rcache.tex +++ b/doc/api/rcache.tex @@ -8,16 +8,31 @@ file-based things, it would be a cache file name). The caching strategy uses non-volatile storage so that replay integrity can be maintained across system failures. +\begin{funcdecl}{krb5_auth_to_rep}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin +\funcarg{krb5_tkt_authent *}{auth} +\funcout +\funcarg{krb5_donot_replay *}{rep} +\end{funcdecl} +Extract the relevant parts of \funcparam{auth} and fill them into the +structure pointed to by \funcparam{rep}. \funcparam{rep{\ptsto}client} +and \funcparam{rep{\ptsto}server} are set to allocated storage and +should be freed when \funcparam{*rep} is no longer needed. + \begin{funcdecl}{krb5_rc_resolve_full}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache *}{id} \funcin \funcarg{char *}{string_name} \end{funcdecl} +\begin{sloppypar} \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. +\end{sloppypar} Before the cache can be used \funcname{krb5_rc_initialize} or \funcname{krb5_rc_recover} must be called. @@ -25,6 +40,7 @@ Before the cache can be used \funcname{krb5_rc_initialize} or Errors: error if cannot resolve name. \begin{funcdecl}{krb5_rc_register_type}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_rc_ops *}{ops} \end{funcdecl} Adds a new replay cache type implemented and identified by @@ -34,17 +50,23 @@ cache of the type named in \funcparam{ops{\ptsto}prefix} has not been previously registered. -\begin{funcdecl}{krb5_rc_default_name}{char *}{\funcvoid} +\begin{funcdecl}{krb5_rc_default_name}{char *}{\funcin} +\funcarg{krb5_context}{context} \end{funcdecl} + +\begin{sloppypar} Returns the name of the default replay cache; this may be equivalent to \funcnamenoparens{getenv}({\tt "KRB5RCACHE"}) with an appropriate fallback. +\end{sloppypar} -\begin{funcdecl}{krb5_rc_default_type}{char *}{\funcvoid} +\begin{funcdecl}{krb5_rc_default_type}{char *}{\funcin} +\funcarg{krb5_context}{context} \end{funcdecl} Returns the type of the default replay cache. \begin{funcdecl}{krb5_rc_default}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache *}{id} \end{funcdecl} @@ -56,6 +78,7 @@ called. \begin{funcdecl}{krb5_rc_initialize}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache}{id} \funcarg{krb5_deltat}{auth_lifespan} \end{funcdecl} @@ -67,6 +90,7 @@ replay cache already exists, its contents are destroyed. Errors: permission errors, system errors \begin{funcdecl}{krb5_rc_recover}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache}{id} \end{funcdecl} Attempts to recover the replay cache \funcparam{id}, (presumably after a @@ -75,6 +99,7 @@ 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_context}{context} \funcarg{krb5_rcache}{id} \end{funcdecl} @@ -84,6 +109,7 @@ Requires that \funcparam{id} identifies a valid replay cache. Errors: permission errors. \begin{funcdecl}{krb5_rc_close}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache}{id} \end{funcdecl} @@ -94,6 +120,7 @@ Requires that \funcparam{id} identifies a valid replay cache. Errors: permission errors \begin{funcdecl}{krb5_rc_store}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache}{id} \funcarg{krb5_donot_replay *}{rep} \end{funcdecl} @@ -104,6 +131,7 @@ Returns KRB5KRB_AP_ERR_REPEAT if \funcparam{rep} is already in the cache. May also return permission errors, storage failure errors. \begin{funcdecl}{krb5_rc_expunge}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache}{id} \end{funcdecl} Removes all expired replay information (i.e. those entries which are @@ -114,6 +142,7 @@ cache. Errors: permission errors. \begin{funcdecl}{krb5_rc_get_lifespan}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache}{id} \funcout \funcarg{krb5_deltat *}{auth_lifespan} @@ -123,6 +152,7 @@ the cache \funcparam{id}. Requires that \funcparam{id} identifies a valid replay cache. \begin{funcdecl}{krb5_rc_resolve}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache}{id} \funcin \funcarg{char *}{name} @@ -143,6 +173,7 @@ Returns: allocation errors. \begin{funcdecl}{krb5_rc_get_name}{char *}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_rcache}{id} \end{funcdecl} |