17 files changed, 442 insertions, 0 deletions
diff --git a/doc/api/ccache.tex b/doc/api/ccache.tex
new file mode 100644
index 000000000..33addc51d
--- /dev/null
+++ b/doc/api/ccache.tex
@@ -0,0 +1,5 @@
+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.
+
diff --git a/doc/api/functions.sty b/doc/api/functions.sty
new file mode 100644
index 000000000..c30c730b2
--- /dev/null
+++ b/doc/api/functions.sty
@@ -0,0 +1,44 @@
+%
+% definitions related to function declarations/displays
+%
+\ifx\undefined\@psfonts
+\def\argfont{\tt}
+\else
+\font\argfont = c-bol
+\hyphenchar\argfont = -1
+\fi
+\newcount\argc@ount
+% funcdecl is used as \begin{funcdecl}[funcname]{return type}{firstline}
+\def\funcdecl{\makeunderletter\@moreindex}
+%
+% this isn't quite right; we need to have \@morefuncdecl{#1} get #1
+% expanded and then re-scanned by TeX to reassign catcodes to _'s in it.
+%
+\def\@moreindex[#1]{\index{#1}\makeunderactive\@morefuncdecl{#1}}
+\def\@morefuncdecl#1#2#3{\argc@ount=0\begin{tabbing}
+#2 \\
+{\bf #1}(\= \+ #3%\doindex%
+}
+\def\endfuncdecl{)
+\end{tabbing}
+}
+\newcommand{\docomm@}{\ifnum\argc@ount >0, \\\fi}
+\newcommand{\funcvoid}{}
+\newcommand{\funcin}{\docomm@\argc@ount=0{\it /* IN */}\\}
+\newcommand{\funcinout}{\docomm@\argc@ount=0{\it /* INOUT */}\\}
+\newcommand{\funcout}{\docomm@\argc@ount=0{\it /* OUT */}\\}
+\newcommand{\funcarg}[2]{\docomm@#1 {\argfont #2}\advance\argc@ount by1}
+\newcommand{\funcparam}[1]{{\argfont #1}}
+\newcommand{\funcname}[1]{{\bf #1}()}
+\newcommand{\libname}[1]{{\argfont #1}}
+\newcommand{\ptsto}{->\discretionary{}{}{}}
+\newcommand{\datatype}[1]{{\bf #1}}
+
+
+
+
+
+
+
+
+
diff --git a/doc/api/keytab.tex b/doc/api/keytab.tex
new file mode 100644
index 000000000..cf68d2ba3
--- /dev/null
+++ b/doc/api/keytab.tex
@@ -0,0 +1,3 @@
+The key table functions deal with storing and retrieving service keys
+for use by unattended services which participate in authentication exchanges.
+
diff --git a/doc/api/krb5.tex b/doc/api/krb5.tex
new file mode 100644
index 000000000..51dbe3504
--- /dev/null
+++ b/doc/api/krb5.tex
@@ -0,0 +1,43 @@
+The main functions deal with the nitty-gritty details: verifying
+tickets, creating authenticators, and the like.
+
+\begin{funcdecl}[krb5_encode_kdc_rep]{krb5_error_code}{\funcin}
+\funcarg{krb5_msgtype}{type}
+\funcarg{krb5_enc_kdc_rep_part *}{encpart}
+\funcarg{krb5_keyblock *}{client_key}
+\funcinout
+\funcarg{krb5_kdc_rep *}{dec_rep}
+\funcout
+\funcarg{krb5_data *}{enc_rep}
+\end{funcdecl}
+
+Takes KDC rep parts in \funcparam{*rep} and \funcparam{*encpart}, and
+formats it into \funcparam{*enc_rep}, using message type \funcparam{type}
+and encryption key \funcparam{client_key} and encryption type
+\funcparam{dec_rep{\ptsto}etype}.
+
+\funcparam{enc_rep{\ptsto}data} will point to  allocated storage upon
+non-error return; the caller should free it when finished.
+
+Returns system errors.
+
+\begin{funcdecl}[krb5_decode_kdc_rep]{krb5_error_code}{\funcin}
+\funcarg{krb5_data *}{enc_rep}
+\funcarg{krb5_keyblock *}{key}
+\funcarg{krb5_enctype}{etype}
+\funcout
+\funcarg{krb5_kdc_rep **}{dec_rep}
+\end{funcdecl}
+
+Takes a KDC_REP message and decrypts encrypted part using
+\funcparam{etype} and \funcparam{*key}, putting result in \funcparam{*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.
+
diff --git a/doc/api/libdes.tex b/doc/api/libdes.tex
new file mode 100644
index 000000000..d72482e91
--- /dev/null
+++ b/doc/api/libdes.tex
@@ -0,0 +1,38 @@
+\documentstyle[newcen,fixunder,functions,twoside]{article}
+\setlength{\oddsidemargin}{0.25in}
+\setlength{\evensidemargin}{-0.25in}
+\setlength{\topmargin}{-.5in}
+\setlength{\textheight}{9in}
+\setlength{\parskip}{.1in}
+\setlength{\parindent}{2em}
+\setlength{\textwidth}{6.25in}
+
+\pagestyle{headings}
+\begin{document}
+\begin{center}
+{\Huge Kerberos V5 Data Encryption Standard library} \\
+{\Large DRAFT}
+\end{center}
+\section{DES functions}
+The DES functions conform to the encryption interface required by the
+Kerberos version 5 library, and provide an encryption mechanism based on
+the DES Cipher-block chaining mode (CBC), with the addition of a
+cyclical redundancy check (CRC-32) for integrity checking upon
+decryption.
+
+The functions have the same signatures as those described by the main
+library document; the names are:
+{\obeylines
+\funcname{mit_des_encrypt_func}
+\funcname{mit_des_decrypt_func}
+\funcname{mit_des_process_key}
+\funcname{mit_des_finish_key}
+\funcname{mit_des_string_to_key}
+\funcname{mit_des_init_random_key}
+\funcname{mit_des_finish_random_key}
+\funcname{mit_des_random_key}
+}
+The \datatype{krb5_cryptosystem_entry} for this cryptosystem is
+\libname{mit_des_cryptosystem_entry}.
+
+\end{document}
diff --git a/doc/api/libos.tex b/doc/api/libos.tex
new file mode 100644
index 000000000..81d40fbbf
--- /dev/null
+++ b/doc/api/libos.tex
@@ -0,0 +1,2 @@
+The operating-system specific functions provide an interface between the
+other parts of the {\tt libkrb5.a} libraries and the operating system.
diff --git a/doc/api/library.tex b/doc/api/library.tex
new file mode 100644
index 000000000..4001d9913
--- /dev/null
+++ b/doc/api/library.tex
@@ -0,0 +1,48 @@
+\documentstyle[newcen,fixunder,functions,twoside]{article}
+\setlength{\oddsidemargin}{0.25in}
+\setlength{\evensidemargin}{-0.25in}
+\setlength{\topmargin}{-.5in}
+\setlength{\textheight}{9in}
+\setlength{\parskip}{.1in}
+\setlength{\parindent}{2em}
+\setlength{\textwidth}{6.25in}
+\makeindex
+\pagestyle{headings}
+\begin{document}
+\begin{center}
+{\Huge Kerberos V5 application programming library} \\
+{\Large DRAFT}
+\end{center}
+\section{libkrb5.a functions}
+This section describes the functions provided in the {\tt libkrb5.a}
+library.  The library is built from several pieces, mostly for convenience in
+programming, maintenance, and porting.
+\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}
+
+\subsection{Operating-system specific functions}
+\input{libos.tex}
+
+\section{CRC-32 checksum functions}
+\input{crc-32.tex}
+
+\section{Principal database functions}
+
+\input{kdb.tex}
+
+\section{Encryption system interface}
+\input{encrypt.tex}
+
+\appendix
+\cleardoublepage
+\input{\jobname.ind}
+\end{document}
diff --git a/doc/api/rcache.tex b/doc/api/rcache.tex
new file mode 100644
index 000000000..06cf1d98c
--- /dev/null
+++ b/doc/api/rcache.tex
@@ -0,0 +1,4 @@
+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.
+
diff --git a/doc/implement/ccache-i.tex b/doc/implement/ccache-i.tex
new file mode 100644
index 000000000..33addc51d
--- /dev/null
+++ b/doc/implement/ccache-i.tex
@@ -0,0 +1,5 @@
+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.
+
diff --git a/doc/implement/crc-32-i.tex b/doc/implement/crc-32-i.tex
new file mode 100644
index 000000000..66d81566f
--- /dev/null
+++ b/doc/implement/crc-32-i.tex
@@ -0,0 +1,19 @@
+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{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
new file mode 100644
index 000000000..5fad68983
--- /dev/null
+++ b/doc/implement/encrypt-i.tex
@@ -0,0 +1,127 @@
+Kerberos v5 has the ability to use multiple encryption systems.  Any
+encryption system which desires to link with and be usable from the MIT
+Kerberos v5 implementation must implement at least this interface:
+
+\subsection{Functional interface}
+
+\begin{funcdecl}[encrypt_func]{krb5_error_code}{\funcvoid}
+\funcarg{const krb5_pointer}{in}
+\funcarg{krb5_pointer}{out}
+\funcarg{const size_t}{size}
+\funcarg{krb5_encrypt_block *}{eblock}
+\funcarg{krb5_pointer}{ivec}
+\end{funcdecl}
+Encrypts \funcparam{size} bytes at \funcparam{in}, storing result in
+\funcparam{out}.  \funcparam{eblock} points to an encrypt block which
+has been initialized by \funcname{process_key}.
+
+\funcparam{in} must include sufficient space beyond the \funcparam{size}
+bytes of input data to hold pad and redundancy check bytes; the macro
+\funcname{krb5_encrypt_size} can be used to compute this size.
+
+\funcparam{out} must be preallocated by the caller to contain sufficient
+storage to hold the output; the macro \funcname{krb5_encrypt_size} can
+be used to compute this size.
+
+\funcparam{ivec} points to an initial vector/seed to be used in the encryption.
+If null, the cryptosystem may choose an appropriate initialization vector.
+
+Returns errors.
+
+\begin{funcdecl}[decrypt_func]{krb5_error_code}{\funcvoid}
+\funcarg{const krb5_pointer}{in}
+\funcarg{krb5_pointer}{out}
+\funcarg{const size_t}{size}
+\funcarg{krb5_encrypt_block *}{eblock}
+\funcarg{krb5_pointer}{ivec}
+\end{funcdecl}
+Decrypts \funcparam{size} bytes at \funcparam{in}, storing result in
+\funcparam{out}.
+\funcparam{eblock} points to an encrypt block which has been initialized
+by \funcname{process_key}.
+
+\funcparam{size} must be a multiple of the encryption block size.
+
+\funcparam{out} must be preallocated by the caller to contain sufficient
+storage to hold the output; this is guaranteed to be no more than
+the input size.
+
+\funcparam{ivec} points to an initial vector/seed to be used in the decryption.
+If null, the cryptosystem may choose an appropriate ivec.
+
+Returns errors.
+
+\begin{funcdecl}[process_key]{krb5_error_code}{\funcvoid}
+\funcarg{krb5_encrypt_block *}{eblock}
+\funcarg{krb5_keyblock *}{keyblock}
+\end{funcdecl}
+Does any necessary key preprocessing (such as computing key
+schedules for DES).
+\funcparam{eblock{\ptsto}crypto_entry} must be set by the caller; the
+other elements of \funcparam{eblock} are to be assigned by this function.
+[In particular, \funcparam{eblock{\ptsto}key} must be set by this
+function if the key is needed in raw form by the encryption routine.]
+
+The caller may not move or reallocate \funcparam{keyblock} before calling
+\funcname{finish_key} on \funcparam{eblock}.
+
+Returns errors.
+
+\begin{funcdecl}[finish_key]{krb5_error_code}{\funcvoid}
+\funcarg{krb5_encrypt_block *}{eblock}
+\end{funcdecl}
+Does any necessary clean-up on \funcparam{eblock} (such as releasing
+resources held by \funcparam{eblock{\ptsto}priv}.
+
+Returns errors.
+
+\begin{funcdecl}[string_to_key]{krb5_error_code}{\funcvoid}
+\funcarg{krb5_keytype}{keytype}
+\funcarg{krb5_keyblock *}{keyblock}
+\funcarg{krb5_data *}{data}
+\funcarg{krb5_principal}{princ}
+\end{funcdecl}
+Converts the string pointed to by \funcparam{data} into an encryption key
+of type \funcparam{keytype}.  \funcparam{*keyblock} is filled in with
+the key info; in particular, \funcparam{keyblock{\ptsto}contents} is to
+be set to allocated storage. It is the responsibility of the caller to
+release this storage when the generated key no longer needed.
+
+The routine may use \funcparam{princ} to seed or alter the conversion
+algorithm.
+
+If the particular function called does not know how to make a
+key of type \funcparam{keytype}, an error may be returned.
+
+Returns errors.
+
+\begin{funcdecl}[init_random_key]{krb5_error_code}{\funcvoid}
+\funcarg{krb5_keyblock *}{seedblock}
+\funcarg{krb5_pointer *}{seed}
+\end{funcdecl}
+Initialize the random key generator using the encryption key
+\funcparam{seedblock} and allocating private sequence information, filling
+in \funcparam{*seed} with the address of such information.
+\funcparam{*seed} is to be passed to \funcname{random_key} to provide
+sequence information.
+
+\begin{funcdecl}[finish_random_key]{krb5_error_code}{\funcvoid}
+\funcarg{krb5_pointer}{seed}
+\end{funcdecl}
+Free any resources held by \funcparam{seed} and assigned by
+\funcname{init_random_key}. 
+
+\begin{funcdecl}[random_key]{krb5_error_code}{\funcvoid}
+\funcarg{krb5_pointer}{seed}
+\funcarg{krb5_keyblock **}{keyblock}
+\end{funcdecl}
+Generate a random encryption key, allocating storage for it and
+filling in the keyblock address in \funcparam{*keyblock}.
+When the caller has finished using the keyblock, he should call
+\funcname{krb5_free_keyblock} to release its storage.
+
+\subsection{Other data elements}
+In addition to the above listed function entry points, each encryption
+system should have an entry in \libname{krb5_cs_table_entry} 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/functions.sty b/doc/implement/functions.sty
new file mode 100644
index 000000000..c30c730b2
--- /dev/null
+++ b/doc/implement/functions.sty
@@ -0,0 +1,44 @@
+%
+% definitions related to function declarations/displays
+%
+\ifx\undefined\@psfonts
+\def\argfont{\tt}
+\else
+\font\argfont = c-bol
+\hyphenchar\argfont = -1
+\fi
+\newcount\argc@ount
+% funcdecl is used as \begin{funcdecl}[funcname]{return type}{firstline}
+\def\funcdecl{\makeunderletter\@moreindex}
+%
+% this isn't quite right; we need to have \@morefuncdecl{#1} get #1
+% expanded and then re-scanned by TeX to reassign catcodes to _'s in it.
+%
+\def\@moreindex[#1]{\index{#1}\makeunderactive\@morefuncdecl{#1}}
+\def\@morefuncdecl#1#2#3{\argc@ount=0\begin{tabbing}
+#2 \\
+{\bf #1}(\= \+ #3%\doindex%
+}
+\def\endfuncdecl{)
+\end{tabbing}
+}
+\newcommand{\docomm@}{\ifnum\argc@ount >0, \\\fi}
+\newcommand{\funcvoid}{}
+\newcommand{\funcin}{\docomm@\argc@ount=0{\it /* IN */}\\}
+\newcommand{\funcinout}{\docomm@\argc@ount=0{\it /* INOUT */}\\}
+\newcommand{\funcout}{\docomm@\argc@ount=0{\it /* OUT */}\\}
+\newcommand{\funcarg}[2]{\docomm@#1 {\argfont #2}\advance\argc@ount by1}
+\newcommand{\funcparam}[1]{{\argfont #1}}
+\newcommand{\funcname}[1]{{\bf #1}()}
+\newcommand{\libname}[1]{{\argfont #1}}
+\newcommand{\ptsto}{->\discretionary{}{}{}}
+\newcommand{\datatype}[1]{{\bf #1}}
+
+
+
+
+
+
+
+
+
diff --git a/doc/implement/implement.tex b/doc/implement/implement.tex
new file mode 100644
index 000000000..4001d9913
--- /dev/null
+++ b/doc/implement/implement.tex
@@ -0,0 +1,48 @@
+\documentstyle[newcen,fixunder,functions,twoside]{article}
+\setlength{\oddsidemargin}{0.25in}
+\setlength{\evensidemargin}{-0.25in}
+\setlength{\topmargin}{-.5in}
+\setlength{\textheight}{9in}
+\setlength{\parskip}{.1in}
+\setlength{\parindent}{2em}
+\setlength{\textwidth}{6.25in}
+\makeindex
+\pagestyle{headings}
+\begin{document}
+\begin{center}
+{\Huge Kerberos V5 application programming library} \\
+{\Large DRAFT}
+\end{center}
+\section{libkrb5.a functions}
+This section describes the functions provided in the {\tt libkrb5.a}
+library.  The library is built from several pieces, mostly for convenience in
+programming, maintenance, and porting.
+\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}
+
+\subsection{Operating-system specific functions}
+\input{libos.tex}
+
+\section{CRC-32 checksum functions}
+\input{crc-32.tex}
+
+\section{Principal database functions}
+
+\input{kdb.tex}
+
+\section{Encryption system interface}
+\input{encrypt.tex}
+
+\appendix
+\cleardoublepage
+\input{\jobname.ind}
+\end{document}
diff --git a/doc/implement/kdb-i.tex b/doc/implement/kdb-i.tex
new file mode 100644
index 000000000..1dd7f3ea5
--- /dev/null
+++ b/doc/implement/kdb-i.tex
@@ -0,0 +1,3 @@
+The \libname{libkdb.a} library provides a principal database interface
+to be used by the Key Distribution center and other database
+manipulation tools.
diff --git a/doc/implement/keytab-i.tex b/doc/implement/keytab-i.tex
new file mode 100644
index 000000000..cf68d2ba3
--- /dev/null
+++ b/doc/implement/keytab-i.tex
@@ -0,0 +1,3 @@
+The key table functions deal with storing and retrieving service keys
+for use by unattended services which participate in authentication exchanges.
+
diff --git a/doc/implement/libos-i.tex b/doc/implement/libos-i.tex
new file mode 100644
index 000000000..81d40fbbf
--- /dev/null
+++ b/doc/implement/libos-i.tex
@@ -0,0 +1,2 @@
+The operating-system specific functions provide an interface between the
+other parts of the {\tt libkrb5.a} libraries and the operating system.
diff --git a/doc/implement/rcache-i.tex b/doc/implement/rcache-i.tex
new file mode 100644
index 000000000..06cf1d98c
--- /dev/null
+++ b/doc/implement/rcache-i.tex
@@ -0,0 +1,4 @@
+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.
+