From 46b1154fba8cd3d8109ba4e274a94bbeb20e0d90 Mon Sep 17 00:00:00 2001 From: no author Date: Wed, 19 Jan 1994 02:45:38 +0000 Subject: [PATCH] This commit was manufactured by cvs2svn to create tag 'BETA_3' git-svn-id: svn://anonsvn.mit.edu/krb5/tags/BETA_3@3366 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/api/Makefile | 29 - doc/api/ccache.tex | 237 ----- doc/api/fixunder.sty | 48 - doc/api/functions.sty | 70 -- doc/api/keytab.tex | 250 ----- doc/api/krb5.tex | 1115 -------------------- doc/api/libdes.tex | 38 - doc/api/libos.tex | 377 ------- doc/api/library.tex | 82 -- doc/api/rcache.tex | 155 --- doc/implement/Makefile | 29 - doc/implement/ccache-i.tex | 237 ----- doc/implement/cksum-i.tex | 31 - doc/implement/crc-32-i.tex | 20 - doc/implement/encrypt-i.tex | 142 --- doc/implement/fixunder.sty | 48 - doc/implement/functions.sty | 70 -- doc/implement/implement.tex | 82 -- doc/implement/kdb-i.tex | 241 ----- doc/implement/keytab-i.tex | 250 ----- doc/implement/libos-i.tex | 377 ------- doc/implement/rcache-i.tex | 155 --- doc/kadm5/api-funcspec.tex | 1521 --------------------------- doc/kadm5/api-server-design.tex | 584 ---------- doc/kadm5/api-unit-test.tex | 1755 ------------------------------- 25 files changed, 7943 deletions(-) delete mode 100644 doc/api/Makefile delete mode 100644 doc/api/ccache.tex delete mode 100644 doc/api/fixunder.sty delete mode 100644 doc/api/functions.sty delete mode 100644 doc/api/keytab.tex delete mode 100644 doc/api/krb5.tex delete mode 100644 doc/api/libdes.tex delete mode 100644 doc/api/libos.tex delete mode 100644 doc/api/library.tex delete mode 100644 doc/api/rcache.tex delete mode 100644 doc/implement/Makefile delete mode 100644 doc/implement/ccache-i.tex delete mode 100644 doc/implement/cksum-i.tex delete mode 100644 doc/implement/crc-32-i.tex delete mode 100644 doc/implement/encrypt-i.tex delete mode 100644 doc/implement/fixunder.sty delete mode 100644 doc/implement/functions.sty delete mode 100644 doc/implement/implement.tex delete mode 100644 doc/implement/kdb-i.tex delete mode 100644 doc/implement/keytab-i.tex delete mode 100644 doc/implement/libos-i.tex delete mode 100644 doc/implement/rcache-i.tex delete mode 100644 doc/kadm5/api-funcspec.tex delete mode 100644 doc/kadm5/api-server-design.tex delete mode 100644 doc/kadm5/api-unit-test.tex 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 983eb0d8b..000000000 --- a/doc/api/ccache.tex +++ /dev/null @@ -1,237 +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_gen_new_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 \funcparam{id} and any other resources -acquired during use of the credentials cache. Requires that -\funcparam{id} identifies a valid credentials cache. After return, -\funcparam{id} must not be used unless it is first reinitialized. - - -\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Stores \funcparam{creds} in the cache \funcparam{id}, tagged with -\funcparam{creds{\ptsto}client}. -Requires that \funcparam{id} identifies a valid credentials cache. - -Errors: permission errors, storage failure errors. - -\begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{whichfields} -\funcarg{krb5_creds *}{mcreds} -\funcout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Searches the cache \funcparam{id} for credentials matching -\funcparam{mcreds}. The fields which are to be matched are specified by -set bits in \funcparam{whichfields}, and always include the principal -name \funcparam{mcreds{\ptsto}server}. -Requires that \funcparam{id} identifies a valid credentials cache. - -If at least one match is found, one of the matching credentials is -returned in \funcparam{*creds}. The credentials should be freed using -\funcname{krb5_free_credentials}. - -Errors: error code if no matches found. - -\begin{funcdecl}{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_creds *}{creds} -\funcinout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Fetches the next entry from \funcparam{id}, returning its values in -\funcparam{*creds}, and updates \funcparam{*cursor} for the next request. -Requires that \funcparam{id} identifies a valid credentials cache and -\funcparam{*cursor} be a cursor returned by -\funcname{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_creds *}{cred} -\end{funcdecl} - -Removes any credentials from \funcparam{id} which match the principal -name {cred{\ptsto}server} and the fields in \funcparam{cred} masked by -\funcparam{which}. -Requires that \funcparam{id} identifies a valid credentials cache. - -Errors: returns error code if nothing matches; returns error code if -couldn't delete. - -\begin{funcdecl}{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 a3165f811..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 /* IN/OUT */}\\} -\newcommand{\funcout}{\docomm@\argc@ount=0{\sl /* OUT */}\\} -\newcommand{\funcarg}[2]{\docomm@#1 {\argfont #2}\advance\argc@ount by1} -\newcommand{\funcparam}[1]{{\argfont #1}} -\newcommand{\funcfuncarg}[2]{\docomm@#1 {\argfont #2}(\= \+ \argc@ount=0} -\newcommand{\funcendfuncarg}{), \- \\ \argc@ount=0} -\newcommand{\libname}[1]{{\argfont #1}} -\newcommand{\globalname}[1]{{\argfont #1}} -\newcommand{\ptsto}{->\discretionary{}{}{}} -\newcommand{\datatype}[1]{{\bf #1}} -\newcommand{\filename}[1]{{\sl #1\/}} - -\newcommand{\funcname}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}()} -\newcommand{\funcnamenoparens}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}} diff --git a/doc/api/keytab.tex b/doc/api/keytab.tex deleted file mode 100644 index a10e40fd4..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{const char *}{string_name} -\funcout -\funcarg{krb5_keytab *}{id} -\end{funcdecl} - -Fills in \funcparam{*id} with a handle identifying the keytab with name -``string_name''. The keytab is not opened. -Requires that \funcparam{string_name} be of the form ``type:residual'' and -``type'' is a type known to the library. - -Errors: badly formatted name. - -\begin{funcdecl}{krb5_kt_default_name}{krb5_error_code}{\funcin} -\funcarg{char *}{name} -\funcarg{int}{namesize} -\end{funcdecl} - -\funcparam{name} is filled in with the first \funcparam{namesize} bytes of -the name of the default keytab. -If the name is shorter than \funcparam{namesize}, then the remainder of -\funcparam{name} will be zeroed. - - -\begin{funcdecl}{krb5_kt_default}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab *}{id} -\end{funcdecl} - -Fills in \funcparam{id} with a handle identifying the default keytab. - -\begin{funcdecl}{krb5_kt_read_service_key}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcout -\funcarg{krb5_keyblock **}{key} -\end{funcdecl} - -This function is suitable for use as a parameter to -\funcname{krb5_rd_req}. - -If \funcname{keyprocarg} is not NULL, it is taken to be a -\datatype{char *} denoting the name of a keytab. Otherwise, the default -keytab will be used. -The keytab is opened and searched for the entry identified by -\funcparam{principal} and \funcparam{vno}, returning the resulting key -in \funcparam{*key} or returning an error code if it is not found. - -\funcname{krb5_free_keyblock} should be called on \funcparam{*key} when -the caller is finished with the key. - -Returns an error code if the entry is not found. - -\begin{funcdecl}{krb5_kt_add_entry}{krb5_error_code}{\funcin} -\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 9a195dbdd..000000000 --- a/doc/api/krb5.tex +++ /dev/null @@ -1,1115 +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{const krb5_msgtype}{type} -\funcarg{const krb5_enc_kdc_rep_part *}{encpart} -\funcarg{const 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{const krb5_keyblock *}{key} -\funcarg{const 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{const krb5_keyblock *}{key} -\funcarg{krb5_const_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{const 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{const 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{const krb5_flags}{options} -\funcarg{const krb5_ticket_times *}{timestruct} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_cksumtype}{sumtype} -\funcarg{krb5_const_principal}{sname} -\funcarg{krb5_address * const *}{addrs} -\funcarg{krb5_authdata * const *}{authorization_data} -\funcarg{krb5_pa_data * const *}{padata} -\funcarg{const 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_data}, if non-NULL, is used for -\funcparam{authorization_data} in the KRB_TGS_REQ. -\funcparam{ padata}, if non-NULL, is combined with any other supplied -pre-authentication data for 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 -\funcarg{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{const 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{krb5_get_credentials} will only search the credentials cache -for a ticket. If \funcparam{options} specifies KRB5_GC_USER_USER, -\funcname{krb5_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{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_preauthtype}{pre_auth_type} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_keytype}{keytype} -\funcfuncarg{krb5_error_code}{(*key_proc)} - \funcarg{const krb5_keytype}{type} - \funcarg{krb5_keyblock **}{key} - \funcarg{krb5_const_pointer}{keyseed} - \funcarg{krb5_pa_data **}{padata} -\funcendfuncarg -\funcarg{krb5_const_pointer}{keyseed} -\funcfuncarg{krb5_error_code}{(*decrypt_proc)} - \funcarg{const krb5_keyblock *}{key} - \funcarg{krb5_const_pointer}{decryptarg} - \funcarg{krb5_kdc_rep *}{dec_rep} -\funcendfuncarg -\funcarg{krb5_const_pointer}{decryptarg} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_ccache}{ccache} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\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}, using the following: -the realm from \funcparam{creds{\ptsto}client}; the options in -\funcparam{options}; and \funcparam{ pre_auth_type}, the preauthentication -method, which could be KRB5_PADATA_NONE if no preauthentication is -desired. \funcname{krb5_get_in_tkt} requests encryption type -\funcparam{etype}, 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. - -% This paragraph needs to be expanded. ?? Along the lines of the -% comment below: - -\funcparam{key_proc} is called to fill in the key to be used for decryption. -\funcparam{keyseed} and \funcparam{padata} passed on to -\funcparam{key_proc}. - -%\funcparam{padata} may contain a hint of the -%proper salting argument for \funcname{ string_to_key}. - -\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. - -If \funcparam{ret_as_reply} is non_null, it is filled in with a -pointer to a structure containing the reply packet from the KDC. Some -programs may find it useful to have direct access to this information. -For example, it can be used to obtain the pre-authentication data -passed back from the KDC. The caller is responsible for freeing this -structure by using \funcname{krb5_free_kdc_rep}. - -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{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_preauthtype}{pre_auth_type} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_keytype}{keytype} -\funcarg{const char *}{password} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\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. - -If \funcparam{ret_as_reply} is non_null, it is filled in with a -pointer to a structure containing the reply packet from the KDC. Some -programs may find it useful to have direct access to this information. -For example, it can be used to obtain the pre-authentication data -passed back from the KDC. The caller is responsible for freeing this -structure by using \funcname{krb5_free_kdc_rep}. - -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{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_preauthtype}{pre_auth_type} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_keyblock *}{key} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\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. - -If \funcparam{ret_as_reply} is non_null, it is filled in with a -pointer to a structure containing the reply packet from the KDC. Some -programs may find it useful to have direct access to this information. -For example, it can be used to obtain the pre-authentication data -passed back from the KDC. The caller is responsible for freeing this -structure by using \funcname{krb5_free_kdc_rep}. - -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_const_principal}{server} -\funcarg{const krb5_flags}{ap_req_options} -\funcarg{const 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{const krb5_flags}{ap_req_options} -\funcarg{const krb5_checksum *}{checksum} -\funcarg{const 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{const krb5_data *}{inbuf} -\funcarg{krb5_const_principal}{server} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{krb5_const_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{const krb5_ap_req *}{req} -\funcarg{krb5_const_principal}{server} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{krb5_const_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{const 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{const 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} -\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{char *}{rc_type} -\funcarg{krb5_int32}{flags} -\funcout -\funcarg{krb5_int32 *}{sequence} -\funcarg{krb5_principal *}{client} -\funcarg{krb5_ticket **}{krb5_ticket} -\funcarg{krb5_authenticator **}{authent} -\end{funcdecl} - -\funcname{krb5_recvauth} provides a convenient means for client and -server programs to send authenticated messages to one another through -network connections. \funcname{krb5_sendauth} is the matching routine -to \funcname{ krb5_recvauth} for the server. \funcname{ -krb5_recvauth} will engage in an authentication dialogue with the -client program running \funcname{krb5_sendauth} to authenticate the -client to the server. In addition, if requested by the client, -\funcname{krb5_recvauth} will also provide mutual authentication to -prove to the client that the server represented by -\funcname{krb5_recvauth} is legitmate. - -\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. - -The \funcparam{flags} argument allows the caller to modify the behavior of -\funcname{krb5_recvauth}. For non-library callers, \funcparam{flags} -should be 0. - -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{const krb5_data *}{userdata} -\funcarg{const krb5_cksumtype}{sumtype} -\funcarg{const krb5_keyblock *}{key,} -\funcarg{const krb5_fulladdr *}{sender_addr} -\funcarg{const 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{const krb5_data *}{inbuf} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const 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{const krb5_data *}{userdata} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const krb5_address *}{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 addresses 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{const krb5_data *}{inbuf} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const krb5_address *}{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 addresses -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{const 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_const_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{const krb5_address *}{addr} -\funcarg{krb5_address * const *}{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{const krb5_address *}{addr1} -\funcarg{const 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_const_principal}{p1} -\funcarg{krb5_const_principal}{p2} -\end{funcdecl} - -If the two principals are the same, return TRUE, else return FALSE. - -\begin{funcdecl}{krb5_fulladdr_order}{int}{\funcin} -\funcarg{const krb5_fulladdr *}{addr1} -\funcarg{const 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{const 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{const 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{const 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{const krb5_data *}{indata} -\funcout -\funcarg{krb5_data **}{outdata} -\end{funcdecl} - -Copy a data structure, 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_const_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. \funcparam{piece} is used to distinguish this replay cache from -others currently in use on the system. -Upon successful return, \funcparam{ret_rcache} is filled in to contain a -handle to an open rcache, which should be closed with -\funcname{krb5_rc_close}. diff --git a/doc/api/libdes.tex b/doc/api/libdes.tex deleted file mode 100644 index c53c81350..000000000 --- a/doc/api/libdes.tex +++ /dev/null @@ -1,38 +0,0 @@ -\documentstyle[ncs,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 5063b5723..000000000 --- a/doc/api/libos.tex +++ /dev/null @@ -1,377 +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_create_secure_file}{krb5_error_code}{\funcin} -\funcarg{const char *}{pathname} -\end{funcdecl} - -Creates a file named pathname which can only be read by the current -user. - -\begin{funcdecl}{krb5_sync_disk_file}{krb5_error_code}{\funcin} -\funcarg{FILE *}{fp} -\end{funcdecl} - -Assures that the changes made to the file pointed to by the file -handle -fp are forced out to disk. - -\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcout} -\funcarg{krb5_int32 *}{timeret} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcout} -\funcarg{krb5_int32 *}{seconds} -\funcarg{krb5_int32 *}{microseconds} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -The seconds portion is returned in \funcparam{*seconds}, the -microseconds portion in \funcparam{*microseconds}. - -\begin{funcdecl}{krb5_net_read}{int}{\funcin} -\funcarg{int}{fd} -\funcout -\funcarg{char *}{buf} -\funcin -\funcarg{int}{len} -\end{funcdecl} - -Like read(2), but guarantees that it reads as much as was requested -or returns -1 and sets errno. - -(make sure your sender will send all the stuff you are looking for!) -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_net_write}{int}{\funcin} -\funcarg{int}{fd} -\funcarg{const char *}{buf} -\funcarg{int}{len} -\end{funcdecl} - -Like write(2), but guarantees that it writes as much as was requested -or returns -1 and sets errno. - -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_write_message}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{fd} -\funcarg{krb5_data *}{data} -\end{funcdecl} - - -\funcname{krb5_write_message} writes data to the network as a message, -using the network connection pointed to by \funcparam{fd}. - -\begin{funcdecl}{krb5_read_message}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{fd} -\funcout -\funcarg{krb5_data *}{data} -\end{funcdecl} - -Reads data from the network as a message, using the network connection -pointed to by fd. - -\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcout} -\funcarg{krb5_address ***}{addr} -\end{funcdecl} - -Return all the protocol addresses of this host. - -Compile-time configuration flags will indicate which protocol family -addresses might be returned. -\funcparam{*addr} is filled in to point to an array of address pointers, -terminated by a null pointer. All the storage pointed to is allocated -and should be freed by the caller with \funcname{krb5_free_address} -when no longer needed. - - -\begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{send} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{krb5_data *}{receive} -\end{funcdecl} - -Send the message \funcparam{send} to a KDC for realm \funcparam{realm} and -return the response (if any) in \funcparam{receive}. - -If the message is sent and a response is received, 0 is returned, -otherwise an error code is returned. - -The storage for \funcparam{receive} is allocated and should be freed by -the caller when finished. - -\begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{char ***}{hostlist} -\end{funcdecl} - -Figures out the Kerberos server names for the given \funcparam{realm}, -filling in \funcparam{hostlist} with a null terminated array of -pointers to hostnames. - -If \funcparam{realm} is unknown, the filled-in pointer is set to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_krbhst}{krb5_error_code}{\funcin} -\funcarg{char * const *}{hostlist} -\end{funcdecl} - -Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}. - -\begin{funcdecl}{krb5_aname_to_localname}{krb5_error_code}{\funcin} -\funcarg{krb5_const_principal}{aname} -\funcarg{int}{lnsize} -\funcout -\funcarg{char *}{lname} -\end{funcdecl} - -Converts a principal name \funcparam{aname} to a local name suitable for use by -programs wishing a translation to an environment-specific name (e.g. -user account name). - -\funcparam{lnsize} specifies the maximum length name that is to be filled into -\funcparam{lname}. -The translation will be null terminated in all non-error returns. - -Returns system errors. - -\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code} -\funcout -\funcarg{char **}{lrealm} -\end{funcdecl} - -Retrieves the default realm to be used if no user-specified realm is -available (e.g. to interpret a user-typed principal name with the -realm omitted for convenience), filling in \funcparam{lrealm} with a -pointer to the default realm in allocated storage. - -It is the caller's responsibility for freeing the allocated storage -pointed to be \funcparam{lream} when it is finished with it. - -Returns system errors. - -\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin} -\funcarg{const char *}{host} -\funcout -\funcarg{char ***}{realmlist} -\end{funcdecl} - -Figures out the Kerberos realm names for \funcparam{host}, filling in -\funcparam{realmlist} with a -pointer to an argv[] style list of names, terminated with a null pointer. - -If \funcparam{host} is NULL, the local host's realms are determined. - -If there are no known realms for the host, the filled-in pointer is set -to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_host_realm}{krb5_error_code}{\funcin} -\funcarg{char * const *}{realmlist} -\end{funcdecl} - -Frees the storage taken by a \funcparam{realmlist} returned by -\funcname{krb5_get_local_realm}. - -\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin} -\funcarg{krb5_principal}{principal} -\funcarg{const char *}{luser} -\end{funcdecl} - -Given a Kerberos principal \funcparam{principal}, and a local username -\funcparam{luser}, -determine whether user is authorized to login to the account \funcparam{luser}. -Returns TRUE if authorized, FALSE if not authorized. - -\begin{funcdecl}{krb5_random_confounder}{krb5_error_code}{\funcin} -\funcarg{int}{size} -\funcout -\funcarg{krb5_pointer}{fillin} -\end{funcdecl} - -Given a length and a pointer, fills in the area pointed to by -\funcparam{fillin} with \funcparam{size} random octets suitable for use -in a confounder. - -\begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin} -\funcarg{const krb5_address *}{adr} -\funcarg{krb5_const_pointer}{ptr} -\funcout -\funcarg{krb5_address **}{outaddr} -\end{funcdecl} - -Given an address \funcparam{adr} and an additional address-type specific -portion pointed to by -\funcparam{port} this routine -combines them into a freshly-allocated -\datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} and fills in -\funcparam{*outaddr} to point to this address. For IP addresses, -\funcparam{ptr} should point to a network-byte-order TCP or UDP port -number. Upon success, \funcparam{*outaddr} will point to an allocated -address which should be freed with \funcname{krb5_free_address}. - -\begin{funcdecl}{krb5_gen_replay_name}{krb5_error_code}{\funcin} -\funcarg{const krb5_address *}{inaddr} -\funcarg{const char *}{uniq} -\funcout -\funcarg{char **}{string} -\end{funcdecl} - -Given a \datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} -in \funcparam{inaddr}, this function unpacks its component address and -additional type, and uses them along with \funcparam{uniq} to allocate a -fresh string to represent the address and additional information. The -string is suitable for use as a replay cache tag. This string is -allocated and should be freed with \funcname{free} when the caller has -finished using it. When using IP addresses, the components in -\funcparam{inaddr\ptsto contents} must be of type -\datatype{ADDRTYPE_INET} and \datatype{ADDRTYPE_PORT}. - -\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin} -\funcarg{const char *}{hostname} -\funcarg{const char *}{sname} -\funcarg{krb5_int32}{type} -\funcout -\funcarg{krb5_principal *}{ret_princ} -\end{funcdecl} - -Given a hostname \funcparam{hostname} and a generic service name -\funcparam{sname}, this function generates a full principal name to be -used when authenticating with the named service on the host. The full -prinicpal name is returned in \funcparam{ret_princ}. - -The realm of the -principal is determined internally by calling \funcname{krb5_get_host_realm}. - -The \funcparam{type} argument controls how -\funcname{krb5_sname_to_principal} generates the principal name, -\funcparam{ret_princ}, for the named service, \funcparam{sname}. -Currently, two values are supported: KRB5_NT_SRV_HOST, and -KRB5_NT_UNKNOWN. - -If \funcparam{type} is set to -KRB5_NT_SRV_HOST, the hostname will be -canonicalized, i.e. a fully qualified lowercase hostname using -the primary name and the domain name, before \funcparam{ret_princ} is -generated in the form -"sname/hostname@LOCAL.REALM." Most applications should use -KRB5_NT_SRV_HOST. - -However, if \funcparam{type} is set to KRB5_NT_UNKNOWN, -while the generated principal name will have the form -"sname/hostname@LOCAL.REALM" the hostname will not be canonicalized -first. It will appear exactly as it was passed in \funcparam{hostname}. - -The caller should release \funcparam{ret_princ}'s storage by calling -\funcname{krb5_free_principal} when it is finished with the principal. diff --git a/doc/api/library.tex b/doc/api/library.tex deleted file mode 100644 index 4a870e8ab..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}{2.00in} -\setlength{\marginparsep}{0.05in} -\setlength{\marginparwidth}{1.95 in} -\setlength{\textwidth}{4.75in} -\setlength{\topmargin}{-.5in} -\setlength{\textheight}{9in} -\setlength{\parskip}{.1in} -\setlength{\parindent}{2em} -\setlength{\footrulewidth}{0.4pt} -\setlength{\plainfootrulewidth}{0.4pt} -\setlength{\plainheadrulewidth}{0.4pt} -\makeindex -\newif\ifdraft -\draftfalse -% -% Far, far too inconvenient... it's still very draft-like anyway.... -% [tytso:19900921.0018EDT] -% -%\typein{Draft flag? (type \noexpand\draftfalse 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 86b35a309..000000000 --- a/doc/api/rcache.tex +++ /dev/null @@ -1,155 +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_donot_replay *}{rep} -\end{funcdecl} -Stores \funcparam{rep} in the replay cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -Returns KRB5KRB_AP_ERR_REPEAT if \funcparam{rep} is already in the -cache. May also return permission errors, storage failure errors. - -\begin{funcdecl}{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: -\begin{verbatim} -krb5_rc_resolve_full(id, - strcat(strcat(krb5_rc_default_type(),``:''), - krb5_rc_default_name)) ; -\end{verbatim} -Except of course you can't do the strcat's with the return values. 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 983eb0d8b..000000000 --- a/doc/implement/ccache-i.tex +++ /dev/null @@ -1,237 +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_gen_new_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 \funcparam{id} and any other resources -acquired during use of the credentials cache. Requires that -\funcparam{id} identifies a valid credentials cache. After return, -\funcparam{id} must not be used unless it is first reinitialized. - - -\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Stores \funcparam{creds} in the cache \funcparam{id}, tagged with -\funcparam{creds{\ptsto}client}. -Requires that \funcparam{id} identifies a valid credentials cache. - -Errors: permission errors, storage failure errors. - -\begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{whichfields} -\funcarg{krb5_creds *}{mcreds} -\funcout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Searches the cache \funcparam{id} for credentials matching -\funcparam{mcreds}. The fields which are to be matched are specified by -set bits in \funcparam{whichfields}, and always include the principal -name \funcparam{mcreds{\ptsto}server}. -Requires that \funcparam{id} identifies a valid credentials cache. - -If at least one match is found, one of the matching credentials is -returned in \funcparam{*creds}. The credentials should be freed using -\funcname{krb5_free_credentials}. - -Errors: error code if no matches found. - -\begin{funcdecl}{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_creds *}{creds} -\funcinout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Fetches the next entry from \funcparam{id}, returning its values in -\funcparam{*creds}, and updates \funcparam{*cursor} for the next request. -Requires that \funcparam{id} identifies a valid credentials cache and -\funcparam{*cursor} be a cursor returned by -\funcname{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_creds *}{cred} -\end{funcdecl} - -Removes any credentials from \funcparam{id} which match the principal -name {cred{\ptsto}server} and the fields in \funcparam{cred} masked by -\funcparam{which}. -Requires that \funcparam{id} identifies a valid credentials cache. - -Errors: returns error code if nothing matches; returns error code if -couldn't delete. - -\begin{funcdecl}{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 7a0e883e6..000000000 --- a/doc/implement/encrypt-i.tex +++ /dev/null @@ -1,142 +0,0 @@ -Kerberos v5 has the ability to use multiple encryption systems. Any -encryption system which desires to link with and be usable from the MIT -Kerberos v5 implementation must implement at least this interface: - -\subsection{Functional interface} - -\begin{funcdecl}{encrypt_func}{krb5_error_code}{\funcvoid} -\funcarg{krb5_const_pointer}{in} -\funcarg{krb5_pointer}{out} -\funcarg{const size_t}{size} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{krb5_pointer}{ivec} -\end{funcdecl} -Encrypts \funcparam{size} bytes at \funcparam{in}, storing result in -\funcparam{out}. \funcparam{eblock} points to an encrypt block which -has been initialized by \funcname{process_key}. - -\funcparam{in} must include sufficient space beyond the \funcparam{size} -bytes of input data to hold pad and redundancy check bytes; the macro -\funcname{krb5_encrypt_size} can be used to compute this size. - -\funcparam{out} must be preallocated by the caller to contain sufficient -storage to hold the output; the macro \funcname{krb5_encrypt_size} can -be used to compute this size. - -\funcparam{ivec} points to an initial vector/seed to be used in the encryption. -If null, the cryptosystem may choose an appropriate initialization vector. - -Returns errors. - -\begin{funcdecl}{decrypt_func}{krb5_error_code}{\funcvoid} -\funcarg{krb5_const_pointer}{in} -\funcarg{krb5_pointer}{out} -\funcarg{const size_t}{size} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{krb5_pointer}{ivec} -\end{funcdecl} -Decrypts \funcparam{size} bytes at \funcparam{in}, storing result in -\funcparam{out}. -\funcparam{eblock} points to an encrypt block which has been initialized -by \funcname{process_key}. - -\funcparam{size} must be a multiple of the encryption block size. - -\funcparam{out} must be preallocated by the caller to contain sufficient -storage to hold the output; this is guaranteed to be no more than -the input size. - -\funcparam{ivec} points to an initial vector/seed to be used in the decryption. -If null, the cryptosystem may choose an appropriate ivec. - -Returns errors. - -\begin{funcdecl}{process_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_keyblock *}{keyblock} -\end{funcdecl} -Does any necessary key preprocessing (such as computing key -schedules for DES). -\funcparam{eblock{\ptsto}crypto_entry} must be set by the caller; the -other elements of \funcparam{eblock} are to be assigned by this function. -[In particular, \funcparam{eblock{\ptsto}key} must be set by this -function if the key is needed in raw form by the encryption routine.] - -The caller may not move or reallocate \funcparam{keyblock} before calling -\funcname{finish_key} on \funcparam{eblock}. - -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{const krb5_keytype}{keytype} -\funcarg{krb5_keyblock *}{keyblock} -\funcarg{const krb5_data *}{data} -\funcarg{const krb5_data}{salt} -\end{funcdecl} -Converts the string pointed to by \funcparam{data} into an encryption key -of type \funcparam{keytype}. \funcparam{*keyblock} is filled in with -the key info; in particular, \funcparam{keyblock{\ptsto}contents} is to -be set to allocated storage. It is the responsibility of the caller to -release this storage when the generated key no longer needed. - -The routine may use \funcparam{salt} to seed or alter the conversion -algorithm. - -If the particular function called does not know how to make a -key of type \funcparam{keytype}, an error may be returned. - -Returns errors. - -\begin{funcdecl}{init_random_key}{krb5_error_code}{\funcvoid} -\funcarg{const krb5_keyblock *}{seedblock} -\funcarg{krb5_pointer *}{seed} -\end{funcdecl} - -Initialize the random key generator using the encryption key -\funcparam{seedblock} and allocating private sequence information, filling -in \funcparam{*seed} with the address of such information. -\funcparam{*seed} is to be passed to \funcname{random_key} to provide -sequence information. - -\begin{funcdecl}{finish_random_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_pointer *}{seed} -\end{funcdecl} - -Free any resources held by \funcparam{seed} and assigned by -\funcname{init_random_key}. - -\begin{funcdecl}{random_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_pointer *}{seed} -\funcarg{krb5_keyblock **}{keyblock} -\end{funcdecl} - -Generate a random encryption key, allocating storage for it and -filling in the keyblock address in \funcparam{*keyblock}. -When the caller has finished using the keyblock, he should call -\funcname{krb5_free_keyblock} to release its storage. - -\begin{funcdecl}{combine_keys}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{key1} -\funcarg{const krb5_keyblock *}{key2} -\funcout -\funcarg{krb5_keyblock **}{outkey} -\end{funcdecl} -Combine the two encryption keys \funcparam{key1} and \funcparam{key2} to -generate a new output key \funcparam{outkey}. \funcparam{outkey} is -filled in to point to the freshly-allocated key. When the caller is -finished using the \funcparam{*outkey}, it should be freed with -\funcname{krb5_free_keyblock}. - -\subsection{Other data elements} -In addition to the above listed function entry points, each encryption -system should have an entry in \globalname{krb5_csarray} and a -\datatype{krb5_cryptosystem_entry} structure describing the entry points -and key and padding sizes for the encryption system. diff --git a/doc/implement/fixunder.sty b/doc/implement/fixunder.sty deleted file mode 100644 index b7ae58dbf..000000000 --- a/doc/implement/fixunder.sty +++ /dev/null @@ -1,48 +0,0 @@ -% fixunder.sty, 31 May 1990, John T. Kohl -% -% The contents of this file are in the public domain. -% -% -% play games with _ to make it active and to provide a reasonable _ -% character (from \tt in most cases), and a discretionary word-break point. - -% -% Some \makeunder... macros for convenience in setting catcodes. -% -\def\makeunderactive{\catcode`\_=\active\relax} -\def\makeunderother{\catcode`\_=12\relax} -\def\makeunderletter{\catcode`\_=11\relax} -\def\makeundernormal{\catcode`\_=8\relax} -\makeunderother -\def\cctwlunder{_} - -% -% The hair here is to allow things like \index to work reasonably with -% the new definition of underscore when the argument to index is part of -% a macro replacement and as such gets tokenized before \index is -% evaluated. -% [in the normal case at top-level, \index{foo_bar} works since \index -% does some hair to make _ into a reasonable character code, and \index -% does NOT use a macro expansion. If you have something like -% \def\foo#1#2{\index{#1} bar #2} -% then \foo{baz_quux}{frobnitz} will result in baz_quux getting -% tokenized BEFORE \foo is expanded, so that the catcode hair in \index -% is to no avail.] -% -% \underrealfalse declares that you want to replace with the \tt _; -% \underrealtrue declares that you want to replace with \char95 (ASCII _). -% -% for things like \index which write things out to files, set -% \underrealfalse before evaluating the \index macro, and what actually -% gets written to the file is an _, rather than something like -% {\leavemode \kern... } (the typical definition of \_). -% -% the above example would then be -% \def\foo#1#2{\underrealfalse\index{#1}\underrealtrue bar #2} -% - -\newif\ifunderreal -\underrealfalse -\makeunderactive -\def_{\ifunderreal\cctwlunder\else\leavevmode {\tt \cctwlunder}\discretionary{}{}{}\fi} -\let\_=_ diff --git a/doc/implement/functions.sty b/doc/implement/functions.sty deleted file mode 100644 index a3165f811..000000000 --- a/doc/implement/functions.sty +++ /dev/null @@ -1,70 +0,0 @@ -% -% definitions related to function declarations/displays -% -\ifx\undefined\@psfonts -\def\argfont{\tt} -\else -\font\argfont = pcrb -\hyphenchar\argfont = -1 -\fi -\let\funcfont=\bf -\newcount\argc@ount -%\setlength{\marginparsep}{0.05in} -%\setlength{\marginparwidth}{1.45in} -% -% This function fixes up the function name to be displayed in the -% margin so that the krb5_, if any, is stripped. -% -% Note: this is a hack; what's really happening is that name beginning with -% krb5 will have its first five characters stripped from it. -% This means that 'Krb5abc' will get rewritten to be 'bc'. -% Unfortunately, we can't do better because of the underscore -% hacks that are going on elsewhere. -% -% WARNING: This is ugly; don't look at it too soon after lunch! -% [tytso:19900920.2231EDT] -\newif\if@krbfunc -\def\endkrb{} -\def\fix@parname#1{\expandafter\parse@krb#1\endkrb% -\endkrb\endkrb\endkrb\endkrb}% In case the argument is less -% than five letters, we don't want to -% lose on the argument parsing. -\def\parse@krb#1#2#3#4#5#6\endkrb{\@krbfuncfalse% -\if#1k\if#2r\if#3b\if#45\@krbfunctrue\fi\fi\fi\fi% -\if@krbfunc#6\else#1#2#3#4#5#6\fi} -% -% funcdecl is used as \begin{funcdecl}{funcname}{return type}{firstline} -% -% see fixunder.sty for comments on why the \underrealtrue & \underrealfalse -% stuff is here. -\newenvironment{funcdecl}[3]{\underrealtrue\index{#1}\underrealfalse% -\medbreak -\gdef\funcn@me{#1} -\argc@ount=0\noindent% -%the \mbox{} is to prevent the line/paragraph breaking from eating the -%fill space. -\marginpar[{{\sloppy \hfil\fix@parname{\funcn@me}\hfill\mbox{}}}]% -{{\sloppy \hfill\fix@parname{\funcn@me}\hfil\mbox{}}}% -\vbox\bgroup\begin{minipage}[t]{\textwidth}\begin{tabbing} -#2 \\ -{\bf #1}(\= \+ #3% -}{) -\end{tabbing}\vfil\end{minipage}\egroup\par\nopagebreak -} -\newcommand{\docomm@}{\ifnum\argc@ount >0, \\\fi} -\newcommand{\funcvoid}{\argc@ount=0} -\newcommand{\funcin}{\docomm@\argc@ount=0{\sl /* IN */}\\} -\newcommand{\funcinout}{\docomm@\argc@ount=0{\sl /* IN/OUT */}\\} -\newcommand{\funcout}{\docomm@\argc@ount=0{\sl /* OUT */}\\} -\newcommand{\funcarg}[2]{\docomm@#1 {\argfont #2}\advance\argc@ount by1} -\newcommand{\funcparam}[1]{{\argfont #1}} -\newcommand{\funcfuncarg}[2]{\docomm@#1 {\argfont #2}(\= \+ \argc@ount=0} -\newcommand{\funcendfuncarg}{), \- \\ \argc@ount=0} -\newcommand{\libname}[1]{{\argfont #1}} -\newcommand{\globalname}[1]{{\argfont #1}} -\newcommand{\ptsto}{->\discretionary{}{}{}} -\newcommand{\datatype}[1]{{\bf #1}} -\newcommand{\filename}[1]{{\sl #1\/}} - -\newcommand{\funcname}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}()} -\newcommand{\funcnamenoparens}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}} diff --git a/doc/implement/implement.tex b/doc/implement/implement.tex deleted file mode 100644 index 4a870e8ab..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}{2.00in} -\setlength{\marginparsep}{0.05in} -\setlength{\marginparwidth}{1.95 in} -\setlength{\textwidth}{4.75in} -\setlength{\topmargin}{-.5in} -\setlength{\textheight}{9in} -\setlength{\parskip}{.1in} -\setlength{\parindent}{2em} -\setlength{\footrulewidth}{0.4pt} -\setlength{\plainfootrulewidth}{0.4pt} -\setlength{\plainheadrulewidth}{0.4pt} -\makeindex -\newif\ifdraft -\draftfalse -% -% Far, far too inconvenient... it's still very draft-like anyway.... -% [tytso:19900921.0018EDT] -% -%\typein{Draft flag? (type \noexpand\draftfalse 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 fb9ac801e..000000000 --- a/doc/implement/kdb-i.tex +++ /dev/null @@ -1,241 +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}, -\funcparam{principal}) where \funcparam{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} -\funcarg{krb5_data }{salt} -\funcinout -\funcarg{krb5_keyblock *}{key} -\end{funcdecl} - -Get the KDC database master key from somewhere, filling it into -\funcparam{*key}. -\funcparam{key{\ptsto}keytype} should be set to the desired key type. - -If \funcparam{fromkeyboard} is TRUE, then the master key is read as a password -from the user's terminal. In this case: -\funcparam{eblock} should point to a block with an appropriate -\funcname{string_to_key} function; if \funcparam{twice} is TRUE, the -password is read twice for verification; and if \funcparam{salt} is -non-NULL, it is used as the salt when converting the typed -password to the master key. - - -If \funcparam{fromkeyboard} is false, then the key is read from -a file whose name is derived from the principal name \funcparam{mname}. -Therefore, \funcparam{eblock}, \funcparam{twice} and \funcparam{salt} -are ignored. - - -\funcparam{mname} is the name of the key sought; this is often used by -\funcname{string_to_key} to aid in conversion of the password to a key. - -\begin{funcdecl}{krb5_kdb_encrypt_key}{krb5_error_code}{\funcin} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_keyblock *}{in} -\funcinout -\funcarg{krb5_encrypted_keyblock *}{out} -\end{funcdecl} - -Encrypt a key for storage in the database. \funcparam{eblock} is used -to encrypt the key in \funcparam{in} into \funcparam{out}; the storage -pointed to by \funcparam{*out} is allocated before use and should be -freed when the caller is finished with it. - -\begin{funcdecl}{krb5_kdb_decrypt_key}{krb5_error_code}{\funcin} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_encrypted_keyblock *}{in} -\funcinout -\funcarg{krb5_keyblock *}{out} -\end{funcdecl} - -Decrypt a key from storage in the database. \funcparam{eblock} is used -to decrypt the key in \funcparam{in} into \funcparam{out}; the storage -pointed to by \funcparam{*out} is allocated before use and should be -freed when the caller is finished with it. - -\begin{funcdecl}{krb5_db_setup_mkey_name}{krb5_error_code}{\funcin} -\funcarg{const}{char *keyname} -\funcarg{const}{char *realm} -\funcout -\funcarg{char **}{fullname} -\funcarg{krb5_principal *}{principal} -\end{funcdecl} - -Given a key name \funcparam{keyname} and a realm name \funcparam{realm}, -construct a principal which can be used to fetch the master key from the -database. This principal is filled into \funcparam{*principal}; -\funcparam{*principal} should be freed by \funcname{krb5_free_principal} -when the caller is finished. - -If \funcparam{keyname} is NULL, the default key name will be used. - -If \funcparam{fullname} is not NULL, it is set to point to a string -representation of the complete principal name; its storage may be freed -by calling \funcname{free} on \funcparam{*fullname}. - diff --git a/doc/implement/keytab-i.tex b/doc/implement/keytab-i.tex deleted file mode 100644 index a10e40fd4..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{const char *}{string_name} -\funcout -\funcarg{krb5_keytab *}{id} -\end{funcdecl} - -Fills in \funcparam{*id} with a handle identifying the keytab with name -``string_name''. The keytab is not opened. -Requires that \funcparam{string_name} be of the form ``type:residual'' and -``type'' is a type known to the library. - -Errors: badly formatted name. - -\begin{funcdecl}{krb5_kt_default_name}{krb5_error_code}{\funcin} -\funcarg{char *}{name} -\funcarg{int}{namesize} -\end{funcdecl} - -\funcparam{name} is filled in with the first \funcparam{namesize} bytes of -the name of the default keytab. -If the name is shorter than \funcparam{namesize}, then the remainder of -\funcparam{name} will be zeroed. - - -\begin{funcdecl}{krb5_kt_default}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab *}{id} -\end{funcdecl} - -Fills in \funcparam{id} with a handle identifying the default keytab. - -\begin{funcdecl}{krb5_kt_read_service_key}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcout -\funcarg{krb5_keyblock **}{key} -\end{funcdecl} - -This function is suitable for use as a parameter to -\funcname{krb5_rd_req}. - -If \funcname{keyprocarg} is not NULL, it is taken to be a -\datatype{char *} denoting the name of a keytab. Otherwise, the default -keytab will be used. -The keytab is opened and searched for the entry identified by -\funcparam{principal} and \funcparam{vno}, returning the resulting key -in \funcparam{*key} or returning an error code if it is not found. - -\funcname{krb5_free_keyblock} should be called on \funcparam{*key} when -the caller is finished with the key. - -Returns an error code if the entry is not found. - -\begin{funcdecl}{krb5_kt_add_entry}{krb5_error_code}{\funcin} -\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 5063b5723..000000000 --- a/doc/implement/libos-i.tex +++ /dev/null @@ -1,377 +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_create_secure_file}{krb5_error_code}{\funcin} -\funcarg{const char *}{pathname} -\end{funcdecl} - -Creates a file named pathname which can only be read by the current -user. - -\begin{funcdecl}{krb5_sync_disk_file}{krb5_error_code}{\funcin} -\funcarg{FILE *}{fp} -\end{funcdecl} - -Assures that the changes made to the file pointed to by the file -handle -fp are forced out to disk. - -\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcout} -\funcarg{krb5_int32 *}{timeret} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcout} -\funcarg{krb5_int32 *}{seconds} -\funcarg{krb5_int32 *}{microseconds} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -The seconds portion is returned in \funcparam{*seconds}, the -microseconds portion in \funcparam{*microseconds}. - -\begin{funcdecl}{krb5_net_read}{int}{\funcin} -\funcarg{int}{fd} -\funcout -\funcarg{char *}{buf} -\funcin -\funcarg{int}{len} -\end{funcdecl} - -Like read(2), but guarantees that it reads as much as was requested -or returns -1 and sets errno. - -(make sure your sender will send all the stuff you are looking for!) -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_net_write}{int}{\funcin} -\funcarg{int}{fd} -\funcarg{const char *}{buf} -\funcarg{int}{len} -\end{funcdecl} - -Like write(2), but guarantees that it writes as much as was requested -or returns -1 and sets errno. - -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_write_message}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{fd} -\funcarg{krb5_data *}{data} -\end{funcdecl} - - -\funcname{krb5_write_message} writes data to the network as a message, -using the network connection pointed to by \funcparam{fd}. - -\begin{funcdecl}{krb5_read_message}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{fd} -\funcout -\funcarg{krb5_data *}{data} -\end{funcdecl} - -Reads data from the network as a message, using the network connection -pointed to by fd. - -\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcout} -\funcarg{krb5_address ***}{addr} -\end{funcdecl} - -Return all the protocol addresses of this host. - -Compile-time configuration flags will indicate which protocol family -addresses might be returned. -\funcparam{*addr} is filled in to point to an array of address pointers, -terminated by a null pointer. All the storage pointed to is allocated -and should be freed by the caller with \funcname{krb5_free_address} -when no longer needed. - - -\begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{send} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{krb5_data *}{receive} -\end{funcdecl} - -Send the message \funcparam{send} to a KDC for realm \funcparam{realm} and -return the response (if any) in \funcparam{receive}. - -If the message is sent and a response is received, 0 is returned, -otherwise an error code is returned. - -The storage for \funcparam{receive} is allocated and should be freed by -the caller when finished. - -\begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{char ***}{hostlist} -\end{funcdecl} - -Figures out the Kerberos server names for the given \funcparam{realm}, -filling in \funcparam{hostlist} with a null terminated array of -pointers to hostnames. - -If \funcparam{realm} is unknown, the filled-in pointer is set to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_krbhst}{krb5_error_code}{\funcin} -\funcarg{char * const *}{hostlist} -\end{funcdecl} - -Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}. - -\begin{funcdecl}{krb5_aname_to_localname}{krb5_error_code}{\funcin} -\funcarg{krb5_const_principal}{aname} -\funcarg{int}{lnsize} -\funcout -\funcarg{char *}{lname} -\end{funcdecl} - -Converts a principal name \funcparam{aname} to a local name suitable for use by -programs wishing a translation to an environment-specific name (e.g. -user account name). - -\funcparam{lnsize} specifies the maximum length name that is to be filled into -\funcparam{lname}. -The translation will be null terminated in all non-error returns. - -Returns system errors. - -\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code} -\funcout -\funcarg{char **}{lrealm} -\end{funcdecl} - -Retrieves the default realm to be used if no user-specified realm is -available (e.g. to interpret a user-typed principal name with the -realm omitted for convenience), filling in \funcparam{lrealm} with a -pointer to the default realm in allocated storage. - -It is the caller's responsibility for freeing the allocated storage -pointed to be \funcparam{lream} when it is finished with it. - -Returns system errors. - -\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin} -\funcarg{const char *}{host} -\funcout -\funcarg{char ***}{realmlist} -\end{funcdecl} - -Figures out the Kerberos realm names for \funcparam{host}, filling in -\funcparam{realmlist} with a -pointer to an argv[] style list of names, terminated with a null pointer. - -If \funcparam{host} is NULL, the local host's realms are determined. - -If there are no known realms for the host, the filled-in pointer is set -to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_host_realm}{krb5_error_code}{\funcin} -\funcarg{char * const *}{realmlist} -\end{funcdecl} - -Frees the storage taken by a \funcparam{realmlist} returned by -\funcname{krb5_get_local_realm}. - -\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin} -\funcarg{krb5_principal}{principal} -\funcarg{const char *}{luser} -\end{funcdecl} - -Given a Kerberos principal \funcparam{principal}, and a local username -\funcparam{luser}, -determine whether user is authorized to login to the account \funcparam{luser}. -Returns TRUE if authorized, FALSE if not authorized. - -\begin{funcdecl}{krb5_random_confounder}{krb5_error_code}{\funcin} -\funcarg{int}{size} -\funcout -\funcarg{krb5_pointer}{fillin} -\end{funcdecl} - -Given a length and a pointer, fills in the area pointed to by -\funcparam{fillin} with \funcparam{size} random octets suitable for use -in a confounder. - -\begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin} -\funcarg{const krb5_address *}{adr} -\funcarg{krb5_const_pointer}{ptr} -\funcout -\funcarg{krb5_address **}{outaddr} -\end{funcdecl} - -Given an address \funcparam{adr} and an additional address-type specific -portion pointed to by -\funcparam{port} this routine -combines them into a freshly-allocated -\datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} and fills in -\funcparam{*outaddr} to point to this address. For IP addresses, -\funcparam{ptr} should point to a network-byte-order TCP or UDP port -number. Upon success, \funcparam{*outaddr} will point to an allocated -address which should be freed with \funcname{krb5_free_address}. - -\begin{funcdecl}{krb5_gen_replay_name}{krb5_error_code}{\funcin} -\funcarg{const krb5_address *}{inaddr} -\funcarg{const char *}{uniq} -\funcout -\funcarg{char **}{string} -\end{funcdecl} - -Given a \datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} -in \funcparam{inaddr}, this function unpacks its component address and -additional type, and uses them along with \funcparam{uniq} to allocate a -fresh string to represent the address and additional information. The -string is suitable for use as a replay cache tag. This string is -allocated and should be freed with \funcname{free} when the caller has -finished using it. When using IP addresses, the components in -\funcparam{inaddr\ptsto contents} must be of type -\datatype{ADDRTYPE_INET} and \datatype{ADDRTYPE_PORT}. - -\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin} -\funcarg{const char *}{hostname} -\funcarg{const char *}{sname} -\funcarg{krb5_int32}{type} -\funcout -\funcarg{krb5_principal *}{ret_princ} -\end{funcdecl} - -Given a hostname \funcparam{hostname} and a generic service name -\funcparam{sname}, this function generates a full principal name to be -used when authenticating with the named service on the host. The full -prinicpal name is returned in \funcparam{ret_princ}. - -The realm of the -principal is determined internally by calling \funcname{krb5_get_host_realm}. - -The \funcparam{type} argument controls how -\funcname{krb5_sname_to_principal} generates the principal name, -\funcparam{ret_princ}, for the named service, \funcparam{sname}. -Currently, two values are supported: KRB5_NT_SRV_HOST, and -KRB5_NT_UNKNOWN. - -If \funcparam{type} is set to -KRB5_NT_SRV_HOST, the hostname will be -canonicalized, i.e. a fully qualified lowercase hostname using -the primary name and the domain name, before \funcparam{ret_princ} is -generated in the form -"sname/hostname@LOCAL.REALM." Most applications should use -KRB5_NT_SRV_HOST. - -However, if \funcparam{type} is set to KRB5_NT_UNKNOWN, -while the generated principal name will have the form -"sname/hostname@LOCAL.REALM" the hostname will not be canonicalized -first. It will appear exactly as it was passed in \funcparam{hostname}. - -The caller should release \funcparam{ret_princ}'s storage by calling -\funcname{krb5_free_principal} when it is finished with the principal. diff --git a/doc/implement/rcache-i.tex b/doc/implement/rcache-i.tex deleted file mode 100644 index 86b35a309..000000000 --- a/doc/implement/rcache-i.tex +++ /dev/null @@ -1,155 +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_donot_replay *}{rep} -\end{funcdecl} -Stores \funcparam{rep} in the replay cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -Returns KRB5KRB_AP_ERR_REPEAT if \funcparam{rep} is already in the -cache. May also return permission errors, storage failure errors. - -\begin{funcdecl}{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: -\begin{verbatim} -krb5_rc_resolve_full(id, - strcat(strcat(krb5_rc_default_type(),``:''), - krb5_rc_default_name)) ; -\end{verbatim} -Except of course you can't do the strcat's with the return values. diff --git a/doc/kadm5/api-funcspec.tex b/doc/kadm5/api-funcspec.tex deleted file mode 100644 index 47895ca5c..000000000 --- a/doc/kadm5/api-funcspec.tex +++ /dev/null @@ -1,1521 +0,0 @@ -\documentstyle[12pt,fullpage,changebar]{article} - -% $Id$ - -\setlength{\parskip}{.7\baselineskip} -\setlength{\parindent}{0pt} - -\def\secure{OV*Secure} -\def\v#1{\verb+#1+} - -\title{OV*Secure Admin \\ Functional Specifications} -\author{Barry Jaspan} -\date{DRAFT --- \today} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% Make _ actually generate an _, and allow line-breaking after it. -\let\underscore=\_ -\catcode`_=13 -\def_{\underscore\penalty75\relax} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{document} - -\maketitle - -{\setlength{\parskip}{0pt}\tableofcontents} - -\section{Policies and Password Quality} - -The Admin API Password Quality mechanism provides the following -controls. Note that two strings are defined to be ``significantly -different'' if they differ by at least one character. The compare is not -case sensitive. - -\begin{itemize} -\item A minimum length can be required; a password with -fewer than the specified number of characters will not be accepted. - -\item A minimum number of character classes can be required; a -password that does not contain at least one character from at least -the specified number of character classes will not be accepted. The -character classes are defined by islower(), isupper(), isdigit(), -ispunct(), and other. - -\item Passwords can be required to be different from -previous passwords; a password that generates the same encryption key -as any of the principal's specified previous number of passwords will -not be accepted. This comparison is performed on the encryption keys -generated from the passwords, not on the passwords themselves. - -\item A single ``forbidden password'' dictionary can be specified for all -users; a password that is not significantly different from every word -in the dictionary will not be accepted. - -\item A password that is not significantly different from each -component and the realm of the principal's name will not be accepted. -\end{itemize} - -\section{Interrealm Operation} - -For version 1.0, the behavior of any function when called with a -principal name that is not in the host's local realm is undefined. - -\section{Admin API} - -This section describes the Admin API that can be used to maintain -principals and policies. It describes the data structures used for -each function and the interpretation of each data type field, the -semantics of each API function, and the possible return codes. - -The Admin API is intended to be used by remote clients using an RPC -interface. It is implemented by the admin server running on the -Kerberos master server. It may also be possible for a program running -on the Kerberos master server to use the Admin API directly, without -going through the admin server. - -\subsection{Data Structures} - -This section describes the data structures used by the Admin API that -are unique to \secure{}. They are defined in $<$ovsec_admin/admin.h$>$. - -\subsubsection{Principals, ovsec_kadm_principal_ent_t} -\label{sec:principal-structure} - -A Kerberos principal entry is represented by a -ovsec_kadm_principal_ent_t. It contains a subset of the information -stored in the master Kerberos database as well as the additional -information maintained by \secure{}. In the current version, the only -additional information is the principal's policy and the -aux_attributes flags. - -The principal may or may not have a policy enforced on it. If the -POLICY bit (see section \ref{sec:masks}) is set in aux_attributes, the -policy field names the principal's policy. If the POLICY bit is not -set in aux_attributes, no policy is enforced on the principal and the -value of the policy field is undefined. - -\begin{figure}[htbp] -\begin{verbatim} -typedef struct _ovsec_kadm_principal_ent_t { - krb5_principal principal; - - krb5_timestamp princ_expire_time; - krb5_timestamp last_pwd_change; - krb5_timestamp pw_expiration; - krb5_deltat max_life; - krb5_principal mod_name; - krb5_timestamp mod_date; - krb5_flags attributes; - krb5_kvno kvno; - krb5_kvno mkvno; - - char * policy; - u_int32 aux_attributes; -} ovsec_kadm_principal_ent_rec, *ovsec_kadm_principal_ent_t; -\end{verbatim} -\caption{Definition of ovsec_kadm_principal_ent_t.} -\label{fig:princ-t} -\end{figure} - -The fields of an ovsec_kadm_principal_ent_t are interpreted as -follows. - -\begin{description} -\item[principal] The name of the principal; must conform to Kerberos -naming specifications. - -\item[princ_expire_time] The expire time of the principal as a Kerberos -timestamp. No Kerberos tickets will be issued for a principal after -its expire time. - -\item[last_pwd_change] The time this principal's password was last -changed, as a Kerberos timestamp. - -\item[pw_expiration] The expire time of the user's current password, as a -Kerberos timestamp. No application service tickets will be issued for the -principal once the password expire time has passed. Note that the user can -only obtain tickets for services that have the PW_CHANGE_SERVICE bit set in -the attributes field. - -\item[max_life] The maximum lifetime of any Kerberos ticket issued to -this principal. - -\item[attributes] A bitfield of attributes for use by the KDC. -Note that only some are explicitly supported by \secure{}. - -\begin{tabular}{clr} -{\bf Supported} & {\bf Name} & {\bf Value} \\ - & KRB5_KDB_DISALLOW_POSTDATED & 0x00000001 \\ - & KRB5_KDB_DISALLOW_FORWARDABLE & 0x00000002 \\ -X & KRB5_KDB_DISALLOW_TGT_BASED & 0x00000004 \\ - & KRB5_KDB_DISALLOW_RENEWABLE & 0x00000008 \\ - & KRB5_KDB_DISALLOW_PROXIABLE & 0x00000010 \\ - & KRB5_KDB_DISALLOW_DUP_SKEY & 0x00000020 \\ -X & KRB5_KDB_DISALLOW_ALL_TIX & 0x00000040 \\ - & KRB5_KDB_REQUIRES_PRE_AUTH & 0x00000080 \\ - & KRB5_KDB_REQUIRES_HW_AUTH & 0x00000100 \\ -X & KRB5_KDB_REQUIRES_PWCHANGE & 0x00000200 \\ - & KRB5_KDB_DISALLOW_SVR & 0x00001000 \\ -X & KRB5_KDB_PWCHANGE_SERVICE & 0x00002000 -\end{tabular} - -The interpretation of each bit is as follows. For each of the bits -that disables a corresponding KDC_OPT option, the option is disabled -on an AS_REQ if the bit is set on either the client or the server, and -the option is disabled on TGS_REQ if the bit is set on the server (the -setting of the bit on the client is irrelevant for a TGS_REQ). - -\begin{description} -\item[KRB5_KDB_DISALLOW_POSTDATED] Disables the ALLOW_POSTDATE -and POSTDATED KDC options on AS_REQ and TGS_REQ. - -\item[KRB5_KDB_DISALLOW_FORWARDABLE] Disables the FORWARDABLE KDC -option for AS_REQ and TGS_REQ. - -\item[KRB5_KDB_DISALLOW_TGT_BASED] All TGS_REQ requests will fail for -a principal with this bit set. - -\item[KRB5_KDB_DISALLOW_RENEWABLE] Disables the RENEWABLE KDC option for -AS_REQ and TGS_REQ. - -\item[KRB5_KDB_DISALLOW_PROXIABLE] Disables the PROXIABLE KDC option on -AS_REQ and TGS_REQ. - -\item[KRB5_KDB_DISALLOW_DUP_SKEY] Disables the ENC_TKT_IN_SKEY option on -TGS_REQ. - -\item[KRB5_KDB_DISALLOW_ALL_TIX] All AS_REQ requests fail if this bit -is set for the client or the server, and all TGS_REQ requests fail if -this bit is set for the server. Note that this bit can be set -automatically if the symbol KRBCONF_KDC_MODIFIES_KDC is defined and a -specified number of pre-authentication attempts fail. - -\item[KRB5_KDB_REQUIRES_PRE_AUTH] Any AS_REQ will fail if this bit is -set and the padata field of the request is empty. Any TGS_REQ will -fail if this bit is set and the TKT_FLAG_PRE_AUTH bit is not set in -the tgt. Thus, it is possible to have the bit not set on the TGT but -to have a specific service require pre-authentication. - -\item[KRB5_KDB_REQUIRES_HW_AUTH] Unclear. - -\item[KRB5_KDB_REQUIRES_PWCHANGE] An AS_REQ will fail if this bit is -set on the client and the KRB5_KDC_PWCHANGE_SERVICE bit is not set on -the server. - -\item[KRB5_KDB_DISALLOW_SVR] All AS_REQ and TGS_REQ request will fail -if the server has this bit set. - -\item[KRB5_KDB_PWCHANGE_SERVICE] An request from a client whose -password has expired will succeed if this bit is set on the server. -Also see KRB5_KDC_REQUIRES_PWCHANGE. -\end{description} - -\item[mod_name] The name of the Kerberos principal that most recently -modified this principal. - -\item[mod_date] The time this principal was last modified, as a Kerberos -timestamp. - -\item[kvno] The version of the principal's current key. - -\item[mkvno] The version of the Kerberos Master Key in effect when -this principal's key was last changed. - -\item[policy] If the POLICY bit is set in aux_attributes, the name -of the policy controlling this principal. - -\item[aux_attributes] A bitfield of flags for use by the -administration system. Currently, the only valid flag is POLICY, and -it indicates whether or not the principal has a policy enforced on it. -\end{description} - -\subsubsection{Policies, ovsec_kadm_policy_ent_t} -\label{sec:policy-fields} - -If the POLICY bit is set in aux_attributes, the \v{policy} name field -in the ovsec_kadm_principal_ent_t structure refers to a password -policy entry defined in a \v{ovsec_kadm_policy_ent_t}. - -\begin{verbatim} -typedef struct _ovsec_kadm_policy_ent_t { - char *policy; - - u_int32 pw_min_life; - u_int32 pw_max_life; - u_int32 pw_min_length; - u_int32 pw_min_classes; - u_int32 pw_history_num; - u_int32 policy_refcnt; -} ovsec_kadm_policy_ent_rec, *ovsec_kadm_policy_ent_t; -\end{verbatim} - -The fields of an ovsec_kadm_policy_ent_t are interpreted as follows. -Note that a policy's values only apply to a principal using that -policy. - -\begin{description} -\item[policy] The name of this policy, as a NULL-terminated string. -The ASCII characters between 32 (space) and 126 (tilde), inclusive, -are legal. - -\item[pw_min_life] The minimum password lifetime, in seconds. -A principal cannot change its password before pw_min_life seconds have -passed since last_pwd_change. - -\item[pw_max_life] The default duration, in seconds, used to compute -pw_expiration when a principal's password is changed. - -\item[pw_min_length] The minimum password length, in characters. A -principal cannot set its password to anything with fewer than this -number of characters. This value must be greater than zero. - -\item[pw_min_classes] The minimum number of character classes in the -password. This value can only be 1, 2, 3, 4, or 5. A principal cannot -set its password to anything with fewer than this number of character -classes in it. - -\item[pw_history_num] The number of past passwords that are -stored for the principal; the minimum value is 1 and the maximum value -is 10. A principal cannot set its password to any of its previous -pw_history_num passwords. The first ``previous'' password is the -current password; thus, a principal with a policy can never reset its -password to its current value. - -\item[policy_refcnt] The number of principals currently using this policy. -A policy cannot be deleted unless this number is zero. -\end{description} - -\subsubsection{Create/Modify Masks} -\label{sec:masks} - -The API functions for creating and modifying principals and policies -allow for a relevant subset of the fields of the -ovsec_kadm_principal_ent_t and ovsec_kadm_policy_ent_t to be specified -or changed. The chosen fields are determined by a bitmask that is -passed to the relevant function. Each API function has different -rules for which mask values can be specified, and can specify whether -a given mask value is mandatory, optional, or forbidden. Mandatory -fields must be present and forbidden fields must not be present or an -error is generated. When creating a principal or policy, optional -fields have a default value if they are not specified; when modifying -a principal or policy, optional fields are unchanged if they are not -specified. The values for forbidden fields are defined in the -function semantics. - -The masks for principals are in table \ref{tab:princ-bits} and the -masks for policies are in table \ref{tab:policy-bits}. They are -defined in $<$ovsec_admin/admin.h$>$. The -OVSEC_KADM_ prefix has been removed from the Name fields. In the -Create and Modify fields, M means mandatory, F means forbidden, and O -means optional. Create fields that are optional specify the default -value. The notation ``K/M value'' means that the field inherits its -value from the corresponding field in the Kerberos master principal. - -Note that the POLICY and POLICY_CLR bits are special. When POLICY is -set, the policy is assigned to the principal. When POLICY_CLR is -specified, the policy is unassigned to the principal and as a result -no policy controls the principal. - -If the principal has a policy assigned, the POLICY bit is set in -aux_attributes. - -\begin{table}[htbp] -\begin{tabular}{@{}lclll} -{\bf Name} & {\bf Value} & {\bf Field Affected} & {\bf Create} & - {\bf Modify} \\ -PRINCIPAL & 0x000001 & principal & M & F \\ -PRINC_EXPIRE_TIME & 0x000002 & princ_expire_time & O, K/M value & O \\ -PW_EXPIRATION & 0x000004 & pw_expiration & O, now+pw_max_life & O \\ -LAST_PWD_CHANGE & 0x000008 & last_pwd_change & F & F \\ -ATTRIBUTES & 0x000010 & attributes & O, 0 & O \\ -MAX_LIFE & 0x000020 & max_life & O, K/M value & O \\ -MOD_TIME & 0x000040 & mod_date & F & F \\ -MOD_NAME & 0x000080 & mod_name & F & F \\ -KVNO & 0x000100 & kvno & O, 1 & O \\ -MKVNO & 0x000200 & mkvno & F & F \\ -AUX_ATTRIBUTES & 0x000400 & aux_attributes & F & F \\ -POLICY & 0x000800 & policy & O, none & O \\ -POLICY_CLR & 0x001000 & policy & F & O -\end{tabular} -\caption{Mask bits for creating/modifying principals.} -\label{tab:princ-bits} -\end{table} - -\begin{table}[htbp] -\begin{tabular}{@{}lclll} -Name & Value & Field Affected & Create & Modify \\ -POLICY & same & policy & M & F \\ -PW_MAX_LIFE & 0x004000 & pw_max_life & O, 0 (infinite) & O \\ -PW_MIN_LIFE & 0x008000 & pw_min_life & O, 0 & O \\ -PW_MIN_LENGTH & 0x010000 & pw_min_length & O, 1 & O \\ -PW_MIN_CLASSES & 0x020000 & pw_min_classes & O, 1 & O \\ -PW_HISTORY_NUM & 0x040000 & pw_history_num & O, 0 & O \\ -REF_COUNT & 0x080000 & pw_refcnt & O, 0 & O -\end{tabular} -\caption{Mask bits for creating/modifying policies.} -\label{tab:policy-bits} -\end{table} - -\subsection{Constants, Header Files, Libraries} - -For release 1.0 both all of the files decribed in this section are -rooted off of the ``stage'' directory in the build tree. If we export -this interface in future releases they will move to the ``install'' -tree. Include files are found under ``stage/include'', libraries under -``stage/lib''. - -$<$ovsec_admin/admin.h$>$ contains ovsec_kadm routine prototypes, data -structures, mask bitfields defines, and the following name and -location definitions: - -\begin{description} -\item[admin service principal] ADM_PRINCIPAL (``ovsec_kadm/admin'') -\item[admin history key] HIST_PRINCIPAL (``ovsec_kadm/history'') -\item[change password principal] CHANGEPW_PRINCIPAL (``ovsec_kadm/changepw'') -\item[server acl file path] ACLFILE (``/krb5/ovsec_admin.acl'') -\item[dictionary] WORDFILE (``/krb5/ovsec_adm_dict'') -\end{description} - -OVSEC_KADM errors are described in $<$ovsec_admin/kadm_err.h$>$. - -The location of the admin policy and principal databases are defined -in $<$ovsec_admin/adb.h$>$: - -\begin{description} -\item[admin policy database] POLICY_DB (``/krb5/ovsec_policy.db'') -\item[admin principal database] PRINCIPAL_DB (``/krb5/ovsec_principal.db'') -\end{description} - -Client applications will link against libclient.a and server programs -against libsrv.a. Right now both clients and servers also need to link -against libcommon.a but we should put that in both libclient.a and -libsrv.a to simplify the linking process. - -\subsection{Error Codes} - -The error codes that can be returned by admin functions are listed -below. Error codes indicated with a ``*'' can be returned by every -admin function and always have the same meaning; these codes are -omitted from the list presented with each function. - -The admin system guarantees that a function that returns an error code -has no other side effect. - -The Admin system will use \v{com_err} for error codes. Note that this -means \v{com_err} codes may returned from functions that the admin -routines call (e.g. the kerberos library). Callers should not expect -that only OVSEC errors will be returned. The Admin system error code -table name will be ``ovk'', and the offsets will be the same as the -order presented here. The error table include file will be -$<$ovsec_admin/kadm_err.h$>$. - -\begin{description} -\item[* OVSEC_KADM_FAILURE] Operation failed for unspecified reason. -\item[* OVSEC_KADM_AUTH_GET] Operation requires ``get'' privilege. -\item[* OVSEC_KADM_AUTH_ADD] Operation requires ``add'' privilege. -\item[* OVSEC_KADM_AUTH_MODIFY] Operation requires ``modify'' privilege. -\item[* OVSEC_KADM_AUTH_DELETE] Operation requires ``delete'' privilege. -\item[* OVSEC_KADM_AUTH_INSUFFICIENT] Insufficient authorization for -operation. -\item[* OVSEC_KADM_BAD_DB] Database inconsistency detected. -\item[OVSEC_KADM_DUP] Principal or policy already exists. -\item[OVSEC_KADM_RPC_ERROR] Communication failure with server. -\item[OVSEC_KADM_NO_SRV] No administration server found for realm. -\item[OVSEC_KADM_BAD_HIST_KEY] Password history principal key version -mismatch. -\item[OVSEC_KADM_NOT_INIT] Connection to server not initialized. -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\item[OVSEC_KADM_UNK_POLICY] Policy does not exist. -\item[OVSEC_KADM_BAD_MASK] Invalid field mask for operation. -\item[OVSEC_KADM_BAD_CLASS] Invalid number of character classes. -\item[OVSEC_KADM_BAD_LENGTH] Invalid password length. -\item[OVSEC_KADM_BAD_POLICY] Illegal policy name. -\item[OVSEC_KADM_BAD_PRINCIPAL] Illegal principal name. XXX use krb5 -error code? -\item[OVSEC_KADM_BAD_AUX_ATTR] Invalid auxillary attributes. -\item[OVSEC_KADM_BAD_HISTORY] Invalid password history count. -\item[OVSEC_KADM_BAD_MIN_PASS_LIFE] Password minimum life is greater -then password maximum life. -\item[OVSEC_KADM_PASS_Q_TOOSHORT] Password is too short. -\item[OVSEC_KADM_PASS_Q_CLASS] Password does not contain enough -character classes. -\item[OVSEC_KADM_PASS_Q_DICT] Password is in the password dictionary. -\item[OVSEC_KADM_PASS_REUSE] Cannot resuse password. -\item[OVSEC_KADM_PASS_TOOSOON] Current password's minimum life has not -expired. -\item[OVSEC_KADM_POLICY_REF] Policy reference count is not zero. -\item[OVSEC_KADM_INIT] Connection to server already initialized. -\item[OVSEC_KADM_BAD_PASSWORD] Incorrect password. -\end{description} - -\subsection{Authentication and Authorization} -\label{sec:auth} - -Two Kerberos principals exist for use in communicating with the Admin -system: ovsec_kadm/admin and ovsec_kadm/changepw. Both principals -have the KRB5_KDB_DISALLOW_TGT_BASED bit set in their attributes so -that service tickets for them can only be acquired via a -password-based (AS_REQ) request. Additionally, ovsec_kadm/changepw -has the KRB5_KDB_PWCHANGE_SERVICE bit set so that a principal with an -expired password can still obtain a service ticket for it. - -The Admin system accepts requests that are authenticated to either -service principal, but the set of operations that can be performed by -a request authenticated to each service are different. In particular, -only the functions chpass_principal, randkey_principal, get_principal, -and get_policy can be performed by a request authenticated to the -ovsec_kadm/changepw service. The function semantics describe the precise -details. - -Each Admin API operation authenticated to the ovsec_kadm/admin service -requires a specific authorization to run. This version uses a simple -named privilege system with the following names and meanings: - -The Authorization checks only happen if you are using the RPC mechanism. -If you are using the server side API functions locally on the admin server, -the only authorization check is if you can access the approporiate local -files. - -\begin{description} -\item[Get] Able to examine the attributes (NOT key data) of principals -and policies. -\item[Add] Able to add principals and policies. -\item[Modify] Able to modify attributes of existing principals and policies. -\item[Delete] Able to remove principals and policies. -\end{description} - -Privileges are specified via an external configuration file on the -Kerberos master server (see section \ref{sec:acls}). - -Table \ref{tab:func-overview} summarizes the authorization -requirements of each function. Additionally, each API function -description identifies the privilege required to perform it. - -\subsection{Function Overview} - -The functions provided by the Admin API, and the authorization they -require, are listed in the table \ref{tab:func-overview}. The -``ovsec_kadm_'' prefix has been removed from each function name. - -The function semantics in the following sections omit details that are -the same for every function. - -\begin{itemize} -\item The effects of every function are atomic. - -\item Every function performs an authorization check and returns -the appropriate OVSEC_KADM_AUTH_* error code if the caller does not -have the required privilege. No other information or error code is -ever returned to an unauthorized user. - -\item Every function checks its arguments for NULL pointers or other -obviously invalid values, and returns EINVAL if any are detected. - -\item Any function that performs a policy check uses the policy named -in the principal's policy field. If the POLICY bit is not set in the -principal's aux_attributes field, however, the principal has no -policy, so the policy check is not performed. - -\item Unless otherwise specified, all functions return OVSEC_KADM_OK. -\end{itemize} - -\begin{table}[htbp] -\caption{Summary of functions and required authorization.} -\label{tab:func-overview} -\begin{tabular}{@{}llp{3.24in}} -\\ -{\bf Function Name} & {\bf Authorization} & {\bf Operation} \\ - -init & none & Open a connection with the ovsec_kadm library. \\ -destroy & none & Close the connection with the ovsec_kadm library. \\ -create_principal & add & Create a new principal. \\ -delete_principal & delete & Delete a principal. \\ -modify_principal & modify & Modify the attributes of an existing - principal (not password). \\ -rename_principal & add and delete & Rename a principal. \\ -get_principal & get\footnotemark & Retrieve a principal. \\ -chpass_principal & modify\footnotemark[\thefootnote] & - Change a principal's password. \\ -chpass_principal_util & modify\footnotemark[\thefootnote] & Utility wrapper around chpass_principal. \\ -randkey_principal & modify\footnotemark[\thefootnote] & - Randomize a principal's key. \\ -create_policy & add & Create a new policy. \\ -delete_policy & delete & Delete a policy. \\ -modify_policy & modify & Modify the attributes of a policy. \\ -get_policy & get & Retrieve a policy. \\ -free_principal_ent & none & Free the memory associated with an - ovsec_kadm_principal_ent_t. \\ -free_policy_ent & none & Free the memory associated with an - ovsec_kadm_policy_ent_t. \\ -get_privs & none & Return the caller's admin server privileges. -\end{tabular} -\end{table} -\footnotetext[\thefootnote]{These functions also allow a principal to -perform the operation on itself; see the function's semantics for -details.} - -\subsection{ovsec_kadm_init} - -\begin{verbatim} -ovsec_kadm_ret_t ovsec_kadm_init(char *client_name, char *pass, - char *service_name, char *realm) -\end{verbatim} - -AUTHORIZATION REQUIRED: none - -Open a connection to the ovsec_kadm library and initialize any -neccessary state information. This function behaves differently when -called from local and remote clients. - -For remote clients, the semantics are: - -\begin{enumerate} -\item Initializes all the com_err error tables used by the Admin -system. - -\item Acquire a Kerberos ticket for the specified service. - -\begin{enumerate} -\item The ticket's client is client_name, which can be any valid -Kerberos principal. If client_name does not include a realm, the -default realm of the local host is used -\item The ticket's service is service_name@realm. service_name must -be one of the constants OVSEC_KADM_ADMIN_SERVICE or -OVSEC_KADM_CHANGEPW_SERVICE. -\item If realm is NULL, client_name's realm is used. -\item The ticket is decoded with the password pass, which must be -client_name's password. If pass is NULL, the user is prompted (via -the tty) for a password. -\end{enumerate} - -\item Create a GSS-API authenticated connection to the Admin server, -using the just-acquired Kerberos ticket. -\end{enumerate} - -Local clients, running on the KDC, may be useful. For now this is will -most likely be used for testing, but could in the future be the basis -for a command-line system that works both remotely and on the KDC -machine. If ovsec_kadm_init is invoked locally its semantics are: - -\begin{enumerate} -\item Initializes all the com_err error tables used by the Admin -system. - -\item Initializes direct access to the KDC database. If pass is NULL, -reads the master password from /.k5.REALM-NAME (created by kstash). -Otherwise, the non-NULL password is ignored and the user is prompted -for it via the tty. - -\item Initializes the dictionary (if present) for dictionary checks. - -\item Parses client_name as a Kerberos principal and initializes the -global current_caller principal to it. client_name should usually be -specified as the name of the program. - -\item The service_name argument is not used. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_NO_SRV] No Admin server can be found for the -specified realm. - -\item[OVSEC_KADM_RPC_ERROR] The RPC connection to the server cannot be -initiated. - -\item[OVSEC_KADM_BAD_PASSWORD] Incorrect password. -\end{description} - -\subsection{ovsec_kadm_destroy} - -\begin{verbatim} -ovsec_kadm_ret_t ovsec_kadm_destroy() -\end{verbatim} - -AUTHORIZATION REQUIRED: none - -Close the connection to the Admin server and releases all related -resources. This function behaves differently when called by local and -remote clients. - -For remote clients, the semantics are: - -\begin{enumerate} -\item Destroy the temporary credential cache created by -ovsec_kadm_init. - -\item Tear down the GSS-API context negotiated with the server. - -\item Close the RPC connection. -\end{enumerate} - -For local clients, this function does nothing. - -RETURN CODES: - -\subsection{ovsec_kadm_create_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_create_principal(ovsec_kadm_principal_ent_t princ, u_int32 mask, - char *pw); -\end{verbatim} - -AUTHORIZATION REQUIRED: add - -\begin{enumerate} - -\item Return OVSEC_KADM_BAD_MASK if the mask is invalid. -\item If the named principal exists, return OVSEC_KADM_DUP. -\item If the POLICY bit is set and the named policy does not exist, -return OVSEC_KADM_UNK_POLICY. -\item If OVSEC_KADM_POLICY bit is set in aux_attributes check to see if -the password does not meets quality standards, return the appropriate -OVSEC_KADM_PASS_Q_* error code if it fails. -\item Store the principal, set the key. The key is generated with -Kerberos' string-to-key function, using the salt method specified on -the admin server's command line; see section \ref{sec:commandline}. -\item If the POLICY bit is set, increment the named policy's reference -count by one. - -\item Set the pw_expiration field. -\begin{enumerate} -\item If the POLICY bit is not set, then -\begin{enumerate} -\item if the PW_EXPIRATION bit is set, set pw_expiration to the given -value, else -\item set pw_expiration to never. -\end{enumerate} -\item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to -the sooner of the given value and now + pw_max_life. -\item Otherwise, set pw_expiration to now + pw_max_life. -\end{enumerate} - -\item Set mod_date to now and set mod_name to caller. -\item Set last_pwd_change to now. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_BAD_MASK] The field mask is invalid for a create -operation. -\item[OVSEC_KADM_DUP] Principal already exists. -\item[OVSEC_KADM_UNK_POLICY] Policy named in entry does not exist. -\item[OVSEC_KADM_PASS_Q_*] Specified password does not meet policy -standards. -\end{description} - -\subsection{ovsec_kadm_delete_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_delete_principal(krb5_principal princ); -\end{verbatim} - -AUTHORIZATION REQUIRED: delete - -\begin{enumerate} -\item Return OVSEC_KADM_UNK_PRINC if the principal does not exist. -\item If the POLICY bit is set in aux_attributes, decrement the named -policy's reference count by one. -\item Delete principal. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\end{description} - -\subsection{ovsec_kadm_modify_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_modify_principal(ovsec_kadm_principal_ent_t princ, u_int32 mask); -\end{verbatim} - -Modify the attributes of the principal named in -ovsec_kadm_principal_ent_t. This does not allow the principal to be -renamed or for its password to be changed. - -AUTHORIZATION REQUIRED: modify - -Although a principal's pw_expiration is usually computed based on its -policy and the time at which it changes its password, this function -also allows it to be specified explicitly. This allows an -administrator, for example, to create a principal and assign it to a -policy with a pw_max_life of one month, but to declare that the new -principal must change its password away from its initial value -sometime within the first week. - -\begin{enumerate} -\item Return OVSEC_KADM_UNK_PRINC if the principal does not exist. -\item Return OVSEC_KADM_BAD_MASK if the mask is invalid. -\item If POLICY bit is set but the new policy does not exist, return -OVSEC_KADM_UNK_POLICY. -\item If either the POLICY or POLICY_CLR bits are set, update the -corresponding bits in aux_attributes. - -\item Update policy reference counts. -\begin{enumerate} -\item If the POLICY bit is set, then increment policy count on new -policy. -\item If the POLICY or POLICY_CLR bit is set, and the POLICY bit in -aux_attributes is set, decrement policy count on old policy. -\end{enumerate} - -\item Set pw_expiration according to the new policy. -\begin{enumerate} -\item If the POLICY bit is not set in aux_attributes, then -\begin{enumerate} -\item if the PW_EXPIRATION bit is set, set pw_expiration to the given -value, else -\item set pw_expiration to never. -\end{enumerate} -\item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to -the sooner of the given value and last_pwd_change + pw_max_life. -\item Otherwise, set pw_expiration to last_pwd_change + pw_max_life. -\end{enumerate} - -\item Update the fields specified in the mask. -\item Update mod_name field to caller and mod_date to now. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Entry does not exist. -\item[OVSEC_KADM_BAD_MASK] The mask is not valid for a modify -operation. -\item[OVSEC_KADM_UNK_POLICY] The POLICY bit is set but the new -policy does not exist. -\end{description} - -\subsection{ovsec_kadm_rename_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_rename_principal(krb5_principal source, krb5_principal target); -\end{verbatim} - -AUTHORIZATION REQUIRED: add and delete - -\begin{enumerate} -\item Check to see if source principal exists, if not return -OVSEC_KADM_UNK_PRINC error. -\item Check to see if target exists, if so return OVSEC_KADM_DUP error. -\item Create the new principal named target, then delete the old -principal named source. All of target's fields will be the same as -source's fields, except that mod_name and mod_date will be updated to -reflect the current caller and time. -\end{enumerate} - -Note that since the principal name may have been used as the salt for -the principal's key, renaming the principal may render the principal's -current password useless; with the new salt, the key generated by -string-to-key on the password will suddenly be different. Therefore, -an application that renames a principal must also require the user to -specify a new password for the principal (and administrators should -notify the affected party). - -Note also that, by the same argument, renaming a principal will -invalidate that principal's password history information; since the -salt will be different, a user will be able to select a previous -password without error. - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Source principal does not exist. -\item[OVSEC_KADM_DUP] Target principal already exist. -\end{description} - -\subsection{ovsec_kadm_chpass_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_chpass_principal(krb5_principal princ, char *pw); -\end{verbatim} - -AUTHORIZATION REQUIRED: modify, or the calling principal being the -same as the princ argument. If the request is authenticated to the -ovsec_kadm/changepw service, the modify privilege is disregarded. - -Change a principal's password. - -This function enforces password policy and dictionary checks. If the -new password specified is in the password dictionary, -OVSEC_KADM_PASS_DICT is returned (even if the policy bit is not set). -If the principal's POLICY bit is set in aux_attributes, compliance -with each of the named policy fields is verified and an appropriate -error code is returned if verification fails. - -Note that the policy checks are only be performed if the POLICY bit is -set in the principal's aux_attributes field. - -\begin{enumerate} -\item Make sure principal exists, if not return OVSEC_KADM_UNK_PRINC error. -\item If caller does not have modify privilege, (now - last_pwd_change) $<$ -pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the -principal's attributes, return OVSEC_KADM_PASS_TOOSOON. -\item If the password does not meet the quality -standards, return the appropriate OVSEC_KADM_PASS_Q_* error code. -\item Convert password to key. The key is generated with -Kerberos' string-to-key function, using the salt method specified on -the admin server's command line; see section \ref{sec:commandline}. -\item If the new key is in the principal's password history, return -OVSEC_KADM_PASS_REUSE. -\item Store old key in history. -\item Update principal to have new key. -\item Increment principal's key version number by one. -\item If the POLICY bit is set, set pw_expiration to now + -max_pw_life. If the POLICY bit is not set, set pw_expiration to -never. -\item If the KRB5_KDB_REQUIRES_PWCHANGE bit is set in the principal's -attributes, clear it. -\item Update last_pwd_change and mod_date to now, update mod_name to -caller. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\item[OVSEC_KADM_PASS_Q_*] Requested password does not meet quality -standards. -\item[OVSEC_KADM_PASS_REUSE] Requested password is in user's -password history. -\item[OVSEC_KADM_PASS_TOOSOON] Current password has not reached minimum -life. -\end{description} - - -\subsection{ovsec_kadm_chpass_principal_util} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_chpass_principal_util(krb5_principal princ, char *new_pw, - char **pw_ret, char *msg_ret); -\end{verbatim} - -AUTHORIZATION REQUIRED: modify, or the calling principal being the -same as the princ argument. If the request is authenticated to the -ovsec_kadm/changepw service, the modify privilege is disregarded. - -This function is a wrapper around ovsec_kadm_chpass_principal. It can -read a new password from a user, change a principal's password, and -return detailed error messages. msg_ret should point to a char buffer -in the caller's space of sufficient length for the error messages -described below. 1024 bytes is recommended. It will also return the -new password to the caller if pw_ret is non-NULL. - -\begin{enumerate} -\item If new_pw is NULL, this routine will prompt the user for the new -password (using the strings specified by OVSEC_KADM_PW_FIRST_PROMPT and -OVSEC_KADM_PW_SECOND_PROMPT) and read (without echoing) the password input. -Since it is likely that this will simply call krb5_read_password only -terminal-based applications will make use of the password reading -functionality. If the passwords don't match the string ``New passwords do -not match - password not changed.'' will be copied into msg_ret, and the -error code KRB5_LIBOS_BADPWDMATCH will be returned. For other errors that -ocurr while reading the new password, copy the string ``$ -occurred while trying to read new password.'' followed by a blank line and -the string specified by CHPASS_UTIL_PASSWORD_NOT_CHANGED into msg_ret and -return the error code returned by krb5_read_password. - -\item If pw_ret is non-NULL, and the password was prompted, set *pw_ret to -point to a static buffer containing the password. If pw_ret is non-NULL -and the password was supplied, set *pw_ret to the supplied password. - -\item Call ovsec_kadm_chpass_principal with princ, and new_pw. - -\item If successful copy the string specified by CHPASS_UTIL_PASSWORD_CHANGED -into msg_ret and return zero. - -\item For a policy related failure copy the appropriate message (from below) -followed by a newline and ``Password not changed.'' into msg_ret -filling in the parameters from the principal's policy information. If -the policy information cannot be obtained copy the generic message if -one is specified below. Return the error code from -ovsec_kadm_chpass_principal. - -Detailed messages: -\begin{description} - -\item[PASS_Q_TOO_SHORT] -New password is too short. Please choose a -password which is more than $<$pw-min-len$>$ characters. - -\item[PASS_Q_TOO_SHORT - generic] -New password is too short. Please choose a longer password. - -\item[PASS_REUSE] -New password was used previously. Please choose a -different password. - -\item[PASS_Q_CLASS] -New password does not have enough character classes. Classes include -lower class letters, upper case letters, digits, punctuation and all -other characters. Please choose a password with at least -$<$min-classes$>$ character classes. - -\item[PASS_Q_CLASS - generic] -New password does not have enough character classes. Classes include -lower class letters, upper case letters, digits, punctuation and all -other characters. - -\item[PASS_Q_DICT] -New password was found in a dictionary of possible passwords and -therefore may be easily guessed. Please choose another password. See -the kpasswd man page for help in choosing a good password. - -\item[PASS_TOOSOON] -Password cannot be changed because it was changed too recently. Please -wait until $<$last-pw-change+pw-min-life$>$ before you change it. If you -need to change your password before then, contact your system -security administrator. - -\item[PASS_TOOSOON - generic] -Password cannot be changed because it was changed too recently. If you -need to change your now please contact your system security -administrator. -\end{description} - -\item For other errors copy the string ``$<$com_err message$>$ occurred while trying to change password.'' following by a blank line and ``Password not changed.'' into msg_ret. Return the error code returned by ovsec_kadm_chpass_principal. -\end{enumerate} - - -RETURN CODES: - -\begin{description} -\item[KRB5_LIBOS_BADPWDMATCH] Typed new passwords did not match. -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\item[OVSEC_KADM_PASS_Q_*] Requested password does not meet quality -standards. -\item[OVSEC_KADM_PASS_REUSE] Requested password is in user's -password history. -\item[OVSEC_KADM_PASS_TOOSOON] Current password has not reached minimum -life. -\end{description} - - -\subsection{ovsec_kadm_randkey_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_randkey_principal(krb5_principal princ, krb5_keyblock **new_key) -\end{verbatim} - -AUTHORIZATION REQUIRED: modify, or the calling principal being the -same as the princ argument. If the request is authenticated to the -ovsec_kadm/changepw service, the modify privilege is disregarded. - -Generate and assign a new random key to the named principal, and -return the generated key in allocated storage. The caller must free -the returned krb5_keyblock * with krb5_free_keyblock. - -If the principal's POLICY bit is set in aux_attributes and the caller does -not have modify privilege , compliance with the password minimum life -specified by the policy is verified and an appropriate error code is returned -if verification fails. - -\begin{enumerate} -\item If the principal does not exist, return OVSEC_KADM_UNK_PRINC. -\item If caller does not have modify privilege, (now - last_pwd_change) $<$ -pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the -principal's attributes, return OVSEC_KADM_PASS_TOOSOON. -\item Store old key in history. -\item Update principal to have new key. -\item Increment principal's key version number by one. -\item If the POLICY bit in aux_attributes is set, set pw_expiration to -now + max_pw_life. -\item If the KRB5_KDC_REQUIRES_PWCHANGE bit is set in the principal's -attributes, clear it. -\item Update last_pwd_change and mod_date to now, update mod_name to -caller. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\item[OVSEC_KADM_PASS_TOOSOON] The minimum lifetime for the current -key has not expired. -\end{description} - -This function can also be used as part of a sequence to create a new -principal with a random key. The steps to perform the operation -securely are - -\begin{enumerate} -\item Create the principal with ovsec_kadm_create_principal with a -random password string and with the KRB5_KDB_DISALLOW_ALL_TIX bit set -in the attributes field. - -\item Randomize the principal's key with ovsec_kadm_randkey_principal. - -\item Call ovsec_kadm_modify_principal to reset the -KRB5_KDB_DISALLOW_ALL_TIX bit in the attributes field. -\end{enumerate} - -The three steps are necessary to ensure secure creation. Since an -attacker might be able to guess the initial password assigned by the -client program, the principal must be disabled until the key can be -truly randomized. - -\subsection{ovsec_kadm_get_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_get_principal(krb5_principal princ, - ovsec_kadm_principal_ent_t *ent); -\end{verbatim} - -Return the principal's attributes in allocated memory. The caller -must free the returned entry with ovsec_kadm_free_principal_ent. -If an error is returned entry is set to NULL. - -AUTHORIZATION REQUIRED: get, or the calling principal being the same -as the princ argument. If the request is authenticated to the -ovsec_kadm/changepw service, the get privilege is disregarded. - - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\end{description} - -\subsection{ovsec_kadm_create_policy} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_create_policy(ovsec_kadm_policy_ent_t policy, u_int32 mask); -\end{verbatim} - -Create a new policy. - -AUTHORIZATION REQUIRED: add - -\begin{enumerate} -\item Check to see if mask is valid, if not return OVSEC_KADM_BAD_MASK error. -\item Return OVSEC_KADM_BAD_POLICY if the policy name contains illegal -characters. - -\item Check to see if the policy already exists, if so return -OVSEC_KADM_DUP error. -\item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2, -3, 4, or 5, return OVSEC_KADM_BAD_CLASS. -\item Create a new policy setting the appropriate fields determined -by the mask. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_DUP] Policy already exists -\item[OVSEC_KADM_BAD_MASK] The mask is not valid for a create -operation. -\item[OVSEC_KADM_BAD_CLASS] The specified number of character classes -is invalid. -\item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters. -\end{description} - -\subsection{ovsec_kadm_delete_policy} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_delete_policy(char *policy); -\end{verbatim} - -Deletes a policy. - -AUTHORIZATION REQUIRED: delete - -\begin{enumerate} -\item Return OVSEC_KADM_BAD_POLICY if the policy name contains illegal -characters. -\item Return OVSEC_KADM_UNK_POLICY if the named policy does not exist. -\item Return OVSEC_KADM_POLICY_REF if the named policy's refcnt is not 0. -\item Delete policy. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters. -\item[OVSEC_KADM_UNK_POLICY] Policy does not exist. -\item[OVSEC_KADM_POLICY_REF] Policy is being referenced. -\end{description} - -\subsection{ovsec_kadm_modify_policy} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_modify_policy(ovsec_kadm_policy_ent_t policy, u_int32 mask); -\end{verbatim} - -Modify an existing policy. Note that modifying a policy has no affect -on a principal using the policy until the next time the principal's -password is changed. - -AUTHORIZATION REQUIRED: modify - -\begin{enumerate} -\item Return OVSEC_KADM_BAD_POLICY if the policy name contains illegal -characters. -\item Check to see if mask is legal, if not return OVSEC_KADM_BAD_MASK error. -\item Check to see if policy exists, if not return -OVSEC_KADM_UNK_POLICY error. -\item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2, -3, 4, or 5, return OVSEC_KADM_BAD_CLASS. -\item Update the fields specified in the mask. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters. -\item[OVSEC_KADM_UNK_POLICY] Policy not found. -\item[OVSEC_KADM_BAD_MASK] The mask is not valid for a modify -operation. -\item[OVSEC_KADM_BAD_CLASS] The specified number of character classes -is invalid. -\end{description} - -\subsection{ovsec_kadm_get_policy} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_get_policy(char *policy, ovsec_kadm_policy_ent_t *ent); -\end{verbatim} - -AUTHORIZATION REQUIRED: get, or the calling principal's policy being -the same as the policy argument. If the request is authenticated to -the ovsec_kadm/changepw service, the get privilege is disregarded. -If an error is returned entry is set to NULL. - -Return the policy's attributes in allocated memory. The caller must -free the returned entry with ovsec_kadm_free_policy_ent. - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters. -\item[OVSEC_KADM_UNK_POLICY] Policy not found. -\end{description} - -\subsection{ovsec_kadm_free_principal_ent, _policy_ent} - -\begin{verbatim} -void ovsec_kadm_free_principal_ent(ovsec_kadm_principal_ent_t princ); -\end{verbatim} - -Free the memory that was allocated by a call to -ovsec_kadm_get_principal. If the argument is NULL, the function -returns succesfully. - -AUTHORIZATION REQUIRED: none (local operation) - -\begin{verbatim} -void ovsec_kadm_free_policy_ent(ovsec_kadm_policy_ent_t policy); -\end{verbatim} - -Free memory that was allocated by a call to ovsec_kadm_get_policy. If -the argument is NULL, the function returns succesfully. - -AUTHORIZATION REQUIRED: none (local operation) - -\subsection{ovsec_kadm_get_privs} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_get_privs(u_int32 *privs); -\end{verbatim} - -Return the caller's admin server privileges in the integer pointed to -by the argument. The Admin API does not define any way for a -principal's privileges to be set. Note that this function will -probably be removed or drastically changed in future versions of this -system. - -The returned value is a bitmask indicating the caller's privileges: - -\begin{tabular}{llr} -{\bf Privilege} & {\bf Symbol} & {\bf Value} \\ -Get & OVSEC_KADM_PRIV_GET & 0x01 \\ -Add & OVSEC_KADM_PRIV_ADD & 0x02 \\ -Modify & OVSEC_KADM_PRIV_MODIFY & 0x04 \\ -Delete & OVSEC_KADM_PRIV_DELETE & 0x08 -\end{tabular} - -There is no guarantee that a caller will have a privilege indicated by -this function for any length of time; applications using this function -must still be prepared to handle all possible OVSEC_KADM_AUTH_* error -codes. - -\section{Server} - -The Admin API will be implemented by a server process running on the -same machine as the Kerberos server, and a client library to -communicate with the server. - -\subsection{Command Line} -\label{sec:commandline} - -The command line syntax of the admin server is - -\begin{verbatim} -ovsec_adm_server [-m] [-r realm] [-createsalt normal|none] - [-modifysalt normal|none|keep] -\end{verbatim} - -The -m argument specifies that the Kerberos master key should be read -from the keyboard instead of from the stash file. If the stash file -does not exist and this argument is not specified, the server will -not start. - -The -r argument specifies the Kerberos realm. If this argument is not -specified, the host's default realm is used. - -The -createsalt and -modifysalt arguments control the type of salt -used when creating and modifying keys in the Kerberos database, -respectively. ``normal'' means the standard V5 salt which uses the -principal and realm name. ``none'' means no salt, which is compatible -with Kerberos V4. ``keep'' means maintain the previous salt when a -key is changed. - -If the either admin principal or policy databases are reloaded using -the tools described in section \ref{sec:tools}, the admin server must -be shut down during the process. If the admin server is left running -during the import process, at best the server may use old information -and at worst the database may become inconsistent. - -\subsection{Protocol and Port Number} - -The admin server accepts TCP Sun RPC connections. The port number -(which the server listens on, and which clients should use to contact -it) is determined by a three step process: - -\begin{enumerate} -\item If ovsec_kadm/tcp exists in /etc/services, the specified port -number is used. - -\item Otherwise, if kerberos_adm/tcp exists in /etc/services, the -specified port number is used. - -\item Otherwise, port number 752 is used. -\end{enumerate} - -\subsection{Key Table, Authorization ACLs} -\label{sec:acls} - -The admin server's keytable is stored in /krb5/ovsec_admin.srvtab. It -contains entries for the principals ovsec_kadm/admin and -ovsec_kadm/changepw. - -The admin server will use a simple ACL mechanism to grant privileges -to principals. The file {\tt /krb5/ovsec_admin_acl} will contain a -list of principals and their privileges. It is read at start-up, and -can only be reread by restarting the admin server. - -The format of this file is: - -\begin{itemize} -\item Blank lines or lines beginning with ``\#'' are ignored. - -\item ACL entry lines contain two fields separated by any number of -spaces, tabs, or newlines, and are terminated with a semi-colon. The -first field is a Kerberos name and the second field is the privilege -list. - -\item The privilege list can contain a comma separated list of the -words ``get'', ``add'', ``modify'', and ``delete''. -\end{itemize} - -The principal named in the first field of each ACL entry has the -privileges listed in the second field the ACL entry. - -\subsection{Logging} - -The Admin server will log various events via the syslog mechanism (see -the syslog(3) manual page). The level depends on the notice, the -facility is LOG_LOCAL6, and notices are identified with the name -``ovsec_adm_server''. Each syslog message described below begins with -a prefix including the time the message was logged, the host name of -the logging machine, and the pid of the logging process: - -\begin{verbatim} -Nov 11 12:37:26 suan-la-chow-show ovsec_adm_server[9229]: -\end{verbatim} - -\subsubsection{Miscellaneous Messages} - -When the server starts successfully and is ready to handle requests, -is logs the message ``starting'' at the LOG_INFO level. When it exits -(due to a signal, for example) it logs the message ``finished, -exiting'' at the LOG_INFO level. - -If the dictionary file does not exist, the server logs the message -``WARNING: Cannot find the dictionary file $<$name$>$, continuing -without one.'' at the LOG_ERR level and continues with dictionary -checking disabled. - -If the server cannot register itself as an RPC server via the portmap -daemon, it logs the message ``Cannot register RPC service, failing.'' -at the LOG_ERR level and exits with non-zero status. This error can -happen if the portmapper is not running. - -If the GSS-API authentication system cannot be initialized, the server -logs the message ``Cannot initialize GSS-API authentication, -failing.'' at the LOG_ERR level and exits with non-zero status. This -error can happen if, for example, the file ovsec_adm.srvtab does not -exist or is incorrect. - -\subsubsection{Request Messages} - -In the event descriptions below, IP address refers to the originating -remote IP address, procedure name refers to the name of the API -function, client name refers to the authenticated name of the caller, -service name refers to the service the client authenticated to (see -section \ref{sec:auth}), primary argument refers to the name of the -principal or policy affected by the call,\footnote{The first release -only logs the primary argument, rather than logging the old and new -values of all fields.} and status refers to the com_err string -corresponding to the error code generated. All of these messages are -logged at the LOG_NOTICE level. - -\begin{itemize} -\item Unsuccessful authentication attempts (e.g.: failures during -GSS-API context establishment). This error occurs inside the RPC; the -admin server is notified via a callback. - -\begin{verbatim} -Authentication attempt failed: , -\end{verbatim} - -Example: A buggy client attempts to authenticate to the admin server -as the existing but invalid service name ``mailserver@REALM.COM'': - -\begin{verbatim} -Authentication attempt failed: 192.231.148.11, Miscellaneous error, Wrong -principal in request -\end{verbatim} - -\item Authentication failure. This error can occur both within the -RPC, while parsing the RPC call header, and while arguments are -decoded by the admin server. It can be the result of a a garbled -{\it or retransmitted} packet, a replay attack, a packet-modification -attack, or a header/argument splicing attack. - -\begin{verbatim} -WARNING! Forged/garbled request: , claimed client = , service = , addr = -\end{verbatim} - -Example: An attacker attempts to replay a previously valid ``create -principal'' message from jon/admin@REALM.COM: - -\begin{verbatim} -WARNING! Forged/garbled request: ovsec_kadm_create_principal, claimed client = -jon/admin@REALM.COM, service = admin@REALM.COM, addr = 192.231.148.12 -\end{verbatim} - -\item Unauthorized request. This error occurs when a properly -authenticated caller attempts to perform an operation for which it is -not authorized. - -\begin{verbatim} -Unauthorized request: , , client = -, service = , addr = -\end{verbatim} - -Example: An attacker cracker@REALM.COM attempts to modify the Kerberos -master principal: - -\begin{verbatim} -Unauthorized request: ovsec_kadm_modify_principal, K/M@REALM.COM, -client = cracker@REALM.COM, service = admin@REALM.COM, addr = -192.231.148.12 -\end{verbatim} - -\item Authorized requests and miscellaneous errors. A message is -logged when an authorized request succeeds or fails for any reason -other than those listed above. In the case of success, the status is -``success''; otherwise, the status can be anything from ``no space -left on device'' (ENOSPC) to an OVSEC_KADM error such as ``principal -does not exist'' (OVSEC_KADM_UNK_PRINC). - -\begin{verbatim} -Request: , , , client = -, service = , addr = -\end{verbatim} - -Example: jon/admin@REALM.COM creates a new principal new@REALM.COM: - -\begin{verbatim} -Request: ovsec_kadm_create_principal, new@REALM.COM, success, -client = jon/admin@REALM.COM, service = admin@REALM.COM, addr = -192.231.148.12 -\end{verbatim} - -Example: A buggy client program attempts to create a principal with a -NULL name: - -\begin{verbatim} -Request: ovsec_kadm_create_principal, (null), Invalid argument, client -= jon/admin@REALM.COM, service = admin@REALM.COM, addr = -192.231.148.12 -\end{verbatim} - -Example: joe/user@REALM.COM changes its own password: - -\begin{verbatim} -Request: ovsec_kadm_chpass_principal, joe/user@REALM.COM, success, -client = joe/user@REALM.COM, server = ovsec_kadm/changepw@REALM.COM, -addr = 192.231.148.12 -\end{verbatim} - -Example: jon/admin@REALM.COM attempts to get a principal that does not -exist: - -\begin{verbatim} -Request: ovsec_kadm_get_principal, does/not/exist@REALM.COM, principal -does not exist, client = jon/admin@REALM.COM, server = -admin@REALM.COM, addr = 192.231.148.12 -\end{verbatim} - -\end{itemize} - -\subsection{Password Dictionary} - -The Admin server's password dictionary is stored in -/krb5/ovsec_adm_dict. It is read once when the server starts. It -contains a list of entries, separated by newlines. An entry may -include any character except a newline and NULL, including spaces. -The dictionary does not need to be sorted. - -\section{Tools} -\label{sec:tools} - -Three tools will be provided to create and manage the admin databases. -This need only run on the admin server machine and do not need to -operate remotely. The tools are: - -\begin{description} -\item[ovsec_adm_create] create the admin service principal, the admin -history principal, the admin password-changing principal, and empty -admin policy database, and an admin principal database with an empty -entry for every exist principal. -\item[ovsec_adm_db_export/import] dump or load the admin policy and -principal databases -\item[ovsec_adm_check] check the KDC and admin databases for -inconsistencies and repair them. -\end{description} - -The details of these tools are described in their own documents. - -\end{document} diff --git a/doc/kadm5/api-server-design.tex b/doc/kadm5/api-server-design.tex deleted file mode 100644 index b330e9ce0..000000000 --- a/doc/kadm5/api-server-design.tex +++ /dev/null @@ -1,584 +0,0 @@ -\documentstyle[12pt,fullpage,changebar]{article} - -% $Id$ - -\setlength{\parskip}{.7\baselineskip} -\setlength{\parindent}{0pt} - -\def\secure{OV*Secure} -\def\v#1{\verb+#1+} -\def\k#1{K$_#1$} - -\title{OV*Secure Admin Server \\ Implementation Design} -\author{Barry Jaspan} -\date{DRAFT --- \today} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% Make _ actually generate an _, and allow line-breaking after it. -\let\underscore=\_ -\catcode`_=13 -\def_{\underscore\penalty75\relax} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{document} - -\maketitle - -{\setlength{\parskip}{0pt}\tableofcontents} - -\section{Overview} - -The admin server is implemented as a nearly-stateless transaction -server, where each admin API function represents a single transaction. -No per-client or per-connection information is stored; only local -database handles are maintained between requests. - -The admin API is exported via an RPC interface that hides all details -about network encoding, authentication, and encryption of data on the -wire. The RPC mechanism does, however, allow the server to access the -underlying authentication credentials for authorization purposes. - -The admin server accesses a total of three databases. - -\begin{itemize} -\item The master Kerberos database is used to store all the -information that the Kerberos server understands, thus allowing the -greatest functionality with no modifications to a standard KDC. - -\item The admin principal database stores \secure{}-specific per-principal -information. - -\item The policy database stores \secure{} policy information. -\end{itemize} - -The per-principal information stored in the admin principal database -consists of the principal's policy name and an array of the -principal's previous keys. The old keys are stored encrypted in the -key of the special principal ``kadmin/history'' that is created by -ovsec_kadm_create. Since a change in kadmin/history's key renders -every principal's key history array useless, it can only be changed -using the ovsec_kadm_edit utility; that program will reencrypt every -principal's key history in the new key. The admin server refuses all -requests to change kdamin/history's key. - -\section{Main} - -The admin server starts by trapping all fatal signals and directing -them to a cleanup-and-exit function. It then creates and exports the -RPC interface and enters its main loop. - -The main loop dispatches all incoming requests to the RPC mechanism. -After 15 seconds of inactivity, the server closes all open databases; -each database will be automatically reopened by the API function -implementations as necessary. - -\section{Remote Procedure Calls} - -The RPC for the Admin system will be based on SUNRPC. SUNRPC is used -because it is a well-known, portable RPC mechanism. The underlying -external data representation (xdr) mechanisms for wire encapsulation -are well-known and extensible. - -Authentication to the admin server will be handled by adding a GSS-API -authentication type within the existing SUNRPC structure. This will -require code modifications to SUNRPC, but the API and wire protocol do -not need to change. This may affect whether the RPC will use UDP or -TCP; although all the admin functions are stateless, the GSS-API -authentication binding will not be and it might be easier to use TCP -for this reason. - -\section{Database Record Types} -\label{sec:db-types} - -\subsection{Admin Principal, osa_princ_ent_t} - -The admin principal database stores records of the type -osa_princ_ent_t (declared in $<$ovsec_admin/adb.h$>$), which is the -subset of the ovsec_kadm_principal_ent_t structure that is not stored -in the Kerberos database plus the necessary bookkeeping information. -The records are keyed by the ASCII representation of the principal's -name, including the trailing NULL. - -\begin{verbatim} -typedef struct _osa_princ_ent_t { - krb5_principal name; - - char * policy; - u_int32 aux_attributes; - - u_int32 num_old_keys; - u_int32 next_old_key; - krb5_kvno admin_history_kvno; - krb5_encrypted_keyblock *old_keys; -} osa_princ_ent_rec, *osa_princ_ent_t; -\end{verbatim} - -The fields that are different from ovsec_kadm_principal_ent_t are: - -\begin{description} -\item[num_old_keys] The number of previous keys in the old_keys array. -This value must be 0 $\le$ num_old_keys $<$ pw_history_num. - -\item[next_old_key] The index into old_keys where the next key should -be inserted. This value must be 0 $\le$ next_old_key $\le$ -num_old_keys. - -\item[admin_history_kvno] The key version number of the admin/history -principal's key used to encrypt the values in old_keys. If the admin -server finds that admin/history's kvno is different from the value in -this field, an error message is logged. (XXX where?) - -\item[old_keys] The array of the principal's previous keys, each -encrypted in the admin/history key. There are num_old_keys elements. -\end{description} - -\subsection{Policy, osa_policy_ent_t} - -The policy database stores records of the type osa_policy_ent_t -(declared in $<$ovsec_admin/adb.h$>$) , which is all of -ovsec_kadm_policy_ent_t plus necessary bookkeeping information. The -records are keyed by the policy name. - -\begin{verbatim} -typedef struct _osa_policy_ent_t { - char *policy; - - u_int32 pw_min_life; - u_int32 pw_max_life; - u_int32 pw_min_length; - u_int32 pw_min_classes; - u_int32 pw_history_num; - - u_int32 refcnt; -} osa_policy_ent_rec, *osa_policy_ent_t; -\end{verbatim} - -\subsection{Kerberos, krb5_db_entry} - -The Kerberos database stores records of type krb5_db_entry, which is -defined in the $<$krb5/kdb.h$>$ header file. - -\begin{verbatim} -typedef struct _krb5_encrypted_keyblock { - krb5_keytype keytype; - int length; - krb5_octet *contents; -} krb5_encrypted_keyblock; - -typedef struct _krb5_db_entry { - krb5_principal principal; - krb5_encrypted_keyblock key; - krb5_kvno kvno; - krb5_deltat max_life; - krb5_deltat max_renewable_life; - krb5_kvno mkvno; - - krb5_timestamp expiration; - krb5_timestamp pw_expiration; - krb5_timestamp last_pwd_change; - krb5_timestamp last_success; - - krb5_timestamp last_failed; - krb5_kvno fail_auth_count; - - krb5_principal mod_name; - krb5_timestamp mod_date; - krb5_flags attributes; - krb5_int32 salt_type:8, - salt_length:24; - krb5_octet *salt; - krb5_encrypted_keyblock alt_key; - krb5_int32 alt_salt_type:8, - alt_salt_length:24; - krb5_octet *alt_salt; - - krb5_int32 expansion[8]; -} krb5_db_entry; -\end{verbatim} - -The interpretation of most of these fields is the same as given in the -``Principals, ovsec_kadm_principal_ent_t'' section of the functional -specification. The fields that are not defined there are not used by -\secure{}; however, the admin server preserves the value of any fields -it does not understand. - -\section{Database Access Methods} - -\subsection{Principal and Policy Databases} - -This section describes the database abstraction used for the admin -principal and policy databases. Since both databases export -equivalent functionality, the API is only described once. The -character T is used to represent both ``princ'' and ``policy''. The -location of the principal database is defined by the \#define -PRINCIPAL_DB (``/krb5/ovsec_principal.db'') in $<$ovsec_admin/adb.h$>$. The -location of the policy database is defined by the \#define POLICY_DB -(``/krb5/ovsec_policy.db'') in $<$ovsec_admin/adb.h$>$. - -Note that this is {\it only} a database abstraction. All functional -intelligence, such as maintaining policy reference counts or sanity -checking, must be implemented above this layer. - -Prototypes for the osa functions are supplied in -$<$ovsec_admin/adb.h$>$. The routines can be found (in the first -relase) in ``stage/lib/libadb.a''. They require linking with the -Berkely DB library (``stage/lib/libdb.a''). [Note: We needed to remove -the dbm compatibility routines from libdb.a because we want to leave -KDB library alone in case somebody wants to run a stock MIT KDC with -our admin server.] - -The database routines use com_err for error codes. The error code -table name is ``adb'' and the offsets are the same as the order -presented here. The error table header file is -$<$ovsec_admin/adb_err.h$>$. Callers of the OSA routines should first call -init_adb_err_tbl() to initialize the database table. - -\begin{description} -\item[OSA_ADB_OK] Operation successful. -\item[OSA_ADB_FAILURE] General failure. -\item[OSA_ADB_DUP] Operation would create a duplicate database entry. -\item[OSA_ADB_NOENT] Named entry not in database. -\item[OSA_ADB_BAD_PRINC] The krb5_principal structure is invalid. -\item[OSA_ADB_BAD_POLICY] The specified policy name is invalid. -\item[OSA_ADB_XDR_FAILURE] The principal or policy structure cannot be -encoded for storage. -\end{description} - -Database functions can also return system errors. Unless otherwise -specified, database functions return OSA_ADB_OK. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_open_T(osa_adb_T_t *db, char *filename); -\end{verbatim} -% -Open the database named filename. Returns OSA_ADB_FAILURE if it -cannot open the database. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_close_T(osa_adb_T_t db); -\end{verbatim} -% -Close an open database. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_create_T(osa_adb_T_t db, osa_T_ent_t entry); -\end{verbatim} -% -Adds the entry to the database. All fields are defined. Returns -OSA_ADB_DUP if it already exists. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_destroy_T(osa_adb_T_t db, osa_T_t name); -\end{verbatim} - -Removes the named entry from the database. Returns OSA_ADB_NOENT if -it does not exist. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_get_T(osa_adb_T_t db, osa_T_t name, - osa_princ_ent_t *entry); -\end{verbatim} - -Looks up the named entry in the db, and returns it in *entry in -allocated storage that must be freed with osa_adb_free_T. Returns -OSA_ADB_NOENT if name does not exist, OSA_ADB_MEM if memory cannot be -allocated. - -\begin{verbatim} -osa_adb_ret_t -osadb_adb_put_T(osa_adb_T_t db, osa_T_ent_t entry); -\end{verbatim} - -Modifies the existing entry named in entry. All fields must be filled -in. Returns OSA_DB_NOENT if the named entry does not exist. Note -that this cannot be used to rename an entry; rename is implemented by -deleting the old name and creating the new one (NOT ATOMIC!). - -\begin{verbatim} -void osa_adb_free_T(osa_T_ent_t); -\end{verbatim} - -Frees the memory associated with an osa_T_ent_t allocated by -osa_adb_get_T. - -\begin{verbatim} -typedef osa_adb_ret_t (*osa_adb_iter_T_func)(void *data, - osa_T_ent_t entry); - -osa_adb_ret_t osa_adb_iter_T(osa_adb_T_t db, osa_adb_iter_T_func func, - void *data); -\end{verbatim} - -Iterates over every entry in the database. For each entry ent in the -database db, the function (*func)(data, ent) is called. If func -returns an error code, osa_adb_iter_T returns an error code. If all -invokations of func return OSA_ADB_OK, osa_adb_iter_T returns -OSA_ADB_OK. The function func is permitted to access the database, -but the consequences of modifying the database during the iteration -are undefined. - -\subsection{Kerberos Database} - -Kerberos uses dbm to store krb5_db_entry records. It can be accessed -and modified in parallel with the Kerberos server, using functions -that are defined inside the KDC and the libkdb.a. - -\subsubsection{Database Manipulation Functions} - -The following functions are declared in \v{lib/kdb/kdb_dbm.c} in the -Kerberos sources and are available in libkdb.a. They can return the -following error codes; error codes that can be returned by any -function are indicated with a ``*'' and are not listed specifically -for each function. - -\begin{description} -\item[* KRB5_KDB_NOTINITED] The database is not open; call -krb5_dbm_db_init. -\item[* KRB5_KDB_CANTLOCK_DB] The necessary lock cannot be acquired. Try -again later. -\item[* system errors] An error occurred accessing the database files. -\item[KRB5_KDB_DB_INUSE] The database was modified without the use -of proper locking.\footnote{This error occurs when the entire database -is swapped out from the under the process, say by a kdb5_edit restore. -It can only be returned by krb5_db_get_principal. It is not yet clear -what a program should do when it gets this error.} -\item[KRB5_KDB_NOENTRY] The principal to be deleted is not -in the database. -\end{description} - -\begin{verbatim} -krb5_dbm_db_init(void) -\end{verbatim} - -Opens the Kerberos database file (but does not actually call -dbm_open). This can be called even if the database is already open, -in which case it just returns success. - -\begin{verbatim} -krb5_dbm_db_fini(void) -\end{verbatim} - -Closes the database file; this MUST be called before the process -exits. Returns KRB5_KDB_DBNOTINITED if the database isn't open, but -that isn't really a fatal error. - -\begin{verbatim} -krb5_dbm_get_principal(krb5_principal searchfor, - krb5_db_entry *entries, int *nentries, krb5_boolean *more) -\end{verbatim} - -Search the database for the principal searchfor and write the results -into *entries. The interface is set up to handle wildcard gets, but -the code doesn't handle it: *nentries is assumed to be 1, and *more is -always returned as 0. - -This function does not retry if the database cannot be locked; that is -up to the caller. - -Returns KRB5_KDB_DB_INUSE. - -\begin{verbatim} -krb5_dbm_put_principal(krb5_db_entry *entries, int *nentries) -\end{verbatim} - -Stores *nentries elements from the entries array into the database. -On return *nentries is set to the number of entries actually written; -the first *nentries entries will have been written, even if an error -pis returned. - -This function does not retry if the database cannot be locked; that is -up to the caller. - -\begin{verbatim} -krb5_dbm_db_delete_principal(krb5_principal searchfor, int *nentries) -\end{verbatim} - -Removes the principal searchfor from the database. nentries will be -set to 0 or 1 on output, indicating the number of entries deleted (the -code does not currently support wildcards). - -Returns KRB5_KDB_NOENTRY. - -\begin{verbatim} -typedef krb5_error_code (*iter_func)(krb5_pointer, krb5_db_entry *); - -krb5_dbm_db_iterate(iter_func func, krb5_point func_arg) -\end{verbatim} - -Calls (*func)(func_arg, entry) for every entry in the database. If -func returns an error code, the iteration stops and that error code is -returned. - -Returns func error codes. - -\begin{verbatim} -void krb5_dbm_db_free_principal(krb5_db_entry *entries, int nentries) -\end{verbatim} - -Frees entries returned by krb5_dbm_db_get_principal. nentries entries -in the array entries will be freed. - -\subsubsection{Initialization and Key Access} - -Keys stored in the Kerberos database are encrypted in the Kerberos -master key. The admin server will therefore have to acquire the key -before it can perform any key-changing operations, and will have to -decrypt and encrypt the keys retrieved from and placed into the -database via krb5_db_get_principal and _put_principal. This section -describes the internal admin server API that will be used to perform -these functions. - -\begin{verbatim} -krb5_principal master_princ; -krb5_encrypt_block master_encblock; -krb5_keyblock master_keyblock; - -void kdc_init_master() -\end{verbatim} - -kdc_init_master opens the database and acquires the master key. It -also sets the global variables master_princ, master_encblock, and -master_keyblock: - -\begin{itemize} -\item master_princ is set to the name of the Kerberos master principal -(\v{K/M@REALM}). - -\item master_encblock is something I have no idea about. - -\item master_keyblock is the Kerberos master key -\end{itemize} - -\begin{verbatim} -krb5_error_code kdb_get_entry_and_key(krb5_principal principal, - krb5_db_entry *entry, - krb5_keyblock *key) -\end{verbatim} - -kdb_get_entry_and_key retrieves the named principal's entry from the -database in entry, and decrypts its key into key. The caller must -free entry with krb5_dbm_db_free_principal and free key-$>$contents with -free.\footnote{The caller should also \v{memset(key-$>$contents, 0, -key-$>$length)}. There should be a function krb5_free_keyblock_contents -for this, but there is not.} - -\begin{verbatim} -krb5_error_code kdb_put_entry_pw(krb5_db_entry *entry, char *pw) -\end{verbatim} - -kdb_put_entry_pw stores entry in the database. All the entry values -must already be set; this function does not change any of them except -the key. pw, the NULL-terminated password string, is converted to a -key using string-to-key with the salt type specified in -entry-$>$salt_type.\footnote{The salt_type should be set based on the -command line arguments to the kadmin server (see the ``Command Line'' -section of the functional specification).} - -\section{Admin Principal and Policy Database Implementation} - -The admin principal and policy databases will each be stored in a -single hash table, implemented by the Berkeley 4.4BSD db library. -Each record will consist of an entire osa_T_ent_t. The key into the -hash table is the entry name (for principals, the ASCII representation -of the name). The value is the T entry structure. Since the key and -data must be self-contained, with no pointers, the Sun xdr mechanisms -will be used to marshal and unmarshal data in the database. - -The server in the first release will be single-threaded in that a -request will run to completion (or error) before the next will run, -but multiple connections will be allowed simultaneously. - -\section{ACLs, acl_check} - -The ACL mechanism described in the ``Authorization ACLs'' section of -the functional specifications will be implemented by the acl_check -function. - -\begin{verbatim} -enum access_t { - ACCESS_DENIED = 0, - ACCESS_OK = 1, -}; - -enum access_t acl_check(krb5_principal princ, char *priv); -\end{verbatim} - -The priv argument must be one of ``get'', ``add'', ``delete'', or -``modify''. acl_check returns 1 if the principal princ has the named -privilege, 0 if it does not. - -\section{Function Details} - -This section discusses specific design issues for Admin API functions -that are not addresed by the functional specifications. - -\subsection{ovsec_kadm_create_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return OVSEC_KADM_BAD_DB. - -The principal's initial key is not stored in the key history array at -creation time. - -\subsection{ovsec_kadm_delete_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return OVSEC_KADM_BAD_DB. - -\subsection{ovsec_kadm_modify_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return OVSEC_KADM_BAD_DB. - -If pw_history_num changes and the new value $n$ is smaller than the -current value of num_old_keys, old_keys should end up with the $n$ -most recent keys; these are found by counting backwards $n$ elements -in old_keys from next_old_key. next_old_keys should then be reset to -0, the oldest of the saved keys, and num_old_keys set to $n$, the -new actual number of old keys in the array. - -\subsection{ovsec_kadm_chpass_principal, randkey_principal} - -The algorithm for determining whether a password is in the principal's -key history is complicated by the use of the kadmin/history \k{h} -encrypting key. - -\begin{enumerate} -\item For ovsec_kadm_chpass_principal, convert the password to a key -using string-to-key and the salt method specified by the command line -arguments. - -\item If the POLICY bit is set and pw_history_num is not zero, check -if the new key is in the history. -\begin{enumerate} -\item Retrieve the principal's current key and decrypt it with \k{M}. -If it is the same as the new key, return OVSEC_KADM_PASS_REUSE. -\item Retrieve the kadmin/history key \k{h} and decrypt it with \k{M}. -\item Encrypt the principal's new key in \k{h}. -\item If the principal's new key encrypted in \k{h} is in old_keys, -return OVSEC_KADM_PASS_REUSE. -\item Encrypt the principal's current key in \k{h} and store it in -old_keys. -\item Erase the memory containing \k{h}. -\end{enumerate} - -\item Encrypt the principal's new key in \k{M} and store it in the -database. -\item Erase the memory containing \k{M}. -\end{enumerate} - -To store the an encrypted key in old_keys, insert it as the -next_old_key element of old_keys, and increment next_old_key by one -modulo pw_history_num. - -\subsection{ovsec_kadm_get_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return OVSEC_KADM_BAD_DB. - -\end{document} diff --git a/doc/kadm5/api-unit-test.tex b/doc/kadm5/api-unit-test.tex deleted file mode 100644 index dc0ce817a..000000000 --- a/doc/kadm5/api-unit-test.tex +++ /dev/null @@ -1,1755 +0,0 @@ -\documentstyle[times,fullpage,rcsid]{article} - -\rcs$Header$ - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% Make _ actually generate an _, and allow line-breaking after it. -\let\underscore=\_ -\catcode`_=13 -\def_{\underscore\penalty75\relax} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\newcommand{\test}[1]{\begin{description} -\setlength{\itemsep}{0pt} -#1 -\end{description} - -} - -\newcommand{\numtest}[2]{\begin{description} -\setlength{\itemsep}{0pt} -\Number{#1} -#2 -\end{description} - -} - -\newcommand{\Number}[1]{\item[Number:] #1} -\newcommand{\Reason}[1]{\item[Reason:] #1} -%\newcommand{\Call}[1]{\item[Call:] #1} -\newcommand{\Expected}[1]{\item[Expected:] #1} -\newcommand{\Conditions}[1]{\item[Conditions:] #1} -\newcommand{\Priority}[1]{\item[Priority:] #1} - -%\newcommand{\Number}[1]{} -%\newcommand{\Reason}[1]{} -\newcommand{\Call}[1]{} -%\newcommand{\Expected}[1]{} -%\newcommand{\Conditions}[1]{} -%\newcommand{\Priority}[1]{} - -\title{OpenV*Secure 1.0 Admin API\\ -Unit Test Description\footnote{\rcsHeader}} -\author{Jonathan I. Kamens} - -\begin{document} - -\maketitle - -%\tableofcontents - -\section{Introduction} - -The following is a description of a black-box unit test of the -OpenV*Secure Admin API. Each API function is listed, followed by the -tests that shoud be performed on it. - -The tests described here are based on the ``OV*Secure Admin Functional -Specifications'' revision 1.27, dated November 17, 1993. - -Since inter-realm functionality is not a requirement for OpenV*Secure -1.0, it is not tested. - -All tests which test for success should verify, using some means other -than the return value of the function being tested, that the requested -operation was successfully performed. For example: for init, test -that other operations can be performed after init; for destroy, test -that other operations can't be performed after destroy; for modify -functions, verify that all modifications to the database which should -have taken place did, and that the new, modified data is in effect; -for get operations, verify that the data retrieved is the data that -should actually be in the database. - -Similarly, all tests which test for failure should verify that the -no component of the requested operation took place. For example: if -init fails, other operations should not work. If a modify fails, all -data in the database should be the same as it was before the attempt -to modify, and the old data should still be what is enforced. -Furthermore, tests which test for failure should verify that the -failure code returned is correct for the specific failure condition -tested. - -Most of the tests listed below should be run twice -- once locally on -the server after linking against the server API library, and once -talking to the server via authenticated Sun RPC after linking against -the client API library. Tests which should only be run locally or via -RPC are labelled with a ``local'' or ``RPC''. - -Furthermore, in addition to the tests labelled below, a test should be -implemented to verify that a client can't perform operations on the -server through the client API library when it's linked against -standard Sun RPC instead of OpenV*Secure's authenticated Sun RPC. -This will require a client with a modified version of ovsec_kadm_init -which doesn't call auth_gssapi_create. This client should call this -modified ovsec_kadm_init and then call some other admin API function, -specifying arguments to both functions that would work if the -authenciated Sun RPC had been used, but shouldn't if authentication -wasn't used. The test should verify that the API function call after -the init doesn't succeed. - -\section{ovsec_kadm_init} - -\numtest{1}{ -\Reason{An empty string realm is rejected.} -} - -\numtest{2}{ -\Reason{A realm containing invalid characters is rejected.} -} - -\numtest{2.5}{ -\Reason{A non-existent realm is rejected.} -} - -\numtest{3}{ -\Reason{A bad service name representing an existing principal - (different from the client principal) is rejected.} -\Conditions{RPC} -} - -\numtest{4}{ -\Reason{A bad service name representing a non-existent - principal is rejected.} -\Conditions{RPC} -} - -\numtest{5}{ -\Reason{A bad service name identical to the (existing) client - name is rejected.} -\Conditions{RPC} -} - -\numtest{6}{ -\Reason{A null password causes password prompting.} -\Conditions{RPC} -} - -\numtest{7}{ -\Reason{An empty-string password is rejected.} -\Conditions{RPC} -} - -\numtest{8}{ -\Reason{An incorrect password which is the password of another - user is rejected.} -\Conditions{RPC} -} - -\numtest{9}{ -\Reason{An incorrect password which isn't the password of any - user is rejected.} -\Conditions{RPC} -} - -\numtest{10}{ -\Reason{A null client_name is rejected.} -} - -% Empty string client name is legal. -%\numtest{11}{ -%\Reason{An empty-string client_name is rejected.} -%} - -\numtest{12}{ -\Reason{A client_name referring to a non-existent principal in - the default realm is rejected.} -\Conditions{RPC} -} - -\numtest{13}{ -\Reason{A client_name referring to a non-existent principal - with the local realm specified explicitly is rejected.} -\Conditions{RPC} -} - -\numtest{14}{ -\Reason{A client_name referring to a non-existent principal in - a nonexistent realm is rejected.} -\Conditions{RPC} -} - -\numtest{15}{ -\Reason{A client_name referring to an existing principal in a - nonexistent realm is rejected.} -\Conditions{RPC} -} - -\numtest{16}{ -\Reason{Valid invocation.} -} - -\numtest{17}{ -\Reason{Valid invocation (explicit client realm).} -} - -\numtest{18}{ -\Reason{Valid invocation (CHANGEPW_SERVICE).} -} - -\numtest{19}{ -\Reason{Valid invocation (explicit service realm).} -} - -\numtest{20}{ -\Reason{Valid invocation (database access allowed after init).} -} - -\numtest{21}{ -\Reason{Init fails when called twice in a row.} -} - -\numtest{22}{ -\Reason{A null password causes master-key prompting.} -\Conditions{local} -} - -\numtest{23}{ -\Reason{A non-null password causes reading from the kstash.} -\Conditions{local} -} - -\numtest{24}{ -\Reason{Null service name is ignored in local invocation.} -\Conditions{local} -} - -\numtest{25}{ -\Reason{Non-null service name is ignored in local invocation.} -\Conditions{local} -} - -\numtest{26}{ -\Reason{Can't do ``get'' operation before calling init.} -} - -\numtest{27}{ -\Reason{Can't do ``add'' operation before calling init.} -} - -\numtest{28}{ -\Reason{Can't do ``modify'' operation before calling init.} -} - -\numtest{29}{ -\Reason{Can't do ``delete'' operation before calling init.} -} - -\nultest{30}{ -\Reason{Can init after failed init attempt.} -\Conditions{local} -} - -\section{ovsec_kadm_destroy} - -\numtest{1}{ -\Reason{Valid invocation.} -} - -\numtest{2}{ -\Reason{Valid invocation (``get'' not allowed after destroy).} -} - -\numtest{3}{ -\Reason{Valid invocation (``add'' not allowed after destroy).} -} - -\numtest{4}{ -\Reason{Valid invocation (``modify'' not allowed after destroy).} -} - -\numtest{5}{ -\Reason{Valid invocation (``delete'' not allowed after destroy).} -} - -\numtest{6}{ -\Reason{Fails if database not initialized.} -} - -\numtest{7}{ -\Reason{Fails if invoked twice in a row.} -} - -\numtest{8}{ -\Reason{Database can be reinitialized after destroy.} -} - -\section{ovsec_kadm_create_principal} - -%In the tests below, ``getu'' refers to a user who has only ``get'' access, -%''addu'' refers to a user who has only ``add'' access, ``modifyu'' refers to -%a user who has only ``modify'' access, and ``deleteu'' refers to a user -%who has only ``delete'' access. ``amu'' refers to a user with ``add'' and -%''modify'' access. ``new_princ'' refers to a principal entry structure -%filled in as follows: -% -% krb5_parse_name("newuser", \&new_princ.principal); -% krb5_timeofday(\&new_princ.princ_expire_time); -% new_princ.princ_expire_time += 130; -% krb5_timeofday(\&new_princ.last_pwd_change); -% new_princ.last_pwd_change += 140; -% krb5_timeofday(\&new_princ.pw_expiration); -% new_princ.pw_expiration += 150; -% new_princ.max_life = 160; -% krb5_parse_name("usera", \&new_princ.mod_name); -% krb5_timeofday(\&new_princ.mod_date); -% new_princ.mod_date += 170; -% new_princ.attributes = 0xabcdabcd; -% new_princ.kvno = 180; -% new_princ.mkvno = 190; -% new_princ.policy = null; -% new_princ.aux_attributes = 0xdeadbeef; -% -%The offsets of 130 through 190 above are used to ensure that the -%fields are all known to be different from each other, so that -%accidentally switched fields can be detected. Some of the fields in -%this structure may be changed by the tests, but they should clean up -%after themselves. - -\numtest{1}{ -\Reason{Fails if database not initialized.} -} - -\numtest{2}{ -\Reason{Fails on null princ argument.} -} - -\numtest{3}{ -\Reason{Fails on null password argument.} -} - -\numtest{4}{ -\Reason{Fails on empty-string password argument.} -} - -\numtest{5}{ -\Reason{Fails when mask contains undefined bit.} -} - -\numtest{6}{ -\Reason{Fails when mask contains LAST_PWD_CHANGE bit.} -} - -\numtest{7}{ -\Reason{Fails when mask contains MOD_TIME bit.} -} - -\numtest{8}{ -\Reason{Fails when mask contains MOD_NAME bit.} -} - -\numtest{9}{ -\Reason{Fails when mask contains MKVNO bit.} -} - -\numtest{10}{ -\Reason{Fails when mask contains AUX_ATTRIBUTES bit.} -} - -\numtest{11}{ -\Reason{Fails when mask contains POLICY_CLR bit.} -} - -\numtest{12}{ -\Reason{Fails for caller with no access bits.} -} - -\numtest{13}{ -\Reason{Fails when caller has ``get'' access and not ``add''.} -\Conditions{RPC} -} - -\numtest{14}{ -\Reason{Fails when caller has ``modify'' access and not ``add''.} -\Conditions{RPC} -} - -\numtest{15}{ -\Reason{Fails when caller has ``delete'' access and not ``add''.} -\Conditions{RPC} -} - -\numtest{16}{ -\Reason{Fails when caller connected with CHANGEPW_SERVICE.} -\Conditions{RPC} -} - -\numtest{17}{ -\Reason{Fails on attempt to create existing principal.} -} - -\numtest{18}{ -\Reason{Fails when password is too short.} -} - -\numtest{19}{ -\Reason{Fails when password has too few classes.} -} - -\numtest{20}{ -\Reason{Fails when password is in dictionary.} -} - -\numtest{21}{ -\Reason{Nonexistent policy is rejected.} -} - -\numtest{22}{ -\Reason{Fails on invalid principal name.} -} - -\numtest{23}{ -\Reason{Valid invocation.} -} - -\numtest{24}{ -\Reason{Succeeds when caller has ``add'' access and another one.} -} - -%\numtest{25}{ -%\Reason{Fails when password is too short, when override_qual is true.} -%} - -%\numtest{26}{ -%\Reason{Fails when password has too few classes, when -% override_qual is true.} -%} - -%\numtest{27}{ -%\Reason{Fails when password is in dictionary, when override_qual is -% true.} -%} - -\numtest{28}{ -\Reason{Succeeds when assigning policy.} -} - -\numtest{29}{ -\Priority{High} -\Reason{Allows 0 (never) for princ_expire_time.} -} - -\numtest{30}{ -\Reason{Allows 0 (never) for pw_expiration when there's no policy.} -} - -\numtest{31}{ -\Reason{Allows 0 (never) for pw_expiration when there's a policy with - 0 for pw_max_life.} -} - -\numtest{32}{ -\Reason{Accepts 0 (never) for pw_expiration when there's a policy with - non-zero pw_max_life, but actually sets pw_expiration to now + - pw_max_life.} -} - -\numtest{33}{ -\Reason{Accepts and sets non-zero pw_expiration when no policy.} -} - -\numtest{34}{ -\Reason{Accepts and sets non-zero pw_expiration when there's a policy - with zero pw_max_life.} -} - -\numtest{35}{ -\Reason{Accepts and sets non-zero pw_expiration when there's a policy - with pw_max_life later than the specified pw_expiration.} -} - -\numtest{36}{ -\Reason{Accepts non-zero pw_expiration and limits it to now + - pw_max_life when it's later than now + non-zero pw_max_life in - policy.} -} - -\numtest{37}{ -\Priority{High} -\Reason{Sets pw_expiration to 0 (never) if there's no policy and no - specified pw_expiration.} -} - -\numtest{38}{ -\Priority{High} -\Reason{Sets pw_expiration to 0 (never) if it isn't specified and the - policy has a 0 (never) pw_max_life.} -} - -\numtest{39}{ -\Priority{High} -\Reason{Sets pw_expiration to now + pw_max_life if it isn't specified - and the policy has a non-zero pw_max_life.} -} - -\numtest{40}{ -\Priority{High} -\Reason{Allows 0 (forever) for max_life.} -} - - - -\section{ovsec_kadm_delete_principal} - -\numtest{1}{ -\Reason{Fails if database not initialized.} -} - -\numtest{2}{ -\Reason{Fails on null principal.} -} - -% Empty string principal is legal. -%\numtest{3}{ -%\Reason{Fails on empty-string principal.} -%} - -\numtest{4}{ -\Reason{Fails on invalid principal name.} -} - -\numtest{5}{ -\Priority{High} -\Reason{Fails on nonexistent principal.} -} - -\numtest{6}{ -\Priority{High} -\Reason{Fails when caller connected with CHANGEPW_SERVICE.} -} - -\numtest{7}{ -\Priority{High} -\Reason{Fails if caller has ``add'' access and not ``delete''.} -} - -\numtest{8}{ -\Priority{High} -\Reason{Fails if caller has ``modify'' access and not ``delete''.} -} - -\numtest{9}{ -\Priority{High} -\Reason{Fails if caller has ``get'' access and not ``delete''.} -} - -\numtest{10}{ -\Priority{High} -\Reason{Fails if caller has no access bits.} -} - -\numtest{11}{ -\Priority{High} -\Reason{Valid invocation.} -} - -\numtest{12}{ -\Priority{High} -\Reason{Valid invocation (on principal with policy).} -} - - - -\section{ovsec_kadm_modify_principal} - -\numtest{1}{ -\Reason{Fails if database not initialized.} -} - -\numtest{2}{ -\Priority{High} -\Reason{Fails if user connected with CHANGEPW_SERVICE.} -} - -\numtest{3}{ -\Reason{Fails on mask with undefined bit set.} -} - -\numtest{4}{ -\Reason{Fails on mask with PRINCIPAL set.} -} - -\numtest{5}{ -\Priority{High} -\Reason{Fails on mask with LAST_PWD_CHANGE set.} -} - -\numtest{6}{ -\Reason{Fails on mask with MOD_TIME set.} -} - -\numtest{7}{ -\Reason{Fails on mask with MOD_NAME set.} -} - -\numtest{8}{ -\Reason{Fails on mask with MKVNO set.} -} - -\numtest{9}{ -\Priority{High} -\Reason{Fails on mask with AUX_ATTRIBUTES set.} -} - -\numtest{10}{ -\Reason{Fails on nonexistent principal.} -} - -\numtest{11}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -} - -\numtest{12}{ -\Priority{High} -\Reason{Fails for user with ``get'' access.} -} - -\numtest{13}{ -\Priority{High} -\Reason{Fails for user with ``add'' access.} -} - -\numtest{14}{ -\Priority{High} -\Reason{Fails for user with ``delete'' access.} -} - -\numtest{15}{ -\Priority{High} -\Reason{Succeeds for user with ``modify'' access.} -} - -\numtest{16}{ -\Reason{Succeeds for user with ``modify'' and another access.} -} - -\numtest{17}{ -\Priority{High} -\Reason{Fails when nonexistent policy is specified.} -} - -\numtest{18}{ -\Priority{High} -\Reason{Succeeds when existent policy is specified.} -} - -\numtest{19}{ -\Reason{Updates policy count when setting policy from none.} -} - -\numtest{20}{ -\Reason{Updates policy count when clearing policy from set.} -} - -\numtest{21}{ -\Reason{Updates policy count when setting policy from other policy.} -} - -\numtest{22}{ -\Reason{Allows 0 (never) for pw_expiration when there's no policy.} -} - -\numtest{23}{ -\Reason{Allows 0 (never) for pw_expiration when there's a policy with - 0 for pw_max_life.} -} - -\numtest{24}{ -\Reason{Accepts 0 (never) for pw_expiration when there's a policy with - non-zero pw_max_life, but actually sets pw_expiration to - last_pwd_change + pw_max_life.} -} - -\numtest{25}{ -\Reason{Accepts and sets non-zero pw_expiration when no policy.} -} - -\numtest{26}{ -\Reason{Accepts and sets non-zero pw_expiration when there's a policy - with zero pw_max_life.} -} - -\numtest{27}{ -\Reason{Accepts and sets non-zero pw_expiration when there's a policy - with pw_max_life later than the specified pw_expiration.} -} - -\numtest{28}{ -\Reason{Accepts non-zero pw_expiration and limits it to last_pwd_change + - pw_max_life when it's later than last_pwd_change + non-zero - pw_max_life in policy.} -} - -\numtest{29}{ -\Priority{High} -\Reason{Sets pw_expiration to 0 (never) if there's no policy and no - specified pw_expiration.} -} - -\numtest{30}{ -\Priority{High} -\Reason{Sets pw_expiration to 0 (never) if it isn't specified and the - policy has a 0 (never) pw_max_life.} -} - -\numtest{31}{ -\Priority{High} -\Reason{Sets pw_expiration to now + pw_max_life if it isn't specified - and the policy has a non-zero pw_max_life.} -} - -\numtest{32}{ -\Priority{High} -\Reason{Accepts princ_expire_time change.} -} - -\numtest{33}{ -\Priority{High} -\Reason{Accepts attributes change.} -} - -\numtest{34}{ -\Priority{High} -\Reason{Accepts max_life change.} -} - -\numtest{35}{ -\Priority{High} -\Reason{Accepts kvno change.} -} - -\numtest{36}{ -\Reason{Behaves correctly when policy is set to the same as it was - before.} -} - -\numtest{37}{ -\Reason{Behaves properly when POLICY_CLR is specified and there was no - policy before.} -} - -\numtest{38}{ -\Priority{High} -\Reason{Accepts 0 (never) for princ_expire_time.} -} - -\numtest{39}{ -\Priority{High} -\Reason{Accepts 0 for max_life.} -} - -\numtest{40}{ -\Reason{Rejects null principal argument.} -} - - -\section{ovsec_kadm_rename_principal} - -\numtest{1}{ -\Reason{Fails if database not initialized.} -} - -\numtest{2}{ -\Priority{High} -\Reason{Fails if user connected with CHANGEPW_SERVICE.} -} - -\numtest{3}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -} - -\numtest{4}{ -\Reason{Fails for user with ``modify'' access and not ``add'' or -``delete''.} -} - -\numtest{5}{ -\Reason{Fails for user with ``get'' access and not ``add'' or -``delete''.} -} - -\numtest{6}{ -\Reason{Fails for user with ``modify'' and ``add'' but not ``delete''.} -} - -\numtest{7}{ -\Reason{Fails for user with ``modify'' and ``delete'' but not ``add''.} -} - -\numtest{8}{ -\Reason{Fails for user with ``get'' and ``add'' but not ``delete''.} -} - -\numtest{9}{ -\Reason{Fails for user with ``get'' and ``delete'' but not ``add.''} -} - -\numtest{10}{ -\Reason{Fails for user with ``modify'', ``get'' and ``add'', but not - ``delete''.} -} - -\numtest{11}{ -\Reason{Fails for user with ``modify'', ``get'' and ``delete'', but - not ``add''.} -} - -\numtest{12}{ -\Priority{High} -\Reason{Fails for user with ``add'' but not ``delete''.} -} - -\numtest{13}{ -\Priority{High} -\Reason{Fails for user with ``delete'' but not ``add''.} -} - -\numtest{14}{ -\Priority{High} -\Reason{Succeeds for user with ``add'' and ``delete''.} -} - -\numtest{15}{ -\Priority{High} -\Reason{Fails if target principal name exists.} -} - - - -\section{ovsec_kadm_chpass_principal} -\label{ovseckadmchpassprincipal} - -\subsection{Quality/history enforcement tests} - -This section lists a series of tests which will be run a number of -times, with various parameter settings (e.g., which access bits user -has, whether user connected with ADMIN_SERVICE or CHANGEPW_SERVICE, -etc.). The table following the -list of tests gives the various parameter settings under which the -tests should be run, as well which should succeed and which should -fail for each choice of parameter settings. - -\subsubsection{List of tests} - -The test number of each of these tests is an offset from the base -given in the table below. - -\numtest{1}{ -\Priority{High} -\Reason{With history setting of 1, change password to itself.} -} - -\numtest{2}{ -\Reason{With history setting of 2 but no password changes since - principal creation, change password to itself.} -} - -\numtest{3}{ -\Reason{With history setting of 2 and one password change since - principal creation, change password to itself - and directly previous password.} -} - -\numtest{4}{ -\Priority{High} -\Reason{With a history setting of 3 and no password changes, - change password to itself.} -} - -\numtest{5}{ -\Priority{High} -\Reason{With a history setting of 3 and 1 password change, - change password to itself or previous password.} -} - -\numtest{6}{ -\Priority{High} -\Reason{With a history setting of 3 and 2 password changes, - change password to itself and the two previous passwords.} -} - -\numtest{7}{ -\Priority{High} -\Reason{Change to previously unused password when now - - last_pwd_change $<$ pw_min_life.} -} - -\numtest{8}{ -\Priority{High} -\Reason{Change to previously unused password that doesn't contain enough - character classes.} -} - -\numtest{9}{ -\Priority{High} -\Reason{Change to previously unused password that's too short.} -} - -\numtest{10}{ -\Priority{High} -\Reason{Change to previously unused password that's in the dictionary.} -} - -\subsubsection{List of parameter settings} - -In the table below, ``7 passes'' means that test 7 above passes and -the rest of the tests fail. - -\begin{tabular}{llllll} -Base & Modify access? & Own password? & Service & Pass/Fail \\ \hline -0 & No & Yes & ADMIN & all fail \\ -20 & No & Yes & CHANGEPW & all fail \\ -40 & No & No & ADMIN & all fail \\ -60 & No & No & CHANGEPW & all fail \\ -80 & Yes & Yes & ADMIN & all fail \\ -100 & Yes & Yes & CHANGEPW & all fail \\ -120 & Yes & No & ADMIN & all fail \\ -140 & Yes & No & CHANGEPW & all fail \\ -\end{tabular} - -\subsection{Other quality/history tests} - -\numtest{161}{ -\Priority{High} -\Reason{With history of 1, can change password to anything other than - itself that doesn't conflict with other quality - rules.} -} - -\numtest{162}{ -\Reason{With history of 2 and 2 password changes, can change password - to original password.} -} - -\numtest{163}{ -\Priority{High} -\Reason{With history of 3 and 3 password changes, can change password - to original password.} -} - -\numtest{164}{ -\Priority{High} -\Reason{Can change password when now - last_pwd_change $>$ pw_min_life.} -} - -\numtest{165}{ -\Priority{High} -\Reason{Can change password when it contains exactly the number of - classes required by the policy.} -} - -\numtest{166}{ -\Priority{High} -\Reason{Can change password when it is exactly the length required by - the policy.} -} - -\numtest{167}{ -\Priority{High} -\Reason{Can change password to a word that isn't in the dictionary.} -} - - -\subsection{Other tests} - -\numtest{168}{ -\Reason{Fails if database not initialized.} -} - -\numtest{169}{ -\Reason{Fails for non-existent principal.} -} - -\numtest{170}{ -\Reason{Fails for null password.} -} - -\numtest{171}{ -\Priority{High} -\Reason{Fails for empty-string password.} -} - -\numtest{172}{ -\Priority{High} -\Reason{Pw_expiration is set to now + max_pw_life if policy exists and - has non-zero max_pw_life.} -} - -\numtest{173}{ -\Priority{High} -\Reason{Pw_expiration is set to 0 if policy exists and has zero - max_pw_life.} -} - -\numtest{174}{ -\Priority{High} -\Reason{Pw_expiration is set to 0 if no policy.} -} - -\numtest{175}{ -\Priority{High} -\Reason{KRB5_KDC_REQUIRES_PWCHANGE bit is cleared when password is - successfully changed.} -} - -\numtest{176}{ -\Priority{High} -\Reason{Fails for user with no access bits, on other's password.} -} - -\numtest{177}{ -\Priority{High} -\Reason{Fails for user with ``get'' but not ``modify'' access, on - other's password.} -} - -\numtest{178}{ -\Reason{Fails for user with ``delete'' but not ``modify'' access, on - other's password.} -} - -\numtest{179}{ -\Reason{Fails for user with ``add'' but not ``modify'' access, on - other's password.} -} - -\numtest{180}{ -\Reason{Succeeds for user with ``get'' and ``modify'' access, on - other's password.} -} - -\numtest{180.5}{ -\Priority{High} -\Reason{Succeeds for user with ``modify'' but not ``get'' access, on - other's password.} -} - -%\numtest{181}{ -%\Reason{Password that would succeed if override_qual were false fails -% if override_qual is true.} -%\Expected{Returns CANNOT_OVERRIDE.} -%} - - -\section{ovsec_kadm_chpass_principal_util} - -Rerun all the tests listed for ovsec_kadm_chpass_principal above in -Section \ref{ovseckadmchpassprincipal}. Verify that they succeed -and fail in the same circumstances. Also verify that in each failure -case, the error message returned in msg_ret is as specified in the -functional specification. - -Also, run the following additional tests. - -\numtest{1}{ -\Reason{Null msg_ret is rejected.} -} - -\numtest{2}{ -\Priority{High} -\Reason{New password is put into pw_ret, when it's prompted for.} -} - -\numtest{3}{ -\Priority{High} -Reason{New password is put into pw_ret, when it's supplied by the - caller.} -} - -\numtest{4}{ -\Priority{High} -\Reason{Successful invocation when pw_ret is null.} -} - - - -\section{ovsec_kadm_randkey_principal} - -\subsection{TOOSOON enforcement tests} - -This test should be run a number of times, as indicated in the table -following it. The table also indicates the expected result of each -run of the test. - -\test{ -\Reason{Change key when now - last_pwd_change $<$ pw_min_life.} -} - -\subsubsection{List of parameter settings} - -\begin{tabular}{llllll} -Number & Modify Access? & Own Key? & Service & Pass/Fail \\ \hline -1 & No & Yes & ADMIN & fail \\ -3 & No & Yes & CHANGEPW & fail \\ -5 & No & No & ADMIN & fail \\ -7 & No & No & CHANGEPW & fail \\ -9 & Yes & Yes & ADMIN & fail \\ -11 & Yes & Yes & CHANGEPW & fail \\ -13 & Yes & No & ADMIN & fail \\ -15 & Yes & No & CHANGEPW & fail \\ -\end{tabular} - -\subsection{Other tests} - -\numtest{17}{ -\Reason{Fails if database not initialized.} -} - -\numtest{18}{ -\Reason{Fails for non-existent principal.} -} - -\numtest{19}{ -\Reason{Fails for null keyblock pointer.} -} - -\numtest{20}{ -\Priority{High} -\Reason{Pw_expiration is set to now + max_pw_life if policy exists and - has non-zero max_pw_life.} -} - -\numtest{21}{ -\Priority{High} -\Reason{Pw_expiration is set to 0 if policy exists and has zero - max_pw_life.} -} - -\numtest{22}{ -\Priority{High} -\Reason{Pw_expiration is set to 0 if no policy.} -} - -\numtest{23}{ -\Priority{High} -\Reason{KRB5_KDC_REQUIRES_PWCHANGE bit is cleared when key is - successfully changed.} -} - -\numtest{24}{ -\Priority{High} -\Reason{Fails for user with no access bits, on other's password.} -} - -\numtest{25}{ -\Priority{High} -\Reason{Fails for user with ``get'' but not ``modify'' access, on - other's password.} -} - -\numtest{26}{ -\Reason{Fails for user with ``delete'' but not ``modify'' access, on - other's password.} -} - -\numtest{27}{ -\Reason{Fails for user with ``add'' but not ``modify'' access, on - other's password.} -} - -\numtest{28}{ -\Reason{Succeeds for user with ``get'' and ``modify'' access, on - other's password.} -} - -\numtest{28.5}{ -\Priority{High} -\Reason{Succeeds for user with ``modify'' but not ``get'' access, on - other's password.} -} - -\numtest{29}{ -\Reason{The new key that's assigned is truly random. XXX not sure how - to test this.} -} - - - -\section{ovsec_kadm_get_principal} - -\numtest{1}{ -\Reason{Fails for null ent.} -} - -\numtest{2}{ -\Reason{Fails for non-existent principal.} -} - -\numtest{3}{ -\Priority{High} -\Reason{Fails for user with no access bits, retrieving other principal.} -} - -\numtest{4}{ -\Priority{High} -\Reason{Fails for user with ``add'' but not ``get'', getting principal - other than his own, using ADMIN_SERVICE.} -} - -\numtest{5}{ -\Reason{Fails for user with ``modify'' but not ``get'', getting - principal other than his own, using ADMIN_SERVICE.} -} - -\numtest{6}{ -\Reason{Fails for user with ``delete'' but not ``get'', getting - principal other than his own, using ADMIN_SERVICE.} -} - -\numtest{7}{ -\Reason{Fails for user with ``delete'' but not ``get'', getting - principal other than his own, using CHANGEPW_SERVICE.} -} - -\numtest{8}{ -\Priority{High} -\Reason{Fails for user with ``get'', getting principal other than his - own, using CHANGEPW_SERVICE.} -} - -\numtest{9}{ -\Priority{High} -\Reason{Succeeds for user without ``get'', retrieving self, using - ADMIN_SERVICE.} -} - -\numtest{10}{ -\Reason{Succeeds for user without ``get'', retrieving self, using - CHANGEPW_SERVICE.} -} - -\numtest{11}{ -\Reason{Succeeds for user with ``get'', retrieving self, using - ADMIN_SERVICE.} -} - -\numtest{12}{ -\Reason{Succeeds for user with ``get'', retrieving self, using - CHANGEPW_SERVICE.} -} - -\numtest{13}{ -\Priority{High} -\Reason{Succeeds for user with ``get'', retrieving other user, using - ADMIN_SERVICE.} -} - -\numtest{14}{ -\Reason{Succeeds for user with ``get'' and ``modify'', retrieving - other principal, using ADMIN_SERVICE.} -} - - - -\section{ovsec_kadm_create_policy} - -\numtest{1}{ -\Reason{Fails for mask with undefined bit set.} -} - -\numtest{2}{ -\Priority{High} -\Reason{Fails if caller connected with CHANGEPW_SERVICE.} -} - -\numtest{3}{ -\Reason{Fails for mask without POLICY bit set.} -} - -\numtest{4}{ -\Reason{Fails for mask with REF_COUNT bit set.} -} - -\numtest{5}{ -\Reason{Fails for invalid policy name.} -} - -\numtest{6}{ -\Priority{High} -\Reason{Fails for existing policy name.} -} - -\numtest{7}{ -\Reason{Fails for null policy name.} -} - -\numtest{8}{ -\Priority{High} -\Reason{Fails for empty-string policy name.} -} - -\numtest{9}{ -\Priority{High} -\Reason{Accepts 0 for pw_min_life.} -} - -\numtest{10}{ -\Priority{High} -\Reason{Accepts non-zero for pw_min_life.} -} - -\numtest{11}{ -\Priority{High} -\Reason{Accepts 0 for pw_max_life.} -} - -\numtest{12}{ -\Priority{High} -\Reason{Accepts non-zero for pw_max_life.} -} - -\numtest{13}{ -\Priority{High} -\Reason{Rejects 0 for pw_min_length.} -} - -\numtest{14}{ -\Priority{High} -\Reason{Accepts non-zero for pw_min_length.} -} - -\numtest{15}{ -\Priority{High} -\Reason{Rejects 0 for pw_min_classes.} -} - -\numtest{16}{ -\Priority{High} -\Reason{Accepts 1 for pw_min_classes.} -} - -\numtest{17}{ -\Priority{High} -\Reason{Accepts 4 for pw_min_classes.} -} - -\numtest{18}{ -\Priority{High} -\Reason{Rejects 5 for pw_min_classes.} -} - -\numtest{19}{ -\Priority{High} -\Reason{Rejects 0 for pw_history_num.} -} - -\numtest{20}{ -\Priority{High} -\Reason{Accepts 1 for pw_history_num.} -} - -\numtest{21}{ -\Priority{High} -\Reason{Accepts 10 for pw_history_num.} -} - -\numtest{21.5}{ -\Reason{Rejects 11 for pw_history_num.} -} - -\numtest{22}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -} - -\numtest{23}{ -\Priority{High} -\Reason{Fails for user with ``get'' but not ``add''.} -} - -\numtest{24}{ -\Reason{Fails for user with ``modify'' but not ``add.''} -} - -\numtest{25}{ -\Reason{Fails for user with ``delete'' but not ``add.''} -} - -\numtest{26}{ -\Priority{High} -\Reason{Succeeds for user with ``add.''} -} - -\numtest{27}{ -\Reason{Succeeds for user with ``get'' and ``add.''} -} - -\numtest{28}{ -\Reason{Rejects null policy argument.} -} - -\numtest{29}{ -\Reason{Rejects pw_min_life greater than pw_max_life.} -} - - - -\section{ovsec_kadm_delete_policy} - -\numtest{1}{ -\Reason{Fails for null policy name.} -} - -\numtest{2}{ -\Priority{High} -\Reason{Fails for empty-string policy name.} -} - -\numtest{3}{ -\Reason{Fails for non-existent policy name.} -} - -\numtest{4}{ -\Reason{Fails for bad policy name.} -} - -\numtest{5}{ -\Priority{High} -\Reason{Fails if caller connected with CHANGEPW_SERVICE.} -} - -\numtest{6}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -} - -\numtest{7}{ -\Priority{High} -\Reason{Fails for user with ``add'' but not ``delete''.} -} - -\numtest{8}{ -\Reason{Fails for user with ``modify'' but not ``delete''.} -} - -\numtest{9}{ -\Reason{Fails for user with ``get'' but not ``delete.''} -} - -\numtest{10}{ -\Priority{High} -\Reason{Succeeds for user with only ``delete''.} -} - -\numtest{11}{ -\Reason{Succeeds for user with ``delete'' and ``add''.} -} - -\numtest{12}{ -\Priority{High} -\Reason{Fails for policy with non-zero reference count.} -} - - - -\section{ovsec_kadm_modify_policy} - -\numtest{1}{ -\Reason{Fails for mask with undefined bit set.} -} - -\numtest{2}{ -\Priority{High} -\Reason{Fails if caller connected with CHANGEPW_SERVICE.} -} - -\numtest{3}{ -\Reason{Fails for mask with POLICY bit set.} -} - -\numtest{4}{ -\Reason{Fails for mask with REF_COUNT bit set.} -} - -\numtest{5}{ -\Reason{Fails for invalid policy name.} -} - -\numtest{6}{ -\Reason{Fails for non-existent policy name.} -} - -\numtest{7}{ -\Reason{Fails for null policy name.} -} - -\numtest{8}{ -\Priority{High} -\Reason{Fails for empty-string policy name.} -} - -\numtest{9}{ -\Priority{High} -\Reason{Accepts 0 for pw_min_life.} -} - -\numtest{10}{ -\Priority{High} -\Reason{Accepts non-zero for pw_min_life.} -} - -\numtest{11}{ -\Priority{High} -\Reason{Accepts 0 for pw_max_life.} -} - -\numtest{12}{ -\Priority{High} -\Reason{Accepts non-zero for pw_max_life.} -} - -\numtest{13}{ -\Priority{High} -\Reason{Accepts 0 for pw_min_length.} -} - -\numtest{14}{ -\Priority{High} -\Reason{Accepts non-zero for pw_min_length.} -} - -\numtest{15}{ -\Priority{High} -\Reason{Rejects 0 for pw_min_classes.} -} - -\numtest{16}{ -\Priority{High} -\Reason{Accepts 1 for pw_min_classes.} -} - -\numtest{17}{ -\Priority{High} -\Reason{Accepts 4 for pw_min_classes.} -} - -\numtest{18}{ -\Priority{High} -\Reason{Rejects 5 for pw_min_classes.} -} - -\numtest{19}{ -\Priority{High} -\Reason{Rejects 0 for pw_history_num.} -} - -\numtest{20}{ -\Priority{High} -\Reason{Accepts 1 for pw_history_num.} -} - -\numtest{21}{ -\Priority{High} -\Reason{Accepts 10 for pw_history_num.} -} - -\numtest{22}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -} - -\numtest{23}{ -\Priority{High} -\Reason{Fails for user with ``get'' but not ``modify''.} -} - -\numtest{24}{ -\Reason{Fails for user with ``add'' but not ``modify.''} -} - -\numtest{25}{ -\Reason{Fails for user with ``delete'' but not ``modify.''} -} - -\numtest{26}{ -\Priority{High} -\Reason{Succeeds for user with ``modify.''} -} - -\numtest{27}{ -\Reason{Succeeds for user with ``get'' and ``modify.''} -} - -\numtest{28}{ -\Reason{Rejects null policy argument.} -} - -\numtest{29}{ -\Reason{Rejects change which makes pw_min_life greater than - pw_max_life.} -} - -\section{ovsec_kadm_get_policy} - -\numtest{1}{ -\Reason{Fails for null policy.} -} - -\numtest{2}{ -\Reason{Fails for invalid policy name.} -} - -\numtest{3}{ -\Priority{High} -\Reason{Fails for empty-string policy name.} -} - -\numtest{4}{ -\Reason{Fails for non-existent policy name.} -} - -\numtest{5}{ -\Reason{Fails for null ent.} -} - -\numtest{6}{ -\Priority{High} -\Reason{Fails for user with no access bits trying to get other's - policy, using ADMIN_SERVICE.} -} - -\numtest{7}{ -\Priority{High} -\Reason{Fails for user with ``add'' but not ``get'' trying to get - other's policy, using ADMIN_SERVICE.} -} - -\numtest{8}{ -\Reason{Fails for user with ``modify'' but not ``get'' trying to get - other's policy, using ADMIN_SERVICE.} -} - -\numtest{9}{ -\Reason{Fails for user with ``delete'' but not ``get'' trying to get - other's policy, using ADMIN_SERVICE.} -} - -\numtest{10}{ -\Reason{Fails for user with ``delete'' but not ``get'' trying to get - other's policy, using CHANGEPW_SERVICE.} -} - -\numtest{11}{ -\Priority{High} -\Reason{Succeeds for user with only ``get'', trying to get own policy, - using ADMIN_SERVICE.} -} - -\numtest{12}{ -\Priority{High} -\Reason{Succeeds for user with only ``get'', trying to get own policy, - using CHANGEPW_SERVICE.} -} - -\numtest{13}{ -\Reason{Succeeds for user with ``add'' and ``get'', trying to get own - policy, using ADMIN_SERVICE.} -} - -\numtest{14}{ -\Reason{Succeeds for user with ``add'' and ``get'', trying to get own - policy, using CHANGEPW_SERVICE.} -} - -\numtest{15}{ -\Reason{Succeeds for user without ``get'', trying to get own policy, - using ADMIN_SERVICE.} -} - -\numtest{16}{ -\Priority{High} -\Reason{Succeeds for user without ``get'', trying to get own policy, - using CHANGEPW_SERVICE.} -} - -\numtest{17}{ -\Priority{High} -\Reason{Succeeds for user with ``get'', trying to get other's policy, - using ADMIN_SERVICE.} -} - -\numtest{18}{ -\Priority{High} -\Reason{Fails for user with ``get'', trying to get other's policy, - using CHANGEPW_SERVICE.} -} - -\numtest{19}{ -\Reason{Succeeds for user with ``modify'' and ``get'', trying to get - other's policy, using ADMIN_SERVICE.} -} - -\numtest{20}{ -\Reason{Fails for user with ``modify'' and ``get'', trying to get - other's policy, using CHANGEPW_SERVICE.} -} - - - -\section{ovsec_kadm_free_principal_ent} - -In addition to the tests listed here, a memory-leak detector such as -TestCenter, Purify or dbmalloc should be used to verify that the -memory freed by this function is really freed. - -\numtest{1}{ -\Reason{Null princ succeeds.} -} - -\numtest{2}{ -\Reason{Non-null princ succeeds.} -} - - -\section{ovsec_kadm_free_policy_ent} - -In addition to the tests listed here, a memory-leak detector such as -TestCenter, Purify or dbmalloc should be used to verify that the -memory freed by this function is really freed. - -\numtest{1}{ -\Reason{Null policy succeeds.} -} - -\numtest{2}{ -\Reason{Non-null policy succeeds.} -} - - - -\section{ovsec_kadm_get_privs} - -\numtest{1}{ -\Reason{Fails for null pointer argument.} -} - -This test should be run with the 16 possible combinations of access -bits (since there are 4 access bits, there are $2^4 = 16$ possible -combinations of them): - -\numtest{2}{ -\Priority{High} -\Reason{Returns correct bit mask for access bits of user.} -\Conditions{RPC} -} - -This test should be run locally: - -\numtest{3}{ -\Priority{High} -\Reason{Returns 0x0f.} -\Conditions{local} -} - -\end{document} -- 2.26.2