From: no author Date: Wed, 30 Sep 1992 14:36:27 +0000 (+0000) Subject: This commit was manufactured by cvs2svn to create tag 'BETA_2' X-Git-Tag: krb5-1.0-beta2 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=3b410397c57b0a90681cfb85f562a03cb48a08d2;p=krb5.git This commit was manufactured by cvs2svn to create tag 'BETA_2' git-svn-id: svn://anonsvn.mit.edu/krb5/tags/BETA_2@2462 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/api/Makefile b/doc/api/Makefile deleted file mode 100644 index d5a6f7908..000000000 --- a/doc/api/Makefile +++ /dev/null @@ -1,29 +0,0 @@ -.SUFFIXES: .tex .dvi .ps - -STYLES=changebar.sty fixunder.sty functions.sty -LIBTEX= library.tex krb5.tex ccache.tex rcache.tex keytab.tex libos.tex \ - kdb.tex encrypt.tex cksum.tex crc-32.tex library.ind - -DESTEX= libdes.tex - -all: library.ps libdes.ps - - -libdes.dvi: $(DESTEX) $(STYLES) - -library.ps: library.dvi - -# hard to capture two-pass semantics in Makefiles... -# library.ind: library.dvi -library.ind: library.idx - index library.idx - -library.dvi: $(LIBTEX) $(STYLES) - -.tex.dvi: - latex $* - - -.dvi.ps: - dvips $*.dvi -o - diff --git a/doc/api/ccache.tex b/doc/api/ccache.tex deleted file mode 100644 index 83607af9b..000000000 --- a/doc/api/ccache.tex +++ /dev/null @@ -1,236 +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{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}. - - -\begin{funcdecl}{krb5_cc_resolve_internal}{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}{krb5_cc_gennew_internal}{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}{krb5_cc_initialize}{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}{krb5_cc_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}{krb5_cc_close}{krb5_error_code}{\funcinout} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Closes the credentials cache \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. - - -\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_credentials *}{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}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{whichfields} -\funcarg{krb5_credentials *}{mcreds} -\funcout -\funcarg{krb5_credentials *}{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}. XXX free the return creds? - -Errors: error code if no matches found. - -\begin{funcdecl}{krb5_cc_get_principal}{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) -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} -\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{krb5_cc_next_cred}. - -\begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_credentials *}{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{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. - -Errors: error code if no more cache entries. - -\begin{funcdecl}{krb5_cc_end_seq_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{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. - -Errors: may return error code if \funcparam{*cursor} is invalid. - - -\begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{which} -\funcarg{krb5_credentials *}{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}{krb5_cc_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 }. - - -\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/api/fixunder.sty b/doc/api/fixunder.sty deleted file mode 100644 index b7ae58dbf..000000000 --- a/doc/api/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/api/functions.sty b/doc/api/functions.sty deleted file mode 100644 index 412df84b3..000000000 --- a/doc/api/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 /* INOUT */}\\} -\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/api/keytab.tex b/doc/api/keytab.tex deleted file mode 100644 index 4a45295c5..000000000 --- a/doc/api/keytab.tex +++ /dev/null @@ -1,250 +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. 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 -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. - -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} -\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}{krb5_kt_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}{krb5_kt_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}{krb5_kt_get_entry}{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. - -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. - -\begin{funcdecl}{krb5_kt_free_entry}{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}. - -\begin{funcdecl}{krb5_kt_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{krb5_kt_next_entry}. - -\begin{funcdecl}{krb5_kt_next_entry}{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 is -guaranteed. \funcparam{*entry} should be freed after use by calling -\funcname{krb5_kt_free_entry}. - -Requires that \funcparam{id} identifies a valid credentials cache. and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. - -Errors: error code if no more cache entries or if the keytab changes. - -\begin{funcdecl}{krb5_kt_end_seq_get}{krb5_error_code}{\funcin} -\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{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. - -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. - -Returns an error code if not found. - - -\begin{funcdecl}{krb5_kt_add_internal}{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. - -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. - -An error is returned if \funcparam{ops{\ptsto}prefix} is already known. - -\begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcin} -\funcarg{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} -\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. - -\begin{funcdecl}{krb5_kt_remove_entry}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -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/api/krb5.tex b/doc/api/krb5.tex deleted file mode 100644 index 5cabeb1ab..000000000 --- a/doc/api/krb5.tex +++ /dev/null @@ -1,1058 +0,0 @@ -The main functions deal with the nitty-gritty details: verifying -tickets, creating authenticators, and the like. - -\begin{funcdecl}{krb5_encode_kdc_rep}{krb5_error_code}{\funcin} -\funcarg{krb5_msgtype}{type} -\funcarg{krb5_enc_kdc_rep_part *}{encpart} -\funcarg{krb5_keyblock *}{client_key} -\funcinout -\funcarg{krb5_kdc_rep *}{dec_rep} -\funcout -\funcarg{krb5_data *}{enc_rep} -\end{funcdecl} - -Takes KDC rep parts in \funcparam{*rep} and \funcparam{*encpart}, and -formats it into \funcparam{*enc_rep}, using message type \funcparam{type} -and encryption key \funcparam{client_key} and encryption type -\funcparam{dec_rep{\ptsto}etype}. - -\funcparam{enc_rep{\ptsto}data} will point to allocated storage upon -non-error return; the caller should free it when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_decode_kdc_rep}{krb5_error_code}{\funcin} -\funcarg{krb5_data *}{enc_rep} -\funcarg{krb5_keyblock *}{key} -\funcarg{krb5_enctype}{etype} -\funcout -\funcarg{krb5_kdc_rep **}{dec_rep} -\end{funcdecl} - -Takes a KDC_REP message and decrypts encrypted part using -\funcparam{etype} and \funcparam{*key}, putting result in \funcparam{*dec_rep}. -The pointers in \funcparam{dec_rep} -are all set to allocated storage which should be freed by the caller -when finished with the response (by using \funcname{krb5_free_kdc_rep}). - - -If the response isn't a KDC_REP (tgs or as), it returns an error from -the decoding routines (usually ISODE_50_LOCAL_ERR_BADDECODE). - -Returns errors from encryption routines, system errors. - -\begin{funcdecl}{krb5_kdc_rep_decrypt_proc}{krb5_error_code}{\funcin} -\funcarg{krb5_keyblock *}{key} -\funcarg{krb5_pointer}{decryptarg} -\funcinout -\funcarg{krb5_kdc_rep *}{dec_rep} -\end{funcdecl} - -Decrypt the encrypted portion of \funcparam{dec_rep}, using the -encryption key \funcparam{key}. \funcparam{decryptarg} is ignored. - -The result is in allocated storage pointed to by -\funcparam{dec_rep{\ptsto}enc_part2}, unless some error occurs. - -This function is suitable for use as the \funcparam{decrypt_proc} -argument to \funcname{krb5_get_in_tkt}. - -\begin{funcdecl}{krb5_encrypt_tkt_part}{krb5_error_code}{ \funcin} -\funcarg{krb5_keyblock *}{srv_key} -\funcinout -\funcarg{krb5_ticket *}{dec_ticket} -\end{funcdecl} - -Takes unencrypted \funcparam{dec_ticket} and -\funcparam{dec_ticket{\ptsto}enc_part2}, encrypts with -\funcparam{dec_ticket{\ptsto}etype} -using \funcparam{srv_key}, and places result in -\funcparam{dec_ticket{\ptsto}enc_part}. -The string \funcparam{dec_ticket{\ptsto}enc_part} will be allocated -before formatting. - -Returns errors from encryption routines, system errors - -\funcparam{enc_part{\ptsto}data} is allocated and filled in with -encrypted stuff. - -\begin{funcdecl}{krb5_decrypt_tkt_part}{krb5_error_code}{\funcin} -\funcarg{krb5_keyblock *}{srv_key} -\funcinout -\funcarg{krb5_ticket *}{dec_ticket} -\end{funcdecl} - -Takes encrypted \funcparam{dec_ticket{\ptsto}enc_part}, encrypts with -\funcparam{dec_ticket{\ptsto}etype} -using \funcparam{srv_key}, and places result in -\funcparam{dec_ticket{\ptsto}enc_part2}. The storage of -\funcparam{dec_ticket{\ptsto}enc_part2} will be allocated before return. - -Returns errors from encryption routines, system errors - -\begin{funcdecl}{krb5_send_tgs}{krb5_error_code}{\funcin} -\funcarg{krb5_flags}{options} -\funcarg{krb5_ticket_times *}{timestruct} -\funcarg{krb5_enctype}{etype} -\funcarg{krb5_cksumtype}{sumtype} -\funcarg{krb5_principal}{sname} -\funcarg{krb5_address **}{addrs} -\funcarg{krb5_authdata **}{authorization_data} -\funcarg{krb5_data *}{second_ticket} -\funcinout -\funcarg{krb5_creds *}{usecred} -\funcout -\funcarg{krb5_response *}{rep} -\end{funcdecl} - -Sends a request to the TGS and waits for a response. -\funcparam{options} is used for the options in the KRB_TGS_REQ. -\funcparam{timestruct} values are used for from, till, and rtime in the -KRB_TGS_REQ. -\funcparam{etype} is used for etype in the KRB_TGS_REQ. -\funcparam{sumtype} is used for the checksum in the AP_REQ in the KRB_TGS_REQ. -\funcparam{sname} is used for sname in the KRB_TGS_REQ. -\funcparam{addrs}, if non-NULL, is used for addresses in the KRB_TGS_REQ. -\funcparam{authorization_dat}, if non-NULL, is used for authorization_dat in the KRB_TGS_REQ. -\funcparam{second_ticket}, if required by options, is used for the 2nd -ticket in the KRB_TGS_REQ. -\funcparam{usecred} is used for the ticket and session key in the KRB_AP_REQ header in the KRB_TGS_REQ. - -The KDC realm is extracted from \funcparam{usecred{\ptsto}server}'s realm. - -The response is placed into \funcparam{*rep}. -\funcparam{rep{\ptsto}response.data} is set to point at allocated storage -which should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_get_cred_from_kdc}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcout -\funcparam{krb5_creds ***}{tgts } -\end{funcdecl} - -Retrieve credentials for principal \funcparam{creds{\ptsto}client}, -server \funcparam{creds{\ptsto}server}, -ticket flags \funcparam{creds{\ptsto}ticket_flags}, possibly -\funcparam{creds{\ptsto}second_ticket} if needed by the ticket flags. - -\funcparam{ccache} is used to fetch initial TGT's to start the authentication -path to the server. - -Credentials are requested from the KDC for the server's realm. Any -TGT credentials obtained in the process of contacting the KDC are -returned in an array of credentials; \funcparam{tgts} is filled in to -point to an array of pointers to credential structures (if no TGT's were -used, the pointer is zeroed). TGT's may be returned even if no useful -end ticket was obtained. - -The returned credentials are NOT cached. - -If credentials are obtained, \funcparam{creds} is filled in with the results; -\funcparam{creds{\ptsto}ticket} and -\funcparam{creds{\ptsto}keyblock{\ptsto}key} are set to allocated storage, -which should be freed by the caller when finished. - -Returns errors, system errors. - - -\begin{funcdecl}{krb5_free_tgt_creds}{void}{\funcin} -\funcarg{krb5_creds **}{tgts} -\end{funcdecl} - -Frees the TGT credentials \funcparam{tgts} returned by -\funcname{krb5_get_cred_from_kdc}. - -\begin{funcdecl}{krb5_get_credentials}{krb5_error_code}{\funcin} -\funcarg{krb5_flags}{options} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Attempts to use the credentials cache \funcparam{ccache} or a TGS -exchange to get an additional ticket for the client identified by -\funcparam{creds{\ptsto}client}, the server identified by -\funcparam{creds{\ptsto}server}, with options \funcparam{options}, -expiration date specified in \funcparam{creds{\ptsto}times.endtime} (0 -means as long as possible), session key type specified in -\funcparam{creds{\ptsto}keyblock.keytype} (if non-zero). - -If \funcparam{options} specifies KRB5_GC_CACHED, \funcname{get_credentials} -will only search the credentials cache for a ticket. If -\funcparam{options} specifies KRB5_GC_USER_USER, \funcname{get_credentials} -will set the KDC_OPT_ENC_TKT_IN_SKEY flag in the KDC request. -\funcparam{creds{\ptsto}second_ticket} must contain a ticket. - -Any returned ticket and intermediate ticket-granting tickets are -stored in \funcparam{ccache}. - -Returns errors from encryption routines, system errors. - -\begin{funcdecl}{krb5_get_in_tkt}{krb5_error_code}{\funcin} -\funcarg{krb5_flags}{options} -\funcarg{krb5_address **}{addrs} -\funcarg{krb5_enctype}{etype} -\funcarg{krb5_keytype}{keytype} -\funcfuncarg{krb5_error_code}{(*key_proc)} - \funcarg{krb5_keytype}{type} - \funcarg{krb5_keyblock **}{key} - \funcarg{krb5_pointer}{keyseed} -\funcendfuncarg -\funcarg{krb5_pointer}{keyseed} -\funcfuncarg{krb5_error_code}{(*decrypt_proc)} - \funcarg{krb5_keyblock *}{key} - \funcarg{krb5_pointer}{decryptarg} - \funcarg{krb5_kdc_rep *}{dec_rep} -\funcendfuncarg -\funcarg{krb5_pointer}{decryptarg} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_ccache}{ccache} -\end{funcdecl} - -All-purpose initial ticket routine, usually called via -\funcname{krb5_get_in_tkt_with_password} or -\funcname{krb5_get_in_tkt_with_skey}. - -Attempts to get an initial ticket for \funcparam{creds{\ptsto}client} to use server -\funcparam{creds{\ptsto}server}, (realm is taken from -\funcparam{creds{\ptsto}client}), with options -\funcparam{options}, requesting encryption type \funcparam{etype}, and using -\funcparam{creds{\ptsto}times.starttime}, \funcparam{creds{\ptsto}times.endtime}, -\funcparam{creds{\ptsto}times.renew_till} -as from, till, and rtime. \funcparam{creds{\ptsto}times.renew_till} is -ignored unless the RENEWABLE option is requested. - -\funcparam{key_proc} is called to fill in the key to be used for decryption. -\funcparam{keyseed} is passed on to \funcparam{key_proc}. - -\funcparam{decrypt_proc} is called to perform the decryption of the -response (the encrypted part is in \funcparam{dec_rep{\ptsto}enc_part}; the -decrypted part should be allocated and filled into -\funcparam{dec_rep{\ptsto}enc_part2}. -\funcparam{decryptarg} is passed on to \funcparam{decrypt_proc}. - -If \funcparam{addrs} is non-NULL, it is used for the addresses -requested. If it is null, the system standard addresses are used. - -A succesful call will place the ticket in the credentials cache -\funcparam{ccache} and fill in \funcparam{creds} with the ticket -information used/returned. - -Returns system errors, encryption errors. - -\begin{funcdecl}{krb5_get_in_tkt_with_password}{krb5_error_code}{\funcin} -\funcarg{krb5_flags}{options} -\funcarg{krb5_address **}{addrs} -\funcarg{krb5_enctype}{etype} -\funcarg{krb5_keytype}{keytype} -\funcarg{char *}{password} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - - -Attempts to get an initial ticket for \funcparam{creds{\ptsto}client} to use server -\funcparam{creds{\ptsto}server}, (realm is taken from -\funcparam{creds{\ptsto}client}), with options -\funcparam{options}, requesting encryption type \funcparam{etype}, and using -\funcparam{creds{\ptsto}times.starttime}, -\funcparam{creds{\ptsto}times.endtime}, -\funcparam{creds{\ptsto}times.renew_till} -as from, till, and rtime. \funcparam{creds{\ptsto}times.renew_till} is -ignored unless the RENEWABLE option is requested. - -If \funcparam{addrs} is non-NULL, it is used for the addresses -requested. If it is null, the system standard addresses are used. - -If \funcparam{password} is non-NULL, it is converted using the -cryptosystem entry point for a string conversion routine, seeded with -the client's principal name. If \funcparam{password} is passed as NULL, -the password is read from the terminal, and then converted into a key. - -A succesful call will place the ticket in the credentials cache -\funcparam{ccache}. - -Returns system errors, encryption errors. - -\begin{funcdecl}{krb5_get_in_tkt_with_skey}{krb5_error_code}{\funcin} -\funcarg{krb5_flags}{options} -\funcarg{krb5_address **}{addrs} -\funcarg{krb5_enctype}{etype} -\funcarg{krb5_keyblock *}{key} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} -Similar to \funcname{krb5_get_in_tkt_with_password}. - -Attempts to get an initial ticket for \funcparam{creds{\ptsto}client} to use server -\funcparam{creds{\ptsto}server}, (realm is taken from -\funcparam{creds{\ptsto}client}), with options \funcparam{options}, requesting -encryption type \funcparam{etype}, and using -\funcparam{creds{\ptsto}times.starttime}, \funcparam{creds{\ptsto}times.endtime}, -\funcparam{creds{\ptsto}times.renew_till} as from, till, and rtime. -\funcparam{creds{\ptsto}times.renew_till} is ignored unless the -RENEWABLE option is requested. - -If \funcparam{addrs} is non-NULL, it is used for the addresses -requested. If it is null, the system standard addresses are used. - -If \funcparam{keyblock} is NULL, an appropriate key for -\funcparam{creds{\ptsto}client} is retrieved from the system key store (e.g. -\filename{/etc/v5srvtab}). If \funcparam{keyblock} is non-NULL, it is -used as the decryption key. - -A succesful call will place the ticket in the credentials cache -\funcparam{ccache}. - -Returns system errors, encryption errors. - -\begin{funcdecl}{krb5_mk_req}{krb5_error_code}{\funcin} -\funcarg{krb5_principal}{server} -\funcarg{krb5_flags}{ap_req_options} -\funcarg{krb5_checksum *}{checksum} -\funcarg{krb5_ccache}{ccache} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_AP_REQ message into \funcparam{outbuf}. - -\funcparam{server} specifies the principal of the server to receive the -message; if credentials are not present in the credentials cache -\funcparam{ccache} for this server, the TGS request with default -parameters is used in an attempt to obtain such credentials, and they -are stored in \funcparam{ccache}. - -\funcparam{ap_req_options} specifies the KRB_AP_REQ options desired. - -\funcparam{checksum} specifies the checksum to be used in the authenticator. - -The \funcparam{outbuf} buffer storage is allocated, and should be freed -by the caller when finished. - -Returns system errors. - - -\begin{funcdecl}{krb5_mk_req_extended}{krb5_error_code}{\funcin} -\funcarg{krb5_flags}{ap_req_options} -\funcarg{krb5_checksum *}{checksum} -\funcarg{krb5_flags}{kdc_options} -\funcarg{krb5_int32}{sequence} -\funcarg{krb5_keyblock **}{newkey} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_authenticator *}{authentp} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_AP_REQ message into \funcparam{outbuf}, with more complete -options than \funcname{krb5_mk_req}. - -\funcparam{outbuf}, \funcparam{ap_req_options}, \funcparam{checksum}, -and \funcparam{ccache} are used in the same fashion as for -\funcname{krb5_mk_req}. - -\funcparam{creds} is used to supply the credentials (ticket and session -key) needed to form the request. - -If \funcparam{creds{\ptsto}ticket} has no data (length == 0), then a -ticket is obtained from either \funcparam{ccache} or the TGS, passing -\funcparam{creds} to \funcname{krb5_get_credentials}. -\funcparam{kdc_options} specifies the options requested for the ticket -to be used. If a ticket with appropriate flags is not found in -\funcparam{ccache}, then these options are passed on in a request to an -appropriate KDC. - -\funcparam{ap_req_options} specifies the KRB_AP_REQ options desired. - -\funcparam{sequence}, if non-zero, specifies the initial sequence number -which the caller will use for KRB_SAFE or KRB_PRIV messages. - -\funcparam{newkey}, if non-NULL, will be filled in upon return with a -sub-session key that the caller can use to protect future KRB_SAFE or -KRB_PRIV messages. When the caller is finished with the key, it should -be freed with \funcname{krb5_free_keyblock}. - -If \funcparam{ap_req_options} specifies AP_OPTS_USE_SESSION_KEY, then -\funcparam{creds{\ptsto}ticket} must contain the appropriate -ENC-TKT-IN-SKEY ticket. - -\funcparam{checksum} specifies the checksum to be used in the -authenticator. - -If \funcparam{authentp} is non-NULL, \funcname{krb5_mk_req_extended} -will store -a copy of authenticator there, with the principal and checksum fields -nulled out. (This is to prevent pointer sharing problems; the caller -shouldn't need these fields anyway, since the caller supplied them.) - -The \funcparam{outbuf} buffer storage is allocated, and should be freed -by the caller when finished. - -On an error return, the credentials pointed to by \funcparam{creds} -might have been augmented with additional fields from the obtained -credentials; the entire credentials should be released by calling -\funcname{krb5_free_creds}. - -Returns system errors. - -\begin{funcdecl}{krb5_generate_subkey}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{key} -\funcout -\funcarg{krb5_keyblock **}{subkey} -\end{funcdecl} - -Generates a pseudo-random sub-session key using the encryption system's -random key functions, based on the input \funcparam{key}. - -\funcparam{subkey} is filled in to point to the generated subkey, unless -an error is returned. The returned key is allocated and should be freed -by the caller with \funcname{krb5_free_keyblock} when it is no longer -needed. - -\begin{funcdecl}{krb5_rd_req_simple}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{inbuf} -\funcarg{krb5_const_principal}{server} -\funcarg{const krb5_address *}{sender_addr} -\funcout -\funcarg{krb5_tkt_authent **}{authdat} -\end{funcdecl} - -Parses a KRB_AP_REQ message, returning its contents. Upon exiting, -\funcparam{*authdat} will be modified to point to allocated storage -containing the ticket and authenticator information. The caller is -responsible for deallocating this space by using -\funcname{krb5_free_tkt_authent}. - -\funcparam{server} specifies the expected server's name for the ticket. - -\funcparam{sender_addr} specifies the address(es) expected to be present -in the ticket. - -A replay cache name derived from the first component of the service name -is used. - -The default key store is consulted to find the service key. - -\funcparam{authdat{\ptsto}ticket} and -\funcparam{authdat{\ptsto}authenticator} are set to allocated storage -structures; the caller should free them when finished. - -Returns system errors, encryption errors, replay errors. - - -\begin{funcdecl}{krb5_rd_req}{krb5_error_code}{\funcin} -\funcarg{krb5_data *}{inbuf} -\funcarg{krb5_principal}{server} -\funcarg{krb5_address *}{sender_addr} -\funcarg{krb5_pointer}{fetchfrom} -\funcfuncarg{krb5_error_code}{(*keyproc)} -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcarg{krb5_keyblock **}{key} -\funcendfuncarg -\funcarg{krb5_pointer}{keyprocarg} -\funcinout -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_tkt_authent **}{authdat} -\end{funcdecl} - -Parses a KRB_AP_REQ message, returning its contents. Upon exiting, -\funcparam{*authdat} will be modified to point to allocated storage -containing the ticket and authenticator information. The caller is -responsible for deallocating this space by using -\funcname{krb5_free_tkt_authent}. - -\funcparam{server} specifies the expected server's name for the ticket. -If \funcparam{server} is NULL, then any server name will be accepted if -the appropriate key can be found, and the caller should verify that the -server principal matches some trust criterion. - -\funcparam{sender_addr} specifies the address(es) expected to be present -in the ticket. - -\funcparam{rcache} specifies a replay detection cache used to store -authenticators and server names. If \funcparam{rcache} is NULL, then no -replay detection is performed. - -\funcparam{keyproc} specifies a procedure to generate a decryption key for the -ticket. If \funcparam{keyproc} is non-NULL, \funcparam{keyprocarg} is -passed to it, and the result used as a decryption key. If -\funcparam{keyproc} is NULL, then \funcparam{fetchfrom} is checked; if -it is non-NULL, it specifies a parameter name from which to retrieve the -decryption key. If \funcparam{fetchfrom} is NULL, then the default key -store is consulted. - -\funcparam{authdat{\ptsto}ticket} and -\funcparam{authdat{\ptsto}authenticator} are set to allocated storage -structures; the caller should free them when finished. - -Returns system errors, encryption errors, replay errors. - -\begin{funcdecl}{krb5_rd_req_decoded}{krb5_error_code}{\funcin} -\funcarg{krb5_ap_req *}{req} -\funcarg{krb5_principal}{server} -\funcarg{krb5_address *}{sender_addr} -\funcarg{krb5_pointer}{fetchfrom} -\funcfuncarg{krb5_error_code}{(*keyproc)} -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcarg{krb5_keyblock **}{key} -\funcendfuncarg -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_tkt_authent **}{authdat} -\end{funcdecl} - -Essentially the same as \funcname{krb5_rd_req}, but uses a decoded AP_REQ -as the input rather than an encoded input. - -\begin{funcdecl}{krb5_mk_rep}{krb5_error_code}{\funcin} -\funcarg{const krb5_ap_rep_enc_part *}{repl} -\funcarg{const krb5_keyblock *}{kblock} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats and encrypts an AP_REP message, using \funcparam{*repl} for the -encrypted part of the message. The message is encrypted under the key -in \funcparam{*kblock}, then encoded and left in outbuf. - -The output buffer storage is allocated, and should be freed by the -caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_rd_rep}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{inbuf} -\funcarg{const krb5_keyblock *}{kblock} -\funcout -\funcarg{krb5_ap_rep_enc_part **}{repl} -\end{funcdecl} - -Parses and decrypts an AP_REP message from \funcparam{*inbuf}, filling in -\funcparam{*repl} with a pointer allocating storage containing the -values from the message. The caller is responsible for freeing this -structure with \funcname{krb5_free_ap_rep_enc_part}. - -The key in \funcparam{*kblock} is used to decrypt the message. - -Returns system errors. - -\begin{funcdecl}{krb5_mk_error}{krb5_error_code}{\funcin} -\funcarg{krb5_error *}{dec_err} -\funcout -\funcarg{krb5_data *}{enc_err} -\end{funcdecl} - -Formats the error structure \funcparam{*dec_err} into an error buffer -\funcparam{*enc_err}. - -The error buffer storage is allocated, and should be freed by the -caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_rd_error}{krb5_error_code}{\funcin} -\funcarg{krb5_data *}{enc_errbuf} -\funcout -\funcarg{krb5_error **}{dec_error} -\end{funcdecl} - -Parses an error message from \funcparam{enc_errbuf} and fills in -\funcparam{*dec_error} with a pointer to allocated storage containing -the error message. The caller is reponsible for free this structure by -using \funcname{krb5_free_error}. - -Upon return \funcparam{dec_error{\ptsto}client}, -\funcparam{dec_error{\ptsto}server}, and -\funcparam{dec_error{\ptsto}text}, if non-NULL, point to allocated -storage which the caller should free when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_generate_seq_number}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{key} -\funcout -\funcarg{krb5_int32 *}{seqno} -\end{funcdecl} - -Generates a pseudo-random sequence number suitable for use as an initial -sequence number for the KRB_SAFE and KRB_PRIV message processing -routines. - -\funcparam{key} parameterizes the choice of the random sequence number, -which is filled into \funcparam{*seqno} upon return. - -\begin{funcdecl}{krb5_sendauth}{krb5_error_code} -\funcin -\funcarg{krb5_pointer}{fd} -\funcarg{char *}{appl_version} -\funcarg{krb5_principal}{client} -\funcarg{krb5_principal}{server} -\funcarg{krb5_flags}{ap_req_options} -\funcarg{krb5_checksum *}{checksump} -\funcinout -\funcarg{krb5_creds *}{credsp} -\funcarg{krb5_ccache}{ccache} -\funcout -\funcarg{krb5_int32 *}{sequence} -\funcarg{krb5_keyblock **}{newkey} -\funcarg{krb5_error **}{error} -\funcarg{krb5_ap_rep_enc_part **}{rep_result} -\end{funcdecl} - -\funcname{krb5_sendauth} provides a convenient means for client and -server programs to send authenticated messages to one another through -network connections. \funcname{krb5_sendauth} sends an authenticated -ticket from the client program to the server program using the network -connection specified by \funcparam{fd}. In the MIT Unix implementation, -\funcparam{fd} should be a pointer to a file descriptor describing the -network socket. This can be changed in other implementations, however, -if the routines \funcname{krb5_read_message}, -\funcname{krb5_write_message}, \funcname{krb5_net_read}, and -\funcname{krb5_net_write} are changed.\footnote{Well, this isn't quite -true; the interfaces for \funcname{krb5_net_read} and -\funcname{krb5_net_write} currently take an integer instead of a pointer -to an integer, but this will be fixed soon\ldots} - -The paramter \funcparam{appl_version} is a string describing the -application protocol version which the client is expecting to use for -this exchange. If the server is using a different application protocol, -an error will be returned. - -The parameters \funcparam{client} and \funcparam{server} specify the -kerberos principals for the client and the server. The -\funcparam{ap_req_options} parameters specifies the options which should -be passed to \funcname{krb5_mk_ap_req}. If \funcparam{ap_req_options} -specifies AP_OPTS_MUTUAL_REQUIRED, then \funcname{krb5_sendauth} will -perform a mutual authentication exchange, and if \funcparam{rep_result} -is non-zero, it will be filled in with the result of the mutual -authentication exchange. - -The \funcparam{checksump} paramter is optional; if it is non-zero, then the -checksum structure will be sent to the server as part of the -authenticated ticket exchange. - -If \funcparam{credsp} is nonzero and contains a valid credentials then -the client credentials will be obtained from the structure pointed to by -\funcparam{credsp}. If not, then \funcparam{ccache} must contain a -credentials cache handle where the required credentials can be fetched. - -If non-zero, \funcparam{sequence} is filled in with the sequence number -which the client should use for sending or receiving messages generated -using \funcname{krb5_mk_safe} and \funcname{krb5_mk_priv}. The sequence -number for the server can be determined by looking in the structured -filled in by \funcparam{rep_result}, if mutual authentication was used. -(If mutual authentication was not used, there is no way to negotiate a -sequence number for the server.) - -If an error occurs during the authenticated ticket exchange, the error -packet that was sent from the server will be filled into -\funcparam{error}, if \funcparam{error} is non-zero. - -\begin{funcdecl}{krb5_recvauth}{krb5_error_code} -\funcin -\funcarg{krb5_pointer}{fd} -\funcarg{char *}{appl_version} -\funcarg{krb5_principal}{server} -\funcarg{krb5_address *}{sender_addr} -\funcarg{krb5_pointer}{fetchfrom} -\funcarg{krb5_rdreq_key_proc}{keyproc} -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{char *}{rc_type} -\funcout -\funcarg{krb5_int32 *}{sequence} -\funcarg{krb5_principal *}{client} -\funcarg{krb5_ticket **}{krb5_ticket} -\funcarg{krb5_authenticator **}{authent} -\end{funcdecl} - -\funcname{krb5_sendauth} provides a convenient means for client and -server programs to send authenticated messages to one another through -network connections. \funcname{krb5_recvauth} receives the ticket from -sent by \funcparam{krb5_sendauth}, and, if requested by the client, will -perform mutual authentication to prove to the client that the server -represented by \funcparam{krb5_recvauth} is legitimate. - -\funcparam{fd} is a pointer to the network connection. As in -\funcname{krb5_sendauth}, \funcparam{fd} is a pointer to a file -descriptor in the MIT Unix implementation. - -The parameter \funcparam{appl_version} is a string describing the -application protocol version which the server is expecting to use for -this exchange. If the client is using a different application protocol, -an error will be returned and the authentication exchange will be -aborted. - -The parameters \funcparam{fetchfrom}, \funcparam{keyproc}, and -\funcparam{keyprocarg} are used by \funcname{krb5_rd_req} to obtain the -server's private key. - -\funcparam{rc_type} is a string which determins which type of replace -cache \funcname{krb5_recvauth} should use. \funcname{krb5_recvauth} -uses a standard convention for determining the name of the replay cache -to be used. - -All of the output paramters are optional and they are only filled in if -they are non-NULL. \funcparam{sequence} is filled in with the -sequence number which the server should use (if desired) for sending or -receiving message using \funcname{krb5_mk_safe} and -\funcname{krb5_mk_priv}. The client's sequence number is passed back -as part of the authenticator structure which is filled in if -\funcparam{authent} is nonzero. - -\funcparam{client} is filled in with the client principal which -initiated the authenticated connection. - -\begin{funcdecl}{krb5_mk_safe}{krb5_error_code}{\funcin} -\funcarg{krb5_data *}{userdata} -\funcarg{krb5_cksumtype}{sumtype} -\funcarg{krb5_keyblock *}{key,} -\funcarg{krb5_fulladdr *}{sender_addr} -\funcarg{krb5_fulladdr *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{safe_flags} -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_SAFE message into \funcparam{outbuf}. - -\funcparam{userdata} is formatted as the user data in the message. -\funcparam{sumtype} specifies the encryption type; \funcparam{key} -specifies the key which might be used to seed the checksum; -\funcparam{sender_addr} and \funcparam{recv_addr} specify the full -addresses (host and port) of the sender and receiver. The host portion -of \funcparam{sender_addr} is used to form the addresses used in the -KRB_SAFE message. - -\funcparam{safe_flags} selects whether sequence numbers or timestamps -should be used to identify the message. If timestamps are to be used, -an entry describing the message will be entered in the replay cache -\funcparam{rcache} so that the caller may detect if this message is sent -back to him by an attacker. - -The functions \funcname{krb5_gen_replay_name} and -\funcname{krb5_get_server_rcache} can be used to open a replay cache -appropriate to use as \funcparam{rcache}. - -The \funcparam{outbuf} buffer storage is allocated, and should be freed by the -caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_rd_safe}{krb5_error_code}{\funcin} -\funcarg{krb5_data *}{inbuf} -\funcarg{krb5_keyblock *}{key} -\funcarg{krb5_address *}{sender_addr} -\funcarg{krb5_address *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{safe_flags} -\funcinout -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Parses a KRB_SAFE message from \funcparam{inbuf}, placing the -integrity-protected user data in \funcparam{*outbuf}. - -\funcparam{key} specifies the key to be used for decryption of the message. - -\funcparam{sender_addr} and \funcparam{recv_addr} specify the full -addresses (host and port) of the sender and receiver. - -\funcparam{outbuf} points to allocated storage which the caller should -free when finished. - -If \funcparam{safe_flags} indicates that sequence numbers are to be -used, \funcparam{seq_number} is used as the sequence number for the -message. If this is not the case, a timestamp is inserted in the -message, and \funcparam{sender_addr} must be of type -\datatype{ADDRTYPE_ADDRPORT}, and the message is checked for replays -against the cache entries in \funcparam{rcache}. - -The function \funcname{krb5_get_server_rcache} and the service-name -portion of the server principal name can be used to open a -replay cache appropriate to use as \funcparam{rcache}. - -Returns system errors, integrity errors. - -\begin{funcdecl}{krb5_mk_priv}{krb5_error_code}{\funcin} -\funcarg{krb5_data *}{userdata} -\funcarg{krb5_enctype}{etype} -\funcarg{krb5_keyblock *}{key} -\funcarg{krb5_fulladdr *}{sender_addr} -\funcarg{krb5_fulladdr *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{priv_flags} -\funcarg{krb5_rcache}{rcache} -\funcinout -\funcarg{krb5_pointer}{i_vector} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_PRIV message into \funcparam{outbuf}. - -\funcparam{userdata} is formatted as the user data in the message. -\funcparam{etype} specifies the encryption type; \funcparam{key} -specifies the key for the encryption; \funcparam{sender_addr} and -\funcparam{recv_addr} specify the full addresses (host and port) of the -sender and receiver. - -\funcparam{i_vector} is used as an initialization vector for the -encryption, and if non-NULL its contents are replaced with the last -block of the encrypted data upon exit. - -\funcparam{priv_flags} selects whether sequence numbers or timestamps -should be used to identify the message. If timestamps are to be used, -an entry describing the message will be entered in the replay cache -\funcparam{rcache} so that the caller may detect if this message is sent -back to him by an attacker. - -The functions \funcname{krb5_gen_replay_name} and -\funcname{krb5_get_server_rcache} can be used to open a replay cache -appropriate to use as \funcparam{rcache}. - -The \funcparam{outbuf} buffer storage is allocated, and should be freed by the -caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_rd_priv}{krb5_error_code}{\funcin} -\funcarg{krb5_data *}{inbuf} -\funcarg{krb5_keyblock *}{key} -\funcarg{krb5_fulladdr *}{sender_addr} -\funcarg{krb5_fulladdr *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{priv_flags} -\funcinout -\funcarg{krb5_pointer}{i_vector} -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Parses a KRB_PRIV message from \funcparam{inbuf}, placing the confidential user -data in \funcparam{*outbuf}. - -\funcparam{key} specifies the key to be used for decryption of the message. - -\funcparam{sender_addr} and \funcparam{recv_addr} specify the full -addresses (host and port) of the sender and receiver. - -\funcparam{outbuf} points to allocated storage which the caller should -free when finished. - -\funcparam{i_vector} is used as an initialization vector for the -encryption, and if non-NULL its contents are replaced with the last -block of the encrypted data upon exit. - -If \funcparam{priv_flags} indicates that sequence numbers are to be -used, \funcparam{seq_number} is used as the sequence number for the -message. If this is not the case, a timestamp is inserted in the -message, and \funcparam{sender_addr} must be of type -\datatype{ADDRTYPE_ADDRPORT}, and the message is checked for replays -against the cache entries in \funcparam{rcache}. - -The function \funcname{krb5_get_server_rcache} and the service-name -portion of the server principal name can be used to open a -replay cache appropriate to use as \funcparam{rcache}. - -Returns system errors, integrity errors. - -\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcin} -\funcarg{char *}{name} -\funcout -\funcarg{krb5_principal *}{principal} -\end{funcdecl} - -Converts a single-string representation \funcparam{name} of the -principal name to the multi-part principal format used in the protocols. - -\funcparam{*principal} will point to allocated storage which should be freed by -the caller (using \funcname{krb5_free_principal}) after use. - -\funcname{krb5_parse_name} returns KRB5_PARSE_MALFORMED if the string is - badly formatted, or ENOMEM if space for the return value can't be -allocated. - -\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcin} -\funcarg{krb5_principal}{principal} -\funcout -\funcarg{char **}{name} -\end{funcdecl} - -Converts the multi-part principal name \funcparam{principal} from the -format used in the protocols to a single-string representation of the name. - -\funcparam{*name} points to allocated storage and should be freed by the caller -when finished. - -\funcname{krb5_unparse_name} returns KRB_PARSE_MALFORMED if the principal -does not contain at least 2 components, and system errors (ENOMEM if -unable to allocate memory). - -\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcout} -\funcarg{krb5_principal *}{princ} -\funcin -\funcarg{int}{rlen} -\funcarg{const char *}{realm} -\funcarg{char}{*s1, *s2, ..., 0} -\end{funcdecl} -\begin{funcdecl}{krb5_build_principal_va}{krb5_error_code}{\funcout} -\funcarg{krb5_principal *}{princ} -\funcin -\funcarg{int}{rlen} -\funcarg{const char *}{realm} -\funcarg{va_list}{ap} -\end{funcdecl} - -\funcname{krb5_build_principal} and \funcname{krb5_build_principal_va} -perform the same function; the former takes variadic arguments, while -the latter takes a pre-computed varargs pointer. - -Both functions take a realm name \funcparam{realm}, realm name length -\funcparam{rlen}, and a list of null-terminated strings, and fill in a -pointer to a principal structure \funcparam{princ}, making it point to a -structure representing the named principal. -The last string must be followed in the argument list by a null pointer. - - -\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcout} -\funcarg{krb5_principal *}{princ} -\funcin -\funcarg{int}{rlen} -\funcarg{const char *}{realm} -\funcarg{}{int len1, char *s1, int len2, char *s2, ..., 0} -\end{funcdecl} - -\funcname{krb5_build_principal_ext} is similar to -\funcname{krb5_build_principal} but it takes its components as a list of -(length, contents) pairs rather than a list of null-terminated strings. -A length of zero indicates the end of the list. - -\begin{funcdecl}{krb5_address_search}{krb5_boolean}{\funcin} -\funcarg{krb5_address *}{addr} -\funcarg{krb5_address **}{addrlist} -\end{funcdecl} - -If \funcparam{addr} is listed in \funcparam{addrlist}, or -\funcparam{addrlist} is null, return TRUE. If not listed, return FALSE. - -\begin{funcdecl}{krb5_address_compare}{krb5_boolean}{\funcin} -\funcarg{krb5_address *}{addr1} -\funcarg{krb5_address *}{addr2} -\end{funcdecl} - -If the two addresses are the same, return TRUE, else return FALSE. - -\begin{funcdecl}{krb5_principal_compare}{krb5_boolean}{\funcin} -\funcarg{krb5_principal}{p1} -\funcarg{krb5_principal}{p2} -\end{funcdecl} - -If the two principals are the same, return TRUE, else return FALSE. - -\begin{funcdecl}{krb5_fulladdr_order}{int}{\funcin} -\funcarg{krb5_fulladdr *}{addr1} -\funcarg{krb5_fulladdr *}{addr2} -\end{funcdecl} - -Return an ordering on the two full addresses: 0 if the same, -$< 0$ if first is less than 2nd, $> 0$ if first is greater than 2nd. - -\begin{funcdecl}{krb5_address_order}{int}{\funcin} -\funcarg{const krb5_address *}{addr1} -\funcarg{const krb5_address *}{addr2} -\end{funcdecl} - -Return an ordering on the two addresses: 0 if the same, -$< 0$ if first is less than 2nd, $> 0$ if first is greater than 2nd. - -\begin{funcdecl}{krb5_copy_keyblock}{krb5_error_code}{\funcin} -\funcarg{krb5_keyblock *}{from} -\funcout -\funcarg{krb5_keyblock **}{to} -\end{funcdecl} - -Copy a keyblock, filling in \funcparam{*to} to point to the newly -allocated copy, which should be freed with -\funcname{krb5_free_keyblock}. - -\begin{funcdecl}{krb5_copy_keyblock_contents}{krb5_error_code}{\funcin} -\funcarg{krb5_keyblock *}{from} -\funcout -\funcarg{krb5_keyblock *}{to} -\end{funcdecl} - -Copy a keyblock from \funcparam{from} to \funcparam{to}, including -allocated storage. The allocated storage in \funcparam{to} should be -freed by using {\bf free}(\funcparam{to->contents}). - -\begin{funcdecl}{krb5_copy_creds}{krb5_error_code}{\funcin} -\funcarg{krb5_creds *}{incred} -\funcout -\funcarg{krb5_creds **}{outcred} -\end{funcdecl} - -Copy a credentials structure, filling in \funcparam{*outcred} to point -to the newly allocated copy, which should be freed with -\funcname{krb5_free_creds}. - -\begin{funcdecl}{krb5_copy_data}{krb5_error_code}{\funcin} -\funcarg{krb5_data *}{indata} -\funcout -\funcarg{krb5_data **}{outdata} -\end{funcdecl} - -Copy a data strucutre, filling in \funcparam{*outdata} to point to the -newly allocated copy, which should be freed with \funcname{krb5_free_data}. - -\begin{funcdecl}{krb5_copy_principal}{krb5_error_code}{\funcin} -\funcarg{krb5_principal}{inprinc} -\funcout -\funcarg{krb5_principal *}{outprinc} -\end{funcdecl} -Copy a principal structure, filling in \funcparam{*outprinc} to point to -the newly allocated copy, which should be freed with -\funcname{krb5_free_principal}. - -\begin{funcdecl}{krb5_auth_to_rep}{krb5_error_code}{\funcin} -\funcarg{krb5_tkt_authent *}{auth} -\funcout -\funcarg{krb5_donot_replay *}{rep} -\end{funcdecl} -Extract the relevant parts of \funcparam{auth} and fill them into the -structure pointed to by \funcparam{rep}. \funcparam{rep{\ptsto}client} -and \funcparam{rep{\ptsto}server} are set to allocated storage and -should be freed when \funcparam{*rep} is no longer needed. - -\begin{funcdecl}{krb5_get_server_rcache}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{piece} -\funcout -\funcarg{krb5_rcache *}{ret_rcache} -\end{funcdecl} -Generate a replay cache name, allocate space for its handle, and open -it. \funcarg{piece} is used to distinguish this replay cache from -others currently in use on the system. -Upon successful return, \funcarg{ret_rcache} is filled in to contain a -handle to an open rcache, which should be closed with -\funcname{krb5_rc_close} and then freed with \funcname{xfree} when the -caller is finished using it. diff --git a/doc/api/libdes.tex b/doc/api/libdes.tex deleted file mode 100644 index d1412bccb..000000000 --- a/doc/api/libdes.tex +++ /dev/null @@ -1,38 +0,0 @@ -\documentstyle[newcen,fixunder,functions,twoside]{article} -\setlength{\oddsidemargin}{0.25in} -\setlength{\evensidemargin}{-0.25in} -\setlength{\topmargin}{-.5in} -\setlength{\textheight}{9in} -\setlength{\parskip}{.1in} -\setlength{\parindent}{2em} -\setlength{\textwidth}{6.25in} - -\pagestyle{headings} -\begin{document} -\begin{center} -{\Huge Kerberos V5 Data Encryption Standard library} \\ -{\Large DRAFT} -\end{center} -\section{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}. - -\end{document} diff --git a/doc/api/libos.tex b/doc/api/libos.tex deleted file mode 100644 index bdd873339..000000000 --- a/doc/api/libos.tex +++ /dev/null @@ -1,325 +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 -}; other definitions (including macros, if used) are -in {\tt }. - -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} - -\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_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_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{krb5_data *}{send} -\funcarg{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{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 -pointer to an argv[] style list of names, terminated with a null -pointer. - -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 **}{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_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{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 **}{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} -\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. -\funcparam{hostname} is placed into canonical form before being composed -into the returned principal \funcparam{ret_princ}. The realm of the -principal is determined internally by calling \funcname{krb5_get_host_realm}. - -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/api/library.tex b/doc/api/library.tex deleted file mode 100644 index 3634b0dc4..000000000 --- a/doc/api/library.tex +++ /dev/null @@ -1,82 +0,0 @@ -\documentstyle[ncs,fixunder,functions,changebar,twoside,fancyheadings]{article} -\setlength{\oddsidemargin}{0in} -\setlength{\evensidemargin}{1.00in} -\setlength{\marginparsep}{0.05in} -\setlength{\marginparwidth}{1in} -\setlength{\textwidth}{5.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 -\drafttrue -% -% Far, far too inconvenient... it's still very draft-like anyway.... -% [tytso:19900921.0018EDT] -% -%\typein{Draft flag? (type \noexpand\draftfalse 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 -\begin{document} -\thispagestyle{empty} -\begin{center} -{\Huge Kerberos V5 application programming library} -\ifdraft \\ {\Large DRAFT---\today}\fi -\end{center} -\section{libkrb5.a functions} -This section describes the functions provided in the \libname{libkrb5.a} -library. The library is built from several pieces, mostly for convenience in -programming, maintenance, and porting. - -\ifdraft\sloppy\fi - -\subsection{Main functions} -\input{krb5.tex} - -\subsection{Credentials cache functions} -\input{ccache.tex} - -\subsection{Replay cache functions} -\input{rcache.tex} - -\subsection{Key table functions} -\input{keytab.tex} - -\section{Operating-system specific functions} -\input{libos.tex} - -\section{Principal database functions} - -\input{kdb.tex} - -\section{Encryption system interface} -\input{encrypt.tex} - -\section{Checksum interface} -\input{cksum.tex} - -\section{CRC-32 checksum functions} -\input{crc-32.tex} - -\appendix -\cleardoublepage -\input{\jobname.ind} -\end{document} diff --git a/doc/api/rcache.tex b/doc/api/rcache.tex deleted file mode 100644 index 7292ed005..000000000 --- a/doc/api/rcache.tex +++ /dev/null @@ -1,151 +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 ``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{Per-type functions} -The following entry points must be implemented for each type of -credentials cache. - -\begin{funcdecl}{krb5_rc_initialize}{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}{krb5_rc_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}{krb5_rc_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}{krb5_rc_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}{krb5_rc_store}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_dont_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}{krb5_rc_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}{krb5_rc_get_lifespan}{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}{krb5_rc_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{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. - -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. - -\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 \funcnamenoparens{krb5_rc_resolve_full}(\funcparam{id}, -\funcnamenoparens{strcat}(\funcnamenoparens{strcat}(\funcname{krb5_rc_default_type},``:''), -\funcname{krb5_rc_default_name})) (except of course you can't do the -strcat's with the return values\ldots). diff --git a/doc/implement/Makefile b/doc/implement/Makefile deleted file mode 100644 index d5a6f7908..000000000 --- a/doc/implement/Makefile +++ /dev/null @@ -1,29 +0,0 @@ -.SUFFIXES: .tex .dvi .ps - -STYLES=changebar.sty fixunder.sty functions.sty -LIBTEX= library.tex krb5.tex ccache.tex rcache.tex keytab.tex libos.tex \ - kdb.tex encrypt.tex cksum.tex crc-32.tex library.ind - -DESTEX= libdes.tex - -all: library.ps libdes.ps - - -libdes.dvi: $(DESTEX) $(STYLES) - -library.ps: library.dvi - -# hard to capture two-pass semantics in Makefiles... -# library.ind: library.dvi -library.ind: library.idx - index library.idx - -library.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 83607af9b..000000000 --- a/doc/implement/ccache-i.tex +++ /dev/null @@ -1,236 +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{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}. - - -\begin{funcdecl}{krb5_cc_resolve_internal}{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}{krb5_cc_gennew_internal}{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}{krb5_cc_initialize}{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}{krb5_cc_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}{krb5_cc_close}{krb5_error_code}{\funcinout} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Closes the credentials cache \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. - - -\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_credentials *}{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}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{whichfields} -\funcarg{krb5_credentials *}{mcreds} -\funcout -\funcarg{krb5_credentials *}{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}. XXX free the return creds? - -Errors: error code if no matches found. - -\begin{funcdecl}{krb5_cc_get_principal}{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) -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} -\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{krb5_cc_next_cred}. - -\begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_credentials *}{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{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. - -Errors: error code if no more cache entries. - -\begin{funcdecl}{krb5_cc_end_seq_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{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. - -Errors: may return error code if \funcparam{*cursor} is invalid. - - -\begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{which} -\funcarg{krb5_credentials *}{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}{krb5_cc_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 }. - - -\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/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 198c3224a..000000000 --- a/doc/implement/encrypt-i.tex +++ /dev/null @@ -1,139 +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{const krb5_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. - -Returns errors. - -\begin{funcdecl}{decrypt_func}{krb5_error_code}{\funcvoid} -\funcarg{const krb5_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. - -Returns errors. - -\begin{funcdecl}{process_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{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}. - -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}. - -Returns errors. - -\begin{funcdecl}{string_to_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_keytype}{keytype} -\funcarg{krb5_keyblock *}{keyblock} -\funcarg{krb5_data *}{data} -\funcarg{krb5_principal}{princ} -\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{princ} 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. - -Returns errors. - -\begin{funcdecl}{init_random_key}{krb5_error_code}{\funcvoid} -\funcarg{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. 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 412df84b3..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 /* INOUT */}\\} -\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 3634b0dc4..000000000 --- a/doc/implement/implement.tex +++ /dev/null @@ -1,82 +0,0 @@ -\documentstyle[ncs,fixunder,functions,changebar,twoside,fancyheadings]{article} -\setlength{\oddsidemargin}{0in} -\setlength{\evensidemargin}{1.00in} -\setlength{\marginparsep}{0.05in} -\setlength{\marginparwidth}{1in} -\setlength{\textwidth}{5.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 -\drafttrue -% -% Far, far too inconvenient... it's still very draft-like anyway.... -% [tytso:19900921.0018EDT] -% -%\typein{Draft flag? (type \noexpand\draftfalse 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 -\begin{document} -\thispagestyle{empty} -\begin{center} -{\Huge Kerberos V5 application programming library} -\ifdraft \\ {\Large DRAFT---\today}\fi -\end{center} -\section{libkrb5.a functions} -This section describes the functions provided in the \libname{libkrb5.a} -library. The library is built from several pieces, mostly for convenience in -programming, maintenance, and porting. - -\ifdraft\sloppy\fi - -\subsection{Main functions} -\input{krb5.tex} - -\subsection{Credentials cache functions} -\input{ccache.tex} - -\subsection{Replay cache functions} -\input{rcache.tex} - -\subsection{Key table functions} -\input{keytab.tex} - -\section{Operating-system specific functions} -\input{libos.tex} - -\section{Principal database functions} - -\input{kdb.tex} - -\section{Encryption system interface} -\input{encrypt.tex} - -\section{Checksum interface} -\input{cksum.tex} - -\section{CRC-32 checksum functions} -\input{crc-32.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 443a7b744..000000000 --- a/doc/implement/kdb-i.tex +++ /dev/null @@ -1,233 +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}. 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. - -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}, -{\sl principal\/}) where {\sl principal\/} points to a record from the -database. - -If \funcparam{(*func)}() ever returns an error code, the iteration is -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} -\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. - -If \funcparam{fromkeyboard} is false, then the key is read from -a file whose name is derived from the principal name \funcparam{mname}. - -\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{krb5_keyblock *}{in} -\funcinout -\funcarg{krb5_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{krb5_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 4a45295c5..000000000 --- a/doc/implement/keytab-i.tex +++ /dev/null @@ -1,250 +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. 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 -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. - -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} -\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}{krb5_kt_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}{krb5_kt_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}{krb5_kt_get_entry}{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. - -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. - -\begin{funcdecl}{krb5_kt_free_entry}{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}. - -\begin{funcdecl}{krb5_kt_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{krb5_kt_next_entry}. - -\begin{funcdecl}{krb5_kt_next_entry}{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 is -guaranteed. \funcparam{*entry} should be freed after use by calling -\funcname{krb5_kt_free_entry}. - -Requires that \funcparam{id} identifies a valid credentials cache. and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. - -Errors: error code if no more cache entries or if the keytab changes. - -\begin{funcdecl}{krb5_kt_end_seq_get}{krb5_error_code}{\funcin} -\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{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. - -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. - -Returns an error code if not found. - - -\begin{funcdecl}{krb5_kt_add_internal}{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. - -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. - -An error is returned if \funcparam{ops{\ptsto}prefix} is already known. - -\begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcin} -\funcarg{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} -\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. - -\begin{funcdecl}{krb5_kt_remove_entry}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -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 deleted file mode 100644 index bdd873339..000000000 --- a/doc/implement/libos-i.tex +++ /dev/null @@ -1,325 +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 -}; other definitions (including macros, if used) are -in {\tt }. - -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} - -\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_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_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{krb5_data *}{send} -\funcarg{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{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 -pointer to an argv[] style list of names, terminated with a null -pointer. - -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 **}{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_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{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 **}{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} -\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. -\funcparam{hostname} is placed into canonical form before being composed -into the returned principal \funcparam{ret_princ}. The realm of the -principal is determined internally by calling \funcname{krb5_get_host_realm}. - -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 deleted file mode 100644 index 7292ed005..000000000 --- a/doc/implement/rcache-i.tex +++ /dev/null @@ -1,151 +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 ``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{Per-type functions} -The following entry points must be implemented for each type of -credentials cache. - -\begin{funcdecl}{krb5_rc_initialize}{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}{krb5_rc_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}{krb5_rc_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}{krb5_rc_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}{krb5_rc_store}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_dont_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}{krb5_rc_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}{krb5_rc_get_lifespan}{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}{krb5_rc_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{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. - -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. - -\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 \funcnamenoparens{krb5_rc_resolve_full}(\funcparam{id}, -\funcnamenoparens{strcat}(\funcnamenoparens{strcat}(\funcname{krb5_rc_default_type},``:''), -\funcname{krb5_rc_default_name})) (except of course you can't do the -strcat's with the return values\ldots). diff --git a/src/.rconf b/src/.rconf deleted file mode 100644 index 7a67b578c..000000000 --- a/src/.rconf +++ /dev/null @@ -1,48 +0,0 @@ -; To build a symlink tree, do: -; -; /mit/synctree/synctree -s /mit/krb5/src -d /mit/krb5/build/@sys - -map * $ - -copy *;d -link *;r -link include/stdc-incl -link include/isode-6.8 -link config -copy include/isode -copy include/com_err.h -copy *Makefile -ignore rconf -ignore *~ -ignore *RCS -ignore *Makefile.bak -ignore *,v -ignore *.o -ignore *.a -ignore include/isode-5.0 -ignore prototype -ignore lib/des.v4 -ignore *.rconf -ignore *.orig -ignore *.rej -ignore .saberinit -ignore TODO -ignore man -ignore *TAGS -ignore *tags -ignore Link_src.sh -ignore cat -ignore RCSFILES -ignore *.new -ignore *.old -ignore CFILES -ignore mdebug -ignore API.CHANGES -ignore util -ignore *fookrb5 -ignore MAKEFILES -ignore STDC-grep -ignore IMAKEFILES -ignore config-files -ignore dtree.out -ignore RCS.locked