.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
+LIBTEX= library.tex intro.tex tables.tex errors.tex krb5.tex ccache.tex \
+ rcache.tex keytab.tex libos.tex library.ind
DESTEX= libdes.tex
(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}{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}.
-\begin{funcdecl}{krb5_cc_resolve_internal}{krb5_error_code}{\funcout}
+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}
-\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}
+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}
-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.
+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}).
\begin{funcdecl}{krb5_cc_initialize}{krb5_error_code}{\funcinout}
\funcarg{krb5_ccache}{id}
\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}.
flags are defined in {\tt <krb5/ccache.h>}.
-\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}).
-
--- /dev/null
+\subsection{error_table krb5}
+
+% $Source$
+% $Author$
+
+The Kerberos v5 library error code table follows.
+Protocol error codes are ERROR_TABLE_BASE_krb5 + the protocol error
+code number. Other error codes start at ERROR_TABLE_BASE_krb5 + 128.
+
+\begin{small}
+\begin{tabular}{ll}
+{\sc krb5kdc_err_none }& No error \\
+{\sc krb5kdc_err_name_exp }& Client's entry in database has expired \\
+{\sc krb5kdc_err_service_exp }& Server's entry in database has expired \\
+{\sc krb5kdc_err_bad_pvno }& Requested protocol version not supported \\
+{\sc krb5kdc_err_c_old_mast_kvno }& Client's key is encrypted in an old master key \\
+{\sc krb5kdc_err_s_old_mast_kvno }& Server's key is encrypted in an old master key \\
+{\sc krb5kdc_err_c_principal_unknown }& Client not found in Kerberos database \\
+{\sc krb5kdc_err_s_principal_unknown }& Server not found in Kerberos database \\
+{\sc krb5kdc_err_principal_not_unique }& Principal has multiple entries in Kerberos database \\
+{\sc krb5kdc_err_null_key }& Client or server has a null key \\
+{\sc krb5kdc_err_cannot_postdate }& Ticket is ineligible for postdating \\
+{\sc krb5kdc_err_never_valid }& Requested effective lifetime is negative or too short \\
+{\sc krb5kdc_err_policy }& KDC policy rejects request \\
+{\sc krb5kdc_err_badoption }& KDC can't fulfill requested option \\
+{\sc krb5kdc_err_etype_nosupp }& KDC has no support for encryption type \\
+{\sc krb5kdc_err_sumtype_nosupp }& KDC has no support for checksum type \\
+{\sc krb5kdc_err_padata_type_nosupp }& KDC has no support for padata type \\
+{\sc krb5kdc_err_trtype_nosupp }& KDC has no support for transited type \\
+{\sc krb5kdc_err_client_revoked }& Clients credentials have been revoked \\
+{\sc krb5kdc_err_service_revoked }& Credentials for server have been revoked \\
+{\sc krb5kdc_err_tgt_revoked }& TGT has been revoked \\
+{\sc krb5kdc_err_client_notyet }& Client not yet valid - try again later \\
+{\sc krb5kdc_err_service_notyet }& Server not yet valid - try again later \\
+{\sc krb5kdc_err_key_exp }& Password has expired \\
+{\sc krb5kdc_preauth_failed }& Preauthentication failed \\
+
+ & \multicolumn{1}{c}{error codes 25-30 are currently placeholders} \\
+\end{tabular}
+
+\begin{tabular}{ll}
+{\sc krb5krb_ap_err_bad_integrity }& Decrypt integrity check failed \\
+{\sc krb5krb_ap_err_tkt_expired }& Ticket expired \\
+{\sc krb5krb_ap_err_tkt_nyv }& Ticket not yet valid \\
+{\sc krb5krb_ap_err_repeat }& Request is a replay \\
+{\sc krb5krb_ap_err_not_us }& The ticket isn't for us \\
+{\sc krb5krb_ap_err_badmatch }& Ticket/authenticator don't match \\
+{\sc krb5krb_ap_err_skew }& Clock skew too great \\
+{\sc krb5krb_ap_err_badaddr }& Incorrect net address \\
+{\sc krb5krb_ap_err_badversion }& Protocol version mismatch \\
+{\sc krb5krb_ap_err_msg_type }& Invalid message type \\
+{\sc krb5krb_ap_err_modified }& Message stream modified \\
+{\sc krb5krb_ap_err_badorder }& Message out of order \\
+{\sc krb5placehold_43 }& KRB5 error code 43 \\
+{\sc krb5krb_ap_err_badkeyver }& Key version is not available \\
+{\sc krb5krb_ap_err_nokey }& Service key not available \\
+{\sc krb5krb_ap_err_mut_fail }& Mutual authentication failed \\
+{\sc krb5krb_ap_err_baddirection }& Incorrect message direction \\
+{\sc krb5krb_ap_err_method }& Alternative authentication method required \\
+{\sc krb5krb_ap_err_badseq }& Incorrect sequence number in message \\
+{\sc krb5krb_ap_err_inapp_cksum }& Inappropriate type of checksum in message \\
+
+ & \multicolumn{1}{c}{error codes 51-59 are currently placeholders} \\
+
+{\sc krb5krb_err_generic }& Generic error (see e-text) \\
+{\sc krb5krb_err_field_toolong }& Field is too long for this implementation \\
+
+& \multicolumn{1}{c}{error codes 62-127 are currently placeholders} \\
+\end{tabular}
+
+\begin{tabular}{ll}
+{\sc krb5_libos_badlockflag }& Invalid flag for file lock mode \\
+{\sc krb5_libos_cantreadpwd }& Cannot read password \\
+{\sc krb5_libos_badpwdmatch }& Password mismatch \\
+{\sc krb5_libos_pwdintr }& Password read interrupted \\
+{\sc krb5_parse_illchar }& Illegal character in component name \\
+{\sc krb5_parse_malformed }& Malformed representation of principal \\
+{\sc krb5_config_cantopen }& Can't open/find configuration file \\
+{\sc krb5_config_badformat }& Improper format of configuration file \\
+{\sc krb5_config_notenufspace }& Insufficient space to return complete information \\
+{\sc krb5_badmsgtype }& Invalid message type specified for encoding \\
+{\sc krb5_cc_badname }& Credential cache name malformed \\
+{\sc krb5_cc_unknown_type }& Unknown credential cache type \\
+{\sc krb5_cc_notfound }& Matching credential not found \\
+{\sc krb5_cc_end }& End of credential cache reached \\
+{\sc krb5_no_tkt_supplied }& Request did not supply a ticket \\
+{\sc krb5krb_ap_wrong_princ }& Wrong principal in request \\
+{\sc krb5krb_ap_err_tkt_invalid }& Ticket has invalid flag set \\
+{\sc krb5_princ_nomatch }& Requested principal and ticket don't match \\
+{\sc krb5_kdcrep_modified }& KDC reply did not match expectations \\
+{\sc krb5_prog_etype_nosupp }& Program lacks support for encryption type \\
+{\sc krb5_prog_keytype_nosupp }& Program lacks support for key type \\
+{\sc krb5_wrong_etype }& Requested encryption type not used in message \\
+{\sc krb5_prog_sumtype_nosupp }& Program lacks support for checksum type \\
+{\sc krb5_realm_unknown }& Cannot find KDC for requested realm \\
+{\sc krb5_kdc_unreach }& Cannot contact any KDC for requested realm \\
+{\sc krb5_no_localname }& No local name found for principal name \\
+
+%\multicolumn{1}{c}{some of these should be combined/supplanted by system codes} \\
+\end{tabular}
+
+\begin{tabular}{ll}
+{\sc krb5_rc_type_exists }& Replay cache type is already registered \\
+{\sc krb5_rc_malloc }& No more memory to allocate (in replay cache code) \\
+{\sc krb5_rc_type_notfound }& Replay cache type is unknown \\
+{\sc krb5_rc_unknown }& Generic unknown RC error \\
+{\sc krb5_rc_replay }& Message is a replay \\
+{\sc krb5_rc_io }& Replay I/O operation failed XXX \\
+{\sc krb5_rc_noio }& Replay cache type does not support non-volatile storage \\
+{\sc krb5_rc_parse }& Replay cache name parse/format error \\
+{\sc krb5_rc_io_eof }& End-of-file on replay cache I/O \\
+{\sc krb5_rc_io_malloc }& No more memory to allocate (in replay cache I/O code)\\
+{\sc krb5_rc_io_perm }& Permission denied in replay cache code \\
+{\sc krb5_rc_io_io }& I/O error in replay cache i/o code \\
+{\sc krb5_rc_io_unknown }& Generic unknown RC/IO error \\
+{\sc krb5_rc_io_space }& Insufficient system space to store replay information \\
+{\sc krb5_trans_cantopen }& Can't open/find realm translation file \\
+{\sc krb5_trans_badformat }& Improper format of realm translation file \\
+{\sc krb5_lname_cantopen }& Can't open/find lname translation database \\
+{\sc krb5_lname_notrans }& No translation available for requested principal \\
+{\sc krb5_lname_badformat }& Improper format of translation database entry \\
+{\sc krb5_crypto_internal }& Cryptosystem internal error \\
+{\sc krb5_kt_badname }& Key table name malformed \\
+{\sc krb5_kt_unknown_type }& Unknown Key table type \\
+{\sc krb5_kt_notfound }& Key table entry not found \\
+{\sc krb5_kt_end }& End of key table reached \\
+{\sc krb5_kt_nowrite }& Cannot write to specified key table \\
+{\sc krb5_kt_ioerr }& Error writing to key table \\
+{\sc krb5_no_tkt_in_rlm }& Cannot find ticket for requested realm \\
+{\sc krb5des_bad_keypar }& DES key has bad parity \\
+{\sc krb5des_weak_key }& DES key is a weak key \\
+{\sc krb5_bad_keytype }& Keytype is incompatible with encryption type \\
+{\sc krb5_bad_keysize }& Key size is incompatible with encryption type \\
+{\sc krb5_bad_msize }& Message size is incompatible with encryption type \\
+{\sc krb5_cc_type_exists }& Credentials cache type is already registered. \\
+{\sc krb5_kt_type_exists }& Key table type is already registered. \\
+{\sc krb5_cc_io }& Credentials cache I/O operation failed XXX \\
+{\sc krb5_fcc_perm }& Credentials cache file permissions incorrect \\
+{\sc krb5_fcc_nofile }& No credentials cache file found \\
+{\sc krb5_fcc_internal }& Internal file credentials cache error \\
+{\sc krb5_cc_nomem }& No more memory to allocate (in credentials cache code) \\
+
+\end{tabular}
+
+\begin{tabular}{ll}
+& \multicolumn{1}{c}{errors for dual TGT library calls} \\
+
+{\sc krb5_invalid_flags }& Invalid KDC option combination (library internal error) \\
+{\sc krb5_no_2nd_tkt }& Request missing second ticket \\
+{\sc krb5_nocreds_supplied }& No credentials supplied to library routine \\
+
+\end{tabular}
+
+\begin{tabular}{ll}
+& \multicolumn{1}{c}{errors for sendauth and recvauth} \\
+
+{\sc krb5_sendauth_badauthvers }& Bad sendauth version was sent \\
+{\sc krb5_sendauth_badapplvers }& Bad application version was sent (via sendauth) \\
+{\sc krb5_sendauth_badresponse }& Bad response (during sendauth exchange) \\
+{\sc krb5_sendauth_rejected }& Server rejected authentication (during sendauth exchange) \\
+{\sc krb5_sendauth_mutual_failed }& Mutual authentication failed (during sendauth exchange) \\
+
+\end{tabular}
+
+\begin{tabular}{ll}
+&\multicolumn{1}{c}{errors for preauthentication} \\
+
+{\sc krb5_preauth_bad_type }& Unsupported preauthentication type \\
+{\sc krb5_preauth_no_key }& Required preauthentication key not supplied \\
+{\sc krb5_preauth_failed }& Generic preauthentication failure \\
+
+\end{tabular}
+
+\begin{tabular}{ll}
+&\multicolumn{1}{c}{version number errors} \\
+
+{\sc krb5_rcache_badvno }& Unsupported replay cache format version number \\
+{\sc krb5_ccache_badvno }& Unsupported credentials cache format version number \\
+{\sc krb5_keytab_badvno }& Unsupported key table format version number \\
+
+\end{tabular}
+
+\begin{tabular}{ll}
+&\multicolumn{1}{c}{other errors} \\
+
+{\sc krb5_prog_atype_nosupp }& Program lacks support for address type \\
+{\sc krb5_rc_required }& Message replay detection requires rcache parameter \\
+{\sc krb5_err_bad_hostname }& Hostname cannot be canonicalized \\
+{\sc krb5_err_host_realm_unknown }& Cannot determine realm for host \\
+{\sc krb5_sname_unsupp_nametype }& Conversion to service principal undefined for name type \\
+\end{tabular}
+\end{small}
+
+\subsection{error_table kdb5}
+
+% $Source$
+% $Author$
+
+The Kerberos v5 database library error code table
+
+\begin{small}
+\begin{tabular}{ll}
+&\multicolumn{1}{c}{From the server side routines} \\
+{\sc krb5_kdb_inuse }& Entry already exists in database\\
+{\sc krb5_kdb_uk_serror }& Database store error\\
+{\sc krb5_kdb_uk_rerror }& Database read error\\
+{\sc krb5_kdb_unauth }& Insufficient access to perform requested operation\\
+{\sc krb5_kdb_noentry }& No such entry in the database\\
+{\sc krb5_kdb_ill_wildcard }& Illegal use of wildcard\\
+{\sc krb5_kdb_db_inuse }& Database is locked or in use--try again later\\
+{\sc krb5_kdb_db_changed }& Database was modified during read\\
+{\sc krb5_kdb_truncated_record }& Database record is incomplete or corrupted\\
+{\sc krb5_kdb_recursivelock }& Attempt to lock database twice\\
+{\sc krb5_kdb_notlocked }& Attempt to unlock database when not locked\\
+{\sc krb5_kdb_badlockmode }& Invalid kdb lock mode\\
+{\sc krb5_kdb_dbnotinited }& Database has not been initialized\\
+{\sc krb5_kdb_dbinited }& Database has already been initialized\\
+{\sc krb5_kdb_illdirection }& Bad direction for converting keys\\
+{\sc krb5_kdb_nomasterkey }& Cannot find master key record in database\\
+{\sc krb5_kdb_badmasterkey }& Master key does not match database\\
+{\sc krb5_kdb_invalidkeysize }& Key size in database is invalid\\
+{\sc krb5_kdb_cantread_stored }& Cannot find/read stored master key\\
+{\sc krb5_kdb_badstored_mkey }& Stored master key is corrupted\\
+{\sc krb5_kdb_cantlock_db }& Insufficient access to lock database \\
+{\sc krb5_kdb_db_corrupt }& Database format error\\
+{\sc krb5_kdb_bad_version }& Unsupported version in database entry \\
+\end{tabular}
+\end{small}
+
+\subsection{error_table isod}
+
+% $Source$
+% $Author$
+
+ The Kerberos v5/ISODE 5.0 error table mappings --- see $<$isode/psap.h$>$
+
+\begin{small}
+\begin{tabular}{ll}
+{\sc isode_50_ps_err_none}& isode (ps): No error \\
+{\sc isode_50_ps_err_overid}& isode (ps):Overflow in ID \\
+{\sc isode_50_ps_err_overlen}& isode (ps):Overflow in length \\
+{\sc isode_50_ps_err_nmem}& isode (ps):Out of memory \\
+{\sc isode_50_ps_err_eof}& isode (ps):End of file \\
+{\sc isode_50_ps_err_eofid}& isode (ps):End of file reading extended ID \\
+{\sc isode_50_ps_err_eoflen}& isode (ps):End of file reading extended length \\
+{\sc isode_50_ps_err_len}& isode (ps):Length mismatch \\
+{\sc isode_50_ps_err_trnc}& isode (ps):Truncated \\
+{\sc isode_50_ps_err_indf}& isode (ps):Indefinite length in primitive form \\
+{\sc isode_50_ps_err_io}& isode (ps):I/O error \\
+{\sc isode_50_ps_err_extra}& isode (ps): Extraneous octets \\
+{\sc isode_50_ps_err_xxx}& isode (ps):XXX \\
+{\sc isode_50_pe_err_none}& isode(pe):No error \\
+{\sc isode_50_pe_err_over}& isode(pe):Overflow \\
+{\sc isode_50_pe_err_nmem}& isode(pe):Out of memory \\
+{\sc isode_50_pe_err_bit}& isode(pe):No such bit \\
+{\sc isode_50_pe_err_utct}& isode(pe):Malformed universal timestring \\
+{\sc isode_50_pe_err_gent}& isode(pe):Malformed generalized timestring \\
+{\sc isode_50_pe_err_mber}& isode(pe):No such member \\
+{\sc isode_50_pe_err_prim}& isode(pe):Not a primitive form \\
+{\sc isode_50_pe_err_cons}& isode(pe):Not a constructor form \\
+{\sc isode_50_pe_err_type}& isode(pe):Class/ID mismatch in constructor \\
+{\sc isode_50_pe_err_oid}& isode(pe):Malformed object identifier \\
+{\sc isode_50_pe_err_bits}& isode(pe):Malformed bitstring \\
+{\sc isode_50_pe_err_nosupp}& isode(pe):Type not supported \\
+{\sc isode_50_pe_err_signed}& isode(pe):Signed integer not expected \\
+{\sc isode_50_local_err_baddecode}& isode: ASN.1 decode failed \\
+{\sc isode_50_local_err_badmsgtype}& isode: wrong message type after decoding \\
+{\sc isode_50_local_err_badcombo}& isode: unacceptable combination of options \\
+{\sc isode_local_err_missing_part}& isode: missing element during translation \\
+\end{tabular}
+\end{small}
--- /dev/null
+ This document describes the routines that make up the Kerberos
+V5 application programming interface. It is geared towards
+programmers who already have a basic familiarity with Kerberos and are
+in the process of including Kerberos authentication as part of
+applications being developed.
+
+ The function descriptions included are up to date, even if the
+description of the functions may be hard to understand for the novice
+Kerberos programmer.
+
+\subsection{Acknoledgments}
+
+
+The Kerberos model is based in part on Needham and Schroeder's trusted
+third-party authentication protocol and on modifications suggested by
+Denning and Sacco. The original design and implementation of Kerberos
+Versions 1 through 4 was the work of Steve Miller of Digital Equipment
+Corporation and Clifford Neuman (now at the Information Sciences
+Institute of the University of Southern California), along with Jerome
+Saltzer, Technical Director of Project Athena, and Jeffrey Schiller,
+MIT Campus Network Manager. Many other members of Project Athena have
+also contributed to the work on Kerberos. Version 4 is publicly
+available, and has seen wide use across the Internet.
+
+Version 5 (described in this document) has evolved from Version 4 based
+on new requirements and desires for features not available in Version 4.
+
+%nlg- a bunch more probably needs to be added here to credit all
+%those that have contributed to V5 -nlg
+
+\subsection{Kerberos Basics}
+
+Kerberos performs authentication as a trusted third-party
+authentication service by using conventional (shared secret
+key\footnote{ {\em Secret} and {\em private} are often used
+interchangeably in the literature. In our usage, it takes two (or
+more) to share a secret, thus a shared DES key is a {\em secret} key.
+Something is only private when no one but its owner knows it. Thus,
+in public key cryptosystems, one has a public and a {\em private} key.
+}) cryptography. Kerberos provides a means of verifying the
+identities of principals, without relying on authentication by the
+host operating system, without basing trust on host addresses, without
+requiring physical security of all the hosts on the network, and under
+the assumption that packets traveling along the network can be read,
+modified, and inserted at will.
+
+When integrating Kerberos into an application it is important to
+review how and when Kerberos functions are used to ensure that the
+application's design does not compromise the authentication. For
+instance, an application which uses Kerberos' functions only upon the
+{\em initiation} of a stream-based network connection, and assumes the
+absence of any active attackers who might be able to ``hijack'' the
+stream connection.
+
+%{\Huge nlg- It would be nice to include more examples here of common
+%mistakes one can make in deisgning kerberized systems -nlg}
+
+The Kerberos protocol code libraries, whose API is described in this
+document, can be used to provide encryption to any application. In
+order to add authentication to its transactions, a typical network
+application adds one or two calls to the Kerberos library, which
+results in the transmission of the necessary messages to achieve
+authentication.
+
+The two methods for obtaining credentials, the inital ticket exchange
+and the ticket granting ticket exchange, use slightly different
+protocols and require different API routines. The basic difference an
+API programmer will see is that the initial request does not require a
+ticket granting ticket (TGT) but does require the client's secret key
+because the reply is sent back encrypted in the client's secret key.
+Usually this request is for a TGT and TGT based exchanges are used
+from then on. In a TGT exchange the TGT is sent as part of the
+request for tickets and the reply is encrypted in the session key from
+the TGT. For example, once a user's password is used to obtain a TGT,
+it is not required for subsequent TGT exchanges.
+
+The reply consists of a ticket and a session key, encrypted either in
+the user's secret key (i.e., pasword), or the TGT session key. The
+combination of a ticket and a session key is known as a set of {\em
+credentials}.\footnote{In Kerberos V4, the ``ticket file'' was a bit of
+a misnomer, since it contained both tickets and their associated session
+keys. In Kerberos V5, the ``ticket file'' has been renamed to be the
+{\em credentials cache}.} An application client can use these
+credentials to authenticate to the application server by sending the
+ticket and an {\em authenticator} to the server. The authenticator is
+encrypted in the session key of the ticket, and contains the name of the
+client, the name of the server, the time the authenticator was created.
+
+In order to verify the authentication, the application server decrypts
+the ticket using its service key, which is only known by the application
+server and the Kerberos server. Inside the ticket, the Kerberos server
+had placed the name of the client, the name of the server, a DES key
+assocuated with this ticket, and some additional information. The
+application server then uses the ticket session key to decrypt the
+authenticator, and verifies that the information in the authenticator
+matches the information in the ticket, and that the timestamp in the
+authenticator is recent (to prvent reply attacks). Since the session
+key was generated randomly by the Kerberos server, and delivered only
+encrypted in the service key, and in a key known only by the user, the
+application server can be confident that user is really who he or she
+claims to be, by virtue of the fact that the user was able to encrypt
+the authenticator in the correct key.
+
+To provide detection of both replay
+attacks and message stream modification attacks, the integrity of all
+the messages exchanged between principals can also be
+guaranteed\footnote{Using
+\funcname{krb5_mk_safe} and \funcname{krb5_rd_safe} to create and
+verify KRB5_SAFE messages} by generating and transmitting a
+collision-proof checksum \footnote{aka cryptographic checksum,
+elsewhere this is called a hash or digest function} of the client's
+message, keyed with the session key. Privacy and integrity of the
+messages exchanged between principals can be secured\footnote{Using
+\funcname{krb5_mk_priv} and \funcname{krb5_rd_priv} to create and
+verify KRB5_PRIV messages} by encrypting the data to be passed using
+the session key.
+
+\subsubsection{The purpose of Realms}
+
+The Kerberos protocol is designed to operate across organizational
+boundaries. Each organization wishing to run a Kerberos
+server establishes its own {\em realm}. The name of the realm in which a
+client is registered is part of the client's name, and can be used by the
+end-service to decide whether to honor a request.
+
+By establishing {\em inter-realm} keys, the administrators of two
+realms can allow a client authenticated in the local realm to use its
+credentials remotely. The exchange of inter-realm keys (a separate
+key may be used for each direction) registers the ticket-granting
+service of each realm as a principal in the other realm. A client is
+then able to obtain a ticket-granting ticket for the remote realm's
+ticket-granting service from its local realm. When that
+ticket-granting ticket is used, the remote ticket-granting service
+uses the inter-realm key (which usually differs from its own normal
+TGS key) to decrypt the ticket-granting ticket, and is thus certain
+that it was issued by the client's own TGS. Tickets issued by the
+remote ticket-granting service will indicate to the end-service that
+the client was authenticated from another realm.
+
+
+This method can be repeated to authenticate throughout an organization
+accross multiple relms. To build a valid authentication
+path\footnote{An {\em authentication path} is the sequence of
+intermediate realms that are transited in communicating from one realm
+to another.} to a distant relm, the local realm must share an
+inter-realm key with an intermediate realm which
+communicates\footnote{A realm is said to {\em communicate} with
+another realm if the two realms share an inter-realm key} with either
+the distant remote realm or yet another intermediate relm.
+
+Realms are typically organized hierarchically. Each realm shares a
+key with its parent and a different key with each child. If an
+inter-realm key is not directly shared by two realms, the hierarchical
+organization allows an authentication path to be easily constructed.
+If a hierarchical organization is not used, it may be necessary to
+consult some database in order to construct an authentication path
+between realms.
+
+Although realms are typically hierarchical, intermediate realms may be
+bypassed to achieve cross-realm authentication through alternate
+authentication paths\footnote{These might be established to make communication
+between two realms more efficient}. It is important for the
+end-service to know which realms were transited when deciding how much
+faith to place in the authentication process. To facilitate this
+decision, a field in each ticket contains the names of the realms that
+were involved in authenticating the client.
+
+\subsubsection{Fundamental assumptions about the environment}
+
+Kerberos has certain limitations that should be kept in mind when
+designing security measures:
+
+\begin{itemize}
+\item
+Kerberos does not address ``Denial of service'' attacks. There are
+places in these protocols where an intruder can prevent an application
+from participating in the proper authentication steps. Detection and
+solution of such attacks (some of which can appear to be not-uncommon
+``normal'' failure modes for the system) is usually best left to
+the human administrators and users.
+
+\item
+Principals must keep their secret keys secret. If an intruder somehow
+steals a principal's key, it will be able to masquerade as that
+principal or impersonate any server to the legitimate principal.
+
+\item
+``Password guessing'' attacks are not solved by Kerberos. If a user
+chooses a poor password, it is possible for an attacker to
+successfully mount an offline dictionary attack by repeatedly
+attempting to decrypt, with successive entries from a dictionary,
+messages obtained which are encrypted under a key derived from the
+user's password.
+
+\end{itemize}
+
+\subsection{Glossary of terms}
+
+Below is a list of terms used throughout this document.
+
+\begin{description}
+\item [Authentication]
+Verifying the claimed identity of a principal.
+
+\item [Authentication header]
+A record containing a Ticket and an Authenticator to be presented to a
+server as part of the authentication process.
+
+\item [Authentication path]
+A sequence of intermediate realms transited in the authentication
+process when communicating from one realm to another.
+
+\item [Authenticator]
+A record containing information that can be shown to
+have been recently generated using the session key known only by the
+client and server.
+
+\item [Authorization]
+The process of determining whether a client may use a
+service, which objects the client is allowed to access, and the
+type of access allowed for each.
+
+\item [Ciphertext]
+The output of an encryption function. Encryption transforms plaintext
+into ciphertext.
+
+\item [Client]
+A process that makes use of a network service on behalf of a
+user. Note that in some cases a {\em Server} may itself be a client of
+some other server (e.g. a print server may be a client of a file server).
+
+\item [Credentials]
+A ticket plus the secret session key necessary to
+successfully use that ticket in an authentication exchange.
+
+\item [KDC]
+Key Distribution Center, a network service that supplies
+tickets and temporary session keys; or an
+instance of that service or the host on which it runs.
+The KDC services both initial ticket and ticket-granting ticket
+requests.
+The initial ticket portion is sometimes referred to as the
+Authentication Server (or service).
+The ticket-granting ticket portion is sometimes referred to as the
+ticket-granting server (or service).
+
+\item [Kerberos]
+Aside from the 3-headed dog guarding Hades, the name given
+to Project Athena's authentication service, the protocol used by that
+service, or the code used to implement the authentication service.
+
+\item [Plaintext]
+The input to an encryption function or the output of a decryption
+function. Decryption transforms ciphertext into plaintext.
+
+\item [Principal]
+A uniquely named client or server instance that participates in
+a network communication.
+
+\item [Principal identifier]
+The name used to uniquely identify each different
+principal.
+
+\item [Seal]
+To encipher a record containing several fields in such a way
+that the fields cannot be individually replaced without either
+knowledge of the encryption key or leaving evidence of tampering.
+
+\item [Secret key]
+An encryption key shared by a principal and the KDC,
+distributed outside the bounds of the system, with a long lifetime.
+In the case of a human user's principal, the secret key is derived from a
+password.
+
+\item [Server]
+A particular Principal which provides a resource to network clients.
+
+\item [Service]
+A resource provided to network clients; often provided by more than one
+server (for example, remote file service).
+
+\item [Session key]
+A temporary encryption key used between two principals,
+with a lifetime limited to the duration of a single login
+{\em session}.
+
+\item [Sub-session key]
+A temporary encryption key used between two
+principals, selected and exchanged by the principals using the session
+key, and with a lifetime limited to the duration of a single
+association.
+
+\item [Ticket]
+A record that helps a client authenticate itself to a server; it contains
+the client's identity, a session key, a timestamp, and other
+information, all sealed using the server's secret key. It only serves to
+authenticate a client when presented along with a fresh Authenticator.
+\end{description}
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.
+Keytab routines are all be atomic. Every routine that acquires
+a non-sharable resource releases it before it returns.
-Any keytab implementations must support multiple concurrent sequential scans.
+All keytab types 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.
+unspecified.
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}
+abnormally, a close routine, \funcname{krb5_kt_free_entry}, is provided
+for freeing resources, etc. People should use the close routine when
+they are finished.
+
+\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
-``residual''. The interpretation of ``residual'' is dependent on the
-type of keytab.
+``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.
\begin{funcdecl}{krb5_kt_get_name}{krb5_error_code}{\funcin}
\funcarg{krb5_keytab}{id}
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.
\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
+\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.
\funcarg{krb5_creds *}{creds}
\end{funcdecl}
-Attempts to use the credentials cache \funcparam{ccache} or a TGS
+This routine 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).
+\funcparam{creds{\ptsto}client}, with following information:
+\begin{itemize}
+\item {\bf The server} identified by \funcparam{creds{\ptsto}server}
+\item {\bf The options} in \funcparam{options}
+Valid options are KRB5_GC_USER_USER and KRB5_GC_GC_CACHED
+\item {\bf The expiration date} specified in
+\funcparam{creds{\ptsto}times.endtime}
+\item {\bf The session key type} specified in
+\funcparam{creds{\ptsto}keyblock.keytype} if it is non-zero.
+\end{itemize}
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.
+for a ticket.
+
+If \funcparam{options} specifies KRB5_GC_USER_USER, then
+\funcname{krb5_get_credentials} will get credentials for a user to user
+authentication. In a user to user authentication, the secret key for
+the server
+is the session key from the server's ticket-granting-ticket
+(TGT). The TGT is passed from the server to the client over the
+network --- this is safe since the TGT is encrypted in a key
+known only by the Kerberos server --- and the client must pass
+this TGT to \funcname{krb5_get_credentials} in
+\funcparam{creds{\ptsto}second_ticket}. The Kerberos server will use
+this TGT to construct a user to user ticket which can be verified by
+the server by using the session key from its TGT.
+
+The effective {\bf expiration date} is the minimen of the following:
+\begin{itemize}
+\item The expiration date as specified in
+\funcparam{creds{\ptsto}times.endtime}
+\item The requested start time plus the maximum lifetime of the
+server as specified by the server's entry in the
+Kerberos database.
+\item The requested start time plus the maximum lifetime of tickets
+allowed in the local site, as specified by the KDC.
+This is currently a compile-time option,
+KRB5_KDB_MAX_LIFE in config.h, and is by default 1 day.
+\end{itemize}
+
+If any special authorization data needs to be included in the ticket,
+--- for example, restrictions on how the ticket can be used ---
+they should be specified in \funcparam{creds{\ptsto}authdata}. If there
+is no special authorization data to be passed,
+\funcparam{creds{\ptsto}authdata} should be NULL.
Any returned ticket and intermediate ticket-granting tickets are
stored in \funcparam{ccache}.
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{options} (listed in Table \ref{KDCOptions});
+and \funcparam{pre_auth_type}, the preauthentication
+method (valid preauthentication methods are listed in Table
+\ref{padata-types}).
+\funcname{krb5_get_in_tkt} requests encryption type
+\funcparam{etype} (valid encryption types are ETYPE_DES_CBC_CRC and
+ETYPE_RAW_DES_CBC),
+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{key_proc} is called, with \funcparam{keytype},
+\funcparam{keyseed} and\funcparam{padata} as arguments, to fill in \funcparam{key} to be used for
+decryption. The valid key types for \funcparam{keytype} are
+KEYTYPE_NULL,\footnote{See RFC section 6.3.1} and
+KEYTYPE_DES.\footnote{See RFC section 6.3.4} However, KEYTYPE_DES is
+the only key type supported by MIT kerberos.
+The content of \funcparam{keyseed}
+depends on the \funcparam{key_proc} being used. %nlg - need a ref here
+The \funcparam{padata} passed
+to \funcparam{key_proc} is the preauthentication data returned by the
+KDC as part of the reply to the initial ticket request. It may
+contain an element of type KRB5_PADATA_PW_SALT, which
+\funcparam{key_proc} should use to determine what salt to use when
+generating the key. \funcparam{key_proc} should fill in
+\funcparam{key} with a key for the client, or return an error code.
\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
+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}.
+\funcparam{decryptarg} is passed on to \funcparam{decrypt_proc}, and
+its content depends on the \funcparam{decrypt_proc} being used.
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
+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
\funcparam{ccache} and fill in \funcparam{creds} with the ticket
information used/returned.
-Returns system errors, encryption errors.
+Returns system errors, preauthentication errors, encryption errors.
+
+% XXX Right now, uses creds->addresses before it's copied into from
+% the reply -- it's passed to krb5_obtain_padata. I think that's
+% wrong, and it should be using either addrs or the result of
+% krb5_os_localaddr instead. If I'm wrong, then this spec has to be
+% updated to document that creds->addresses is used. On the other
+% hand, if I'm right, then the bug in get_in_tkt needs to be fixed.
+% See ov-cambridge PR 1525.
\begin{funcdecl}{krb5_get_in_tkt_with_password}{krb5_error_code}{\funcin}
\funcarg{const krb5_flags}{options}
\funcarg{krb5_kdc_rep **}{ret_as_reply}
\end{funcdecl}
+Attempts to get an initial ticket using the null-terminated string
+\funcparam{password}. If \funcparam{password} is NULL, the password
+is read from the terminal.
-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}.
+The password is converted into a key using the appropriate
+string-to-key conversion function for the specified
+\funcparam{keytype}, and using any salt data returned by the KDC in
+response to the authentication request.
-A succesful call will place the ticket in the credentials cache
-\funcparam{ccache}.
+See \funcname{krb5_get_in_tkt} for documentation of the
+\funcparam{options}, \funcparam{addrs}, \funcparam{pre_auth_type},
+\funcparam{etype}, \funcparam{keytype}, \funcparam{ccache},
+\funcparam{creds} and \funcparam{ret_as_reply} arguments.
-Returns system errors, encryption errors.
+Returns system errors, preauthentication errors, encryption errors.
\begin{funcdecl}{krb5_get_in_tkt_with_skey}{krb5_error_code}{\funcin}
\funcarg{const krb5_flags}{options}
\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.
+Attempts to get an initial ticket using \funcparam{key}. If
+\funcparam{key} is NULL, an appropriate key is retrieved from the
+system key store (e.g., \filename{/etc/v5srvtab}).
-If \funcparam{addrs} is non-NULL, it is used for the addresses
-requested. If it is null, the system standard addresses are used.
+See \funcname{krb5_get_in_tkt} for documentation of the
+\funcparam{options}, \funcparam{addrs}, \funcparam{pre_auth_type},
+\funcparam{etype}, \funcparam{ccache}, \funcparam{creds} and
+\funcparam{ret_as_reply} arguments.
-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.
+Returns system errors, preauthentication errors, encryption errors.
\begin{funcdecl}{krb5_mk_req}{krb5_error_code}{\funcin}
\funcarg{krb5_const_principal}{server}
are stored in \funcparam{ccache}.
\funcparam{ap_req_options} specifies the KRB_AP_REQ options desired.
+Valid options are
+AP_OPTS_USE_SESSION_KEY and
+AP_OPTS_MUTUAL_REQUIRED.
-\funcparam{checksum} specifies the checksum to be used in the authenticator.
+\funcparam{checksum} specifies the checksum to be used in the
+authenticator. If it is null, no checksum is included.
-The \funcparam{outbuf} buffer storage is allocated, and should be freed
-by the caller when finished.
+% XXX Not sure if it's legal in the protocol for no checksum to be
+% included, or if so, how the server reacts to a request with no
+% checksum.
-Returns system errors.
+\funcparam{outbuf} should point to an existing \datatype{krb5_data}
+structure. \funcparam{outbuf{\ptsto}length} and
+\funcparam{outbuf{\ptsto}data} will be filled in on success, and the latter
+should be freed by the caller when it is no longer needed; if an error
+is returned, however, no storage is allocated and {\tt
+outbuf{\ptsto}data} does not need to be freed.
+Returns system errors, error getting credentials for
+\funcparam{server}.
\begin{funcdecl}{krb5_mk_req_extended}{krb5_error_code}{\funcin}
\funcarg{const krb5_flags}{ap_req_options}
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
+ticket is obtained from either \funcparam{ccache} or the TGS, and the
+resulting ticket is stored in the \funcparam{creds} structure.
+\funcparam{kdc_options} specifies the options
+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.
+During this call, the structure elements in \funcparam{creds} may be
+freed and reallocated. Hence all of the structure elements which are
+pointers should point to allocated memory, and there should be no other
+pointers aliased to the same memory, since it may be deallocated during
+this procedure call.
\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}.
+be freed with \funcname{krb5_free_keyblock}. \funcparam{newkey} will
+not be filled in if an error is returned by
+\funcname{krb5_mk_req_extended}.
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
+a copy of the authenticator there, with the principal and checksum fields
+nulled out, unless an error is returned. (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.
+Returns system errors, errors contacting the KDC, KDC errors getting
+a new ticket for the authenticator.
\begin{funcdecl}{krb5_generate_subkey}{krb5_error_code}{\funcin}
\funcarg{const krb5_keyblock *}{key}
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.
+an error is returned. The returned key (i.e., \funcparam{*subkey}) 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}
+\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{const char *}{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,
+Parses a KRB_AP_REQ message, returning its contents. Upon successful
+return,
\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{inbuf} should contain the KRB_AP_REQ message to be parsed.
+
\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.
-A replay cache name derived from the first component of the service name
-is used.
+\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 is used as a decryption key. If
+\funcparam{keyproc} is NULL, then the decryption key is taken from a key store
+\footnote{i.e., srvtab file in Kerberos V4 parlance} specified by
+\funcparam{fetchfrom}. If \funcparam{fetchfrom} is NULL, then the
+default key store is consulted; otherwise, \funcparam{fetchfrom}
+specifies the name of the key store, using the format as specified by
+\funcname{krb5_kt_resolve}.
-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.
+ then \funcparam{fetchfrom} is checked; if
+it is non-NULL, it specifies a the name of the key store from which to
+retrieve the decription key. If \funcparam{fetchfrom} is NULL, then
+the default key store is consulted.
+\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.
-\begin{funcdecl}{krb5_rd_req}{krb5_error_code}{\funcin}
+Returns system errors, encryption errors, replay errors.
+
+\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}
-\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}.
+Similar to \funcname{krb5_rd_req}, but with some arguments replaced by
+defaults.
-\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.
+The \funcparam{inbuf}, \funcparam{server}, \funcparam{sender_addr} and
+\funcparam{authdat} arguments are as in \funcname{krb5_rd_req}, with
+the exception that {\tt server} should be specified. If
+\funcparam{server} is null, then any server name will be accepted as
+long as a service key can be found for that service. It is then the
+caller's responsibility to check the actual server that was
+authenticated by looking in the \funcparam{authdat} structure. Also,
+if
+\funcparam{server} is null, replay cache protection is {\em not}
+provided!
-\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.
+A replay cache name derived from the first component of the service
+name is used.
-\funcparam{authdat{\ptsto}ticket} and
-\funcparam{authdat{\ptsto}authenticator} are set to allocated storage
-structures; the caller should free them when finished.
+The default key store is consulted to find the service key.
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}
+\funcarg{const char *}{fetchfrom}
\funcfuncarg{krb5_error_code}{(*keyproc)}
\funcarg{krb5_pointer}{keyprocarg}
\funcarg{krb5_principal}{principal}
\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.
+Formats and encrypts an AP_REP message, including in it the data in
+\funcparam{*repl}, encrypted using \funcparam{*kblock}.
-The output buffer storage is allocated, and should be freed by the
-caller when finished.
+When successfull, \funcparam{outbuf{\ptsto}length} and
+\funcparam{outbuf{\ptsto}data} are filled in with the length of the
+AP_REQ message and allocated data holding it.
+\funcparam{outbuf{\ptsto}data} should be freed by the
+caller when it is no longer needed.
Returns system errors.
\end{funcdecl}
Parses and decrypts an AP_REP message from \funcparam{*inbuf}, filling in
-\funcparam{*repl} with a pointer allocating storage containing the
+\funcparam{*repl} with a pointer to allocated 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.
+Returns system errors, encryption errors, replay errors.
\begin{funcdecl}{krb5_mk_error}{krb5_error_code}{\funcin}
\funcarg{const krb5_error *}{dec_err}
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.
+The error buffer storage (\funcparam{enc_err{\ptsto}data}) is
+allocated, and should be freed by the caller when finished.
Returns system errors.
\funcarg{krb5_error **}{dec_error}
\end{funcdecl}
-Parses an error message from \funcparam{enc_errbuf} and fills in
+Parses an error protocol 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}
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}
+\funcname{krb5_net_write} are changed.
The paramter \funcparam{appl_version} is a string describing the
application protocol version which the client is expecting to use for
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
+kerberos principals for the client and the server. They are
+ignored if \funcparam{credsp} is non-null. Otherwise,
+\funcparam{server} must be non-null, but \funcparam{client} may be
+null, in which case the client principal used is the one in the
+credential cache's default principal.
+
+The \funcparam{ap_req_options} parameters specifies the options which
+should be passed to \funcname{krb5_mk_req}. Valid options are listed
+in Table \ref{ap-req-options}. If \funcparam{ap_req_options}
+specifies MUTUAL_REQUIRED, then \funcname{krb5_sendauth} will perform
+a mutual authentication exchange, and if \funcparam{rep_result} is
+non-null, it will be filled in with the result of the mutual
+authentication exchange; the caller should free
+\funcparam{*rep_result} with
+\funcname{krb5_free_ap_rep_enc_part} when done with it.
+
+The \funcparam{checksump} parameter is optional; if it is non-null,
+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
+If \funcparam{credsp} is non-null, then \funcparam{credsp{\ptsto}client} and
+\funcparam{credsp{\ptsto}server} must be filled in, and either
+the other structure fields should be filled in with valid credentials,
+or \funcparam{credsp{\ptsto}ticket.length} should be zero. If
+\funcparam{credsp{\ptsto}ticket.length} is non-zero, then
+\funcparam{credsp} will be used as-is as the credentials to send to
+the server, and \funcparam{ccache} is ignored; otherwise,
+\funcparam{ccache} is used as described below, and \funcparam{credsp}
+is filled in with the retrieved credentials.
+
+\funcname{ccache} specifies the credential cache to use when one is
+needed (i.e., when \funcname{credsp} is null or
+\funcparam{credsp{\ptsto}ticket.length} is zero). When a credential
+cache is not needed, \funcname{ccache} is ignored. When a credential
+cache is needed and \funcname{ccache} is null, the default credential
+cache is used. Note that if the credential cache is needed and does
+not contain the needed credentials, they will be retrieved from the
+KDC and stored in the credential cache.
+
+If non-null, \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.)
+using \funcname{krb5_mk_safe} and \funcname{krb5_mk_priv}. If mutual
+authentication is used and \funcparam{rep_result} is non-null, the
+sequence number for the server is available to the caller in
+\funcparam{*rep_result->seq_number}. (If mutual authentication is not
+used, there is no way to negotiate a sequence number for the server.)
+
+The \funcparam{newkey} parameter functions as described for
+\funcname{krb5_mk_req_extended}.
-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.
+If an error occurs during the authenticated ticket exchange and
+\funcparam{error} is non-null, the error packet (if any) that was sent
+from the server will be placed in it. This error should be freed with
+\funcname{krb5_free_error}.
\begin{funcdecl}{krb5_recvauth}{krb5_error_code}
\funcin
\funcout
\funcarg{krb5_int32 *}{sequence}
\funcarg{krb5_principal *}{client}
-\funcarg{krb5_ticket **}{krb5_ticket}
+\funcarg{krb5_ticket **}{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
+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
+\funcname{krb5_recvauth} will provide mutual authentication to
prove to the client that the server represented by
-\funcname{krb5_recvauth} is legitmate.
+\funcname{krb5_recvauth} is legitimate.
\funcparam{fd} is a pointer to the network connection. As in
-\funcname{krb5_sendauth}, \funcparam{fd} is a pointer to a file
-descriptor in the MIT Unix implementation.
+\funcname{krb5_sendauth}, in the MIT Unix implementation
+\funcparam{fd} is a pointer to a file descriptor.
The parameter \funcparam{appl_version} is a string describing the
application protocol version which the server is expecting to use for
an error will be returned and the authentication exchange will be
aborted.
+If \funcparam{server} is non-null, then \funcname{krb5_recvauth}
+verifies that the server principal requested by the client matches
+\funcparam{server}. If not, an error will be returned and the
+authentication exchange will be aborted.
+
+If \funcparam{sender_addr} is non-null, then \funcname{krb5_recvauth}
+verifies that the address(es) specified is/are present in the
+credentials sent by the client. If not, 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.
+\funcparam{rc_type} is a string which determins which type of replay
+cache \funcname{krb5_recvauth} should use. If it is null, the default
+replay cache type will be used. \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.
+% XXX Note that if the bug I submitted entitled ``"flags" argument
+% should not have been added to krb5_recvauth'' (OpenVision Cambridge
+% bug number 1585) causes code changes, this will have to be updated.
+
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
+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
+messages 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{authent} is non-null (\funcparam{authent} should be freed
+with \funcname{krb5_free_authenticator} when it is no longer needed).
\funcparam{client} is filled in with the client principal which
-initiated the authenticated connection.
+initiated the authenticated connection, and should be freed with
+\funcname{krb5_free_principal} when it is no longer needed.
+
+\funcparam{ticket} is filled in with the data from the ticket sent by
+the client, and should be freed with \funcname{krb5_free_ticket} when
+it is no longer needed.
\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_keyblock *}{key}
\funcarg{const krb5_fulladdr *}{sender_addr}
\funcarg{const krb5_fulladdr *}{recv_addr}
\funcarg{krb5_int32}{seq_number}
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}
+\funcparam{sumtype} specifies the checksum 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.
+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{recv_addr} is optional; if the
+receiver's address is not known, it may be replaced by NULL.
+\funcparam{sender_addr}, however, is mandatory.
\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
+should be used to identify the message. Valid flags are listed below.
+
+\begin{tabular}{ll}
+\multicolumn{1}{c}{Symbol} & Meaning \\
+KRB5_SAFE_NOTIME & Don't use timestamps \\
+KRB5_SAFE_DOSEQUENCE & Use sequence numbers \\
+\end{tabular}
+
+If timestamps are to be used (i.e., if KRB5_SAFE_NOTIME is not set in
+\funcparam{safe_flags}), 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.
+back to him by an attacker. If KRB5_SAFE_NOTIME is set,
+\funcparam{rcache} is not used.
+
+If sequence numbers are to be used (i.e., if KRB5_SAFE_DOSEQUENCE is
+set in \funcparam{safe_flags}), then \funcparam{seq_number} will be
+placed in the protected message as its sequence number. Otherwise,
+\funcparam{seq_number} is unused.
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.
+The \funcparam{outbuf} buffer storage (i.e.,
+\funcparam{outbuf{\ptsto}data}) is allocated, and should be freed by
+the caller when finished.
-Returns system errors.
+Returns system errors, encryption errors.
\begin{funcdecl}{krb5_rd_safe}{krb5_error_code}{\funcin}
\funcarg{const krb5_data *}{inbuf}
\end{funcdecl}
Parses a KRB_SAFE message from \funcparam{inbuf}, placing the
-integrity-protected user data in \funcparam{*outbuf}.
+data in \funcparam{*outbuf} after verifying its integrity.
-\funcparam{key} specifies the key to be used for decryption of the message.
+\funcparam{key} specifies the key to be used for verifying the
+integrity of the message.
\funcparam{sender_addr} and \funcparam{recv_addr} specify the full
-addresses (host and port) of the sender and receiver.
+addresses (host and port) of the sender and receiver, and must be of
+type \datatype{ADDRTYPE_ADDRPORT}.
+
+The \funcparam{sender_addr} parameter is mandatory; it
+specifies the address of the sender. If the address of the sender in
+the message does not match \funcparam{sender_addr}, the error
+KRB5KRB_AP_ERR_BADADDR will be returned.
-\funcparam{outbuf} points to allocated storage which the caller should
-free when finished.
+If \funcparam{recv_addr} is non-NULL, then the address of the receiver
+in the message much match it. If it is null, the receiver address in
+the message will be checked against the list of local addresses as
+returned by \funcname{krb5_os_localaddr}.
+
+The \funcparam{outbuf} buffer storage (i.e.,
+\funcparam{outbuf{\ptsto}data} is allocated storage which the caller
+should free when it is no longer needed.
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}.
+used (i.e., if KRB5_SAFE_DOSEQUENCE is set in it),
+\funcparam{seq_number} is compared to the sequence number for the
+message, and KRB5_KRB_AP_ERR_BADORDER is returned if it does not
+match. Otherwise, \funcparam{seq_number} is not used.
+
+If timestamps are to be used (i.e., if KRB5_SAFE_NOTIME is not set in
+\funcparam{safe_flags}), then four additional checks are performed:
+\begin{itemize}
+\item The timestamp in the message must be within the permitted clock
+ skew (which is usually five minutes), or KRB5KRB_AP_ERR_SKEW
+ is returned.
+\item The address in the message must match \funcparam{sender_addr},
+ or KRB5KRB_AP_ERR_BADADDR is returned.
+\item If \funcparam{recv_addr} is supplied, then it must match
+ the receiver address in the message (if \funcparam{recv_addr}
+ is null, this check is not done), or KRB5KRB_AP_ERR_BADADDR is
+ returned.
+\item The message must not be a replayed message, according to
+ \funcparam{rcache}.
+\end{itemize}
+If NOTIME is specified, then \funcparam{sender_addr},
+\funcparam{recv_addr} and \funcparam{rcache} are not used.
+
+% XXX The text above might change -- the address checks might move
+% outside of the NOTIME restriction. See PR 1576.
The function \funcname{krb5_get_server_rcache} and the service-name
portion of the server principal name can be used to open a
\funcarg{krb5_data *}{outbuf}
\end{funcdecl}
-Formats a KRB_PRIV message into \funcparam{outbuf}.
+Formats a KRB_PRIV message into \funcparam{outbuf}. Behaves similarly
+to \funcname{krb5_mk_safe}, but the message is encrypted and
+integrity-protected rather than just integrity-protected.
-\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{userdata}, \funcparam{server_addr}, \funcparam{recv_addr},
+\funcparam{seq_number}, \funcparam{priv_flags}, \funcparam{rcache} and
+\funcparam{outbuf} function as in \funcname{krb5_mk_safe}.
-\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.
+As in \funcname{krb5_mk_safe}, \funcparam{recv_addr} is optional; if
+the receiver's address is not known, it may be replaced by NULL.
+\funcparam{sender_addr}, however, is mandatory.
-\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.
+\funcparam{etype} specifies the encryption type to use;
+\funcparam{key} specifies the encryption key. If \funcparam{i_vector}
+is non-null, it is used as an initialization vector for the encryption
+(if encryption type \funcparam{etype} supports initialization vectors)
+and its contents are replaced with the last block of encrypted data
+upon return.
-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}.
+\funcparam{priv_flags} selects whether sequence numbers or timestamps
+should be used to identify the message. Valid flags are listed below.
-The \funcparam{outbuf} buffer storage is allocated, and should be freed by the
-caller when finished.
+\begin{tabular}{ll}
+\multicolumn{1}{c}{Symbol} & Meaning \\
+KRB5_PRIV_NOTIME & Don't use timestamps \\
+KRB5_PRIV_DOSEQUENCE & Use sequence numbers \\
+\end{tabular}
-Returns system errors.
+Returns system errors, encryption errors.
\begin{funcdecl}{krb5_rd_priv}{krb5_error_code}{\funcin}
\funcarg{const krb5_data *}{inbuf}
\funcarg{krb5_data *}{outbuf}
\end{funcdecl}
-Parses a KRB_PRIV message from \funcparam{inbuf}, placing the confidential user
-data in \funcparam{*outbuf}.
+Parses a KRB_PRIV message from \funcparam{inbuf}, placing the data in
+\funcparam{*outbuf} after decrypting it. Behaves similarly to
+\funcname{krb5_rd_safe}, but the message is decrypted rather than
+integrity-checked.
-\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{inbuf}, \funcparam{sender_addr}, \funcparam{recv_addr},
+\funcparam{seq_number}, \funcparam{rcache} and \funcparam{outbuf}
+function as in \funcname{krb5_rd_safe}.
-\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.
+The \funcparam{sender_addr} parameter is mandatory; it
+specifies the address of the sender. If the address of the sender in
+the message does not match \funcparam{sender_addr}, the error
+KRB5KRB_AP_ERR_BADADDR will be returned.
-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}.
+If \funcparam{recv_addr} is non-NULL, then the address of the receiver
+in the message much match it. If it is null, the receiver address in
+the message will be checked against the list of local addresses as
+returned by \funcname{krb5_os_localaddr}.
-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}.
+\funcparam{key} specifies the key to be used for decryption of the
+message. If \funcparam{i_vector} is non-null, it is used as an
+initialization vector for the decryption (if the encryption type of
+the message supports initialization vectors) and its contents are
+replaced with the last block of encrypted data in the message.
+
+\funcparam{priv_flags} specifies whether timestamps and sequence
+numbers are to be used; it functions as the \funcparam{safe_flags}
+argument of \funcname{krb5_rd_safe} (but expects KRB5_PRIV_ flags
+rather than KRB5_SAFE_ flags).
Returns system errors, integrity errors.
Converts a single-string representation \funcparam{name} of the
principal name to the multi-part principal format used in the protocols.
+A single-string representation of a Kerberos name consists of one or
+more principal name components, separated by slashes, optionally
+followed by the ``@'' character and a realm name. If the realm name
+is not specified, the local realm is used.
+
+The slash and ``@'' characters may be quoted (i.e., included as part
+of a component rather than as a component separator or realm prefix)
+by preceding them with a backslash (``$\backslash$'') character.
+Similarly, newline, tab, backspace, and null characters may be
+included in a component by using $\backslash{}n$, $\backslash{}t$,
+$\backslash{}b$ or $\backslash{}0$, respectively.
+
+The realm in a Kerberos name may not contain the slash, colon or null
+characters.
+
\funcparam{*principal} will point to allocated storage which should be freed by
the caller (using \funcname{krb5_free_principal}) after use.
\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.
+format used in the protocols to a single-string representation of the
+name. The resulting single-string representation will use the format
+and quoting conventions described for \funcname{krb5_parse_name}
+above.
\funcparam{*name} points to allocated storage and should be freed by the caller
when finished.
does not contain at least 2 components, and system errors (ENOMEM if
unable to allocate memory).
+\begin{funcdecl}{krb5_unparse_name_ext}{krb5_error_code}{\funcin}
+\funcarg{krb5_const_principal}{principal}
+\funcinout
+\funcarg{char **}{name}
+\funcarg{int *}{size}
+\end{funcdecl}
+
+\funcname{krb5_unparse_name_ext} is designed for applications which
+must unparse a large number of principals, and are concerned about the
+speed impact of needing to do a lot of memory allocations and
+deallocations. It functions similarly to \funcname{krb5_unparse_name}
+except if \funcparam{*name} is non-null, in which case, it is assumed
+to contain an allocated buffer of size \funcparam{*size} and this
+buffer will be resized with \funcname{realloc} to hold the unparsed
+name. Note that in this case,
+\funcparam{size} must not be null.
+
+If \funcparam{size} is non-null (whether or not \funcparam{*name} is
+null when the function is called), it will be filled in with the size
+of the unparsed name upon successful return.
+
\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcout}
\funcarg{krb5_principal *}{princ}
\funcin
\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.
+others currently in use on the system. Typically, \funcparam{piece}
+is the first component of the principal name for the client or server
+which is calling \funcname{krb5_get_server_rcache}.
+
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}.
+
+
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
+\funcparam{inaddr{\ptsto}contents} must be of type
\datatype{ADDRTYPE_INET} and \datatype{ADDRTYPE_PORT}.
+% XXX Note that if the bug I sent in entitled ``krb5_gen_replay_name
+% outputs char * when krb5_get_server_rcache expects krb5_data''
+% (OpenVision Cambridge bug number 1582) causes the code of this
+% function to change, the documentation above will have to be updated.
+
\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin}
\funcarg{const char *}{hostname}
\funcarg{const char *}{sname}
\documentstyle[ncs,fixunder,functions,changebar,twoside,fancyheadings]{article}
+%\setlength{\oddsidemargin}{1in}
+%\setlength{\evensidemargin}{1.00in}
+%\setlength{\textwidth}{6.5in}
\setlength{\oddsidemargin}{0in}
-\setlength{\evensidemargin}{2.00in}
-\setlength{\marginparsep}{0.05in}
+\setlength{\evensidemargin}{1.50in}
+\setlength{\textwidth}{5.25in}
+\setlength{\marginparsep}{0.0in}
\setlength{\marginparwidth}{1.95 in}
-\setlength{\textwidth}{4.75in}
\setlength{\topmargin}{-.5in}
\setlength{\textheight}{9in}
\setlength{\parskip}{.1in}
\rfoot[{\bf DRAFT---DO NOT REDISTRIBUTE}]{}
\cfoot{\thepage}
\else\pagestyle{headings}\fi
+
+%nlg- time to make this a real document
+
+\title{\Huge Kerberos V5 application programming library}
+\date{\ifdraft \\ {\Large DRAFT---}\fi\today}
+\author{MIT Information Systems}
+
\begin{document}
-\thispagestyle{empty}
-\begin{center}
-{\Huge Kerberos V5 application programming library}
-\ifdraft \\ {\Large DRAFT---\today}\fi
-\end{center}
+\maketitle
+\tableofcontents
+
+%\thispagestyle{empty}
+%\begin{center}
+%{\Huge Kerberos V5 application programming library}
+%\ifdraft \\ {\Large DRAFT---\today}\fi
+%\end{center}
+
+\section{Introduction}
+\input{intro.tex}
+
+\section{Useful KDC parameters to know about}
+\input{tables.tex}
+
+\section{Error tables}
+\input{errors.tex}
+
+%\addtolength{\oddsidemargin}{-1in}
+%\addtolength{\evensidemargin}{1.00in}
+%\addtolength{\textwidth}{-1.75in}
+\newpage
+
\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
\subsection{Main functions}
\input{krb5.tex}
-\subsection{Credentials cache functions}
+\section{Credentials cache functions}
\input{ccache.tex}
-\subsection{Replay cache functions}
+\section{Replay cache functions}
\input{rcache.tex}
-\subsection{Key table functions}
+\section{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}
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
+caching strategy uses 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_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.
+
+Before the cache can be used \funcname{krb5_rc_initialize} or
+\funcname{krb5_rc_recover} must be called.
+
+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}. This function requires that a ticket
+cache of the type named in
+\funcparam{ops{\ptsto}prefix} has not been previously registered.
+
+
+\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}
+
+This function returns an unopened replay cache of the default type and
+default name (as would be returned by \funcname{krb5_rc_default_type}
+and \funcname{krb5_rc_default_name}). Before the cache can be used
+\funcname{krb5_rc_initialize} or \funcname{krb5_rc_recover} must be
+called.
+
\begin{funcdecl}{krb5_rc_initialize}{krb5_error_code}{\funcin}
\funcarg{krb5_rcache}{id}
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.
--- /dev/null
+The following is a list of options which can be passed to the Kerberos
+server (also known as the Key Distribution Center or KDC). These
+options affect what sort of tickets the KDC will return to the
+application program. The KDC options can be passed to
+\funcname{krb5_get_in_tkt}, \funcname{krb5_get_in_tkt_with_password},
+\funcname{krb5_get_in_tkt_with_skey}, and \funcname{krb5_send_tgs}.
+
+
+\begin{center}
+\begin{tabular}{llc}
+\multicolumn{1}{c}{Symbol}&\multicolumn{1}{c}{RFC}& Valid for \\
+&\multicolumn{1}{c}{section}&get_in_tkt? \\ \hline
+KDC_OPT_FORWARDABLE & 2.6 & yes \\
+KDC_OPT_FORWARDED & 2.6 & \\
+KDC_OPT_PROXIABLE & 2.5 & yes \\
+KDC_OPT_PROXY & 2.5 & \\
+KDC_OPT_ALLOW_POSTDATE & 2.4 & yes \\
+KDC_OPT_POSTDATED & 2.4 & yes \\
+KDC_OPT_RENEWABLE & 2.3 & yes \\
+KDC_OPT_RENEWABLE_OK & 2.7 & yes \\
+KDC_OPT_ENC_TKT_IN_SKEY & 2.7 & \\
+KDC_OPT_RENEW & 2.3 & \\
+KDC_OPT_VALIDATE & 2.2 & \\
+\end{tabular}
+\end{center}
+\label{KDCOptions}
+
+The following is a list of preauthentication methods which are supported
+by Kerberos. Most preauthentication methods are used by
+krb5_get_in_tkt(), krb5_get_in_tkt_with_password(), and
+krb5_get_in_tkt_with_skey(); at some sites, the Kerberos server can be
+configured so that during the initial ticket transation, it will only
+return encrypted tickets after the user has proven his or her identity
+using a supported preauthentication mechanism. This is done to make
+certain password guessing attacks more difficult to carry out.
+
+
+
+\begin{center}
+\begin{tabular}{lcc}
+\multicolumn{1}{c}{Symbol}&In & Valid for \\
+&RFC?&get_in_tkt? \\ \hline
+KRB5_PADATA_NONE & yes & yes \\
+KRB5_PADATA_AP_REQ & yes & \\
+KRB5_PADATA_TGS_REQ & yes & \\
+KRB5_PADATA_PW_SALT & yes & \\
+KRB5_PADATA_ENC_TIMESTAMP & yes & yes \\
+KRB5_PADATA_ENC_SECURID & & yes \\
+\end{tabular}
+\end{center}
+\label{padata-types}
+
+KRB5_PADATA_TGS_REQ is rarely used by a programmer; it is used to pass
+the ticket granting ticket to the Ticket Granting Service (TGS) during a
+TGS transaction (as opposed to an initial ticket transaction).
+
+KRB5_PW_SALT is not really a preauthentication method at all. It is
+passed back from the Kerberos server to application program, and it
+contains a hint to the proper password salting algorithm which should be
+used during the initial ticket exchange.
+
+%The encription type can also be specified in
+%\funcname{krb5_get_in_tkt}, however normally only one keytype is used
+%in any one database.
+%
+%\begin{center}
+%\begin{tabular}{llc}
+%\multicolumn{1}{c}{Symbol}&\multicolumn{1}{c}{RFC}& Supported? \\
+%& \multicolumn{1}{c}{section} & \\ \hline
+%ETYPE_NULL & 6.3.1 & \\
+%ETYPE_DES_CBC_CRC & 6.3.2 & yes \\
+%ETYPE_DES_CBC_MD4 & 6.3.3 & \\
+%ETYPE_DES_CBC_MD5 & 6.3.4 & \\
+%ETYPE_RAW_DES_CBC & & yes \\
+%\end{tabular}
+%\end{center}
+%\label{etypes}
+
+
.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
+LIBTEX= implement.tex ccache-i.tex rcache-i.tex keytab-i.tex libos-i.tex \
+ kdb-i.tex encrypt-i.tex cksum-i.tex crc-32-i.tex implement.ind
-DESTEX= libdes.tex
-all: library.ps libdes.ps
+all: implement.ps
-libdes.dvi: $(DESTEX) $(STYLES)
-
-library.ps: library.dvi
+implement.ps: implement.dvi
# hard to capture two-pass semantics in Makefiles...
-# library.ind: library.dvi
-library.ind: library.idx
- index library.idx
+# implement.ind: implement.dvi
+implement.ind: implement.idx
+ index implement.idx
-library.dvi: $(LIBTEX) $(STYLES)
+implement.dvi: $(LIBTEX) $(STYLES)
.tex.dvi:
latex $*
\rfoot[{\bf DRAFT---DO NOT REDISTRIBUTE}]{}
\cfoot{\thepage}
\else\pagestyle{headings}\fi
+
+%nlg- time to make this a real document
+
+\title{\Huge Kerberos V5 Implementer's Guide}
+\date{\ifdraft \\ {\Large DRAFT---}\fi\today}
+\author{MIT Information Systems}
+
\begin{document}
-\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.
+\maketitle
+\tableofcontents
+
+\section{Introduction}
+
+ This document is designed to aide the programmer who plans to
+change MIT's implementation of Kerberos significantly. It is geared towards
+programmers who are already familiar with Kerberos and how MIT's
+implementation is structured.
+
+ Some of the more basic information needed can be found in the
+API document, although many functions have been repeated where
+additional information has been included for the implementer. The
+function descriptions included are up to date, even if the description
+of the functions may not be very verbose.
\ifdraft\sloppy\fi
-\subsection{Main functions}
-\input{krb5.tex}
+\section{Cache and Key table functions}
\subsection{Credentials cache functions}
-\input{ccache.tex}
+\input{ccache-i.tex}
\subsection{Replay cache functions}
-\input{rcache.tex}
+\input{rcache-i.tex}
\subsection{Key table functions}
-\input{keytab.tex}
+\input{keytab-i.tex}
\section{Operating-system specific functions}
-\input{libos.tex}
+\input{libos-i.tex}
\section{Principal database functions}
-\input{kdb.tex}
+\input{kdb-i.tex}
\section{Encryption system interface}
-\input{encrypt.tex}
+\input{encrypt-i.tex}
\section{Checksum interface}
-\input{cksum.tex}
+\input{cksum-i.tex}
\section{CRC-32 checksum functions}
-\input{crc-32.tex}
+\input{crc-32-i.tex}
\appendix
\cleardoublepage
projects / krb5.git / commitdiff