From c0af96f6e06ebf68e770053083f8165ec755da79 Mon Sep 17 00:00:00 2001 From: Nancy Gilman Date: Tue, 14 Jun 1994 19:09:21 +0000 Subject: The first revision after the creation of the implementor's guide git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@3771 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/implement/ccache-i.tex | 159 ++++++++++---------- doc/implement/encrypt-i.tex | 32 ++++- doc/implement/kdb-i.tex | 19 +-- doc/implement/keytab-i.tex | 226 ++++++++++++----------------- doc/implement/libos-i.tex | 343 -------------------------------------------- doc/implement/rcache-i.tex | 121 +++++++--------- 6 files changed, 254 insertions(+), 646 deletions(-) (limited to 'doc') diff --git a/doc/implement/ccache-i.tex b/doc/implement/ccache-i.tex index 983eb0d8b4..bff804f968 100644 --- a/doc/implement/ccache-i.tex +++ b/doc/implement/ccache-i.tex @@ -3,14 +3,58 @@ 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. +\subsubsection{The krb5_cc_ops structure} +In order to implement a new credentials cache type, the programmer should +declare a {\bf krb5_cc_ops} structure, and fill in the elements of the +structure appropriately, by implementing each of the credential cache +functions for the new credentials cache type. + +The prefix element specifies the prefix name of the the new credential +cache type. For example, if the prefix name is ``FILE'', then if the +program calls \funcname{krb5_cc_resolve} with a credential cache name +such as ``FILE:/tmp/krb5_cc_15806'', then \funcname{krb5_cc_resolve} +will call the resolve function (as defined by the {\bf krb5_cc_ops} +structure where the prefix element is ``FILE'') and pass it the +argument ``/tmp/krb5_cc_15806''. + +Before a new credentials cache type can be recognized by +\funcname{krb5_cc_resolve}, it must be registered with the Kerberos +library by calling \funcname{krb5_cc_register}. + +\begin{verbatim} +typedef struct _krb5_cc_ops { + char *prefix; + char *(*get_name)((krb5_ccache)); + krb5_error_code (*resolve)((krb5_ccache *, char *)); + krb5_error_code (*gen_new)((krb5_ccache *)); + krb5_error_code (*init)((krb5_ccache, krb5_principal)); + krb5_error_code (*destroy)((krb5_ccache)); + krb5_error_code (*close)((krb5_ccache)); + krb5_error_code (*store)((krb5_ccache, krb5_creds *)); + krb5_error_code (*retrieve)((krb5_ccache, krb5_flags, + krb5_creds *, krb5_creds *)); + krb5_error_code (*get_princ)((krb5_ccache, + krb5_principal *)); + krb5_error_code (*get_first)((krb5_ccache, + krb5_cc_cursor *)); + krb5_error_code (*get_next)((krb5_ccache, krb5_cc_cursor *, + krb5_creds *)); + krb5_error_code (*end_get)((krb5_ccache, krb5_cc_cursor *)); + krb5_error_code (*remove_cred)((krb5_ccache, krb5_flags, + krb5_creds *)); + krb5_error_code (*set_flags)((krb5_ccache, krb5_flags)); +} krb5_cc_ops; +\end{verbatim} + + \subsubsection{Per-type functions} The following entry points must be implemented for each type of -credentials cache; however, applications are not expected to have a need -to call either \funcname{krb5_cc_resolve_internal} or -\funcname{krb5_cc_gennew_internal}. +credentials cache. However, \funcname{resolve} and +\funcname{gen_new} are only called by the credentials cache glue code. +They are not called directly by the application. -\begin{funcdecl}{krb5_cc_resolve_internal}{krb5_error_code}{\funcout} +\begin{funcdecl}{resolve}{krb5_error_code}{\funcout} \funcarg{krb5_ccache *}{id} \funcin \funcarg{char *}{residual} @@ -20,7 +64,7 @@ Creates a credentials cache named by \funcparam{residual} (which may be interpreted differently by each type of ccache). The cache is not opened, but the cache name is held in reserve. -\begin{funcdecl}{krb5_cc_gen_new_internal}{krb5_error_code}{\funcout} +\begin{funcdecl}{gen_new}{krb5_error_code}{\funcout} \funcarg{krb5_ccache *}{id} \end{funcdecl} @@ -29,7 +73,7 @@ unique. The cache is not opened. \funcparam{*id} is filled in with a \datatype{krb5_ccache} which may be used in subsequent calls to ccache functions. -\begin{funcdecl}{krb5_cc_initialize}{krb5_error_code}{\funcinout} +\begin{funcdecl}{init}{krb5_error_code}{\funcinout} \funcarg{krb5_ccache}{id} \funcin \funcarg{krb5_principal}{primary_principal} @@ -39,11 +83,11 @@ Creates/refreshes a credentials cache identified by \funcparam{id} with primary principal set to \funcparam{primary_principal}. If the credentials cache already exists, its contents are destroyed. -Errors: permission errors, system errors. +%Errors: permission errors, system errors. Modifies: cache identified by \funcparam{id}. -\begin{funcdecl}{krb5_cc_destroy}{krb5_error_code}{\funcin} +\begin{funcdecl}{destroy}{krb5_error_code}{\funcin} \funcarg{krb5_ccache}{id} \end{funcdecl} @@ -53,9 +97,9 @@ the credentials cache. Requires that \funcparam{id} identifies a valid credentials cache. After return, \funcparam{id} must not be used unless it is first reinitialized. -Errors: permission errors. +%Errors: permission errors. -\begin{funcdecl}{krb5_cc_close}{krb5_error_code}{\funcinout} +\begin{funcdecl}{close}{krb5_error_code}{\funcinout} \funcarg{krb5_ccache}{id} \end{funcdecl} @@ -66,7 +110,7 @@ acquired during use of the credentials cache. Requires that \funcparam{id} must not be used unless it is first reinitialized. -\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin} +\begin{funcdecl}{store}{krb5_error_code}{\funcin} \funcarg{krb5_ccache}{id} \funcarg{krb5_creds *}{creds} \end{funcdecl} @@ -75,9 +119,9 @@ Stores \funcparam{creds} in the cache \funcparam{id}, tagged with \funcparam{creds{\ptsto}client}. Requires that \funcparam{id} identifies a valid credentials cache. -Errors: permission errors, storage failure errors. +%Errors: permission errors, storage failure errors. -\begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin} +\begin{funcdecl}{retrieve}{krb5_error_code}{\funcin} \funcarg{krb5_ccache}{id} \funcarg{krb5_flags}{whichfields} \funcarg{krb5_creds *}{mcreds} @@ -95,22 +139,22 @@ If at least one match is found, one of the matching credentials is returned in \funcparam{*creds}. The credentials should be freed using \funcname{krb5_free_credentials}. -Errors: error code if no matches found. +%Errors: error code if no matches found. -\begin{funcdecl}{krb5_cc_get_principal}{krb5_error_code}{\funcin} +\begin{funcdecl}{get_princ}{krb5_error_code}{\funcin} \funcarg{krb5_ccache}{id} \funcarg{krb5_principal *}{principal} \end{funcdecl} Retrieves the primary principal of the credentials cache (as -set by the \funcname{krb5_cc_initialize} request) +set by the \funcname{init} request) The primary principal is filled into \funcparam{*principal}; the caller should release this memory by calling \funcname{krb5_free_principal} on \funcparam{*principal} when finished. Requires that \funcparam{id} identifies a valid credentials cache. -\begin{funcdecl}{krb5_cc_start_seq_get}{krb5_error_code}{\funcin} +\begin{funcdecl}{get_first}{krb5_error_code}{\funcin} \funcarg{krb5_ccache}{id} \funcout \funcarg{krb5_cc_cursor *}{cursor} @@ -120,9 +164,9 @@ Prepares to sequentially read every set of cached credentials. Requires that \funcparam{id} identifies a valid credentials cache opened by \funcname{krb5_cc_open}. \funcparam{cursor} is filled in with a cursor to be used in calls to -\funcname{krb5_cc_next_cred}. +\funcname{get_next}. -\begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcin} +\begin{funcdecl}{get_next}{krb5_error_code}{\funcin} \funcarg{krb5_ccache}{id} \funcout \funcarg{krb5_creds *}{creds} @@ -134,12 +178,12 @@ Fetches the next entry from \funcparam{id}, returning its values in \funcparam{*creds}, and updates \funcparam{*cursor} for the next request. Requires that \funcparam{id} identifies a valid credentials cache and \funcparam{*cursor} be a cursor returned by -\funcname{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. +\funcname{get_first} or a subsequent call to +\funcname{get_next}. -Errors: error code if no more cache entries. +%Errors: error code if no more cache entries. -\begin{funcdecl}{krb5_cc_end_seq_get}{krb5_error_code}{\funcin} +\begin{funcdecl}{end_get}{krb5_error_code}{\funcin} \funcarg{krb5_ccache}{id} \funcarg{krb5_cc_cursor *}{cursor} \end{funcdecl} @@ -149,13 +193,13 @@ Finishes sequential processing mode and invalidates \funcparam{*cursor}. Requires that \funcparam{id} identifies a valid credentials cache and \funcparam{*cursor} be a cursor returned by -\funcname{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. +\funcname{get_first} or a subsequent call to +\funcname{get_next}. -Errors: may return error code if \funcparam{*cursor} is invalid. +%Errors: may return error code if \funcparam{*cursor} is invalid. -\begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcin} +\begin{funcdecl}{remove_cred}{krb5_error_code}{\funcin} \funcarg{krb5_ccache}{id} \funcarg{krb5_flags}{which} \funcarg{krb5_creds *}{cred} @@ -166,10 +210,10 @@ name {cred{\ptsto}server} and the fields in \funcparam{cred} masked by \funcparam{which}. Requires that \funcparam{id} identifies a valid credentials cache. -Errors: returns error code if nothing matches; returns error code if +%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}{set_flags}{krb5_error_code}{\funcin} \funcarg{krb5_ccache}{id} \funcarg{krb5_flags}{flags} \end{funcdecl} @@ -178,60 +222,3 @@ Sets the flags on the cache \funcparam{id} to \funcparam{flags}. Useful flags are defined in {\tt }. -\subsubsection{Glue functions} -The following functions are implemented in the base library and serve to -glue together the various types of credentials caches. - - -\begin{funcdecl}{krb5_cc_resolve}{krb5_error_code}{\funcin} -\funcarg{char *}{string_name} -\funcout -\funcarg{krb5_ccache *}{id} -\end{funcdecl} - -Fills in \funcparam{id} with a ccache identifier which corresponds to -the name in \funcparam{string_name}. The cache is left unopened. - -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} -\funcarg{krb5_cc_ops *}{ops} -\funcout -\funcarg{krb5_ccache *}{id} -\end{funcdecl} - - -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} -\funcarg{krb5_cc_ops *}{ops} -\funcarg{krb5_boolean}{override} -\end{funcdecl} - -Adds a new cache type identified and implemented by \funcparam{ops} to -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} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Returns the name of the ccache denoted by \funcparam{id}. - -\begin{funcdecl}{krb5_cc_default_name}{char *}{\funcvoid} -\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} -\funcarg{krb5_ccache *}{ccache} -\end{funcdecl} - -Equivalent to -\funcnamenoparens{krb5_cc_resolve}(\funcname{krb5_cc_default_name}, -\funcparam{ccache}). - diff --git a/doc/implement/encrypt-i.tex b/doc/implement/encrypt-i.tex index 7a0e883e61..6e4b0ab44f 100644 --- a/doc/implement/encrypt-i.tex +++ b/doc/implement/encrypt-i.tex @@ -26,7 +26,7 @@ be used to compute this size. \funcparam{ivec} points to an initial vector/seed to be used in the encryption. If null, the cryptosystem may choose an appropriate initialization vector. -Returns errors. +%Errors: Returns errors. \begin{funcdecl}{decrypt_func}{krb5_error_code}{\funcvoid} \funcarg{krb5_const_pointer}{in} @@ -49,7 +49,7 @@ the input size. \funcparam{ivec} points to an initial vector/seed to be used in the decryption. If null, the cryptosystem may choose an appropriate ivec. -Returns errors. +%Errors: Returns errors. \begin{funcdecl}{process_key}{krb5_error_code}{\funcvoid} \funcarg{krb5_encrypt_block *}{eblock} @@ -65,7 +65,7 @@ function if the key is needed in raw form by the encryption routine.] The caller may not move or reallocate \funcparam{keyblock} before calling \funcname{finish_key} on \funcparam{eblock}. -Returns errors. +%Errors: Returns errors. \begin{funcdecl}{finish_key}{krb5_error_code}{\funcvoid} \funcarg{krb5_encrypt_block *}{eblock} @@ -73,7 +73,7 @@ Returns errors. Does any necessary clean-up on \funcparam{eblock} (such as releasing resources held by \funcparam{eblock{\ptsto}priv}. -Returns errors. +%Errors: Returns errors. \begin{funcdecl}{string_to_key}{krb5_error_code}{\funcvoid} \funcarg{const krb5_keytype}{keytype} @@ -93,7 +93,7 @@ algorithm. If the particular function called does not know how to make a key of type \funcparam{keytype}, an error may be returned. -Returns errors. +%Errors: Returns errors. \begin{funcdecl}{init_random_key}{krb5_error_code}{\funcvoid} \funcarg{const krb5_keyblock *}{seedblock} @@ -140,3 +140,25 @@ In addition to the above listed function entry points, each encryption system should have an entry in \globalname{krb5_csarray} and a \datatype{krb5_cryptosystem_entry} structure describing the entry points and key and padding sizes for the encryption system. + +\subsection{DES functions} +The DES functions conform to the encryption interface required by the +Kerberos version 5 library, and provide an encryption mechanism based on +the DES Cipher-block chaining mode (CBC), with the addition of a +cyclical redundancy check (CRC-32) for integrity checking upon +decryption. + +The functions have the same signatures as those described by the main +library document; the names are: +{\obeylines +\funcname{mit_des_encrypt_func} +\funcname{mit_des_decrypt_func} +\funcname{mit_des_process_key} +\funcname{mit_des_finish_key} +\funcname{mit_des_string_to_key} +\funcname{mit_des_init_random_key} +\funcname{mit_des_finish_random_key} +\funcname{mit_des_random_key} +} +The \datatype{krb5_cryptosystem_entry} for this cryptosystem is +\globalname{mit_des_cryptosystem_entry}. diff --git a/doc/implement/kdb-i.tex b/doc/implement/kdb-i.tex index fb9ac801ed..dc81971bbe 100644 --- a/doc/implement/kdb-i.tex +++ b/doc/implement/kdb-i.tex @@ -7,8 +7,8 @@ manipulation tools. \funcarg{char *}{name} \end{funcdecl} -Set the name of the database to \funcparam{name}. If it doesn't exist, -an error code is returned. +Set the name of the database to \funcparam{name}. +%Errors: If it doesn't exist, an error code is returned. Must be called before \funcname{krb5_db_init} or after \funcname{krb5_db_fini}; must not be called while db functions are active. @@ -40,7 +40,7 @@ Called before using \funcname{krb5_db_get_principal}, Does any required initialization. -Errors: init errors, system errors. +%Errors: init errors, system errors. \begin{funcdecl}{krb5_db_fini}{krb5_error_code}{\funcvoid} \end{funcdecl} @@ -48,7 +48,7 @@ Errors: init errors, system errors. Called after all database operations are complete, to perform any required clean-up. -Errors: sysytem errors. +%Errors: sysytem errors. \begin{funcdecl}{krb5_db_get_age}{krb5_error_code}{\funcin} @@ -63,7 +63,7 @@ default database if \funcname{db_name} is NULL). \funcparam{*age} is filled in in local system time units, and represents the last modification time of the database. -Errors: system errors. +%Errors: system errors. \begin{funcdecl}{krb5_db_create}{krb5_error_code}{\funcin} @@ -74,7 +74,7 @@ Creates a new database named \funcname{db_name}. Will not create a database by that name if it already exists. The database must be populated by the caller by using \funcname{krb5_db_put_principal}. -Errors: db exists, system errors. +%Errors: db exists, system errors. \begin{funcdecl}{krb5_db_rename}{krb5_error_code}{\funcin} \funcarg{char *}{source} @@ -84,7 +84,7 @@ Renames the database \funcarg{source} to \funcarg{dest} Any database named \funcarg{dest} is destroyed. -Errors: system errors. +%Errors: system errors. \begin{funcdecl}{krb5_db_get_principal}{krb5_error_code}{\funcin} \funcarg{krb5_principal}{searchfor} @@ -135,7 +135,7 @@ Stores the \funcparam{*nentries} principal structures pointed to by acutally stored; the first \funcparam{*nentries} records will have been stored in the database. -Returns error code if not all entries were stored. +%Errors: Returns error code if not all entries were stored. \begin{funcdecl}{krb5_db_iterate}{krb5_error_code}{\funcin} \funcfuncarg{krb5_error_code}{(*func)} @@ -150,7 +150,8 @@ and calling \funcparam{(*func)}(\funcparam{iterate_arg}, \funcparam{principal}) where \funcparam{principal} points to a record from the database. -If \funcparam{(*func)}() ever returns an error code, the iteration is +If \funcparam{(*func)}() ever returns an error code, the iteration +should be aborted and that error code is returned by this function. \begin{funcdecl}{krb5_db_store_mkey}{krb5_error_code}{\funcin} diff --git a/doc/implement/keytab-i.tex b/doc/implement/keytab-i.tex index a10e40fd41..697728721c 100644 --- a/doc/implement/keytab-i.tex +++ b/doc/implement/keytab-i.tex @@ -1,33 +1,67 @@ The key table functions deal with storing and retrieving service keys for use by unattended services which participate in authentication exchanges. -Keytab routines should all be atomic. Every routine that acquires -a non-sharable resource must release it before it returns. For -example, an implementation is not allowed to leave a file open -for writing or to have a lock on a file. - -Any keytab implementations must support multiple concurrent sequential scans. - -The order of values returned from \funcname{krb5_kt_next_entry} is +Keytab routines should all be atomic. Before a routine returns it +must make sure that all non-sharable resources it acquires are +released and in a consistent state. For example, an implementation is not +allowed to leave a file open for writing or to have a lock on a file. + +Note that all keytab implementations must support multiple concurrent +sequential scans. Another detail to note is that +the order of values returned from \funcname{get_next} is unspecified and may be sorted to the implementor's convenience. -Although the ``right thing'' should happen if the program aborts -abnormally, a close routine is provided for freeing resources, -etc. People should use the close routine when they are -finished. - -\subsubsection{Per-type functions} -The following entry points must be implemented for each type of -key table; however, application programs are not expected to call -\funcname{krb5_kt_resolve_internal}, \funcname{krb5_kt_remove_internal}, -or \funcname{krb5_kt_add_internal} directly. +\subsubsection{The krb5_kt_ops structure} +In order to implement a new key table type, the programmer should +declare a {\bf krb5_kt_ops} structure, and fill in the elements of the +structure appropriately, by implementing each of the key table +functions for the new key table type. In order to reduce the size of binary programs when static linking is used, it is common to provide two \datatype{krb5_kt_ops} structures for each key table type, one for reading only in which the pointers to the add and delete functions are zero, and one for reading and writing. -\begin{funcdecl}{krb5_kt_resolve_internal}{krb5_error_code}{\funcin} +\begin{verbatim} +typedef struct _krb5_kt_ops { + char *prefix; + /* routines always present */ + krb5_error_code (*resolve)((char *, + krb5_keytab *)); + krb5_error_code (*get_name)((krb5_keytab, + char *, + int)); + krb5_error_code (*close)((krb5_keytab)); + krb5_error_code (*get)((krb5_keytab, + krb5_principal, + krb5_kvno, + krb5_keytab_entry *)); + krb5_error_code (*start_seq_get)((krb5_keytab, + krb5_kt_cursor *)); + krb5_error_code (*get_next)((krb5_keytab, + krb5_keytab_entry *, + krb5_kt_cursor *)); + krb5_error_code (*end_get)((krb5_keytab, + krb5_kt_cursor *)); + /* routines to be included on extended version (write routines) */ + krb5_error_code (*add)((krb5_keytab, + krb5_keytab_entry *)); + krb5_error_code (*remove)((krb5_keytab, + krb5_keytab_entry *)); +} krb5_kt_ops; +\end{verbatim} + +\subsubsection{Per-type functions that are always present} +The following entry points must be implemented for each type of +key table. However, \funcname{resolve}, \funcname{remove} and +\funcname{add} are only called by the key table glue code. +They are not called directly by the application. + + however, application programs are not expected to call +\funcname{resolve}, \funcname{remove}, +or \funcname{add} directly. + +\begin{funcdecl}{resolve}{krb5_error_code}{\funcin} \funcarg{char *}{residual} \funcout \funcarg{krb5_keytab *}{id} @@ -37,7 +71,7 @@ Fills in \funcparam{*id} with a handle identifying the keytab with name ``residual''. The interpretation of ``residual'' is dependent on the type of keytab. -\begin{funcdecl}{krb5_kt_get_name}{krb5_error_code}{\funcin} +\begin{funcdecl}{get_name}{krb5_error_code}{\funcin} \funcarg{krb5_keytab}{id} \funcout \funcarg{char *}{name} @@ -50,7 +84,7 @@ 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}{close}{krb5_error_code}{\funcin} \funcarg{krb5_keytab}{id} \end{funcdecl} @@ -60,7 +94,7 @@ the key table. Requires that \funcparam{id} identifies a valid credentials cache. -\begin{funcdecl}{krb5_kt_get_entry}{krb5_error_code}{\funcin} +\begin{funcdecl}{get}{krb5_error_code}{\funcin} \funcarg{krb5_keytab}{id} \funcarg{krb5_principal}{principal} \funcarg{krb5_kvno}{vno} @@ -73,20 +107,21 @@ principal matches \funcparam{principal} and whose key version number matches \funcparam{vno}. If \funcparam{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 \funcparam{*entry}; its contents should -be deallocated by calling \funcname{krb5_kt_free_entry} when no longer -needed. +%Errors: +This routine should return an error code if no suitable entry is +found. If an entry is found, the entry is returned in +\funcparam{*entry}; its contents should be deallocated by calling +\funcname{close} when no longer needed. -\begin{funcdecl}{krb5_kt_free_entry}{krb5_error_code}{\funcinout} +\begin{funcdecl}{close}{krb5_error_code}{\funcinout} \funcarg{krb5_keytab_entry *}{entry} \end{funcdecl} 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}. +to a structure previously filled in by \funcname{get} or +\funcname{get_next}. -\begin{funcdecl}{krb5_kt_start_seq_get}{krb5_error_code}{\funcin} +\begin{funcdecl}{start_seq_get}{krb5_error_code}{\funcin} \funcarg{krb5_keytab}{id} \funcout \funcarg{krb5_kt_cursor *}{cursor} @@ -95,9 +130,9 @@ to a structure previously filled in by \funcname{krb5_kt_get_entry} or Prepares to read sequentially every key in the keytab identified by \funcparam{id}. \funcparam{cursor} is filled in with a cursor to be used in calls to -\funcname{krb5_kt_next_entry}. +\funcname{get_next}. -\begin{funcdecl}{krb5_kt_next_entry}{krb5_error_code}{\funcin} +\begin{funcdecl}{get_next}{krb5_error_code}{\funcin} \funcarg{krb5_keytab}{id} \funcout \funcarg{krb5_keytab_entry *}{entry} @@ -107,18 +142,21 @@ Prepares to read sequentially every key in the keytab identified by Fetches the ``next'' entry in the keytab, returning it in \funcparam{*entry}, and updates \funcparam{*cursor} for the next -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}. +request. If the keytab changes during the sequential get, an error +must be +%Errors: +guaranteed. \funcparam{*entry} should be freed after use by +calling +\funcname{close}. Requires that \funcparam{id} identifies a valid credentials cache. and \funcparam{*cursor} be a cursor returned by -\funcname{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. +\funcname{start_seq_get} or a subsequent call to +\funcname{get_next}. -Errors: error code if no more cache entries or if the keytab changes. +%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}{end_get}{krb5_error_code}{\funcin} \funcarg{krb5_keytab}{id} \funcarg{krb5_kt_cursor *}{cursor} \end{funcdecl} @@ -128,23 +166,14 @@ which must never be re-used after this call. Requires that \funcparam{id} identifies a valid credentials cache. and \funcparam{*cursor} be a cursor returned by -\funcname{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. +\funcname{start_seq_get} or a subsequent call to +\funcname{get_next}. -May return error code if \funcparam{cursor} is invalid. - -\begin{funcdecl}{krb5_kt_remove_internal}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Searches the keytab \funcparam{id} for an entry that exactly matches -\funcparam{entry}. If one is found, it is removed from the keytab. +%Errors: May return error code if \funcparam{cursor} is invalid. -Returns an error code if not found. +\subsubsection{Per-type functions to be included for write routines} - -\begin{funcdecl}{krb5_kt_add_internal}{krb5_error_code}{\funcin} +\begin{funcdecl}{add}{krb5_error_code}{\funcin} \funcarg{krb5_keytab}{id} \funcarg{krb5_keytab_entry *}{entry} \end{funcdecl} @@ -158,93 +187,18 @@ For example, in a UNIX file-based implementation, this routine (or the part of the underlying implementation that it calls) would be responsible for doing an \funcname{fsync} on the file before returning. -Returns an error code if \funcparam{entry} is already present in the -keytab or if the key could not be stored (quota problem, etc). - - -\subsubsection{Glue functions} -The following functions are implemented in the base library and serve to -glue together the various types of key tables. - -\begin{funcdecl}{krb5_kt_register}{krb5_error_code}{\funcin} -\funcarg{krb5_kt_ops *}{ops} -\end{funcdecl} - - -Adds a new ticket cache type to the set recognized by -\funcname{krb5_kt_resolve}. -Requires that a keytab type named \funcparam{ops{\ptsto}prefix} is not -yet known. +%Errors: +This routine should return an error code if \funcparam{entry} is +already present in the keytab or if the key could not be stored (quota +problem, etc). -An error is returned if \funcparam{ops{\ptsto}prefix} is already known. - -\begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcin} -\funcarg{const char *}{string_name} -\funcout -\funcarg{krb5_keytab *}{id} -\end{funcdecl} - -Fills in \funcparam{*id} with a handle identifying the keytab with name -``string_name''. The keytab is not opened. -Requires that \funcparam{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}{\funcin} -\funcarg{char *}{name} -\funcarg{int}{namesize} -\end{funcdecl} - -\funcparam{name} is filled in with the first \funcparam{namesize} bytes of -the name of the default keytab. -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} -\funcarg{krb5_keytab *}{id} -\end{funcdecl} - -Fills in \funcparam{id} with a handle identifying the default keytab. - -\begin{funcdecl}{krb5_kt_read_service_key}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcout -\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. -The keytab is opened and searched for the entry identified by -\funcparam{principal} and \funcparam{vno}, returning the resulting key -in \funcparam{*key} or returning an error code if it is not found. - -\funcname{krb5_free_keyblock} should be called on \funcparam{*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}{\funcin} +\begin{funcdecl}{remove}{krb5_error_code}{\funcin} \funcarg{krb5_keytab}{id} \funcarg{krb5_keytab_entry *}{entry} \end{funcdecl} -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. +Searches the keytab \funcparam{id} for an entry that exactly matches +\funcparam{entry}. If one is found, it is removed from the keytab. -\begin{funcdecl}{krb5_kt_remove_entry}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} +%Errors: Returns an error code if not found. -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. diff --git a/doc/implement/libos-i.tex b/doc/implement/libos-i.tex index 5063b57233..cdd4861ff3 100644 --- a/doc/implement/libos-i.tex +++ b/doc/implement/libos-i.tex @@ -32,346 +32,3 @@ for password reading. \end{description} -\begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin} -\funcarg{char *}{prompt} -\funcarg{char *}{prompt2} -\funcout -\funcarg{char *}{return_pwd} -\funcinout -\funcarg{int *}{size_return} -\end{funcdecl} - -Read a password from the keyboard. The first \funcparam{*size_return} -bytes of the password entered are returned in \funcparam{return_pwd}. -If fewer than \funcparam{*size_return} bytes are typed as a password, -the remainder of \funcparam{return_pwd} is zeroed. Upon success, the -total number of bytes filled in is stored in \funcparam{*size_return}. - -\funcparam{prompt} is used as the prompt for the first reading of a password. -It is printed to the terminal, and then a password is read from the -keyboard. No newline or spaces are emitted between the prompt and the -cursor, unless the newline/space is included in the prompt. - -If \funcparam{prompt2} is a null pointer, then the password is read -once. If \funcparam{prompt2} is set, then it is used as a prompt to -read another password in the same manner as described for -\funcparam{prompt}. After the second password is read, the two -passwords are compared, and an error is returned if they are not -identical. - -Echoing is turned off when the password is read. - -If there is an error in reading or verifying the password, an error code -is returned; else zero is returned. - -\begin{funcdecl}{krb5_lock_file}{krb5_error_code}{\funcvoid} -\funcarg{FILE *}{filep} -\funcarg{char *}{pathname} -\funcarg{int}{mode} -\end{funcdecl} - -Attempts to lock the file in the given \funcparam{mode}; returns 0 for a -successful lock, or an error code otherwise. - -The caller should arrange that both \funcparam{filep} and -\funcparam{pathname} refer to the same -file. The implementation may use whichever is more convenient. - -Modes are given in {\tt } - - -\begin{funcdecl}{krb5_unlock_file}{krb5_error_code}{\funcvoid} -\funcarg{FILE *}{filep} -\funcarg{char *}{pathname} -\end{funcdecl} - -Attempts to (completely) unlock the file. Returns 0 if successful, -or an error code otherwise. - -The caller should arrange that both \funcparam{filep} and -\funcparam{pathname} refer to the same file. The implementation may -use whichever is more convenient. - -\begin{funcdecl}{krb5_create_secure_file}{krb5_error_code}{\funcin} -\funcarg{const char *}{pathname} -\end{funcdecl} - -Creates a file named pathname which can only be read by the current -user. - -\begin{funcdecl}{krb5_sync_disk_file}{krb5_error_code}{\funcin} -\funcarg{FILE *}{fp} -\end{funcdecl} - -Assures that the changes made to the file pointed to by the file -handle -fp are forced out to disk. - -\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcout} -\funcarg{krb5_int32 *}{timeret} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcout} -\funcarg{krb5_int32 *}{seconds} -\funcarg{krb5_int32 *}{microseconds} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -The seconds portion is returned in \funcparam{*seconds}, the -microseconds portion in \funcparam{*microseconds}. - -\begin{funcdecl}{krb5_net_read}{int}{\funcin} -\funcarg{int}{fd} -\funcout -\funcarg{char *}{buf} -\funcin -\funcarg{int}{len} -\end{funcdecl} - -Like read(2), but guarantees that it reads as much as was requested -or returns -1 and sets errno. - -(make sure your sender will send all the stuff you are looking for!) -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_net_write}{int}{\funcin} -\funcarg{int}{fd} -\funcarg{const char *}{buf} -\funcarg{int}{len} -\end{funcdecl} - -Like write(2), but guarantees that it writes as much as was requested -or returns -1 and sets errno. - -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_write_message}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{fd} -\funcarg{krb5_data *}{data} -\end{funcdecl} - - -\funcname{krb5_write_message} writes data to the network as a message, -using the network connection pointed to by \funcparam{fd}. - -\begin{funcdecl}{krb5_read_message}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{fd} -\funcout -\funcarg{krb5_data *}{data} -\end{funcdecl} - -Reads data from the network as a message, using the network connection -pointed to by fd. - -\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcout} -\funcarg{krb5_address ***}{addr} -\end{funcdecl} - -Return all the protocol addresses of this host. - -Compile-time configuration flags will indicate which protocol family -addresses might be returned. -\funcparam{*addr} is filled in to point to an array of address pointers, -terminated by a null pointer. All the storage pointed to is allocated -and should be freed by the caller with \funcname{krb5_free_address} -when no longer needed. - - -\begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{send} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{krb5_data *}{receive} -\end{funcdecl} - -Send the message \funcparam{send} to a KDC for realm \funcparam{realm} and -return the response (if any) in \funcparam{receive}. - -If the message is sent and a response is received, 0 is returned, -otherwise an error code is returned. - -The storage for \funcparam{receive} is allocated and should be freed by -the caller when finished. - -\begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{char ***}{hostlist} -\end{funcdecl} - -Figures out the Kerberos server names for the given \funcparam{realm}, -filling in \funcparam{hostlist} with a null terminated array of -pointers to hostnames. - -If \funcparam{realm} is unknown, the filled-in pointer is set to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_krbhst}{krb5_error_code}{\funcin} -\funcarg{char * const *}{hostlist} -\end{funcdecl} - -Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}. - -\begin{funcdecl}{krb5_aname_to_localname}{krb5_error_code}{\funcin} -\funcarg{krb5_const_principal}{aname} -\funcarg{int}{lnsize} -\funcout -\funcarg{char *}{lname} -\end{funcdecl} - -Converts a principal name \funcparam{aname} to a local name suitable for use by -programs wishing a translation to an environment-specific name (e.g. -user account name). - -\funcparam{lnsize} specifies the maximum length name that is to be filled into -\funcparam{lname}. -The translation will be null terminated in all non-error returns. - -Returns system errors. - -\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code} -\funcout -\funcarg{char **}{lrealm} -\end{funcdecl} - -Retrieves the default realm to be used if no user-specified realm is -available (e.g. to interpret a user-typed principal name with the -realm omitted for convenience), filling in \funcparam{lrealm} with a -pointer to the default realm in allocated storage. - -It is the caller's responsibility for freeing the allocated storage -pointed to be \funcparam{lream} when it is finished with it. - -Returns system errors. - -\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin} -\funcarg{const char *}{host} -\funcout -\funcarg{char ***}{realmlist} -\end{funcdecl} - -Figures out the Kerberos realm names for \funcparam{host}, filling in -\funcparam{realmlist} with a -pointer to an argv[] style list of names, terminated with a null pointer. - -If \funcparam{host} is NULL, the local host's realms are determined. - -If there are no known realms for the host, the filled-in pointer is set -to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_host_realm}{krb5_error_code}{\funcin} -\funcarg{char * const *}{realmlist} -\end{funcdecl} - -Frees the storage taken by a \funcparam{realmlist} returned by -\funcname{krb5_get_local_realm}. - -\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin} -\funcarg{krb5_principal}{principal} -\funcarg{const char *}{luser} -\end{funcdecl} - -Given a Kerberos principal \funcparam{principal}, and a local username -\funcparam{luser}, -determine whether user is authorized to login to the account \funcparam{luser}. -Returns TRUE if authorized, FALSE if not authorized. - -\begin{funcdecl}{krb5_random_confounder}{krb5_error_code}{\funcin} -\funcarg{int}{size} -\funcout -\funcarg{krb5_pointer}{fillin} -\end{funcdecl} - -Given a length and a pointer, fills in the area pointed to by -\funcparam{fillin} with \funcparam{size} random octets suitable for use -in a confounder. - -\begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin} -\funcarg{const krb5_address *}{adr} -\funcarg{krb5_const_pointer}{ptr} -\funcout -\funcarg{krb5_address **}{outaddr} -\end{funcdecl} - -Given an address \funcparam{adr} and an additional address-type specific -portion pointed to by -\funcparam{port} this routine -combines them into a freshly-allocated -\datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} and fills in -\funcparam{*outaddr} to point to this address. For IP addresses, -\funcparam{ptr} should point to a network-byte-order TCP or UDP port -number. Upon success, \funcparam{*outaddr} will point to an allocated -address which should be freed with \funcname{krb5_free_address}. - -\begin{funcdecl}{krb5_gen_replay_name}{krb5_error_code}{\funcin} -\funcarg{const krb5_address *}{inaddr} -\funcarg{const char *}{uniq} -\funcout -\funcarg{char **}{string} -\end{funcdecl} - -Given a \datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} -in \funcparam{inaddr}, this function unpacks its component address and -additional type, and uses them along with \funcparam{uniq} to allocate a -fresh string to represent the address and additional information. The -string is suitable for use as a replay cache tag. This string is -allocated and should be freed with \funcname{free} when the caller has -finished using it. When using IP addresses, the components in -\funcparam{inaddr\ptsto contents} must be of type -\datatype{ADDRTYPE_INET} and \datatype{ADDRTYPE_PORT}. - -\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin} -\funcarg{const char *}{hostname} -\funcarg{const char *}{sname} -\funcarg{krb5_int32}{type} -\funcout -\funcarg{krb5_principal *}{ret_princ} -\end{funcdecl} - -Given a hostname \funcparam{hostname} and a generic service name -\funcparam{sname}, this function generates a full principal name to be -used when authenticating with the named service on the host. The full -prinicpal name is returned in \funcparam{ret_princ}. - -The realm of the -principal is determined internally by calling \funcname{krb5_get_host_realm}. - -The \funcparam{type} argument controls how -\funcname{krb5_sname_to_principal} generates the principal name, -\funcparam{ret_princ}, for the named service, \funcparam{sname}. -Currently, two values are supported: KRB5_NT_SRV_HOST, and -KRB5_NT_UNKNOWN. - -If \funcparam{type} is set to -KRB5_NT_SRV_HOST, the hostname will be -canonicalized, i.e. a fully qualified lowercase hostname using -the primary name and the domain name, before \funcparam{ret_princ} is -generated in the form -"sname/hostname@LOCAL.REALM." Most applications should use -KRB5_NT_SRV_HOST. - -However, if \funcparam{type} is set to KRB5_NT_UNKNOWN, -while the generated principal name will have the form -"sname/hostname@LOCAL.REALM" the hostname will not be canonicalized -first. It will appear exactly as it was passed in \funcparam{hostname}. - -The caller should release \funcparam{ret_princ}'s storage by calling -\funcname{krb5_free_principal} when it is finished with the principal. diff --git a/doc/implement/rcache-i.tex b/doc/implement/rcache-i.tex index 86b35a3094..e00a639daa 100644 --- a/doc/implement/rcache-i.tex +++ b/doc/implement/rcache-i.tex @@ -2,17 +2,51 @@ The replay cache functions deal with verifying that AP_REQ's do not contain duplicate authenticators; the storage must be non-volatile for the site-determined validity period of authenticators. -Each replay cache has a string ``name'' associated with it. The use of +Each replay cache has a string {\bf name} associated with it. The use of this name is dependent on the underlying caching strategy (for file-based things, it would be a cache file name). The caching strategy should use non-volatile storage so that replay integrity can be maintained across system failures. +\subsubsection{The krb5_rc_ops structure} +In order to implement a new replay cache type, the programmer should +declare a {\bf krb5_rc_ops} structure, and fill in the elements of the +structure appropriately, by implementing each of the replay cache +functions for the new replay cache type. + +The prefix element specifies the prefix {bf name} of the the new replay +cache type. For example, if the prefix {\bf name} is ``dfl'', then if the +program calls \funcname{krb5_rc_resolve} with a credential cache name +such as ``dfl:host'', then \funcname{krb5_rc_resolve} +will call the resolve function (as defined by the {\bf krb5_rc_ops} +structure where the prefix element is ``dfl'') and pass it the +argument ``host''. + +Before a new replay cache type can be recognized by +\funcname{krb5_rc_resolve}, it must be registered with the Kerberos +library by calling \funcname{krb5_rc_register}. + +\begin{verbatim} +typedef struct _krb5_rc_ops { + char *type; + krb5_error_code (*init)((krb5_rcache,krb5_deltat)); + krb5_error_code (*recover)((krb5_rcache)); + krb5_error_code (*destroy)((krb5_rcache)); + krb5_error_code (*close)((krb5_rcache)); + krb5_error_code (*store)((krb5_rcache,krb5_donot_replay *)); + krb5_error_code (*expunge)((krb5_rcache)); + krb5_error_code (*get_span)((krb5_rcache,krb5_deltat *)); + char *(*get_name)((krb5_rcache)); + krb5_error_code (*resolve)((krb5_rcache, char *)); +} krb5_rc_ops; +\end{verbatim} + + \subsubsection{Per-type functions} The following entry points must be implemented for each type of -credentials cache. +replay cache. -\begin{funcdecl}{krb5_rc_initialize}{krb5_error_code}{\funcin} +\begin{funcdecl}{init}{krb5_error_code}{\funcin} \funcarg{krb5_rcache}{id} \funcarg{krb5_deltat}{auth_lifespan} \end{funcdecl} @@ -21,26 +55,26 @@ Creates/refreshes the replay cache identified by \funcparam{id} and sets its authenticator lifespan to \funcparam{auth_lifespan}. If the replay cache already exists, its contents are destroyed. -Errors: permission errors, system errors +%Errors: permission errors, system errors -\begin{funcdecl}{krb5_rc_recover}{krb5_error_code}{\funcin} +\begin{funcdecl}{recover}{krb5_error_code}{\funcin} \funcarg{krb5_rcache}{id} \end{funcdecl} Attempts to recover the replay cache \funcparam{id}, (presumably after a system crash or server restart). -Errors: error indicating that no cache was found to recover +%Errors: error indicating that no cache was found to recover -\begin{funcdecl}{krb5_rc_destroy}{krb5_error_code}{\funcin} +\begin{funcdecl}{destroy}{krb5_error_code}{\funcin} \funcarg{krb5_rcache}{id} \end{funcdecl} Destroys the replay cache \funcparam{id}. Requires that \funcparam{id} identifies a valid replay cache. -Errors: permission errors. +%Errors: permission errors. -\begin{funcdecl}{krb5_rc_close}{krb5_error_code}{\funcin} +\begin{funcdecl}{close}{krb5_error_code}{\funcin} \funcarg{krb5_rcache}{id} \end{funcdecl} @@ -48,9 +82,9 @@ Closes the replay cache \funcparam{id}, invalidates \funcparam{id}, and releases any other resources acquired during use of the replay cache. Requires that \funcparam{id} identifies a valid replay cache. -Errors: permission errors +%Errors: permission errors -\begin{funcdecl}{krb5_rc_store}{krb5_error_code}{\funcin} +\begin{funcdecl}{store}{krb5_error_code}{\funcin} \funcarg{krb5_rcache}{id} \funcarg{krb5_donot_replay *}{rep} \end{funcdecl} @@ -60,7 +94,7 @@ Requires that \funcparam{id} identifies a valid replay cache. 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} +\begin{funcdecl}{expunge}{krb5_error_code}{\funcin} \funcarg{krb5_rcache}{id} \end{funcdecl} Removes all expired replay information (i.e. those entries which are @@ -68,9 +102,9 @@ older than then authenticator lifespan of the cache) from the cache \funcparam{id}. Requires that \funcparam{id} identifies a valid replay cache. -Errors: permission errors. +%Errors: permission errors. -\begin{funcdecl}{krb5_rc_get_lifespan}{krb5_error_code}{\funcin} +\begin{funcdecl}{get_span}{krb5_error_code}{\funcin} \funcarg{krb5_rcache}{id} \funcout \funcarg{krb5_deltat *}{auth_lifespan} @@ -79,7 +113,7 @@ Fills in \funcparam{auth_lifespan} with the lifespan of the cache \funcparam{id}. Requires that \funcparam{id} identifies a valid replay cache. -\begin{funcdecl}{krb5_rc_resolve}{krb5_error_code}{\funcinout} +\begin{funcdecl}{resolve}{krb5_error_code}{\funcinout} \funcarg{krb5_rcache}{id} \funcin \funcarg{char *}{name} @@ -91,12 +125,12 @@ be called before the other per-replay cache functions. Requires that \funcparam{id} points to allocated space, with an initialized \funcparam{id{\ptsto}ops} field. -Since \funcname{krb5_rc_resolve} allocates memory, -\funcname{krb5_rc_close} must be called to free the allocated memory, -even if neither \funcname{krb5_rc_initialize} or -\funcname{krb5_rc_recover} were successfully called by the application. +Since \funcname{resolve} allocates memory, +\funcname{close} must be called to free the allocated memory, +even if neither \funcname{init} or +\funcname{recover} were successfully called by the application. -Returns: allocation errors. +%Returns: allocation errors. \begin{funcdecl}{krb5_rc_get_name}{char *}{\funcin} @@ -106,50 +140,3 @@ Returns: allocation errors. Returns the name (excluding the type) of the rcache \funcparam{id}. Requires that \funcparam{id} identifies a valid replay cache. -\subsubsection{Glue functions} -The following functions are implemented in the base library and serve to -glue together the various types of replay caches. - -\begin{funcdecl}{krb5_rc_resolve_full}{krb5_error_code}{\funcinout} -\funcarg{krb5_rcache *}{id} -\funcin -\funcarg{char *}{string_name} -\end{funcdecl} - -\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. - -Errors: error if cannot resolve name. - -\begin{funcdecl}{krb5_rc_register_type}{krb5_error_code}{\funcin} -\funcarg{krb5_rc_ops *}{ops} -\end{funcdecl} -Adds a new replay cache type implemented and identified by -\funcparam{ops} to the set recognized by -\funcname{krb5_rc_resolve}. Requires that a ticket cache type named -\funcparam{ops{\ptsto}prefix} is not yet known. - - -\begin{funcdecl}{krb5_rc_default_name}{char *}{\funcvoid} -\end{funcdecl} -Returns the name of the default replay cache; this may be equivalent to -\funcnamenoparens{getenv}({\tt "KRB5RCACHE"}) with an appropriate fallback. - -\begin{funcdecl}{krb5_rc_default_type}{char *}{\funcvoid} -\end{funcdecl} - -Returns the type of the default replay cache. - -\begin{funcdecl}{krb5_rc_default}{krb5_error_code}{\funcinout} -\funcarg{krb5_rcache *}{id} -\end{funcdecl} - -Equivalent to: -\begin{verbatim} -krb5_rc_resolve_full(id, - strcat(strcat(krb5_rc_default_type(),``:''), - krb5_rc_default_name)) ; -\end{verbatim} -Except of course you can't do the strcat's with the return values. -- cgit