diff options
| -rw-r--r-- | doc/implement/Makefile | 38 | ||||
| -rw-r--r-- | doc/implement/ccache-i.tex | 224 | ||||
| -rw-r--r-- | doc/implement/cksum-i.tex | 31 | ||||
| -rw-r--r-- | doc/implement/crc-32-i.tex | 20 | ||||
| -rw-r--r-- | doc/implement/encrypt-i.tex | 164 | ||||
| -rw-r--r-- | doc/implement/fancyheadings.sty | 233 | ||||
| -rw-r--r-- | doc/implement/fixunder.sty | 48 | ||||
| -rw-r--r-- | doc/implement/functions.sty | 70 | ||||
| -rw-r--r-- | doc/implement/implement.tex | 94 | ||||
| -rw-r--r-- | doc/implement/kdb-i.tex | 242 | ||||
| -rw-r--r-- | doc/implement/keytab-i.tex | 204 | ||||
| -rw-r--r-- | doc/implement/libos-i.tex | 34 | ||||
| -rw-r--r-- | doc/implement/rcache-i.tex | 142 |
13 files changed, 0 insertions, 1544 deletions
diff --git a/doc/implement/Makefile b/doc/implement/Makefile deleted file mode 100644 index 4c5116132..000000000 --- a/doc/implement/Makefile +++ /dev/null @@ -1,38 +0,0 @@ -.SUFFIXES: .tex .dvi .ps - -STYLES= fixunder.sty functions.sty -LIBTEX= implement.tex ccache-i.tex rcache-i.tex keytab-i.tex libos-i.tex \ - kdb-i.tex encrypt-i.tex cksum-i.tex crc-32-i.tex implement.ind - - -all: implement.ps - - -implement.ps: implement.dvi - -# hard to capture two-pass semantics in Makefiles... -# implement.ind: implement.dvi -implement.ind: implement.idx - makeindex implement.idx - -implement.idx: - touch implement.ind - latex implement.tex - rm implement.ind - -clean: - rm -f *.toc *.log *.idx *.ind *.aux *.ilg - -really-clean: clean - rm -f *.dvi *.ps - - -implement.dvi: $(LIBTEX) $(STYLES) - -.tex.dvi: - latex $* - - -.dvi.ps: - dvips $*.dvi -o - diff --git a/doc/implement/ccache-i.tex b/doc/implement/ccache-i.tex deleted file mode 100644 index 66d7b61bf..000000000 --- a/doc/implement/ccache-i.tex +++ /dev/null @@ -1,224 +0,0 @@ -The credentials cache functions (some of which are macros which call to -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, \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}{resolve}{krb5_error_code}{\funcout} -\funcarg{krb5_ccache *}{id} -\funcin -\funcarg{char *}{residual} -\end{funcdecl} - -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}{gen_new}{krb5_error_code}{\funcout} -\funcarg{krb5_ccache *}{id} -\end{funcdecl} - -Creates a new credentials cache whose name is guaranteed to be -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}{init}{krb5_error_code}{\funcinout} -\funcarg{krb5_ccache}{id} -\funcin -\funcarg{krb5_principal}{primary_principal} -\end{funcdecl} - -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. - -Modifies: cache identified by \funcparam{id}. - -\begin{funcdecl}{destroy}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Destroys the credentials cache identified by \funcparam{id}, invalidates -\funcparam{id}, and releases any other resources acquired during use of -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. - -\begin{funcdecl}{close}{krb5_error_code}{\funcinout} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Closes the credentials cache \funcparam{id}, invalidates -\funcparam{id}, and releases \funcparam{id} and any other resources -acquired during use of 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. - - -\begin{funcdecl}{store}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -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. - -\begin{funcdecl}{retrieve}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{whichfields} -\funcarg{krb5_creds *}{mcreds} -\funcout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Searches the cache \funcparam{id} for credentials matching -\funcparam{mcreds}. The fields which are to be matched are specified by -set bits in \funcparam{whichfields}, and always include the principal -name \funcparam{mcreds{\ptsto}server}. -Requires that \funcparam{id} identifies a valid credentials cache. - -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. - -\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{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}{get_first}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -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{get_next}. - -\begin{funcdecl}{get_next}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_creds *}{creds} -\funcinout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -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{get_first} or a subsequent call to -\funcname{get_next}. - -%Errors: error code if no more cache entries. - -\begin{funcdecl}{end_get}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Finishes sequential processing mode and invalidates \funcparam{*cursor}. -\funcparam{*cursor} 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{get_first} or a subsequent call to -\funcname{get_next}. - -%Errors: may return error code if \funcparam{*cursor} is invalid. - - -\begin{funcdecl}{remove_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{which} -\funcarg{krb5_creds *}{cred} -\end{funcdecl} - -Removes any credentials from \funcparam{id} which match the principal -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 -%couldn't delete. - -\begin{funcdecl}{set_flags}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\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>}. - - diff --git a/doc/implement/cksum-i.tex b/doc/implement/cksum-i.tex deleted file mode 100644 index c7f763738..000000000 --- a/doc/implement/cksum-i.tex +++ /dev/null @@ -1,31 +0,0 @@ -Kerberos v5 has the ability to use multiple checksum algorithms. Any -checksum implementation which desires to link with and be usable from the MIT -Kerberos v5 implementation must implement this interface: - -\subsection{Functional interface} - -\begin{funcdecl}{sum_func}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{in} -\funcarg{size_t}{in_length} -\funcarg{krb5_pointer}{seed} -\funcarg{size_t}{seed_length} -\funcout -\funcarg{krb5_checksum *}{outcksum} -\end{funcdecl} - -This routine computes the desired checksum over \funcparam{in_length} bytes -at \funcparam{in}. \funcparam{seed_length} bytes of a seed (usually an -encryption key) are pointed to by \funcparam{seed}. Some checksum -algorithms may choose to ignore \funcparam{seed}. If -\funcparam{seed_length} is zero, then there is no seed available. -The routine places the resulting value into \funcparam{outcksum{\ptsto}contents}. - -\funcparam{outcksum{\ptsto}contents} must be set by the caller to point -to enough storage to contain the checksum; the size necessary is an -element of the \datatype{krb5_checksum_entry} structure. - -\subsection{Other data elements} -In addition to the above listed function entry point, each checksum algorithm -should have an entry in \globalname{krb5_cksumarray} and a -\datatype{krb5_checksum_entry} structure describing the entry points -and checksum size for the algorithm. diff --git a/doc/implement/crc-32-i.tex b/doc/implement/crc-32-i.tex deleted file mode 100644 index c5d07a33d..000000000 --- a/doc/implement/crc-32-i.tex +++ /dev/null @@ -1,20 +0,0 @@ -The \libname{libcrc32.a} library provides an implementation of the -CRC-32 checksum algorithm which conforms to the interface required by -the Kerberos library. - -\begin{funcdecl}{crc32_sum_func}{static krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{in} -\funcarg{size_t}{in_length} -\funcarg{krb5_pointer}{seed} -\funcarg{size_t}{seed_length} -\funcout -\funcarg{krb5_checksum *}{outcksum} -\end{funcdecl} - -This routine computes a CRC-32 checksum over \funcparam{in_length} bytes -at \funcparam{in}, and places the resulting value into -\funcparam{outcksum{\ptsto}contents}. \funcparam{seed} is ignored. - -\funcparam{outcksum{\ptsto}contents} must be set by the caller to point -to at least 4 bytes of storage. - diff --git a/doc/implement/encrypt-i.tex b/doc/implement/encrypt-i.tex deleted file mode 100644 index 57e8c833a..000000000 --- a/doc/implement/encrypt-i.tex +++ /dev/null @@ -1,164 +0,0 @@ -Kerberos v5 has the ability to use multiple encryption systems. Any -encryption system which desires to link with and be usable from the MIT -Kerberos v5 implementation must implement at least this interface: - -\subsection{Functional interface} - -\begin{funcdecl}{encrypt_func}{krb5_error_code}{\funcvoid} -\funcarg{krb5_const_pointer}{in} -\funcarg{krb5_pointer}{out} -\funcarg{const size_t}{size} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{krb5_pointer}{ivec} -\end{funcdecl} -Encrypts \funcparam{size} bytes at \funcparam{in}, storing result in -\funcparam{out}. \funcparam{eblock} points to an encrypt block which -has been initialized by \funcname{process_key}. - -\funcparam{in} must include sufficient space beyond the \funcparam{size} -bytes of input data to hold pad and redundancy check bytes; the macro -\funcname{krb5_encrypt_size} can be used to compute this size. - -\funcparam{out} must be preallocated by the caller to contain sufficient -storage to hold the output; the macro \funcname{krb5_encrypt_size} can -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. - -%Errors: Returns errors. - -\begin{funcdecl}{decrypt_func}{krb5_error_code}{\funcvoid} -\funcarg{krb5_const_pointer}{in} -\funcarg{krb5_pointer}{out} -\funcarg{const size_t}{size} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{krb5_pointer}{ivec} -\end{funcdecl} -Decrypts \funcparam{size} bytes at \funcparam{in}, storing result in -\funcparam{out}. -\funcparam{eblock} points to an encrypt block which has been initialized -by \funcname{process_key}. - -\funcparam{size} must be a multiple of the encryption block size. - -\funcparam{out} must be preallocated by the caller to contain sufficient -storage to hold the output; this is guaranteed to be no more than -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. - -%Errors: Returns errors. - -\begin{funcdecl}{process_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_keyblock *}{keyblock} -\end{funcdecl} -Does any necessary key preprocessing (such as computing key -schedules for DES). -\funcparam{eblock{\ptsto}crypto_entry} must be set by the caller; the -other elements of \funcparam{eblock} are to be assigned by this function. -[In particular, \funcparam{eblock{\ptsto}key} must be set by this -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}. - -%Errors: Returns errors. - -\begin{funcdecl}{finish_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_encrypt_block *}{eblock} -\end{funcdecl} -Does any necessary clean-up on \funcparam{eblock} (such as releasing -resources held by \funcparam{eblock{\ptsto}priv}. - -%Errors: Returns errors. - -\begin{funcdecl}{string_to_key}{krb5_error_code}{\funcvoid} -\funcarg{const krb5_keytype}{keytype} -\funcarg{krb5_keyblock *}{keyblock} -\funcarg{const krb5_data *}{data} -\funcarg{const krb5_data}{salt} -\end{funcdecl} -Converts the string pointed to by \funcparam{data} into an encryption key -of type \funcparam{keytype}. \funcparam{*keyblock} is filled in with -the key info; in particular, \funcparam{keyblock{\ptsto}contents} is to -be set to allocated storage. It is the responsibility of the caller to -release this storage when the generated key no longer needed. - -The routine may use \funcparam{salt} to seed or alter the conversion -algorithm. - -If the particular function called does not know how to make a -key of type \funcparam{keytype}, an error may be returned. - -%Errors: Returns errors. - -\begin{funcdecl}{init_random_key}{krb5_error_code}{\funcvoid} -\funcarg{const krb5_keyblock *}{seedblock} -\funcarg{krb5_pointer *}{seed} -\end{funcdecl} - -Initialize the random key generator using the encryption key -\funcparam{seedblock} and allocating private sequence information, filling -in \funcparam{*seed} with the address of such information. -\funcparam{*seed} is to be passed to \funcname{random_key} to provide -sequence information. - -\begin{funcdecl}{finish_random_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_pointer *}{seed} -\end{funcdecl} - -Free any resources held by \funcparam{seed} and assigned by -\funcname{init_random_key}. - -\begin{funcdecl}{random_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_pointer *}{seed} -\funcarg{krb5_keyblock **}{keyblock} -\end{funcdecl} - -Generate a random encryption key, allocating storage for it and -filling in the keyblock address in \funcparam{*keyblock}. -When the caller has finished using the keyblock, he should call -\funcname{krb5_free_keyblock} to release its storage. - -%\begin{funcdecl}{combine_keys}{krb5_error_code}{\funcin} -%\funcarg{const krb5_keyblock *}{key1} -%\funcarg{const krb5_keyblock *}{key2} -%\funcout -%\funcarg{krb5_keyblock **}{outkey} -%\end{funcdecl} -%Combine the two encryption keys \funcparam{key1} and \funcparam{key2} to -%generate a new output key \funcparam{outkey}. \funcparam{outkey} is -%filled in to point to the freshly-allocated key. When the caller is -%finished using the \funcparam{*outkey}, it should be freed with -%\funcname{krb5_free_keyblock}. - -\subsection{Other data elements} -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/fancyheadings.sty b/doc/implement/fancyheadings.sty deleted file mode 100644 index a71de0fb5..000000000 --- a/doc/implement/fancyheadings.sty +++ /dev/null @@ -1,233 +0,0 @@ -% fancyheadings.sty version 1.0 -% Fancy headers and footers. -% Piet van Oostrum, Dept of Computer Science, University of Utrecht -% Padualaan 14, P.O. Box 80.089, 3508 TB Utrecht, The Netherlands -% Telephone: +31-30-531806. piet@cs.ruu.nl (mcvax!hp4nl!ruuinf!piet) -% March, 1989. - -% Here is a documentstylestyle option that allows you to customize your -% page headers and footers in an easy way. It combines features that were -% separately available in other pagestyles, without introducing much -% complexity. You can define: -% - three-part headers and footers -% - rules in header and footer -% - headers and footers wider than \textwidth -% - multiline headers and footers -% - separate headers and footers for even and odd pages -% - separate headers and footers for chapter pages -% -% To use this pagestyle, you must include the ``fancyheadings'' style -% option in your \documentstyle, and issue the \pagestyle{fancy} command. -% The \pagestyle{fancy} command should be issued after any changes made to -% \textwidth. -% -% The page layout will be as follows: -% -% LHEAD CHEAD RHEAD -% ----------------------------------- (rule) -% -% page body -% -% -% ----------------------------------- (rule) -% LFOOT CFOOT RFOOT -% -% The L-fields will be leftadjusted, the C-fields centered and the -% R-fields rightadjusted. -% Each of the six fields and the two rules can be defined separately. -% -% Simple use: -% -% The header and footer fields can be defined by commands \lhead{LHEAD} -% and so on for the other fields. If the field depends on something in the -% document (e.g. section titles) you must in general use the \markboth and -% \markright commands, otherwise a title may end on the wrong page. You -% can do this e.g. by redefining the commands \chaptermark, \sectionmark -% and so on (see example below). The defaults for these marks are as in -% the standard pagestyles. The marks can be put into a header or footer -% field by referencing \leftmark and \rightmark. -% -% Rules in header and footer -% -% The thickness of the rules below the header and above the footer can be -% changed by redefining the length parameters \headrulewidth (default -% 0.4pt) and \footrulewidth (default 0). These may be redefined by the -% \setlength command. A thickness of 0pt makes the rule invisible. -% If you want to make more complicated changes, you have to redefine the -% commands \headrule and/or \footrule. -% -% Headers and footers wider than \textwidth -% -% The headers and footers are set in a box of width \headwidth. The -% default for this is the value of \textwidth. You can make it wider (or -% smaller) by redefining \headwidth with the \setlength or \addtolength -% command. The headers and footers will stick out the page on the same -% side as the marginal notes. For example to include the marginal notes, -% add both \marginparsep and \marginparwidth to \headwidth (see also the -% example below). -% -% Multiline headers and footers -% -% Each of the six fields is set in an appropriate parbox, so you can put a -% multiline part in it with the \\ command. It is also possible to put -% extra space in it with the \vspace command. Note that if you do this you -% will probably have to increase the \headheight or \footskip lengths. -% -% Separate headers and footers for even and odd pages -% -% If you want the headers and footers to be different on even- and -% odd-numbered pages in the ``twoside'' style, the field-defining macros -% can be given an optional argument, to be used on the even-numbered -% pages, like \lhead[EVEN-LHEAD]{ODD-RHEAD}. -% -% Separate headers and footers for chapter pages -% -% LaTeX gives a \thispagestyle{plain} command for the first page of the -% document, the first page of each chapter and a couple of other pages. It -% might be incompatible with your pagestyle. In this case you can use a -% slightly different version of the pagestyle, called \pagestyle{fancyplain}. -% This pagestyle redefines the pagestyle ``plain'' to also use pagestyle -% ``fancy'' with the following modifications: -% - the thicknesses of the rules is defined by \plainheadrulewidth and -% \plainfootrulewidth (both default 0). -% - the 6 fields may be defined separately for the plain pages by -% giving them the value \fancyplain{PLAIN-VALUE}{NORMAL-VALUE}. This -% construct may be used in both the optional argument and the normal -% argument. Thus \lhead[\fancyplain{F1}{F2}]{\fancyplain{F3}{F4}} -% specifies the LHEAD value in a two-sided document: -% F1 on an even-numbered ``plain'' page -% F2 on an even-numbered normal page -% F3 on an odd-numbered ``plain'' page -% F4 on an odd-numbered normal page. -% -% Defaults: -% -% \headrulewidth 0.4pt -% \footrulewidth 0pt -% \plainheadrulewidth 0pt -% \plainfootrulewidth 0pt -% -% \lhead[\fancyplain{}{\sl\rightmark}]{\fancyplain{}{\sl\leftmark}} -% % i.e. empty on ``plain'' pages \rightmark on even, \leftmark on odd pages -% \chead{} -% \rhead[\fancyplain{}{\sl\leftmark}]{\fancyplain{}{\sl\rightmark}} -% % i.e. empty on ``plain'' pages \leftmark on even, \rightmark on odd pages -% \lfoot{} -% \cfoot{\rm\thepage} % page number -% \rfoot{} -% -% Examples: -% -% To put two lines containing the section title and the subsection title -% in the righthandside corner, use: -% -% \documentstyle[fancyheadings]{article} -% \pagestyle{fancy} -% \renewcommand{\sectionmark}[1]{\markboth{#1}{}} -% \renewcommand{\subsectionmark}[1]{\markright{#1}} -% \rfoot{\leftmark\\\rightmark} -% -% The following definitions give an approximation of the style used in the -% LaTeX book: -% -% \documentstyle[fancyheadings]{book} -% \pagestyle{fancyplain} -% \addtolength{\headwidth}{\marginparsep} -% \addtolength{\headwidth}{\marginparwidth} -% \renewcommand{\chaptermark}[1]{\markboth{#1}{#1}} % remember chapter title -% \renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}} -% % section number and title -% \lhead[\fancyplain{}{\bf\thepage}]{\fancyplain{}{\bf\rightmark}} -% \rhead[\fancyplain{}{\bf\leftmark}]{\fancyplain{}{\bf\thepage}} -% \cfoot{} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\def\lhead{\@ifnextchar[{\@xlhead}{\@ylhead}} -\def\@xlhead[#1]#2{\gdef\@elhead{#1}\gdef\@olhead{#2}} -\def\@ylhead#1{\gdef\@elhead{#1}\gdef\@olhead{#1}} - -\def\chead{\@ifnextchar[{\@xchead}{\@ychead}} -\def\@xchead[#1]#2{\gdef\@echead{#1}\gdef\@ochead{#2}} -\def\@ychead#1{\gdef\@echead{#1}\gdef\@ochead{#1}} - -\def\rhead{\@ifnextchar[{\@xrhead}{\@yrhead}} -\def\@xrhead[#1]#2{\gdef\@erhead{#1}\gdef\@orhead{#2}} -\def\@yrhead#1{\gdef\@erhead{#1}\gdef\@orhead{#1}} - -\def\lfoot{\@ifnextchar[{\@xlfoot}{\@ylfoot}} -\def\@xlfoot[#1]#2{\gdef\@elfoot{#1}\gdef\@olfoot{#2}} -\def\@ylfoot#1{\gdef\@elfoot{#1}\gdef\@olfoot{#1}} - -\def\cfoot{\@ifnextchar[{\@xcfoot}{\@ycfoot}} -\def\@xcfoot[#1]#2{\gdef\@ecfoot{#1}\gdef\@ocfoot{#2}} -\def\@ycfoot#1{\gdef\@ecfoot{#1}\gdef\@ocfoot{#1}} - -\def\rfoot{\@ifnextchar[{\@xrfoot}{\@yrfoot}} -\def\@xrfoot[#1]#2{\gdef\@erfoot{#1}\gdef\@orfoot{#2}} -\def\@yrfoot#1{\gdef\@erfoot{#1}\gdef\@orfoot{#1}} - -\newdimen\headrulewidth -\newdimen\footrulewidth -\newdimen\plainheadrulewidth -\newdimen\plainfootrulewidth -\newdimen\headwidth -\newif\if@fancyplain \@fancyplainfalse -\def\fancyplain#1#2{\if@fancyplain#1\else#2\fi} - -% Initialization of the head and foot text. - -\headrulewidth 0.4pt -\footrulewidth\z@ -\plainheadrulewidth\z@ -\plainfootrulewidth\z@ - -\lhead[\fancyplain{}{\sl\rightmark}]{\fancyplain{}{\sl\leftmark}} -% i.e. empty on ``plain'' pages \rightmark on even, \leftmark on odd pages -\chead{} -\rhead[\fancyplain{}{\sl\leftmark}]{\fancyplain{}{\sl\rightmark}} -% i.e. empty on ``plain'' pages \leftmark on even, \rightmark on odd pages -\lfoot{} -\cfoot{\rm\thepage} % page number -\rfoot{} - -% Put together a header or footer given the left, center and -% right text, fillers at left and right and a rule. -% The \lap commands put the text into an hbox of zero size, -% so overlapping text does not generate an errormessage. - -\def\@fancyhead#1#2#3#4#5{#1\hbox to\headwidth{\vbox{\hbox -{\rlap{\parbox[b]{\headwidth}{\raggedright#2\strut}}\hfill -\parbox[b]{\headwidth}{\centering#3\strut}\hfill -\llap{\parbox[b]{\headwidth}{\raggedleft#4\strut}}}\headrule}}#5} - - -\def\@fancyfoot#1#2#3#4#5{#1\hbox to\headwidth{\vbox{\footrule -\hbox{\rlap{\parbox[t]{\headwidth}{\raggedright#2\strut}}\hfill -\parbox[t]{\headwidth}{\centering#3\strut}\hfill -\llap{\parbox[t]{\headwidth}{\raggedleft#4\strut}}}}}#5} - -\def\headrule{{\if@fancyplain\headrulewidth\plainheadrulewidth\fi -\hrule\@height\headrulewidth\@width\headwidth \vskip-\headrulewidth}} - -\def\footrule{{\if@fancyplain\footrulewidth\plainfootrulewidth\fi -\vskip-0.3\normalbaselineskip\vskip-\footrulewidth -\hrule\@width\headwidth\@height\footrulewidth\vskip0.3\normalbaselineskip}} - -\def\ps@fancy{ -\let\@mkboth\markboth -\@ifundefined{chapter}{\def\sectionmark##1{\markboth -{\uppercase{\ifnum \c@secnumdepth>\z@ - \thesection\hskip 1em\relax \fi ##1}}{}} -\def\subsectionmark##1{\markright {\ifnum \c@secnumdepth >\@ne - \thesubsection\hskip 1em\relax \fi ##1}}} -{\def\chaptermark##1{\markboth {\uppercase{\ifnum \c@secnumdepth>\m@ne - \@chapapp\ \thechapter. \ \fi ##1}}{}} -\def\sectionmark##1{\markright{\uppercase{\ifnum \c@secnumdepth >\z@ - \thesection. \ \fi ##1}}}} -\def\@oddhead{\@fancyhead\relax\@olhead\@ochead\@orhead\hss} -\def\@oddfoot{\@fancyfoot\relax\@olfoot\@ocfoot\@orfoot\hss} -\def\@evenhead{\@fancyhead\hss\@elhead\@echead\@erhead\relax} -\def\@evenfoot{\@fancyfoot\hss\@elfoot\@ecfoot\@erfoot\relax} -\headwidth\textwidth} -\def\ps@fancyplain{\ps@fancy \let\ps@plain\ps@plain@fancy} -\def\ps@plain@fancy{\@fancyplaintrue\ps@fancy} diff --git a/doc/implement/fixunder.sty b/doc/implement/fixunder.sty deleted file mode 100644 index b7ae58dbf..000000000 --- a/doc/implement/fixunder.sty +++ /dev/null @@ -1,48 +0,0 @@ -% fixunder.sty, 31 May 1990, John T. Kohl -% -% The contents of this file are in the public domain. -% -% -% play games with _ to make it active and to provide a reasonable _ -% character (from \tt in most cases), and a discretionary word-break point. - -% -% Some \makeunder... macros for convenience in setting catcodes. -% -\def\makeunderactive{\catcode`\_=\active\relax} -\def\makeunderother{\catcode`\_=12\relax} -\def\makeunderletter{\catcode`\_=11\relax} -\def\makeundernormal{\catcode`\_=8\relax} -\makeunderother -\def\cctwlunder{_} - -% -% The hair here is to allow things like \index to work reasonably with -% the new definition of underscore when the argument to index is part of -% a macro replacement and as such gets tokenized before \index is -% evaluated. -% [in the normal case at top-level, \index{foo_bar} works since \index -% does some hair to make _ into a reasonable character code, and \index -% does NOT use a macro expansion. If you have something like -% \def\foo#1#2{\index{#1} bar #2} -% then \foo{baz_quux}{frobnitz} will result in baz_quux getting -% tokenized BEFORE \foo is expanded, so that the catcode hair in \index -% is to no avail.] -% -% \underrealfalse declares that you want to replace with the \tt _; -% \underrealtrue declares that you want to replace with \char95 (ASCII _). -% -% for things like \index which write things out to files, set -% \underrealfalse before evaluating the \index macro, and what actually -% gets written to the file is an _, rather than something like -% {\leavemode \kern... } (the typical definition of \_). -% -% the above example would then be -% \def\foo#1#2{\underrealfalse\index{#1}\underrealtrue bar #2} -% - -\newif\ifunderreal -\underrealfalse -\makeunderactive -\def_{\ifunderreal\cctwlunder\else\leavevmode {\tt \cctwlunder}\discretionary{}{}{}\fi} -\let\_=_ diff --git a/doc/implement/functions.sty b/doc/implement/functions.sty deleted file mode 100644 index a3165f811..000000000 --- a/doc/implement/functions.sty +++ /dev/null @@ -1,70 +0,0 @@ -% -% definitions related to function declarations/displays -% -\ifx\undefined\@psfonts -\def\argfont{\tt} -\else -\font\argfont = pcrb -\hyphenchar\argfont = -1 -\fi -\let\funcfont=\bf -\newcount\argc@ount -%\setlength{\marginparsep}{0.05in} -%\setlength{\marginparwidth}{1.45in} -% -% This function fixes up the function name to be displayed in the -% margin so that the krb5_, if any, is stripped. -% -% Note: this is a hack; what's really happening is that name beginning with -% krb5 will have its first five characters stripped from it. -% This means that 'Krb5abc' will get rewritten to be 'bc'. -% Unfortunately, we can't do better because of the underscore -% hacks that are going on elsewhere. -% -% WARNING: This is ugly; don't look at it too soon after lunch! -% [tytso:19900920.2231EDT] -\newif\if@krbfunc -\def\endkrb{} -\def\fix@parname#1{\expandafter\parse@krb#1\endkrb% -\endkrb\endkrb\endkrb\endkrb}% In case the argument is less -% than five letters, we don't want to -% lose on the argument parsing. -\def\parse@krb#1#2#3#4#5#6\endkrb{\@krbfuncfalse% -\if#1k\if#2r\if#3b\if#45\@krbfunctrue\fi\fi\fi\fi% -\if@krbfunc#6\else#1#2#3#4#5#6\fi} -% -% funcdecl is used as \begin{funcdecl}{funcname}{return type}{firstline} -% -% see fixunder.sty for comments on why the \underrealtrue & \underrealfalse -% stuff is here. -\newenvironment{funcdecl}[3]{\underrealtrue\index{#1}\underrealfalse% -\medbreak -\gdef\funcn@me{#1} -\argc@ount=0\noindent% -%the \mbox{} is to prevent the line/paragraph breaking from eating the -%fill space. -\marginpar[{{\sloppy \hfil\fix@parname{\funcn@me}\hfill\mbox{}}}]% -{{\sloppy \hfill\fix@parname{\funcn@me}\hfil\mbox{}}}% -\vbox\bgroup\begin{minipage}[t]{\textwidth}\begin{tabbing} -#2 \\ -{\bf #1}(\= \+ #3% -}{) -\end{tabbing}\vfil\end{minipage}\egroup\par\nopagebreak -} -\newcommand{\docomm@}{\ifnum\argc@ount >0, \\\fi} -\newcommand{\funcvoid}{\argc@ount=0} -\newcommand{\funcin}{\docomm@\argc@ount=0{\sl /* IN */}\\} -\newcommand{\funcinout}{\docomm@\argc@ount=0{\sl /* IN/OUT */}\\} -\newcommand{\funcout}{\docomm@\argc@ount=0{\sl /* OUT */}\\} -\newcommand{\funcarg}[2]{\docomm@#1 {\argfont #2}\advance\argc@ount by1} -\newcommand{\funcparam}[1]{{\argfont #1}} -\newcommand{\funcfuncarg}[2]{\docomm@#1 {\argfont #2}(\= \+ \argc@ount=0} -\newcommand{\funcendfuncarg}{), \- \\ \argc@ount=0} -\newcommand{\libname}[1]{{\argfont #1}} -\newcommand{\globalname}[1]{{\argfont #1}} -\newcommand{\ptsto}{->\discretionary{}{}{}} -\newcommand{\datatype}[1]{{\bf #1}} -\newcommand{\filename}[1]{{\sl #1\/}} - -\newcommand{\funcname}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}()} -\newcommand{\funcnamenoparens}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}} diff --git a/doc/implement/implement.tex b/doc/implement/implement.tex deleted file mode 100644 index 7b709f56f..000000000 --- a/doc/implement/implement.tex +++ /dev/null @@ -1,94 +0,0 @@ -\documentstyle[fixunder,functions,twoside,fancyheadings]{article} -\setlength{\oddsidemargin}{0in} -\setlength{\evensidemargin}{2.00in} -\setlength{\marginparsep}{0.05in} -\setlength{\marginparwidth}{1.95 in} -\setlength{\textwidth}{4.75in} -\setlength{\topmargin}{-.5in} -\setlength{\textheight}{9in} -\setlength{\parskip}{.1in} -\setlength{\parindent}{2em} -\setlength{\footrulewidth}{0.4pt} -\setlength{\plainfootrulewidth}{0.4pt} -\setlength{\plainheadrulewidth}{0.4pt} -\makeindex -\newif\ifdraft -\draftfalse -% -% Far, far too inconvenient... it's still very draft-like anyway.... -% [tytso:19900921.0018EDT] -% -%\typein{Draft flag? (type \noexpand\draftfalse<CR> if not draft...)} -\ifdraft -\pagestyle{fancyplain} -\addtolength{\headwidth}{\marginparsep} -\addtolength{\headwidth}{\marginparwidth} -\makeatletter -\renewcommand{\sectionmark}[1]{\markboth {\uppercase{\ifnum \c@secnumdepth >\z@ - \thesection\hskip 1em\relax \fi #1}}{}}% -\renewcommand{\subsectionmark}[1]{\markright {\ifnum \c@secnumdepth >\@ne - \thesubsection\hskip 1em\relax \fi #1}} -\makeatother -\lhead[\thepage]{\fancyplain{}{\sl\rightmark}} -\rhead[\fancyplain{}{\sl\rightmark}]{\thepage} -\lfoot[]{{\bf DRAFT---DO NOT REDISTRIBUTE}} -\rfoot[{\bf DRAFT---DO NOT REDISTRIBUTE}]{} -\cfoot{\thepage} -\else\pagestyle{headings}\fi - -%nlg- time to make this a real document - -\title{\Huge Kerberos V5 Implementer's Guide} -\date{\ifdraft \\ {\Large DRAFT---}\fi\today} -\author{MIT Information Systems} - -\begin{document} -\maketitle -\tableofcontents - -\section{Introduction} - - This document is designed to aide the programmer who plans to -change MIT's implementation of Kerberos significantly. It is geared towards -programmers who are already familiar with Kerberos and how MIT's -implementation is structured. - - Some of the more basic information needed can be found in the -API document, although many functions have been repeated where -additional information has been included for the implementer. The -function descriptions included are up to date, even if the description -of the functions may not be very verbose. - -\ifdraft\sloppy\fi - -\section{Cache and Key table functions} - -\subsection{Credentials cache functions} -\input{ccache-i.tex} - -\subsection{Replay cache functions} -\input{rcache-i.tex} - -\subsection{Key table functions} -\input{keytab-i.tex} - -\section{Operating-system specific functions} -\input{libos-i.tex} - -\section{Principal database functions} - -\input{kdb-i.tex} - -\section{Encryption system interface} -\input{encrypt-i.tex} - -\section{Checksum interface} -\input{cksum-i.tex} - -\section{CRC-32 checksum functions} -\input{crc-32-i.tex} - -\appendix -\cleardoublepage -\input{\jobname.ind} -\end{document} diff --git a/doc/implement/kdb-i.tex b/doc/implement/kdb-i.tex deleted file mode 100644 index dc81971bb..000000000 --- a/doc/implement/kdb-i.tex +++ /dev/null @@ -1,242 +0,0 @@ -The \libname{libkdb.a} library provides a principal database interface -to be used by the Key Distribution center and other database -manipulation tools. - - -\begin{funcdecl}{krb5_db_set_name}{krb5_error_code}{\funcin} -\funcarg{char *}{name} -\end{funcdecl} - -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. - -\begin{funcdecl}{krb5_db_set_nonblocking}{krb5_error_code}{\funcin} -\funcarg{krb5_boolean}{newmode} -\funcout -\funcarg{krb5_boolean *}{oldmode} -\end{funcdecl} - -Changes the locking mode of the database functions, returning the previous -mode in \funcparam{*oldmode}. - -If \funcparam{newmode} is TRUE, then the database is put into -non-blocking mode, which may result in ``database busy'' error codes from -the get, put, and iterate routines. - -If \funcparam{newmode} is FALSE, then the database is put into blocking mode, -which may result in delays from the get, put and iterate routines. - -The default database mode is blocking mode. - -\begin{funcdecl}{krb5_db_init}{krb5_error_code}{\funcvoid} -\end{funcdecl} - -Called before using \funcname{krb5_db_get_principal}, -\funcname{krb5_db_put_principal}, \funcname{krb5_db_iterate}, and -\funcname{krb5_db_set_nonblocking}. - -Does any required initialization. - -%Errors: init errors, system errors. - -\begin{funcdecl}{krb5_db_fini}{krb5_error_code}{\funcvoid} -\end{funcdecl} - -Called after all database operations are complete, to perform any required -clean-up. - -%Errors: sysytem errors. - - -\begin{funcdecl}{krb5_db_get_age}{krb5_error_code}{\funcin} -\funcarg{char *}{db_name} -\funcout -\funcarg{time_t *}{age} -\end{funcdecl} - -Retrieves the age of the database \funcname{db_name} (or the current -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. - - -\begin{funcdecl}{krb5_db_create}{krb5_error_code}{\funcin} -\funcarg{char *}{db_name} -\end{funcdecl} - -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. - -\begin{funcdecl}{krb5_db_rename}{krb5_error_code}{\funcin} -\funcarg{char *}{source} -\funcarg{char *}{dest} -\end{funcdecl} -Renames the database \funcarg{source} to \funcarg{dest} - -Any database named \funcarg{dest} is destroyed. - -%Errors: system errors. - -\begin{funcdecl}{krb5_db_get_principal}{krb5_error_code}{\funcin} -\funcarg{krb5_principal}{searchfor} -\funcout -\funcarg{krb5_db_entry *}{entries} -\funcinout -\funcarg{int *}{nentries} -\funcout -\funcarg{krb5_boolean *}{more} -\end{funcdecl} - -Retrieves the principal records named by \funcparam{searchfor}. - -\funcparam{entries} must point to an array of \funcparam{*nentries} -krb5_db_entry structures. -At most \funcparam{*nentries} structures are filled in, and -\funcparam{*nentries} is modified to reflect the number actually returned. - -\funcparam{*nentries} must be at least one (1) when this function is called. - -\funcparam{*more} is set to TRUE if there are more records that wouldn't fit -in the available space, and FALSE otherwise. - -The principal structures filled in have pointers to allocated storage; -\funcname{krb5_db_free_principal} should be called with -\funcparam{entries} and \funcparam{*nentries} -in order to free this storage when no longer needed. - - -\begin{funcdecl}{krb5_db_free_principal}{void}{\funcin} -\funcarg{krb5_db_entry *}{entries} -\funcarg{int}{nentries} -\end{funcdecl} - -Frees allocated storage held by \funcparam{entries} as filled in by -\funcname{krb5_db_get_principal}. - - -\begin{funcdecl}{krb5_db_put_principal}{krb5_error_code}{\funcin} -\funcarg{krb5_db_entry *}{entries} -\funcarg{int *}{nentries} -\end{funcdecl} - -Stores the \funcparam{*nentries} principal structures pointed to by -\funcparam{entries} in the database. - -\funcparam{*nentries} is updated upon return to reflect the number of records -acutally stored; the first \funcparam{*nentries} records will have been -stored in the database. - -%Errors: Returns error code if not all entries were stored. - -\begin{funcdecl}{krb5_db_iterate}{krb5_error_code}{\funcin} -\funcfuncarg{krb5_error_code}{(*func)} -\funcarg{krb5_pointer}{} -\funcarg{krb5_db_entry *}{} -\funcendfuncarg -\funcarg{krb5_pointer}{iterate_arg} -\end{funcdecl} - -Iterates over the database, fetching every entry in an unspecified order -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 -should be -aborted and that error code is returned by this function. - -\begin{funcdecl}{krb5_db_store_mkey}{krb5_error_code}{\funcin} -\funcarg{char *}{keyfile} -\funcarg{krb5_principal}{mname} -\funcarg{krb5_keyblock *}{key} -\end{funcdecl} - -Put the KDC database master key into the file \funcparam{keyfile}. If -\funcparam{keyfile} is NULL, then a default file name derived from the -principal name \funcparam{mname} is used. - -\begin{funcdecl}{krb5_db_fetch_mkey}{krb5_error_code}{\funcin} -\funcarg{krb5_principal}{mname} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{krb5_boolean}{fromkeyboard} -\funcarg{krb5_boolean}{twice} -\funcarg{krb5_data }{salt} -\funcinout -\funcarg{krb5_keyblock *}{key} -\end{funcdecl} - -Get the KDC database master key from somewhere, filling it into -\funcparam{*key}. -\funcparam{key{\ptsto}keytype} should be set to the desired key type. - -If \funcparam{fromkeyboard} is TRUE, then the master key is read as a password -from the user's terminal. In this case: -\funcparam{eblock} should point to a block with an appropriate -\funcname{string_to_key} function; if \funcparam{twice} is TRUE, the -password is read twice for verification; and if \funcparam{salt} is -non-NULL, it is used as the salt when converting the typed -password to the master key. - - -If \funcparam{fromkeyboard} is false, then the key is read from -a file whose name is derived from the principal name \funcparam{mname}. -Therefore, \funcparam{eblock}, \funcparam{twice} and \funcparam{salt} -are ignored. - - -\funcparam{mname} is the name of the key sought; this is often used by -\funcname{string_to_key} to aid in conversion of the password to a key. - -\begin{funcdecl}{krb5_kdb_encrypt_key}{krb5_error_code}{\funcin} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_keyblock *}{in} -\funcinout -\funcarg{krb5_encrypted_keyblock *}{out} -\end{funcdecl} - -Encrypt a key for storage in the database. \funcparam{eblock} is used -to encrypt the key in \funcparam{in} into \funcparam{out}; the storage -pointed to by \funcparam{*out} is allocated before use and should be -freed when the caller is finished with it. - -\begin{funcdecl}{krb5_kdb_decrypt_key}{krb5_error_code}{\funcin} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_encrypted_keyblock *}{in} -\funcinout -\funcarg{krb5_keyblock *}{out} -\end{funcdecl} - -Decrypt a key from storage in the database. \funcparam{eblock} is used -to decrypt the key in \funcparam{in} into \funcparam{out}; the storage -pointed to by \funcparam{*out} is allocated before use and should be -freed when the caller is finished with it. - -\begin{funcdecl}{krb5_db_setup_mkey_name}{krb5_error_code}{\funcin} -\funcarg{const}{char *keyname} -\funcarg{const}{char *realm} -\funcout -\funcarg{char **}{fullname} -\funcarg{krb5_principal *}{principal} -\end{funcdecl} - -Given a key name \funcparam{keyname} and a realm name \funcparam{realm}, -construct a principal which can be used to fetch the master key from the -database. This principal is filled into \funcparam{*principal}; -\funcparam{*principal} should be freed by \funcname{krb5_free_principal} -when the caller is finished. - -If \funcparam{keyname} is NULL, the default key name will be used. - -If \funcparam{fullname} is not NULL, it is set to point to a string -representation of the complete principal name; its storage may be freed -by calling \funcname{free} on \funcparam{*fullname}. - diff --git a/doc/implement/keytab-i.tex b/doc/implement/keytab-i.tex deleted file mode 100644 index 697728721..000000000 --- a/doc/implement/keytab-i.tex +++ /dev/null @@ -1,204 +0,0 @@ -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. 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. - -\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{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} -\end{funcdecl} - -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}{get_name}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{char *}{name} -\funcin -\funcarg{int}{namesize} -\end{funcdecl} - -\funcarg{name} is filled in with the first \funcparam{namesize} bytes of -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}{close}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\end{funcdecl} - -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. - -\begin{funcdecl}{get}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcout -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Searches the keytab identified by \funcparam{id} for an entry whose -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. - -%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}{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{get} or -\funcname{get_next}. - -\begin{funcdecl}{start_seq_get}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{krb5_kt_cursor *}{cursor} -\end{funcdecl} - -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{get_next}. - -\begin{funcdecl}{get_next}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{krb5_keytab_entry *}{entry} -\funcinout -\funcarg{krb5_kt_cursor}{cursor} -\end{funcdecl} - -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 -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{start_seq_get} or a subsequent call to -\funcname{get_next}. - -%Errors: error code if no more cache entries or if the keytab changes. - -\begin{funcdecl}{end_get}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_kt_cursor *}{cursor} -\end{funcdecl} - -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 -\funcparam{*cursor} be a cursor returned by -\funcname{start_seq_get} or a subsequent call to -\funcname{get_next}. - -%Errors: May return error code if \funcparam{cursor} is invalid. - -\subsubsection{Per-type functions to be included for write routines} - -\begin{funcdecl}{add}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Stores \funcparam{entry} in the keytab \funcparam{id}. -Fails if the entry already exists. - -This operation must, within the constraints of the operating system, not -return until it can verify that the write has completed succesfully. -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. - -%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). - -\begin{funcdecl}{remove}{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: Returns an error code if not found. - diff --git a/doc/implement/libos-i.tex b/doc/implement/libos-i.tex deleted file mode 100644 index cdd4861ff..000000000 --- a/doc/implement/libos-i.tex +++ /dev/null @@ -1,34 +0,0 @@ -The operating-system specific functions provide an interface between the -other parts of the \libname{libkrb5.a} libraries and the operating system. - -Beware! Any of the functions below are allowed to be implemented as -macros. Prototypes for functions can be found in {\tt -<krb5/libos-proto.h>}; other definitions (including macros, if used) are -in {\tt <krb5/libos.h>}. - -The following global symbols are provided in \libname{libos.a}. If you -wish to substitute for any of them, you must substitute for all of them -(they are all declared and initialized in the same object file): -\begin{description} -% These come from src/lib/osconfig.c -\item[extern char *\globalname{krb5_config_file}:] name of configuration file -\item[extern char *\globalname{krb5_trans_file}:] name of hostname/realm -name translation file -\item[extern char *\globalname{krb5_defkeyname}:] default name of key -table file -\item[extern char *\globalname{krb5_lname_file}:] name of aname/lname -translation database -\item[extern int \globalname{krb5_max_dgram_size}:] maximum allowable -datagram size -\item[extern int \globalname{krb5_max_skdc_timeout}:] maximum -per-message KDC reply timeout -\item[extern int \globalname{krb5_skdc_timeout_shift}:] shift factor -(bits) to exponentially back-off the KDC timeouts -\item[extern int \globalname{krb5_skdc_timeout_1}:] initial KDC timeout -\item[extern char *\globalname{krb5_kdc_udp_portname}:] name of KDC UDP port -\item[extern char *\globalname{krb5_default_pwd_prompt1}:] first prompt -for password reading. -\item[extern char *\globalname{krb5_default_pwd_prompt2}:] second prompt - -\end{description} - diff --git a/doc/implement/rcache-i.tex b/doc/implement/rcache-i.tex deleted file mode 100644 index e00a639da..000000000 --- a/doc/implement/rcache-i.tex +++ /dev/null @@ -1,142 +0,0 @@ -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 {\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 -replay cache. - -\begin{funcdecl}{init}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_deltat}{auth_lifespan} -\end{funcdecl} - -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 - -\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 - -\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. - -\begin{funcdecl}{close}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -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 - -\begin{funcdecl}{store}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_donot_replay *}{rep} -\end{funcdecl} -Stores \funcparam{rep} in the replay cache \funcparam{id}. -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}{expunge}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} -Removes all expired replay information (i.e. those entries which are -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. - -\begin{funcdecl}{get_span}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcout -\funcarg{krb5_deltat *}{auth_lifespan} -\end{funcdecl} -Fills in \funcparam{auth_lifespan} with the lifespan of -the cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -\begin{funcdecl}{resolve}{krb5_error_code}{\funcinout} -\funcarg{krb5_rcache}{id} -\funcin -\funcarg{char *}{name} -\end{funcdecl} - -Initializes private data attached to \funcparam{id}. This function MUST -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{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. - - -\begin{funcdecl}{krb5_rc_get_name}{char *}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Returns the name (excluding the type) of the rcache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - |