From 6df379c29d553a1e73037b24d92912f9280305a5 Mon Sep 17 00:00:00 2001 From: John Kohl Date: Wed, 30 May 1990 19:16:12 +0000 Subject: [PATCH] *** empty log message *** git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@970 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/api/ccache.tex | 5 ++ doc/api/functions.sty | 44 +++++++++++++ doc/api/keytab.tex | 3 + doc/api/krb5.tex | 43 ++++++++++++ doc/api/libdes.tex | 38 +++++++++++ doc/api/libos.tex | 2 + doc/api/library.tex | 48 ++++++++++++++ doc/api/rcache.tex | 4 ++ doc/implement/ccache-i.tex | 5 ++ doc/implement/crc-32-i.tex | 19 ++++++ doc/implement/encrypt-i.tex | 127 ++++++++++++++++++++++++++++++++++++ doc/implement/functions.sty | 44 +++++++++++++ doc/implement/implement.tex | 48 ++++++++++++++ doc/implement/kdb-i.tex | 3 + doc/implement/keytab-i.tex | 3 + doc/implement/libos-i.tex | 2 + doc/implement/rcache-i.tex | 4 ++ 17 files changed, 442 insertions(+) create mode 100644 doc/api/ccache.tex create mode 100644 doc/api/functions.sty create mode 100644 doc/api/keytab.tex create mode 100644 doc/api/krb5.tex create mode 100644 doc/api/libdes.tex create mode 100644 doc/api/libos.tex create mode 100644 doc/api/library.tex create mode 100644 doc/api/rcache.tex create mode 100644 doc/implement/ccache-i.tex create mode 100644 doc/implement/crc-32-i.tex create mode 100644 doc/implement/encrypt-i.tex create mode 100644 doc/implement/functions.sty create mode 100644 doc/implement/implement.tex create mode 100644 doc/implement/kdb-i.tex create mode 100644 doc/implement/keytab-i.tex create mode 100644 doc/implement/libos-i.tex create mode 100644 doc/implement/rcache-i.tex 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. + -- 2.26.2