From: Robbie Harwood Date: Fri, 19 Aug 2016 21:06:25 +0000 (-0400) Subject: Remove outdated TeX documentation from doc/api X-Git-Tag: krb5-1.15-beta1~68 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e394d42e8fbd6ae176ad042f9668ec252188239a;p=thirdparty%2Fkrb5.git Remove outdated TeX documentation from doc/api --- diff --git a/doc/api/Makefile b/doc/api/Makefile deleted file mode 100644 index 2d5d6b784f..0000000000 --- a/doc/api/Makefile +++ /dev/null @@ -1,40 +0,0 @@ -.SUFFIXES: .tex .dvi .ps - -SHELL=/bin/sh - -STYLES= fixunder.sty functions.sty krb5idx.sty -LIBTEX= library.tex intro.tex tables.tex errors.tex krb5.tex ccache.tex \ - rcache.tex keytab.tex libos.tex free.tex - -DESTEX= libdes.tex - -all: library.ps libdes.ps - - -libdes.dvi: $(DESTEX) $(STYLES) - -library.ps: library.dvi - -clean: - rm -f *.toc *.log *.idx *.ind *.aux *.ilg lib1.stamp - -really-clean: clean - rm -f *.dvi *.ps - - -library.dvi: lib1.stamp $(LIBTEX) $(STYLES) - latex library - -lib1.stamp: $(LIBTEX) $(STYLES) - touch library.ind - latex library - makeindex -s krb5.ist library.idx - date > lib1.stamp - -.tex.dvi: - latex $* - - -.dvi.ps: - dvips $*.dvi -o - diff --git a/doc/api/ccache.tex b/doc/api/ccache.tex deleted file mode 100644 index d6e24e834d..0000000000 --- a/doc/api/ccache.tex +++ /dev/null @@ -1,239 +0,0 @@ -The credentials cache functions (some of which are macros which call to -specific types of credentials caches) deal with storing credentials -(tickets, session keys, and other identifying information) in a -semi-permanent store for later use by different programs. - -\begin{funcdecl}{krb5_cc_resolve}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\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}. - -Requires that \funcparam{string_name} be of the form ``type:residual'' and -``type'' is a type known to the library. - -\begin{funcdecl}{krb5_cc_gen_new}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\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}{\funcinout} -\funcarg{krb5_context}{context} -\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 *}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Returns the name of the ccache denoted by \funcparam{id}. - -\begin{funcdecl}{krb5_cc_default_name}{char *}{\funcinout} -\funcarg{krb5_context}{context} -\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}{\funcinout} -\funcarg{krb5_context}{context} -\funcout -\funcarg{krb5_ccache *}{ccache} -\end{funcdecl} - -Equivalent to -\funcnamenoparens{krb5_cc_resolve}(\funcparam{context}, -\funcname{krb5_cc_default_name}, -\funcparam{ccache}). - -\begin{funcdecl}{krb5_cc_initialize}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ccache}{id} -\funcin -\funcarg{krb5_principal}{primary_principal} -\end{funcdecl} - -Creates/refreshes a credentials cache identified by \funcparam{id} with -primary principal set to \funcparam{primary_principal}. -If the credentials cache already exists, its contents are destroyed. - -Errors: permission errors, system errors. - -Modifies: cache identified by \funcparam{id}. - -\begin{funcdecl}{krb5_cc_destroy}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Destroys the credentials cache identified by \funcparam{id}, invalidates -\funcparam{id}, and releases any other resources acquired during use of -the credentials cache. Requires that \funcparam{id} identifies a valid -credentials cache. After return, \funcparam{id} must not be used unless -it is first reinitialized using \funcname{krb5_cc_resolve} or -\funcname{krb5_cc_gen_new}. - -Errors: permission errors. - -\begin{funcdecl}{krb5_cc_close}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Closes the credentials cache \funcparam{id}, invalidates -\funcparam{id}, and releases \funcparam{id} and any other resources -acquired during use of the credentials cache. Requires that -\funcparam{id} identifies a valid credentials cache. After return, -\funcparam{id} must not be used unless it is first reinitialized using -\funcname{krb5_cc_resolve} or \funcname{krb5_cc_gen_new}. - - -\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_ccache}{id} -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Stores \funcparam{creds} in the cache \funcparam{id}, tagged with -\funcparam{creds{\ptsto}client}. -Requires that \funcparam{id} identifies a valid credentials cache. - -Errors: permission errors, storage failure errors. - -\begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{whichfields} -\funcarg{krb5_creds *}{mcreds} -\funcout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Searches the cache \funcparam{id} for credentials matching -\funcparam{mcreds}. The fields which are to be matched are specified by -set bits in \funcparam{whichfields}, and always include the principal -name \funcparam{mcreds{\ptsto}server}. -Requires that \funcparam{id} identifies a valid credentials cache. - -If at least one match is found, one of the matching credentials is -returned in \funcparam{*creds}. The credentials should be freed using -\funcname{krb5_free_credentials}. - -Errors: error code if no matches found. - -\begin{funcdecl}{krb5_cc_get_principal}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_ccache}{id} -\funcarg{krb5_principal *}{principal} -\end{funcdecl} - -Retrieves the primary principal of the credentials cache (as -set by the \funcname{krb5_cc_initialize} request) -The primary principal is filled into \funcparam{*principal}; the caller -should release this memory by calling \funcname{krb5_free_principal} on -\funcparam{*principal} when finished. - -Requires that \funcparam{id} identifies a valid credentials cache. - -\begin{funcdecl}{krb5_cc_start_seq_get}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Prepares to sequentially read every set of cached credentials. -\funcparam{cursor} is filled in with a cursor to be used in calls to -\funcname{krb5_cc_next_cred}. - -\begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_creds *}{creds} -\funcinout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Fetches the next entry from \funcparam{id}, returning its values in -\funcparam{*creds}, and updates \funcparam{*cursor} for the next request. -Requires that \funcparam{id} identifies a valid credentials cache and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. - -Errors: error code if no more cache entries. - -\begin{funcdecl}{krb5_cc_end_seq_get}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Finishes sequential processing mode and invalidates \funcparam{*cursor}. -\funcparam{*cursor} must never be re-used after this call. - -Requires that \funcparam{id} identifies a valid credentials cache and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. - -Errors: may return error code if \funcparam{*cursor} is invalid. - - -\begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{which} -\funcarg{krb5_creds *}{cred} -\end{funcdecl} - -Removes any credentials from \funcparam{id} which match the principal -name {cred{\ptsto}server} and the fields in \funcparam{cred} masked by -\funcparam{which}. -Requires that \funcparam{id} identifies a valid credentials cache. - -Errors: returns error code if nothing matches; returns error code if -couldn't delete. - -\begin{funcdecl}{krb5_cc_set_flags}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ccache}{id} -\funcin -\funcarg{krb5_flags}{flags} -\end{funcdecl} - -Sets the flags on the cache \funcparam{id} to \funcparam{flags}. Useful -flags are defined in {\tt }. - -\begin{funcdecl}{krb5_get_notification_message}{unsigned int}{\funcvoid} -\end{funcdecl} - -Intended for use by Windows. Will register a unique message type using -\funcname{RegisterWindowMessage} which will be notified whenever the -cache changes. This will allow all processes to recheck their caches. diff --git a/doc/api/errors.tex b/doc/api/errors.tex deleted file mode 100644 index 923668ba73..0000000000 --- a/doc/api/errors.tex +++ /dev/null @@ -1,310 +0,0 @@ -\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 }& \parbox[t]{2in}{Client's key is encrypted in an old master key} \\ -{\sc krb5kdc_err_s_old_mast_kvno }& \parbox[t]{2in}{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 }&\parbox[t]{2in}{\raggedright{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 }& \parbox[t]{2in}{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 }& Client's 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 \\ -{\sc krb5kdc_err_preauth_require }& Additional pre-authentication required \\ -{\sc krb5kdc_err_server_nomatch }& Requested server and ticket don't match \\ -\multicolumn{2}{c}{error codes 27-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{2}{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{2}{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_kdcrep_skew }& Clock skew too great in KDC reply \\ -{\sc krb5_in_tkt_realm_mismatch }&\parbox[t]{2.5 in}{Client/server realm -mismatch in initial ticket requst}\\ - -{\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_service_unknown }& Kerberos service unknown \\ -{\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 }& \parbox[t]{3in}{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 }& \parbox[t]{3in}{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 }& \parbox[t]{3in}{No more memory to allocate (in credentials cache code)}\\ -\end{tabular} - -\begin{tabular}{ll} -\multicolumn{2}{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{2}{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{2}{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{2}{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{2}{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 \\ -{\sc krb5krb_ap_err_v4_reply }& Initial Ticket Response appears to be\\ -&\ Version 4 error \\ -{\sc krb5_realm_cant_resolve }& Cannot resolve KDC for requested realm \\ -{\sc krb5_tkt_not_forwardable }& Requesting ticket can't get forwardable tickets \\ -\end{tabular} -\end{small} - -\subsection{error_table kdb5} - -% $Source$ -% $Author$ - -The Kerberos v5 database library error code table - -\begin{small} -\begin{tabular}{ll} -\multicolumn{2}{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} - -% $Source$ -% $Author$ - -\subsection{error_table kv5m} - -The Kerberos v5 magic numbers errorcode table follows. These are used -for the magic numbers found in data structures. - -\begin{small} -\begin{tabular}{ll} -{\sc kv5m_none }& Kerberos V5 magic number table \\ -{\sc kv5m_principal }& Bad magic number for krb5_principal structure \\ -{\sc kv5m_data }& Bad magic number for krb5_data structure \\ -{\sc kv5m_keyblock }& Bad magic number for krb5_keyblock structure \\ -{\sc kv5m_checksum }& Bad magic number for krb5_checksum structure \\ -{\sc kv5m_encrypt_block }& Bad magic number for krb5_encrypt_block structure \\ -{\sc kv5m_enc_data }& Bad magic number for krb5_enc_data structure \\ -{\sc kv5m_cryptosystem_entry }& Bad magic number for krb5_cryptosystem_entry\\&\ structure \\ -{\sc kv5m_cs_table_entry }& Bad magic number for krb5_cs_table_entry structure \\ -{\sc kv5m_checksum_entry }& Bad magic number for krb5_checksum_entry structure \\ - -{\sc kv5m_authdata }& Bad magic number for krb5_authdata structure \\ -{\sc kv5m_transited }& Bad magic number for krb5_transited structure \\ -{\sc kv5m_enc_tkt_parT }& Bad magic number for krb5_enc_tkt_part structure \\ -{\sc kv5m_ticket }& Bad magic number for krb5_ticket structure \\ -{\sc kv5m_authenticator }& Bad magic number for krb5_authenticator structure \\ -{\sc kv5m_tkt_authent }& Bad magic number for krb5_tkt_authent structure \\ -{\sc kv5m_creds }& Bad magic number for krb5_creds structure \\ -{\sc kv5m_last_req_entry }& Bad magic number for krb5_last_req_entry structure \\ -{\sc kv5m_pa_data }& Bad magic number for krb5_pa_data structure \\ -{\sc kv5m_kdc_req }& Bad magic number for krb5_kdc_req structure \\ -{\sc kv5m_enc_kdc_rep_part }& Bad magic number for krb5_enc_kdc_rep_part structure \\ -{\sc kv5m_kdc_rep }& Bad magic number for krb5_kdc_rep structure \\ -{\sc kv5m_error }& Bad magic number for krb5_error structure \\ -{\sc kv5m_ap_req }& Bad magic number for krb5_ap_req structure \\ -{\sc kv5m_ap_rep }& Bad magic number for krb5_ap_rep structure \\ -{\sc kv5m_ap_rep_enc_part }& Bad magic number for krb5_ap_rep_enc_part structure \\ -{\sc kv5m_response }& Bad magic number for krb5_response structure \\ -{\sc kv5m_safe }& Bad magic number for krb5_safe structure \\ -{\sc kv5m_priv }& Bad magic number for krb5_priv structure \\ -{\sc kv5m_priv_enc_part }& Bad magic number for krb5_priv_enc_part structure \\ -{\sc kv5m_cred }& Bad magic number for krb5_cred structure \\ -{\sc kv5m_cred_info }& Bad magic number for krb5_cred_info structure \\ -{\sc kv5m_cred_enc_part }& Bad magic number for krb5_cred_enc_part structure \\ -{\sc kv5m_pwd_data }& Bad magic number for krb5_pwd_data structure \\ -{\sc kv5m_address }& Bad magic number for krb5_address structure \\ -{\sc kv5m_keytab_entry }& Bad magic number for krb5_keytab_entry structure \\ -{\sc kv5m_context }& Bad magic number for krb5_context structure \\ -{\sc kv5m_os_context }& Bad magic number for krb5_os_context structure \\ - -\end{tabular} -\end{small} - -\subsection{error_table asn1} - -The Kerberos v5/ASN.1 error table mappings - -\begin{small} -\begin{tabular}{ll} -{\sc asn1_bad_timeformat }& ASN.1 failed call to system time library \\ -{\sc asn1_missing_field }& ASN.1 structure is missing a required field \\ -{\sc asn1_misplaced_field }& ASN.1 unexpected field number \\ -{\sc asn1_type_mismatch }& ASN.1 type numbers are inconsistent \\ -{\sc asn1_overflow }& ASN.1 value too large \\ -{\sc asn1_overrun }& ASN.1 encoding ended unexpectedly \\ -{\sc asn1_bad_id }& ASN.1 identifier doesn't match expected value \\ -{\sc asn1_bad_length }& ASN.1 length doesn't match expected value \\ -{\sc asn1_bad_format }& ASN.1 badly-formatted encoding \\ -{\sc asn1_parse_error }& ASN.1 parse error \\ -\end{tabular} -\end{small} - diff --git a/doc/api/fancyheadings.sty b/doc/api/fancyheadings.sty deleted file mode 100644 index a71de0fb5f..0000000000 --- a/doc/api/fancyheadings.sty +++ /dev/null @@ -1,233 +0,0 @@ -% fancyheadings.sty version 1.0 -% Fancy headers and footers. -% Piet van Oostrum, Dept of Computer Science, University of Utrecht -% Padualaan 14, P.O. Box 80.089, 3508 TB Utrecht, The Netherlands -% Telephone: +31-30-531806. piet@cs.ruu.nl (mcvax!hp4nl!ruuinf!piet) -% March, 1989. - -% Here is a documentstylestyle option that allows you to customize your -% page headers and footers in an easy way. It combines features that were -% separately available in other pagestyles, without introducing much -% complexity. You can define: -% - three-part headers and footers -% - rules in header and footer -% - headers and footers wider than \textwidth -% - multiline headers and footers -% - separate headers and footers for even and odd pages -% - separate headers and footers for chapter pages -% -% To use this pagestyle, you must include the ``fancyheadings'' style -% option in your \documentstyle, and issue the \pagestyle{fancy} command. -% The \pagestyle{fancy} command should be issued after any changes made to -% \textwidth. -% -% The page layout will be as follows: -% -% LHEAD CHEAD RHEAD -% ----------------------------------- (rule) -% -% page body -% -% -% ----------------------------------- (rule) -% LFOOT CFOOT RFOOT -% -% The L-fields will be leftadjusted, the C-fields centered and the -% R-fields rightadjusted. -% Each of the six fields and the two rules can be defined separately. -% -% Simple use: -% -% The header and footer fields can be defined by commands \lhead{LHEAD} -% and so on for the other fields. If the field depends on something in the -% document (e.g. section titles) you must in general use the \markboth and -% \markright commands, otherwise a title may end on the wrong page. You -% can do this e.g. by redefining the commands \chaptermark, \sectionmark -% and so on (see example below). The defaults for these marks are as in -% the standard pagestyles. The marks can be put into a header or footer -% field by referencing \leftmark and \rightmark. -% -% Rules in header and footer -% -% The thickness of the rules below the header and above the footer can be -% changed by redefining the length parameters \headrulewidth (default -% 0.4pt) and \footrulewidth (default 0). These may be redefined by the -% \setlength command. A thickness of 0pt makes the rule invisible. -% If you want to make more complicated changes, you have to redefine the -% commands \headrule and/or \footrule. -% -% Headers and footers wider than \textwidth -% -% The headers and footers are set in a box of width \headwidth. The -% default for this is the value of \textwidth. You can make it wider (or -% smaller) by redefining \headwidth with the \setlength or \addtolength -% command. The headers and footers will stick out the page on the same -% side as the marginal notes. For example to include the marginal notes, -% add both \marginparsep and \marginparwidth to \headwidth (see also the -% example below). -% -% Multiline headers and footers -% -% Each of the six fields is set in an appropriate parbox, so you can put a -% multiline part in it with the \\ command. It is also possible to put -% extra space in it with the \vspace command. Note that if you do this you -% will probably have to increase the \headheight or \footskip lengths. -% -% Separate headers and footers for even and odd pages -% -% If you want the headers and footers to be different on even- and -% odd-numbered pages in the ``twoside'' style, the field-defining macros -% can be given an optional argument, to be used on the even-numbered -% pages, like \lhead[EVEN-LHEAD]{ODD-RHEAD}. -% -% Separate headers and footers for chapter pages -% -% LaTeX gives a \thispagestyle{plain} command for the first page of the -% document, the first page of each chapter and a couple of other pages. It -% might be incompatible with your pagestyle. In this case you can use a -% slightly different version of the pagestyle, called \pagestyle{fancyplain}. -% This pagestyle redefines the pagestyle ``plain'' to also use pagestyle -% ``fancy'' with the following modifications: -% - the thicknesses of the rules is defined by \plainheadrulewidth and -% \plainfootrulewidth (both default 0). -% - the 6 fields may be defined separately for the plain pages by -% giving them the value \fancyplain{PLAIN-VALUE}{NORMAL-VALUE}. This -% construct may be used in both the optional argument and the normal -% argument. Thus \lhead[\fancyplain{F1}{F2}]{\fancyplain{F3}{F4}} -% specifies the LHEAD value in a two-sided document: -% F1 on an even-numbered ``plain'' page -% F2 on an even-numbered normal page -% F3 on an odd-numbered ``plain'' page -% F4 on an odd-numbered normal page. -% -% Defaults: -% -% \headrulewidth 0.4pt -% \footrulewidth 0pt -% \plainheadrulewidth 0pt -% \plainfootrulewidth 0pt -% -% \lhead[\fancyplain{}{\sl\rightmark}]{\fancyplain{}{\sl\leftmark}} -% % i.e. empty on ``plain'' pages \rightmark on even, \leftmark on odd pages -% \chead{} -% \rhead[\fancyplain{}{\sl\leftmark}]{\fancyplain{}{\sl\rightmark}} -% % i.e. empty on ``plain'' pages \leftmark on even, \rightmark on odd pages -% \lfoot{} -% \cfoot{\rm\thepage} % page number -% \rfoot{} -% -% Examples: -% -% To put two lines containing the section title and the subsection title -% in the righthandside corner, use: -% -% \documentstyle[fancyheadings]{article} -% \pagestyle{fancy} -% \renewcommand{\sectionmark}[1]{\markboth{#1}{}} -% \renewcommand{\subsectionmark}[1]{\markright{#1}} -% \rfoot{\leftmark\\\rightmark} -% -% The following definitions give an approximation of the style used in the -% LaTeX book: -% -% \documentstyle[fancyheadings]{book} -% \pagestyle{fancyplain} -% \addtolength{\headwidth}{\marginparsep} -% \addtolength{\headwidth}{\marginparwidth} -% \renewcommand{\chaptermark}[1]{\markboth{#1}{#1}} % remember chapter title -% \renewcommand{\sectionmark}[1]{\markright{\thesection\ #1}} -% % section number and title -% \lhead[\fancyplain{}{\bf\thepage}]{\fancyplain{}{\bf\rightmark}} -% \rhead[\fancyplain{}{\bf\leftmark}]{\fancyplain{}{\bf\thepage}} -% \cfoot{} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\def\lhead{\@ifnextchar[{\@xlhead}{\@ylhead}} -\def\@xlhead[#1]#2{\gdef\@elhead{#1}\gdef\@olhead{#2}} -\def\@ylhead#1{\gdef\@elhead{#1}\gdef\@olhead{#1}} - -\def\chead{\@ifnextchar[{\@xchead}{\@ychead}} -\def\@xchead[#1]#2{\gdef\@echead{#1}\gdef\@ochead{#2}} -\def\@ychead#1{\gdef\@echead{#1}\gdef\@ochead{#1}} - -\def\rhead{\@ifnextchar[{\@xrhead}{\@yrhead}} -\def\@xrhead[#1]#2{\gdef\@erhead{#1}\gdef\@orhead{#2}} -\def\@yrhead#1{\gdef\@erhead{#1}\gdef\@orhead{#1}} - -\def\lfoot{\@ifnextchar[{\@xlfoot}{\@ylfoot}} -\def\@xlfoot[#1]#2{\gdef\@elfoot{#1}\gdef\@olfoot{#2}} -\def\@ylfoot#1{\gdef\@elfoot{#1}\gdef\@olfoot{#1}} - -\def\cfoot{\@ifnextchar[{\@xcfoot}{\@ycfoot}} -\def\@xcfoot[#1]#2{\gdef\@ecfoot{#1}\gdef\@ocfoot{#2}} -\def\@ycfoot#1{\gdef\@ecfoot{#1}\gdef\@ocfoot{#1}} - -\def\rfoot{\@ifnextchar[{\@xrfoot}{\@yrfoot}} -\def\@xrfoot[#1]#2{\gdef\@erfoot{#1}\gdef\@orfoot{#2}} -\def\@yrfoot#1{\gdef\@erfoot{#1}\gdef\@orfoot{#1}} - -\newdimen\headrulewidth -\newdimen\footrulewidth -\newdimen\plainheadrulewidth -\newdimen\plainfootrulewidth -\newdimen\headwidth -\newif\if@fancyplain \@fancyplainfalse -\def\fancyplain#1#2{\if@fancyplain#1\else#2\fi} - -% Initialization of the head and foot text. - -\headrulewidth 0.4pt -\footrulewidth\z@ -\plainheadrulewidth\z@ -\plainfootrulewidth\z@ - -\lhead[\fancyplain{}{\sl\rightmark}]{\fancyplain{}{\sl\leftmark}} -% i.e. empty on ``plain'' pages \rightmark on even, \leftmark on odd pages -\chead{} -\rhead[\fancyplain{}{\sl\leftmark}]{\fancyplain{}{\sl\rightmark}} -% i.e. empty on ``plain'' pages \leftmark on even, \rightmark on odd pages -\lfoot{} -\cfoot{\rm\thepage} % page number -\rfoot{} - -% Put together a header or footer given the left, center and -% right text, fillers at left and right and a rule. -% The \lap commands put the text into an hbox of zero size, -% so overlapping text does not generate an errormessage. - -\def\@fancyhead#1#2#3#4#5{#1\hbox to\headwidth{\vbox{\hbox -{\rlap{\parbox[b]{\headwidth}{\raggedright#2\strut}}\hfill -\parbox[b]{\headwidth}{\centering#3\strut}\hfill -\llap{\parbox[b]{\headwidth}{\raggedleft#4\strut}}}\headrule}}#5} - - -\def\@fancyfoot#1#2#3#4#5{#1\hbox to\headwidth{\vbox{\footrule -\hbox{\rlap{\parbox[t]{\headwidth}{\raggedright#2\strut}}\hfill -\parbox[t]{\headwidth}{\centering#3\strut}\hfill -\llap{\parbox[t]{\headwidth}{\raggedleft#4\strut}}}}}#5} - -\def\headrule{{\if@fancyplain\headrulewidth\plainheadrulewidth\fi -\hrule\@height\headrulewidth\@width\headwidth \vskip-\headrulewidth}} - -\def\footrule{{\if@fancyplain\footrulewidth\plainfootrulewidth\fi -\vskip-0.3\normalbaselineskip\vskip-\footrulewidth -\hrule\@width\headwidth\@height\footrulewidth\vskip0.3\normalbaselineskip}} - -\def\ps@fancy{ -\let\@mkboth\markboth -\@ifundefined{chapter}{\def\sectionmark##1{\markboth -{\uppercase{\ifnum \c@secnumdepth>\z@ - \thesection\hskip 1em\relax \fi ##1}}{}} -\def\subsectionmark##1{\markright {\ifnum \c@secnumdepth >\@ne - \thesubsection\hskip 1em\relax \fi ##1}}} -{\def\chaptermark##1{\markboth {\uppercase{\ifnum \c@secnumdepth>\m@ne - \@chapapp\ \thechapter. \ \fi ##1}}{}} -\def\sectionmark##1{\markright{\uppercase{\ifnum \c@secnumdepth >\z@ - \thesection. \ \fi ##1}}}} -\def\@oddhead{\@fancyhead\relax\@olhead\@ochead\@orhead\hss} -\def\@oddfoot{\@fancyfoot\relax\@olfoot\@ocfoot\@orfoot\hss} -\def\@evenhead{\@fancyhead\hss\@elhead\@echead\@erhead\relax} -\def\@evenfoot{\@fancyfoot\hss\@elfoot\@ecfoot\@erfoot\relax} -\headwidth\textwidth} -\def\ps@fancyplain{\ps@fancy \let\ps@plain\ps@plain@fancy} -\def\ps@plain@fancy{\@fancyplaintrue\ps@fancy} diff --git a/doc/api/fixunder.sty b/doc/api/fixunder.sty deleted file mode 100644 index b7ae58dbf3..0000000000 --- a/doc/api/fixunder.sty +++ /dev/null @@ -1,48 +0,0 @@ -% fixunder.sty, 31 May 1990, John T. Kohl -% -% The contents of this file are in the public domain. -% -% -% play games with _ to make it active and to provide a reasonable _ -% character (from \tt in most cases), and a discretionary word-break point. - -% -% Some \makeunder... macros for convenience in setting catcodes. -% -\def\makeunderactive{\catcode`\_=\active\relax} -\def\makeunderother{\catcode`\_=12\relax} -\def\makeunderletter{\catcode`\_=11\relax} -\def\makeundernormal{\catcode`\_=8\relax} -\makeunderother -\def\cctwlunder{_} - -% -% The hair here is to allow things like \index to work reasonably with -% the new definition of underscore when the argument to index is part of -% a macro replacement and as such gets tokenized before \index is -% evaluated. -% [in the normal case at top-level, \index{foo_bar} works since \index -% does some hair to make _ into a reasonable character code, and \index -% does NOT use a macro expansion. If you have something like -% \def\foo#1#2{\index{#1} bar #2} -% then \foo{baz_quux}{frobnitz} will result in baz_quux getting -% tokenized BEFORE \foo is expanded, so that the catcode hair in \index -% is to no avail.] -% -% \underrealfalse declares that you want to replace with the \tt _; -% \underrealtrue declares that you want to replace with \char95 (ASCII _). -% -% for things like \index which write things out to files, set -% \underrealfalse before evaluating the \index macro, and what actually -% gets written to the file is an _, rather than something like -% {\leavemode \kern... } (the typical definition of \_). -% -% the above example would then be -% \def\foo#1#2{\underrealfalse\index{#1}\underrealtrue bar #2} -% - -\newif\ifunderreal -\underrealfalse -\makeunderactive -\def_{\ifunderreal\cctwlunder\else\leavevmode {\tt \cctwlunder}\discretionary{}{}{}\fi} -\let\_=_ diff --git a/doc/api/free.tex b/doc/api/free.tex deleted file mode 100644 index 02733b7022..0000000000 --- a/doc/api/free.tex +++ /dev/null @@ -1,266 +0,0 @@ -The free functions deal with deallocation of memory that has been -allocated by various routines. It is recommended that the developer use -these routines as they will know about the contents of the structures. - -\begin{funcdecl}{krb5_xfree}{void}{\funcinout} -\funcarg{void *}{ptr} -\end{funcdecl} - -Frees the pointer \funcarg{ptr}. This is a wrapper macro to -\funcname{free} that is designed to keep lint ``happy.'' - -\begin{funcdecl}{krb5_free_data}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_data *}{val} -\end{funcdecl} - -Frees the data structure \funcparam{val}, including the pointer -\funcparam{val} which has been allocate by any of numerous routines. - - -\begin{funcdecl}{krb5_free_princial}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_principal}{val} -\end{funcdecl} - -Frees the pwd_data \funcparam{val} that has been allocated from -\funcname{krb5_copy_principal}. - -\begin{funcdecl}{krb5_free_authenticator}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_authenticator *}{val} -\end{funcdecl} - -Frees the authenticator \funcparam{val}, including the pointer -\funcparam{val}. - -\begin{funcdecl}{krb5_free_authenticator_contents}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_authenticator *}{val} -\end{funcdecl} - -Frees the authenticator contents of \funcparam{val}. The pointer -\funcparam{val} is not freed. - - -\begin{funcdecl}{krb5_free_addresses}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_address **}{val} -\end{funcdecl} - -Frees the series of addresses \funcparam{*val} that have been allocated from -\funcname{krb5_copy_addresses}. - -\begin{funcdecl}{krb5_free_address}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_address *}{val} -\end{funcdecl} - -Frees the address \funcparam{val}. - -\begin{funcdecl}{krb5_free_authdata}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_authdata **}{val} -\end{funcdecl} - -Frees the authdata structure pointed to by \funcparam{val} that has been -allocated from -\funcname{krb5_copy_authdata}. - -\begin{funcdecl}{krb5_free_enc_tkt_part}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_enc_tkt_part *}{val} -\end{funcdecl} - -Frees \funcparam{val} that has been allocated from -\funcname{krb5_enc_tkt_part} and \funcname{krb5_decrypt_tkt_part}. - -\begin{funcdecl}{krb5_free_ticket}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ticket *}{val} -\end{funcdecl} - -Frees the ticket \funcparam{val} that has been allocated from -\funcname{krb5_copy_ticket} and other routines. - -\begin{funcdecl}{krb5_free_tickets}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ticket **}{val} -\end{funcdecl} - -Frees the tickets pointed to by \funcparam{val}. - -\begin{funcdecl}{krb5_free_kdc_req}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_kdc_req *}{val} -\end{funcdecl} - -Frees the kdc_req \funcparam{val} and all substructures. The pointer -\funcparam{val} is freed as well. - -\begin{funcdecl}{krb5_free_kdc_rep}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_kdc_rep *}{val} -\end{funcdecl} - -Frees the kdc_rep \funcparam{val} that has been allocated from -\funcname{krb5_get_in_tkt}. - -\begin{funcdecl}{krb5_free_kdc_rep_part}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_enc_kdc_rep_part *}{val} -\end{funcdecl} - -Frees the kdc_rep_part \funcparam{val}. - -\begin{funcdecl}{krb5_free_error}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_error *}{val} -\end{funcdecl} - -Frees the error \funcparam{val} that has been allocated from -\funcname{krb5_read_error} or \funcname{krb5_sendauth}. - -\begin{funcdecl}{krb5_free_ap_req}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ap_req *}{val} -\end{funcdecl} - -Frees the ap_req \funcparam{val}. - -\begin{funcdecl}{krb5_free_ap_rep}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ap_rep *}{val} -\end{funcdecl} - -Frees the ap_rep \funcparam{val}. - -\begin{funcdecl}{krb5_free_safe}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_safe *}{val} -\end{funcdecl} - -Frees the safe application data \funcparam{val} that is allocated with -\funcparam{decode_krb5_safe}. - - -\begin{funcdecl}{krb5_free_priv}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_priv *}{val} -\end{funcdecl} - -Frees the private data \funcparam{val} that has been allocated from -\funcname{decode_krb5_priv}. - -\begin{funcdecl}{krb5_free_priv_enc_part}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_priv_enc_part *}{val} -\end{funcdecl} - -Frees the private encoded part \funcparam{val} that has been allocated from -\funcname{decode_krb5_enc_priv_part}. - -\begin{funcdecl}{krb5_free_cred}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_cred *}{val} -\end{funcdecl} - -Frees the credential \funcparam{val}. - -\begin{funcdecl}{krb5_free_creds}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_creds *}{val} -\end{funcdecl} - -Calls \funcname{krb5_free_cred_contents} with \funcparam{val} as the -argument. \funcparam{val} is freed as well. - -\begin{funcdecl}{krb5_free_cred_contents}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_creds *}{val} -\end{funcdecl} - -The function zeros out the session key stored in the credential and then -frees the credentials structures. The argument \funcparam{val} is -{\bf not} freed. - - -\begin{funcdecl}{krb5_free_cred_enc_part}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_cred_enc_part *}{val} -\end{funcdecl} - -Frees the addresses and ticket_info elements of -\funcparam{val}. \funcparam{val} is {\bf not} freed by this routine. - -\begin{funcdecl}{krb5_free_checksum}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_checksum *}{val} -\end{funcdecl} - -The checksum and the pointer \funcparam{val} are both freed. - -\begin{funcdecl}{krb5_free_keyblock}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_keyblock *}{val} -\end{funcdecl} - -The keyblock contents of \funcparam{val} are zeroed and the memory -freed. The pointer \funcparam{val} is freed as well. - -\begin{funcdecl}{krb5_free_pa_data}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_pa_data **}{val} -\end{funcdecl} - -Frees the contents of \funcparam{*val}. \funcparam{val} is freed as -well. - -\begin{funcdecl}{krb5_free_ap_rep_enc_part}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_ap_rep_enc_part *}{val} -\end{funcdecl} - -Frees the subkey keyblock (if set) as well as \funcparam{val} that has -been allocated from \funcname{krb5_rd_rep} or \funcname{krb5_send_auth}. - -\begin{funcdecl}{krb5_free_tkt_authent}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_tkt_authent *}{val} -\end{funcdecl} - -Frees the ticket and authenticator portions of \funcparam{val}. The -pointer \funcparam{val} is freed as well. - -\begin{funcdecl}{krb5_free_pwd_data}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{passwd_pwd_data *}{val} -\end{funcdecl} - -Frees the pwd_data \funcparam{val} that has been allocated from -\funcname{decode_krb5_pwd_data}. - -\begin{funcdecl}{krb5_free_pwd_sequences}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{passwd_phrase_element **}{val} -\end{funcdecl} - -Frees the passwd_phrase_element \funcparam{val}. This is usually called -from \funcname{krb5_free_pwd_data}. - -\begin{funcdecl}{krb5_free_realm_tree}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_principal *}{realms} -\end{funcdecl} - -Frees the realms tree \funcparam{realms} returned by -\funcname{krb5_walk_realm_tree}. - -\begin{funcdecl}{krb5_free_tgt_creds}{void}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_creds **}{tgts} -\end{funcdecl} - -Frees the TGT credentials \funcparam{tgts} returned by -\funcname{krb5_get_cred_from_kdc}. - diff --git a/doc/api/functions.sty b/doc/api/functions.sty deleted file mode 100644 index a3165f8114..0000000000 --- a/doc/api/functions.sty +++ /dev/null @@ -1,70 +0,0 @@ -% -% definitions related to function declarations/displays -% -\ifx\undefined\@psfonts -\def\argfont{\tt} -\else -\font\argfont = pcrb -\hyphenchar\argfont = -1 -\fi -\let\funcfont=\bf -\newcount\argc@ount -%\setlength{\marginparsep}{0.05in} -%\setlength{\marginparwidth}{1.45in} -% -% This function fixes up the function name to be displayed in the -% margin so that the krb5_, if any, is stripped. -% -% Note: this is a hack; what's really happening is that name beginning with -% krb5 will have its first five characters stripped from it. -% This means that 'Krb5abc' will get rewritten to be 'bc'. -% Unfortunately, we can't do better because of the underscore -% hacks that are going on elsewhere. -% -% WARNING: This is ugly; don't look at it too soon after lunch! -% [tytso:19900920.2231EDT] -\newif\if@krbfunc -\def\endkrb{} -\def\fix@parname#1{\expandafter\parse@krb#1\endkrb% -\endkrb\endkrb\endkrb\endkrb}% In case the argument is less -% than five letters, we don't want to -% lose on the argument parsing. -\def\parse@krb#1#2#3#4#5#6\endkrb{\@krbfuncfalse% -\if#1k\if#2r\if#3b\if#45\@krbfunctrue\fi\fi\fi\fi% -\if@krbfunc#6\else#1#2#3#4#5#6\fi} -% -% funcdecl is used as \begin{funcdecl}{funcname}{return type}{firstline} -% -% see fixunder.sty for comments on why the \underrealtrue & \underrealfalse -% stuff is here. -\newenvironment{funcdecl}[3]{\underrealtrue\index{#1}\underrealfalse% -\medbreak -\gdef\funcn@me{#1} -\argc@ount=0\noindent% -%the \mbox{} is to prevent the line/paragraph breaking from eating the -%fill space. -\marginpar[{{\sloppy \hfil\fix@parname{\funcn@me}\hfill\mbox{}}}]% -{{\sloppy \hfill\fix@parname{\funcn@me}\hfil\mbox{}}}% -\vbox\bgroup\begin{minipage}[t]{\textwidth}\begin{tabbing} -#2 \\ -{\bf #1}(\= \+ #3% -}{) -\end{tabbing}\vfil\end{minipage}\egroup\par\nopagebreak -} -\newcommand{\docomm@}{\ifnum\argc@ount >0, \\\fi} -\newcommand{\funcvoid}{\argc@ount=0} -\newcommand{\funcin}{\docomm@\argc@ount=0{\sl /* IN */}\\} -\newcommand{\funcinout}{\docomm@\argc@ount=0{\sl /* IN/OUT */}\\} -\newcommand{\funcout}{\docomm@\argc@ount=0{\sl /* OUT */}\\} -\newcommand{\funcarg}[2]{\docomm@#1 {\argfont #2}\advance\argc@ount by1} -\newcommand{\funcparam}[1]{{\argfont #1}} -\newcommand{\funcfuncarg}[2]{\docomm@#1 {\argfont #2}(\= \+ \argc@ount=0} -\newcommand{\funcendfuncarg}{), \- \\ \argc@ount=0} -\newcommand{\libname}[1]{{\argfont #1}} -\newcommand{\globalname}[1]{{\argfont #1}} -\newcommand{\ptsto}{->\discretionary{}{}{}} -\newcommand{\datatype}[1]{{\bf #1}} -\newcommand{\filename}[1]{{\sl #1\/}} - -\newcommand{\funcname}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}()} -\newcommand{\funcnamenoparens}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}} diff --git a/doc/api/intro.tex b/doc/api/intro.tex deleted file mode 100644 index 370775b026..0000000000 --- a/doc/api/intro.tex +++ /dev/null @@ -1,299 +0,0 @@ - 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{Acknowledgments} - - -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 designing 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 initial 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., password), 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 -associated 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 prevent 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 -guar\-an\-teed\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 -across multiple realms. 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 realm, 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 realm. - -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} diff --git a/doc/api/keytab.tex b/doc/api/keytab.tex deleted file mode 100644 index 63e27e5386..0000000000 --- a/doc/api/keytab.tex +++ /dev/null @@ -1,221 +0,0 @@ -The key table functions deal with storing and retrieving service keys -for use by unattended services which participate in authentication exchanges. - -Keytab routines are all be atomic. Every routine that acquires -a non-sharable resource releases it before it returns. - -All keytab types support multiple concurrent sequential scans. - -The order of values returned from \funcname{krb5_kt_next_entry} is -unspecified. - -Although the ``right thing'' should happen if the program aborts -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}{\funcinout} -\funcarg{krb5_context}{context} -\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}{\funcinout} -\funcarg{krb5_context}{context} -\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}{\funcinout} -\funcarg{krb5_context}{context} -\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}{\funcinout} -\funcarg{krb5_context}{context} -\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}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcarg{krb5_keytype}{keytype} -\funcout -\funcarg{krb5_keyblock **}{key} -\end{funcdecl} - -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}, \funcparam{keytype}, 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}{\funcinout} -\funcarg{krb5_context}{context} -\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}{\funcinout} -\funcarg{krb5_context}{context} -\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}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{char *}{name} -\funcin -\funcarg{unsigned int}{namesize} -\end{funcdecl} - -\funcarg{name} is filled in with the first \funcparam{namesize} bytes of -the name of the keytab identified by \funcname{id}. -If the name is shorter than \funcparam{namesize}, then \funcarg{name} -will be null-terminated. - -\begin{funcdecl}{krb5_kt_close}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_keytab}{id} -\end{funcdecl} - -Closes the keytab identified by \funcparam{id} and invalidates -\funcparam{id}, and releases any other resources acquired during use of -the key table. - -Requires that \funcparam{id} identifies a keytab. - -\begin{funcdecl}{krb5_kt_get_entry}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_keytab}{id} -\funcin -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcarg{krb5_keytype}{keytype} -\funcout -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -\begin{sloppypar} -Searches the keytab identified by \funcparam{id} for an entry whose -principal matches \funcparam{principal}, whose keytype matches -\funcparam{keytype}, and -whose key version number matches \funcparam{vno}. If \funcparam{vno} is -zero, the first entry whose principal matches is returned. -\end{sloppypar} - -Returns an error code if no suitable entry is found. If an entry is -found, the entry is returned in \funcparam{*entry}; its contents should -be deallocated by calling \funcname{krb5_kt_free_entry} when no longer -needed. - -\begin{funcdecl}{krb5_kt_free_entry}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Releases all storage allocated for \funcparam{entry}, which must point -to a structure previously filled in by \funcname{krb5_kt_get_entry} or -\funcname{krb5_kt_next_entry}. - -\begin{funcdecl}{krb5_kt_start_seq_get}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{krb5_kt_cursor *}{cursor} -\end{funcdecl} - -Prepares to read sequentially every key in the keytab identified by -\funcparam{id}. -\funcparam{cursor} is filled in with a cursor to be used in calls to -\funcname{krb5_kt_next_entry}. - -\begin{funcdecl}{krb5_kt_next_entry}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{krb5_keytab_entry *}{entry} -\funcinout -\funcarg{krb5_kt_cursor *}{cursor} -\end{funcdecl} - -Fetches the ``next'' entry in the keytab, returning it in -\funcparam{*entry}, and updates \funcparam{*cursor} for the next -request. If the keytab changes during the sequential get, an error is -guaranteed. \funcparam{*entry} should be freed after use by calling -\funcname{krb5_kt_free_entry}. - -Requires that \funcparam{id} identifies a valid keytab. and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. - -Errors: error code if no more cache entries or if the keytab changes. - -\begin{funcdecl}{krb5_kt_end_seq_get}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_kt_cursor *}{cursor} -\end{funcdecl} - -Finishes sequential processing mode and invalidates \funcparam{cursor}, -which must never be re-used after this call. - -Requires that \funcparam{id} identifies a valid keytab and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. - -May return error code if \funcparam{cursor} is invalid. - - diff --git a/doc/api/krb5.ist b/doc/api/krb5.ist deleted file mode 100644 index 36e9adb2b8..0000000000 --- a/doc/api/krb5.ist +++ /dev/null @@ -1,26 +0,0 @@ -%% -%% This is based on the gind.ist -%% -actual '=' -quote '!' -level '>' -preamble -"\n \\begin{theindex} \n" -postamble -"\n\n \\end{theindex}\n" -item_x1 "\\efill \n \\subitem " -item_x2 "\\efill \n \\subsubitem " -delim_0 "\\pfill " -delim_1 "\\pfill " -delim_2 "\\pfill " -% The next lines will produce some warnings when -% running Makeindex as they try to cover two different -% versions of the program: -lethead_prefix "{\\bfseries\\hfil " -lethead_suffix "\\hfil}\\nopagebreak\n" -lethead_flag 1 -heading_prefix "{\\bfseries\\hfil " -heading_suffix "\\hfil}\\nopagebreak\n" -headings_flag 1 -%% -%% diff --git a/doc/api/krb5.tex b/doc/api/krb5.tex deleted file mode 100644 index 3e347a47c5..0000000000 --- a/doc/api/krb5.tex +++ /dev/null @@ -1,1827 +0,0 @@ -The main functions deal with the nitty-gritty details: verifying -tickets, creating authenticators, and the like. - -\subsubsection{The krb5_context} -The \datatype{krb5_context} is designed to represent the per process -state. When the library is made thread-safe, the context will represent -the per-thread state. Global parameters which are ``context'' specific -are stored in this structure, including default realm, default -encryption type, default configuration files and the like. Functions -exist to provide full access to the data structures stored in the -context and should not be accessed directly by developers. - -\begin{funcdecl}{krb5_init_context}{krb5_error_code}{\funcout} -\funcarg{krb5_context *}{context} -\end{funcdecl} - -Initializes the context \funcparam{*context} for the -application. Currently the context contains the encryption types, a -pointer to operating specific data and the default realm. In the future, -the context may be also contain thread specific data. The data in the -context should be freed with \funcname{krb5_free_context}. - -Returns system errors. - -\begin{funcdecl}{krb5_free_context}{void}{\funcinout} -\funcarg{krb5_context}{context} -\end{funcdecl} - -Frees the context returned by \funcname{krb5_init_context}. Internally -calls \funcname{krb5_os_free_context}. - -\begin{funcdecl}{krb5_set_default_in_tkt_etypes}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_enctype *}{etypes} -\end{funcdecl} - -Sets the desired default encryption type \funcparam{etypes} for the context -if valid. - -Returns {\sc enomem}, {\sc krb5_prog_etype_nosupp}. - -\begin{funcdecl}{krb5_get_default_in_tkt_etypes}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcout -\funcarg{krb5_enctype **}{etypes} -\end{funcdecl} - -Retrieves the default encryption types from the context and stores them -in \funcarg{etypes} which should be freed by the caller. - -Returns {\sc enomem}. - -\subsubsection{The krb5_auth_context} - -While the \datatype{krb5_context} represents a per-process or per-thread -context, the \datatype{krb5_auth_context} represents a per-connection -context are are used by the various functions involved directly in -client/server authentication. Some of the data stored in this context -include keyblocks, addresses, sequence numbers, authenticators, checksum -type, and replay cache pointer. - -\begin{funcdecl}{krb5_auth_con_init}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcout -\funcarg{krb5_auth_context *}{auth_context} -\end{funcdecl} - -The auth_context may be described as a per connection context. This -context contains all data pertinent to the the various authentication -routines. This function initializes the auth_context. - -The default flags for the context are set to enable the use of the replay cache -(KRB5_AUTH_CONTEXT_DO_TIME) but no sequence numbers. The function -\funcname{krb5_auth_con_setflags} allows the flags to be changed. - -The default checksum type is set to CKSUMTYPE_RSA_MD4_DES. This may be -changed with \funcname{krb5_auth_con_setcksumtype}. - -The auth_context structure should be freed with -\funcname{krb5_auth_con_free}. - -\begin{funcdecl}{krb5_auth_con_free}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\end{funcdecl} - -Frees the auth_context \funcparam{auth_context} returned by -\funcname{krb5_auth_con_init}. - -% perhaps some comment about which substructures are freed and which are not? - -\begin{funcdecl}{krb5_auth_con_setflags}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{krb5_int32}{flags} -\end{funcdecl} - -Sets the flags of \funcparam{auth_context} to funcparam{flags}. Valid -flags are: - -\begin{tabular}{ll} -\multicolumn{1}{c}{Symbol} & Meaning \\ -KRB5_AUTH_CONTEXT_DO_TIME & Use timestamps \\ -KRB5_AUTH_CONTEXT_RET_TIME & Save timestamps\\ &\ to output structure\\ -KRB5_AUTH_CONTEXT_DO_SEQUENCE & Use sequence numbers \\ -KRB5_AUTH_CONTEXT_RET_SEQUENCE & Copy sequence numbers \\ &\ to output structure\\ -\end{tabular} - - -\begin{funcdecl}{krb5_auth_con_getflags}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_auth_context}{auth_context} -\funcout -\funcarg{krb5_int32 *}{flags} -\end{funcdecl} - -Retrievs the flags of \funcparam{auth_context}. - -\begin{funcdecl}{krb5_auth_con_setaddrs}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{krb5_address *}{local_addr} -\funcarg{krb5_address *}{remote_addr} -\end{funcdecl} - -Copies the \funcparam{local_addr} and \funcparam{remote_addr} into the -\funcparam{auth_context}. If either address is NULL, the previous -address remains in place. - -\begin{funcdecl}{krb5_auth_con_getaddrs}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcout -\funcarg{krb5_address **}{local_addr} -\funcarg{krb5_address **}{remote_addr} -\end{funcdecl} - -Retrieves \funcparam{local_addr} and \funcparam{remote_addr} from the -\funcparam{auth_context}. If \funcparam{local_addr} or -\funcparam{remote_addr} is not NULL, the memory is first freed with -\funcname{krb5_free_address} and then newly allocated. It is the callers -responsibility to free the returned addresses in this way. - - -\begin{funcdecl}{krb5_auth_con_setports}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{krb5_address *}{local_port} -\funcarg{krb5_address *}{remote_port} -\end{funcdecl} - -Copies the \funcparam{local_port} and \funcparam{remote_port} addresses -into the \funcparam{auth_context}. If either address is NULL, the previous -address remains in place. These addresses are set by -\funcname{krb5_auth_con_genaddrs}. - -\begin{funcdecl}{krb5_auth_con_setuserkey}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{krb5_keyblock *}{keyblock} -\end{funcdecl} - -This function overloads the keyblock field. It is only useful prior to a -\funcname{krb5_rd_req_decode} call for user to user authentication where -the server has the key and needs to use it to decrypt the incoming -request. Once decrypted this key is no longer necessary and is then -overwritten with the session key sent by the client. - -\begin{funcdecl}{krb5_auth_con_getkey}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcout -\funcarg{krb5_keyblock **}{keyblock} -\end{funcdecl} - -Retrieves the keyblock stored in \funcparam{auth_context}. The memory -allocated in this function should be freed with a call to -\funcname{krb5_free_keyblock}. - -\begin{funcdecl}{krb5_auth_con_getrecvsubkey}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcout -\funcarg{krb5_keyblock **}{keyblock} -\end{funcdecl} - -Retrieves the recv\_subkey keyblock stored in -\funcparam{auth_context}. The memory allocated in this function should -be freed with a call to \funcname{krb5_free_keyblock}. - -\begin{funcdecl}{krb5_auth_con_getsendsubkey}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcout -\funcarg{krb5_keyblock **}{keyblock} -\end{funcdecl} - -Retrieves the send\_subkey keyblock stored in -\funcparam{auth_context}. The memory allocated in this function should -be freed with a call to \funcname{krb5_free_keyblock}. - -\begin{funcdecl}{krb5_auth_con_setrecvsubkey}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcout -\funcarg{krb5_keyblock *}{keyblock} -\end{funcdecl} - -Sets the recv\_subkey keyblock stored in \funcparam{auth_context}. - -\begin{funcdecl}{krb5_auth_con_setsendsubkey}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcout -\funcarg{krb5_keyblock *}{keyblock} -\end{funcdecl} - -Sets the send\_subkey keyblock stored in \funcparam{auth_context}. - -\begin{funcdecl}{krb5_auth_setcksumtype}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{krb5_cksumtype}{cksumtype} -\end{funcdecl} - -Sets the checksum type used by the other functions in the library. - -\begin{funcdecl}{krb5_auth_getlocalseqnumber}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{krb5_int32 *}{seqnumber} -\end{funcdecl} - -Retrieves the local sequence number that was used during authentication -and stores it in \funcparam{seqnumber}. - -\begin{funcdecl}{krb5_auth_getremoteseqnumber}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{krb5_int32 *}{seqnumber} -\end{funcdecl} - -Retrieves the remote sequence number that was used during authentication -and stores it in \funcparam{seqnumber}. - -\begin{funcdecl}{krb5_auth_getauthenticator}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcout -\funcarg{krb5_authenticator **}{authenticator} -\end{funcdecl} - -Retrieves the authenticator that was used during mutual -authentication. It is the callers responsibility to free the memory -allocated to \funcparam{authenticator} by calling -\funcname{krb5_free_authenticator}. - -\begin{funcdecl}{krb5_auth_con_initivector}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\end{funcdecl} - -Allocates memory for and zeros the initial vector in the -\funcparam{auth_context} keyblock. - -\begin{funcdecl}{krb5_auth_con_setivector}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context *}{auth_context} -\funcin -\funcarg{krb5_pointer}{ivector} -\end{funcdecl} - -Sets the i_vector portion of \funcparam{auth_context} to -\funcparam{ivector}. - -\begin{funcdecl}{krb5_auth_con_setrcache}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{krb5_rcache}{rcache} -\end{funcdecl} - -Sets the replay cache that is used by the authentication routines to \funcparam{rcache}. - -%% -%% The following prototypes exist, but there is no code at this time -%% krb5_auth_con_getcksumtype, krb5_auth_con_getivector, -%% krb5_auth_con_getrcache. -- Ezra - -\subsubsection{Principal access functions} - -Principals define a uniquely named client or server instance that -participates in a network communication. The following functions allow -one to create, modify and access portions of the -\datatype{krb5_principal}. - -Other functions found in orther portions of the manual include -\funcname{krb5_sname_to_principal}, \funcname{krb5_free_principal}, - -While it is possible to directly access the data structure in the -structure, it is recommended that the functions be used. - -\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const char *}{name} -\funcout -\funcarg{krb5_principal *}{principal} -\end{funcdecl} - -Converts a single-string representation \funcparam{name} of the -principal name to the multi-part principal format used in the protocols. - -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. - -\funcname{krb5_parse_name} returns KRB5_PARSE_MALFORMED if the string is - badly formatted, or ENOMEM if space for the return value can't be -allocated. - -\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_const_principal}{principal} -\funcout -\funcarg{char **}{name} -\end{funcdecl} - -Converts the multi-part principal name \funcparam{principal} from the -format used in the protocols to a single-string representation of the -name. 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. - -\funcname{krb5_unparse_name} returns {\sc KRB_PARSE_MALFORMED} if the principal -does not contain at least 2 components, and system errors ({\sc ENOMEM} if -unable to allocate memory). - -\begin{funcdecl}{krb5_unparse_name_ext}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_const_principal}{principal} -\funcinout -\funcarg{char **}{name} -\funcarg{unsigned 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_princ_realm}{krb5_data *}{\funcinout} -\funcparam{krb5_context}{context} -\funcparam{krb5_principal}{principal} -\end{funcdecl} - -A macro which returns the realm of \funcparam{principal}. - -\begin{funcdecl}{krb5_princ_set_realm}{void}{\funcinout} -\funcparam{krb5_context}{context} -\funcparam{krb5_principal}{principal} -\funcparam{krb5_data *}{realm} -\end{funcdecl} - -A macro which returns sets the realm of \funcparam{principal} to -\funcparam{realm}. - -\begin{funcdecl}{krb5_princ_set_realm_data}{void}{\funcinout} -\funcparam{krb5_context}{context} -\funcparam{krb5_principal}{principal} -\funcparam{char *}{data} -\end{funcdecl} - -\internalfunc - -A macro which returns sets the data portion of the realm of -\funcparam{principal} to \funcparam{data}. - -\begin{funcdecl}{krb5_princ_set_realm_length}{void}{\funcinout} -\funcparam{krb5_context}{context} -\funcparam{krb5_principal}{principal} -\funcparam{int}{length} -\end{funcdecl} - -\internalfunc - -A macro which returns sets the length \funcparam{principal} to -\funcparam{length}. - -\begin{funcdecl}{krb5_princ_size}{void}{\funcinout} -\funcparam{krb5_context}{context} -\funcparam{krb5_principal}{principal} -\end{funcdecl} - -\internalfunc - -A macro which gives the number of elements in the principal. -May also be used on the left size of an assignment. - -\begin{funcdecl}{krb5_princ_type}{void}{\funcinout} -\funcparam{krb5_context}{context} -\funcparam{krb5_principal}{principal} -\end{funcdecl} - -\internalfunc - -A macro which gives the type of the principal. -May also be used on the left size of an assignment. - -\begin{funcdecl}{krb5_princ_data}{} -\funcparam{krb5_context}{context} -\funcparam{krb5_principal}{principal} -\end{funcdecl} - -\internalfunc - -A macro which gives the pointer to data portion of the principal. -May also be used on the left size of an assignment. - - -\begin{funcdecl}{krb5_princ_component}{} -\funcparam{krb5_context}{context} -\funcparam{krb5_principal}{principal} -\funcparam{int}{i} -\end{funcdecl} - -\internalfunc - -A macro which gives the pointer to ith element of the principal. -May also be used on the left size of an assignment. - -\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcout -\funcarg{krb5_principal *}{princ} -\funcin -\funcarg{unsigned int}{rlen} -\funcarg{const char *}{realm} -\funcarg{char}{*s1, *s2, ..., 0} -\end{funcdecl} -\begin{funcdecl}{krb5_build_principal_va}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcout -\funcarg{krb5_principal *}{princ} -\funcin -\funcarg{unsigned int}{rlen} -\funcarg{const char *}{realm} -\funcarg{va_list}{ap} -\end{funcdecl} - -\begin{sloppypar} -\funcname{krb5_build_principal} and -\funcname{krb5_build_principal_va} -perform the same function; the former takes variadic arguments, while -the latter takes a pre-computed varargs pointer. -\end{sloppypar} - -Both functions take a realm name \funcparam{realm}, realm name length -\funcparam{rlen}, and a list of null-terminated strings, and fill in a -pointer to a principal structure \funcparam{princ}, making it point to a -structure representing the named principal. -The last string must be followed in the argument list by a null pointer. - - -\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcout -\funcarg{krb5_principal *}{princ} -\funcin -\funcarg{unsigned int}{rlen} -\funcarg{const char *}{realm} -\funcarg{}{int len1, char *s1, int len2, char *s2, ..., 0} -\end{funcdecl} - -\funcname{krb5_build_principal_ext} is similar to -\funcname{krb5_build_principal} but it takes its components as a list of -(length, contents) pairs rather than a list of null-terminated strings. -A length of zero indicates the end of the list. - -\begin{funcdecl}{krb5_copy_principal}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_const_principal}{inprinc} -\funcout -\funcarg{krb5_principal *}{outprinc} -\end{funcdecl} - -Copy a principal structure, filling in \funcparam{*outprinc} to point to -the newly allocated copy, which should be freed with -\funcname{krb5_free_principal}. - -\begin{funcdecl}{krb5_principal_compare}{krb5_boolean}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_const_principal}{princ1} -\funcarg{krb5_const_principal}{princ2} -\end{funcdecl} - -If the two principals are the same, return TRUE, else return FALSE. - -\begin{funcdecl}{krb5_realm_compare}{krb5_boolean}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_const_principal}{princ1} -\funcarg{krb5_const_principal}{princ2} -\end{funcdecl} - -If the realms of the two principals are the same, return TRUE, else -return FALSE. - - -\begin{funcdecl}{krb5_425_conv_principal}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const char *}{name} -\funcarg{const char *}{instance} -\funcarg{const char *}{realm} -\funcout -\funcarg{krb5_principal *}{princ} -\end{funcdecl} - -Build a principal \funcparam{princ} from a V4 specification made up of -\funcparam{name}.\funcparam{instance}@\funcparam{realm}. The routine is -site-customized to convert the V4 naming scheme to a V5 one. For -instance, the V4 ``rcmd'' is changed to ``host''. - -The returned principal should be freed with -\funcname{krb5_free_principal}. - -\subsubsection{The application functions} - -\begin{funcdecl}{krb5_encode_kdc_rep}{krb5_error_code}{\funcin} -\funcarg{const krb5_msgtype}{type} -\funcarg{const krb5_enc_kdc_rep_part *}{encpart} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_keyblock *}{client_key} -\funcinout -\funcarg{krb5_kdc_rep *}{dec_rep} -\funcout -\funcarg{krb5_data **}{enc_rep} -\end{funcdecl} - -\internalfunc - -Takes KDC rep parts in \funcparam{*rep} and \funcparam{*encpart}, and -formats it into \funcparam{*enc_rep}, using message type -\funcparam{type} and encryption key \funcparam{client_key} and -encryption block \funcparam{eblock}. - -\funcparam{enc_rep{\ptsto}data} will point to allocated storage upon -non-error return; the caller should free it when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_decode_kdc_rep}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_data *}{enc_rep} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_enctype}{etype} -\funcout -\funcarg{krb5_kdc_rep **}{dec_rep} -\end{funcdecl} - -\internalfunc - -Takes a KDC_REP message and decrypts encrypted part using -\funcparam{etype} and \funcparam{*key}, putting result in \funcparam{*dec_rep}. -The pointers in \funcparam{dec_rep} -are all set to allocated storage which should be freed by the caller -when finished with the response (by using \funcname{krb5_free_kdc_rep}). - - -If the response isn't a KDC_REP (tgs or as), it returns an error from -the decoding routines. - -Returns errors from encryption routines, system errors. - -\begin{funcdecl}{krb5_kdc_rep_decrypt_proc}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_keyblock *}{key} -\funcarg{krb5_const_pointer}{decryptarg} -\funcinout -\funcarg{krb5_kdc_rep *}{dec_rep} -\end{funcdecl} - -Decrypt the encrypted portion of \funcparam{dec_rep}, using the -encryption key \funcparam{key}. The parameter \funcparam{decryptarg} is -ignored. - -The result is in allocated storage pointed to by -\funcparam{dec_rep{\ptsto}enc_part2}, unless some error occurs. - -This function is suitable for use as the \funcparam{decrypt_proc} -argument to \funcname{krb5_get_in_tkt}. - -\begin{funcdecl}{krb5_encrypt_tkt_part}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_keyblock *}{srv_key} -\funcinout -\funcarg{krb5_ticket *}{dec_ticket} -\end{funcdecl} - -\internalfunc - -\begin{sloppypar} -Encrypts the unecrypted part of the ticket found in -\funcparam{dec_ticket{\ptsto}enc_part2} using -\funcparam{srv_key}, and places result in -\funcparam{dec_ticket{\ptsto}enc_part}. -The \funcparam{dec_ticket{\ptsto}enc_part} will be allocated by this -function. -\end{sloppypar} - -Returns errors from encryption routines, system errors - -\funcparam{enc_part{\ptsto}data} is allocated and filled in with -encrypted stuff. - -\begin{funcdecl}{krb5_decrypt_tkt_part}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_keyblock *}{srv_key} -\funcinout -\funcarg{krb5_ticket *}{dec_ticket} -\end{funcdecl} - -\internalfunc - -Takes encrypted \funcparam{dec_ticket{\ptsto}enc_part}, decrypts with -\funcparam{dec_ticket{\ptsto}etype} -using \funcparam{srv_key}, and places result in -\funcparam{dec_ticket{\ptsto}enc_part2}. The storage of -\funcparam{dec_ticket{\ptsto}enc_part2} will be allocated before return. - -Returns errors from encryption routines, system errors - -\begin{funcdecl}{krb5_send_tgs}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_flags}{kdcoptions} -\funcarg{const krb5_ticket_times *}{timestruct} -\funcarg{const krb5_enctype *}{etypes} -\funcarg{const krb5_cksumtype}{sumtype} -\funcarg{krb5_const_principal}{sname} -\funcarg{krb5_address * const *}{addrs} -\funcarg{krb5_authdata * const *}{authorization_data} -\funcarg{krb5_pa_data * const *}{padata} -\funcarg{const krb5_data *}{second_ticket} -\funcinout -\funcarg{krb5_creds *}{in_cred} -\funcout -\funcarg{krb5_response *}{rep} -\end{funcdecl} - -\internalfunc - -Sends a request to the TGS and waits for a response. -\funcparam{kdcoptions} is used for the options in the KRB_TGS_REQ. -\funcparam{timestruct} values are used for from, till, and rtime in the -KRB_TGS_REQ. -\funcparam{etypes} is a list of etypes used in the KRB_TGS_REQ. -\funcparam{sumtype} is used for the checksum in the AP_REQ in the KRB_TGS_REQ. -\funcparam{sname} is used for sname in the KRB_TGS_REQ. -\funcparam{addrs}, if non-NULL, is used for addresses in the KRB_TGS_REQ. -\funcparam{authorization_data}, if non-NULL, is used for -\funcparam{authorization_data} in the KRB_TGS_REQ. -\funcparam{padata}, if non-NULL, is combined with any other supplied -pre-authentication data for the KRB_TGS_REQ. -\funcparam{second_ticket}, if required by options, is used for the 2nd -ticket in the KRB_TGS_REQ. -\funcparam{in_cred} is used for the ticket and session key in the KRB_AP_REQ header in the KRB_TGS_REQ. - -The KDC realm is extracted from \funcparam{in_cred{\ptsto}server}'s realm. - -The response is placed into \funcparam{*rep}. -\funcparam{rep{\ptsto}response.data} is set to point at allocated storage -which should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_get_cred_from_kdc}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_ccache}{ccache} -\funcarg{krb5_creds *}{in_cred} -\funcout -\funcarg{krb5_cred **}{out_cred} -\funcarg{krb5_creds ***}{tgts} -\end{funcdecl} - - -Retrieve credentials for principal \funcparam{in_cred{\ptsto}client}, -server \funcparam{creds{\ptsto}server}, possibly -\funcparam{creds{\ptsto}second_ticket} if needed by the ticket flags. - -\funcparam{ccache} is used to fetch initial TGT's to start the authentication -path to the server. - -Credentials are requested from the KDC for the server's realm. Any -TGT credentials obtained in the process of contacting the KDC are -returned in an array of credentials; \funcparam{tgts} is filled in to -point to an array of pointers to credential structures (if no TGT's were -used, the pointer is zeroed). TGT's may be returned even if no useful -end ticket was obtained. - -The returned credentials are NOT cached. - -If credentials are obtained, \funcparam{creds} is filled in with the results; -\funcparam{creds{\ptsto}ticket} and -\funcparam{creds{\ptsto}keyblock{\ptsto}key} are set to allocated storage, -which should be freed by the caller when finished. - -Returns errors, system errors. - -\begin{funcdecl}{krb5_get_cred_via_tkt}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_creds *}{tkt} -\funcarg{const krb5_flags}{kdcoptions} -\funcarg{krb5_address *const *}{address} -\funcarg{krb5_creds *}{in_cred} -\funcout -\funcarg{krb5_creds **}{out_cred} -\end{funcdecl} - -Takes a ticket \funcparam{tkt} and a target credential -\funcparam{in_cred}, attempts to fetch a TGS from the KDC. Upon -success the resulting is stored in \funcparam{out_cred}. The memory -allocated in \funcparam{out_cred} should be freed by the called when -finished by using \funcname{krb5_free_creds}. - -\funcparam{kdcoptions} refers to the options as listed in Table -\ref{KDCOptions}. The optional \funcparam{address} is used for addressed -in the KRB_TGS_REQ (see \funcname{krb5_send_tgs}). - -Returns errors, system errors. - - -\begin{funcdecl}{krb5_get_credentials}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_flags}{options} -\funcarg{krb5_ccache}{ccache} -\funcarg{krb5_creds *}{in_creds} -\funcout -\funcarg{krb5_creds *}{out_creds} -\end{funcdecl} - -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{in_creds{\ptsto}client}, with following information: -\begin{itemize} -\item {\bf The server} identified by \funcparam{in_creds{\ptsto}server} -\item {\bf The options} in \funcparam{options}. -Valid choices are KRB5_GC_USER_USER and KRB5_GC_GC_CACHED -\item {\bf The expiration date} specified in -\funcparam{in_creds{\ptsto}times.endtime} -\item {\bf The session key type} specified in -\funcparam{in_creds{\ptsto}keyblock.keytype} if it is non-zero. -\end{itemize} - -If \funcparam{options} specifies KRB5_GC_CACHED, -then \funcname{krb5_get_credentials} will only search the credentials cache -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{in_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 minimum of the following: -\begin{itemize} -\item The expiration date as specified in -\funcparam{in_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{in_creds{\ptsto}authdata}. If there -is no special authorization data to be passed, -\funcparam{in_creds{\ptsto}authdata} should be NULL. - -Any returned ticket and intermediate ticket-granting tickets are -stored in \funcparam{ccache}. - -Returns errors from encryption routines, system errors. - -\begin{funcdecl}{krb5_get_in_tkt}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_enctype *}{etypes} -\funcarg{const krb5_preauthtype *}{ptypes} -\funcfuncarg{krb5_error_code}{(*key_proc)} - \funcarg{krb5_context}{context} - \funcarg{const krb5_keytype}{type} - \funcarg{krb5_data *}{salt} - \funcarg{krb5_const_pointer}{keyseed} - \funcarg{krb5_keyblock **}{key} -\funcendfuncarg -\funcarg{krb5_const_pointer}{keyseed} -\funcfuncarg{krb5_error_code}{(*decrypt_proc)} - \funcarg{krb5_context}{context} - \funcarg{const krb5_keyblock *}{key} - \funcarg{krb5_const_pointer}{decryptarg} - \funcarg{krb5_kdc_rep *}{dec_rep} -\funcendfuncarg -\funcarg{krb5_const_pointer}{decryptarg} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_ccache}{ccache} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\end{funcdecl} - -This all-purpose initial ticket routine, usually called via -\funcname{krb5_get_in_tkt_with_skey} or -\funcname{krb5_get_in_tkt_with_password} or -\funcname{krb5_get_in_tkt_with_keytab}. - - -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} (listed in Table \ref{KDCOptions}); -and \funcparam{ptypes}, the preauthentication -method (valid preauthentication methods are listed in Table -\ref{padata-types}). -\funcname{krb5_get_in_tkt} requests encryption type -\funcparam{etypes} (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. - -\funcparam{key_proc} is called, with \funcparam{context}, \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 -\funcparam{dec_rep{\ptsto}enc_part2}. -\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 -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}. - -If \funcparam{etypes} is non-NULL, the it is used as for the list of -valid encyrption types. Otherwise, the context default is used (as -returned by \funcname{krb5_get_default_in_tkt_etypes}. - -A succesful call will place the ticket in the credentials cache -\funcparam{ccache} and fill in \funcparam{creds} with the ticket -information used/returned. - -Returns system errors, 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}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_enctype *}{etypes} -\funcarg{const krb5_preauthtype *}{pre_auth_types} -\funcarg{const char *}{password} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\end{funcdecl} - -Attempts to get an initial ticket using the null-terminated string -\funcparam{password}. If \funcparam{password} is NULL, the password -is read from the terminal using as a prompt the globalname -\globalname{krb5_default_pwd_prompt1}. - -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. - -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, preauthentication errors, encryption errors. - -\begin{funcdecl}{krb5_get_in_tkt_with_keytab}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_enctype *}{etypes} -\funcarg{const krb5_preauthtype *}{pre_auth_types} -\funcarg{const krb5_keytab *}{keytab} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\end{funcdecl} - -Attempts to get an initial ticket using \funcparam{keytab}. If -\funcparam{keytab} is NULL, the default keytab is used -(e.g., \filename{/etc/v5srvtab}). - -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. - -Returns system errors, preauthentication errors, encryption errors. - -\begin{funcdecl}{krb5_get_in_tkt_with_skey}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_enctype *}{etypes} -\funcarg{const krb5_preauthtype *}{pre_auth_types} -\funcarg{const krb5_keyblock *}{key} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\end{funcdecl} - -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}). - -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. - -Returns system errors, preauthentication errors, encryption errors. - -\begin{funcdecl}{krb5_mk_req}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context *}{auth_context} -\funcin -\funcarg{const krb5_flags}{ap_req_options} -\funcarg{char *}{service} -\funcarg{char *}{hostname} -\funcarg{krb5_data *}{in_data} -\funcinout -\funcarg{krb5_ccache}{ccache} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_AP_REQ message into \funcparam{outbuf}. - -The server to receive the message is specified by -\funcparam{hostname}. The principal of the server to receive the message -is specified by \funcparam{hostname} and \funcparam{service}. -If credentials are not present in the credentials cache -\funcparam{ccache} for this server, the TGS request with default -parameters is used in an attempt to obtain such credentials, and they -are stored in \funcparam{ccache}. - -\funcparam{ap_req_options} specifies the KRB_AP_REQ options desired. -Valid options are: - -\begin{tabular}{ll} -AP_OPTS_USE_SESSION_KEY&\\ -AP_OPTS_MUTUAL_REQUIRED&\\ -\end{tabular} -\label{ap-req-options} - -The checksum method to be used is as specified in \funcparam{auth_context}. - -% 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. - -\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}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context *}{auth_context} -\funcin -\funcarg{const krb5_flags}{ap_req_options} -\funcarg{krb5_data *}{in_data} -\funcarg{krb5_creds *}{in_creds} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_AP_REQ message into \funcparam{outbuf}, with more complete -options than \funcname{krb5_mk_req}. - -\funcparam{outbuf}, \funcparam{ap_req_options}, \funcparam{auth_context}, -and \funcparam{ccache} are used in the same fashion as for -\funcname{krb5_mk_req}. - -\funcparam{in_creds} is used to supply the credentials (ticket and session -key) needed to form the request. - -If \funcparam{in_creds{\ptsto}ticket} has no data (length == 0), then an -error is returned. - -During this call, the structure elements in \funcparam{in_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. - - -If \funcparam{ap_req_options} specifies AP_OPTS_USE_SUBKEY, then a -subkey will be generated if need be by \funcname{krb5_generate_subkey}. - -A copy of the authenticator will be stored in the -\funcparam{auth_context}, 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.) - -Returns system errors, errors contacting the KDC, KDC errors getting -a new ticket for the authenticator. - -\begin{funcdecl}{krb5_generate_subkey}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_keyblock *}{key} -\funcout -\funcarg{krb5_keyblock **}{subkey} -\end{funcdecl} - -Generates a pseudo-random sub-session key using the encryption system's -random key functions, based on the input \funcparam{key}. - -\funcparam{subkey} is filled in to point to the generated subkey, unless -an error is returned. The returned key (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}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context *}{auth_context} -\funcin -\funcarg{const krb5_data *}{inbuf} -\funcarg{krb5_const_principal}{server} -\funcarg{krb5_keytab}{keytab} -\funcinout -\funcarg{krb5_flags *}{ap_req_options} -\funcout -\funcarg{krb5_ticket **}{ticket} -\end{funcdecl} - -Parses a KRB_AP_REQ message, returning its contents. Upon successful -return, if \funcparam{ticket} is non-NULL, \funcparam{*ticket} will be -modified to point to allocated storage containing the ticket -information. The caller is responsible for deallocating this space by -using \funcname{krb5_free_ticket}. - -\funcparam{inbuf} should contain the KRB_AP_REQ message to be parsed. - -If \funcparam{auth_context} is NULL, one will be generated and freed -internally by the function. - -\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. - -If \funcparam{server} is not NULL, and a replay detaction cache has not been -established with the \funcparam{auth_context}, one will be generated. - -\funcparam{keytab} specifies a keytab containing generate a decryption key. If -NULL, \funcparam{krb5_kt_default} will be used to find the default -keytab and the key taken from there\footnote{i.e., srvtab file in -Kerberos V4 parlance}. - - -If a keyblock is present in the \funcparam{auth_context}, it will be -used to decrypt the ticket request and the keyblock freed with -\funcname{krb5_free_keyblock}. This is useful for user to user -authentication. If no keyblock is specified, the \funcparam{keytab} is -consulted for an entry matching the requested keytype, server and -version number and used instead. - -The authentcator in the request is decrypted and stored in the -\funcparam{auth_context}. The client specified in the decrypted -authenticator is compared to the client specified in the decoded ticket -to ensure that the compare. - -If the remote_addr portion of the \funcparam{auth_context} is set, -then this routine checks if the request came from the right client. - -\funcparam{sender_addr} specifies the address(es) expected to be present -in the ticket. - -The replay cache is checked to see if the ticket and authenticator have -been seen and if so, returns an error. If not, the ticket and -authenticator are entered into the cache. - -Various other checks are made of the decoded data, including, -cross-realm policy, clockskew and ticket validation times. - -The keyblock, subkey, and sequence number of the request are all stored -in the \funcparam{auth_context} for future use. - -If the request has the AP_OPTS_MUTUAL_REQUIRED bit set, the local -sequence number, which is stored in the auth_context, is XORed with the -remote sequence number in the request. - -If \funcparam{ap_req_options} is non-NULL, it will be set to contain the -application request flags. - -Returns system errors, encryption errors, replay errors. - -\begin{funcdecl}{krb5_rd_req_decoded}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context *}{auth_context} -\funcin -\funcarg{const krb5_ap_req *}{req} -\funcarg{krb5_const_principal}{server} -\funcinout -\funcarg{krb5_keytab}{keytab} -\funcout -\funcarg{krb5_ticket **}{ticket} -\end{funcdecl} - -Essentially the same as \funcname{krb5_rd_req}, but uses a decoded AP_REQ -as the input rather than an encoded input. - -\begin{funcdecl}{krb5_mk_rep}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats and encrypts an AP_REP message, including in it the data in the -authentp portion of \funcparam{auth_context}, encrypted using the -keyblock portion of \funcparam{auth_context}. - -When successful, \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. - -If the flags in \funcparam{auth_context} indicate that a sequence number -should be used (either {\sc KRB5_AUTH_CONTEXT_DO_SEQUENCE} or -{\sc KRB5_AUTH_CONTEXT_RET_SEQUENCE}) and the local sequqnce number in the -\funcparam{auth_context} is 0, a new number will be generated with -\funcname{krb5_generate_seq_number}. - -Returns system errors. - -\begin{funcdecl}{krb5_rd_rep}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{const krb5_data *}{inbuf} -\funcout -\funcarg{krb5_ap_rep_enc_part **}{repl} -\end{funcdecl} - -Parses and decrypts an AP_REP message from \funcparam{*inbuf}, filling in -\funcparam{*repl} with a pointer 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 keyblock stored in \funcparam{auth_context} is used to decrypt the -message after establishing any key pre-processing with -\funcname{krb5_process_key}. - -Returns system errors, encryption errors, replay errors. - -\begin{funcdecl}{krb5_mk_error}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_error *}{dec_err} -\funcout -\funcarg{krb5_data *}{enc_err} -\end{funcdecl} - -Formats the error structure \funcparam{*dec_err} into an error buffer -\funcparam{*enc_err}. - -The error buffer storage (\funcparam{enc_err{\ptsto}data}) is -allocated, and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_rd_error}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_data *}{enc_errbuf} -\funcout -\funcarg{krb5_error **}{dec_error} -\end{funcdecl} - -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 freeing this structure by -using \funcname{krb5_free_error}. - -Returns system errors. - -\begin{funcdecl}{krb5_generate_seq_number}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_keyblock *}{key} -\funcout -\funcarg{krb5_int32 *}{seqno} -\end{funcdecl} - -Generates a pseudo-random sequence number suitable for use as an initial -sequence number for the KRB_SAFE and KRB_PRIV message processing -routines. - -\funcparam{key} parameterizes the choice of the random sequence number, -which is filled into \funcparam{*seqno} upon return. - -\begin{funcdecl}{krb5_sendauth}{krb5_error_code} -\funcinout -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context *}{auth_context} -\funcin -\funcarg{krb5_pointer}{fd} -\funcarg{char *}{appl_version} -\funcarg{krb5_principal}{client} -\funcarg{krb5_principal}{server} -\funcarg{krb5_flags}{ap_req_options} -\funcarg{krb5_data *}{in_data} -\funcarg{krb5_creds *}{in_creds} -\funcinout -\funcarg{krb5_ccache}{ccache} -\funcout -\funcarg{krb5_error **}{error} -\funcarg{krb5_ap_rep_enc_part **}{rep_result} -\funcarg{krb5_creds **}{out_creds} -\end{funcdecl} - -\funcname{krb5_sendauth} provides a convenient means for client and -server programs to send authenticated messages to one another through -network connections. \funcname{krb5_sendauth} sends an authenticated -ticket from the client program to the server program using the network -connection specified by \funcparam{fd}. In the MIT Unix implementation, -\funcparam{fd} should be a pointer to a file descriptor describing the -network socket. This can be changed in other implementations, however, -if the routines \funcname{krb5_read_message}, -\funcname{krb5_write_message}, \funcname{krb5_net_read}, and -\funcname{krb5_net_write} are changed. - -The paramter \funcparam{appl_version} is a string describing the -application protocol version which the client is expecting to use for -this exchange. If the server is using a different application protocol, -an error will be returned. - -The parameters \funcparam{client} and \funcparam{server} specify the -kerberos principals for the client and the server. They are -ignored if \funcparam{in_creds} 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. - -If \funcparam{in_creds} is non-null, then -\funcparam{in_creds{\ptsto}client} and -\funcparam{in_creds{\ptsto}server} must be filled in, and either -the other structure fields should be filled in with valid credentials, -or \funcparam{in_creds{\ptsto}ticket.length} should be zero. If -\funcparam{in_creds{\ptsto}ticket.length} is non-zero, then -\funcparam{in_creds} 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{out_creds} -, if not NULL, is filled in with the retrieved credentials. - -\funcname{ccache} specifies the credential cache to use when one is -needed (i.e., when \funcname{in_creds} is null or -\funcparam{in_creds{\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 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.) - -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}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context *}{auth_context} -\funcin -\funcarg{krb5_pointer}{fd} -\funcarg{char *}{appl_version} -\funcarg{krb5_principal}{server} -\funcarg{char *}{rc_type} -\funcarg{krb5_int32}{flags} -\funcarg{krb5_keytab}{keytab} -\funcout -\funcarg{krb5_ticket **}{ticket} -\end{funcdecl} - -\funcname{krb5_recvauth} provides a convenient means for client and -server programs to send authenticated messages to one another through -network connections. \funcname{krb5_sendauth} is the matching routine -to \funcname{krb5_recvauth} for the server. \funcname{krb5_recvauth} -will engage in an authentication dialogue with the -client program running \funcname{krb5_sendauth} to authenticate the -client to the server. In addition, if requested by the client, -\funcname{krb5_recvauth} will provide mutual authentication to -prove to the client that the server represented by -\funcname{krb5_recvauth} is legitimate. - -\funcparam{fd} is a pointer to the network connection. As in -\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 -this exchange. If the client is using a different application protocol, -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. - -The parameters \funcparam{server}, \funcparam{auth_context}, -and \funcparam{keytab} are used by \funcname{krb5_rd_req} to obtain the -server's private key. - -If \funcparam{server} is non-null, the princicpal component of it is -ysed to determine the replay cache to use. Otherwise, -\funcname{krb5_recvauth} will use a default replay cache. - -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. - -\funcparam{ticket} is optional and is only filled in if non-null. It is -filled 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}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{const krb5_data *}{userdata} -\funcout -\funcarg{krb5_data *}{outbuf} -\funcinout -\funcarg{krb5_replay_data *}{outdata} -\end{funcdecl} - -Formats a KRB_SAFE message into \funcparam{outbuf}. - -\funcparam{userdata} is formatted as the user data in the message. -Portions of \funcparam{auth_context} specify the checksum type; the -keyblockm which might be used to seed the checksum; -full addresses (host and port) for the sender and receiver. -The \funcparam{local_addr} portion of \funcparam{*auth_context} -is used to form the addresses usedin the KRB_SAFE message. The \funcparam{remote_addr} is optional; if the -receiver's address is not known, it may be replaced by NULL. -\funcparam{local_addr}, however, is mandatory. - -The \funcparam{auth_context} flags select whether sequence numbers or -timestamps should be used to identify the message. Valid flags are -listed below. - -\begin{tabular}{ll} -\multicolumn{1}{c}{Symbol} & Meaning \\ -KRB5_AUTH_CONTEXT_DO_TIME & Use timestamps\\ - &\ and replay cache\\ -KRB5_AUTH_CONTEXT_RET_TIME & Copy timestamp \\ - &\ to \funcparam{*outdata} \\ -KRB5_AUTH_CONTEXT_DO_SEQUENCE & Use sequence numbers \\ -KRB5_AUTH_CONTEXT_RET_SEQUENCE & Copy sequence numbers\\ - &\ to \funcparam{*outdata} \\ -\end{tabular} - -If timestamps are to be used (i.e., if KRB5_AUTH_CONTEXT_DO_TIME is -set), an entry describing the message will be entered in the replay -cache so that the caller may detect if this message is sent -back to him by an attacker. If KRB5_AUTH_CONTEXT_DO_TIME is not set, -the \funcparam{auth_context} replay cache is not used. - -If sequence numbers are to be used (i.e., if either -KRB5_AUTH_CONTEXT_DO_SEQUENCE or KRB5_AUTH_CONTEXT_RET_SEQUENCE is -set), then \funcparam{auth_context} local sequence number will be -placed in the protected message as its sequence number. - -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, encryption errors. - -\begin{funcdecl}{krb5_rd_safe}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{const krb5_data *}{inbuf} -\funcout -\funcarg{krb5_data *}{outbuf} -\funcinout -\funcarg{krb5_replay_data *}{outdata} -\end{funcdecl} - -Parses a KRB_SAFE message from \funcparam{inbuf}, placing the -data in \funcparam{*outbuf} after verifying its integrity. - -The keyblock used for verifying the integrity of the message is taken -from the \funcparam{auth_context} recv\_subkey or keyblock. The -keyblock is chosen in the above order by the first one which is not -NULL. - -The remote_addr and localaddr portions of the \funcparam{*auth_context} -specify the full addresses (host and port) of the sender and receiver, -and must be of type \datatype{ADDRTYPE_ADDRPORT}. - - -The \funcparam{remote_addr} parameter is mandatory; it -specifies the address of the sender. If the address of the sender in -the message does not match \funcparam{remote_addr}, the error -KRB5KRB_AP_ERR_BADADDR will be returned. - -If \funcparam{local_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}. If the check fails, -KRB5KRB_AP_ERR_BADARRD is returned. - -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 auth_context_flags portion of \funcparam{auth_context} indicates -that sequence numbers are to be used (i.e., if KRB5_AUTH_CONTEXT_DOSEQUENCE is -set in it), The \funcparam{remote_seq_number} portion of -\funcparam{auth_context} is compared to the sequence number for the -message, and KRB5_KRB_AP_ERR_BADORDER is returned if it does not match. -Otherwise, the sequence number is not used. - - -If timestamps are to be used (i.e., if KRB5_AUTH_CONTEXT_DO_TIME is set -in the \funcparam{auth_context}), then two 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 message must not be a replayed message, according to - \funcparam{rcache}. -\end{itemize} - -Returns system errors, integrity errors. - -\begin{funcdecl}{krb5_mk_priv}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{const krb5_data *}{userdata} -\funcout -\funcarg{krb5_data *}{outbuf} -\funcarg{krb5_replay_data *}{outdata} -\end{funcdecl} - -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{inbuf}, \funcparam{auth_context}, -\funcparam{outdata} and -\funcparam{outbuf} function as in \funcname{krb5_mk_safe}. - -As in \funcname{krb5_mk_safe}, the remote_addr and remote_port part of -the \funcparam{auth_context} is optional; if the receiver's address is -not known, it may be replaced by NULL. The local_addr, however, is -mandatory. - -The encryption type is taken from the \funcparam{auth_context} keyblock -portion. If i_vector portion of the \funcparam{auth_context} -is non-null, it is used as an initialization vector for the encryption -(if the chosen encryption type supports initialization vectors) -and its contents are replaced with the last block of encrypted data -upon return. - -The flags from the \funcparam{auth_context} selects whether sequence numbers or timestamps -should be used to identify the message. Valid flags are listed below. - -\begin{tabular}{ll} -\multicolumn{1}{c}{Symbol} & Meaning \\ -KRB5_AUTH_CONTEXT_DO_TIME& Use timestamps in replay cache\\ -KRB5_AUTH_CONTEXT_RET_TIME& Use timestamps in output data\\ -KRB5_AUTH_CONTEXT_DO_SEQUENCE& Use sequence numbers\\ - &\ in replay cache\\ -KRB5_AUTH_CONTEXT_RET_SEQUENCE& Use sequence numbers\\ - &\ in replay cache and output data \\ -\end{tabular} - -Returns system errors, encryption errors. - -\begin{funcdecl}{krb5_rd_priv}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context}{auth_context} -\funcin -\funcarg{const krb5_data *}{inbuf} -\funcout -\funcarg{krb5_data *}{outbuf} -\funcarg{krb5_data *}{outdata} -\end{funcdecl} - -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{inbuf}, \funcparam{auth_context}, -\funcparam{outdata} and \funcparam{outbuf} -function as in \funcname{krb5_rd_safe}. - - -The remote_addr part of the \funcparam{auth_context} as set by -\funcname{krb5_auth_con_setaddrs} is mandatory; it -specifies the address of the sender. If the address of the sender in -the message does not match the remote_addr, the error -KRB5KRB_AP_ERR_BADADDR will be returned. - -If local_addr portion of the auth_context 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{keyblock} portion of \funcparam{auth_context} specifies -the key to be used for decryption of the message. If the -\funcparam{i_vector} element, 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. - -The \funcparam{auth_context} flags specify whether timestamps -(KRB5_AUTH_CONTEXT_DO_TIME) and sequence numbers -(KRB5_AUTH_CONTEXT_DO_SEQUENCE) are to be used. - -Returns system errors, integrity errors. - -\subsubsection{Miscellaneous main functions} - -\begin{funcdecl}{krb5_address_search}{krb5_boolean}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_address *}{addr} -\funcarg{krb5_address * const *}{addrlist} -\end{funcdecl} - -If \funcparam{addr} is listed in \funcparam{addrlist}, or -\funcparam{addrlist} is null, return TRUE. If not listed, return FALSE. - -\begin{funcdecl}{krb5_address_compare}{krb5_boolean}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_address *}{addr1} -\funcarg{const krb5_address *}{addr2} -\end{funcdecl} - -If the two addresses are the same, return TRUE, else return FALSE. - -\begin{funcdecl}{krb5_fulladdr_order}{int}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_fulladdr *}{addr1} -\funcarg{const krb5_fulladdr *}{addr2} -\end{funcdecl} - -Return an ordering on the two full addresses: 0 if the same, -$< 0$ if first is less than 2nd, $> 0$ if first is greater than 2nd. - -\begin{funcdecl}{krb5_address_order}{int}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_address *}{addr1} -\funcarg{const krb5_address *}{addr2} -\end{funcdecl} - -Return an ordering on the two addresses: 0 if the same, -$< 0$ if first is less than 2nd, $> 0$ if first is greater than 2nd. - -\begin{funcdecl}{krb5_copy_addresses}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_address * const *}{inaddr} -\funcout -\funcarg{krb5_address ***}{outaddr} -\end{funcdecl} - -Copy addresses in \funcparam{inaddr} to \funcparam{*outaddr} which is -allocated memory and should be freed with \funcname{krb5_free_addresses}. - -\begin{funcdecl}{krb5_copy_authdata}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_authdata * const *}{inauthdat} -\funcout -\funcarg{krb5_authdata ***}{outauthdat} -\end{funcdecl} - -Copy an authdata structure, filling in \funcparam{*outauthdat} to point to the -newly allocated copy, which should be freed with -\funcname{krb5_free_authdata}. - -\begin{funcdecl}{krb5_copy_authenticator}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_authenticator *}{authfrom} -\funcout -\funcarg{krb5_authenticator **}{authto} -\end{funcdecl} - -Copy an authenticator structure, filling in \funcparam{*outauthdat} to -point to the newly allocated copy, which should be freed with -\funcname{krb5_free_authenticator}. - -\begin{funcdecl}{krb5_copy_keyblock}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_keyblock *}{from} -\funcout -\funcarg{krb5_keyblock **}{to} -\end{funcdecl} - -Copy a keyblock, filling in \funcparam{*to} to point to the newly -allocated copy, which should be freed with -\funcname{krb5_free_keyblock}. - -\begin{funcdecl}{krb5_copy_keyblock_contents}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_keyblock *}{from} -\funcout -\funcarg{krb5_keyblock *}{to} -\end{funcdecl} - -Copy keyblock contents from \funcparam{from} to \funcparam{to}, including -allocated storage. The allocated storage in \funcparam{to} should be -freed by using {\bf free}(\funcparam{to->contents}). - -\begin{funcdecl}{krb5_copy_checksum}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_checksum *}{ckfrom} -\funcout -\funcarg{krb5_checksum **}{ckto} -\end{funcdecl} - -Copy a checksum structure, filling in \funcparam{*ckto} to point to -the newly allocated copy, which should be freed with -\funcname{krb5_free_checksum}. - -\begin{funcdecl}{krb5_copy_creds}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_creds *}{incred} -\funcout -\funcarg{krb5_creds **}{outcred} -\end{funcdecl} - -Copy a credentials structure, filling in \funcparam{*outcred} to point -to the newly allocated copy, which should be freed with -\funcname{krb5_free_creds}. - -\begin{funcdecl}{krb5_copy_data}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_data *}{indata} -\funcout -\funcarg{krb5_data **}{outdata} -\end{funcdecl} - -Copy a data structure, filling in \funcparam{*outdata} to point to the -newly allocated copy, which should be freed with \funcname{krb5_free_data}. - -\begin{funcdecl}{krb5_copy_ticket}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_ticket *}{from} -\funcout -\funcarg{krb5_ticket **}{pto} -\end{funcdecl} - -Copy a ticket structure, filling in \funcparam{*pto} to point to -the newly allocated copy, which should be freed with -\funcname{krb5_free_ticket}. - - -\begin{funcdecl}{krb5_get_server_rcache}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const krb5_data *}{piece} -\funcout -\funcarg{krb5_rcache *}{ret_rcache} -\end{funcdecl} - -Generate a replay cache name, allocate space for its handle, and open -it. \funcparam{piece} is used to distinguish this replay cache from -others currently in use on the system. 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}. - - diff --git a/doc/api/krb5idx.sty b/doc/api/krb5idx.sty deleted file mode 100644 index 729ed9779b..0000000000 --- a/doc/api/krb5idx.sty +++ /dev/null @@ -1,10 +0,0 @@ -\usepackage{makeidx} - -% The following defintions are for our indexing scheme. Stolen from -% doc.sty. -\def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus 1fill}% -\def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil}% -\def\efill{\hfill\nopagebreak}% -\def\pfill{\unskip~\dotfill\penalty500\strut\nobreak - \dotfil~\ignorespaces}% -%% diff --git a/doc/api/libdes.tex b/doc/api/libdes.tex deleted file mode 100644 index 71e75c59b2..0000000000 --- a/doc/api/libdes.tex +++ /dev/null @@ -1,38 +0,0 @@ -\documentstyle[fixunder,functions,twoside]{article} -\setlength{\oddsidemargin}{0.25in} -\setlength{\evensidemargin}{-0.25in} -\setlength{\topmargin}{-.5in} -\setlength{\textheight}{9in} -\setlength{\parskip}{.1in} -\setlength{\parindent}{2em} -\setlength{\textwidth}{6.25in} - -\pagestyle{headings} -\begin{document} -\begin{center} -{\Huge Kerberos V5 Data Encryption Standard library} \\ -{\Large DRAFT} -\end{center} -\section{DES functions} -The DES functions conform to the encryption interface required by the -Kerberos version 5 library, and provide an encryption mechanism based on -the DES Cipher-block chaining mode (CBC), with the addition of a -cyclical redundancy check (CRC-32) for integrity checking upon -decryption. - -The functions have the same signatures as those described by the main -library document; the names are: -{\obeylines -\funcname{mit_des_encrypt_func} -\funcname{mit_des_decrypt_func} -\funcname{mit_des_process_key} -\funcname{mit_des_finish_key} -\funcname{mit_des_string_to_key} -\funcname{mit_des_init_random_key} -\funcname{mit_des_finish_random_key} -\funcname{mit_des_random_key} -} -The \datatype{krb5_cryptosystem_entry} for this cryptosystem is -\globalname{mit_des_cryptosystem_entry}. - -\end{document} diff --git a/doc/api/libos.tex b/doc/api/libos.tex deleted file mode 100644 index 447044fec6..0000000000 --- a/doc/api/libos.tex +++ /dev/null @@ -1,486 +0,0 @@ -The operating-system specific functions provide an interface between the -other parts of the \libname{libkrb5.a} libraries and the operating system. - -Beware! Any of the functions below are allowed to be implemented as -macros. Prototypes for functions can be found in {\tt -}; other definitions (including macros, if used) are -in {\tt }. - -The following global symbols are provided in \libname{libos.a}. If you -wish to substitute for any of them, you must substitute for all of them -(they are all declared and initialized in the same object file): -\begin{description} -% These come from src/lib/osconfig.c -\item[extern char *\globalname{krb5_defkeyname}:] default name of key -table file -\item[extern char *\globalname{krb5_lname_file}:] name of aname/lname -translation database -\item[extern int \globalname{krb5_max_dgram_size}:] maximum allowable -datagram size -\item[extern int \globalname{krb5_max_skdc_timeout}:] maximum -per-message KDC reply timeout -\item[extern int \globalname{krb5_skdc_timeout_shift}:] shift factor -(bits) to exponentially back-off the KDC timeouts -\item[extern int \globalname{krb5_skdc_timeout_1}:] initial KDC timeout -\item[extern char *\globalname{krb5_kdc_udp_portname}:] name of KDC UDP port -\item[extern char *\globalname{krb5_default_pwd_prompt1}:] first prompt -for password reading. -\item[extern char *\globalname{krb5_default_pwd_prompt2}:] second prompt - -\end{description} - -\subsubsection{Operating specific context} -The \datatype{krb5_context} has space for operating system specific -data. These functions are called from \funcname{krb5_init_context} and -\funcname{krb5_free_context}, but are included here for completeness. - -\begin{funcdecl}{krb5_os_init_context}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\end{funcdecl} - -\internalfunc - -Initializes \funcparam{context{\ptsto}os_context} and establishes the -location of the initial configuration files. - -\begin{funcdecl}{krb5_os_free_context}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\end{funcdecl} - -\internalfunc - -Frees the operating system specific portion of \funcparam{context}. - -\subsubsection{Configuration based functions} -These functions allow access to configuration specific information. In -some cases, the configuration may be overriden by program control. - - -\begin{funcdecl}{krb5_set_config_files}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const char **}{filenames} -\end{funcdecl} - -Sets the list of configuration files to be examined in determining -machine defaults. \funcparam{filenames} is an array of files to check in -order. The array must have a NULL entry as the last element. - -Returns system errors. - -\begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{char ***}{hostlist} -\end{funcdecl} - -Figures out the Kerberos server names for the given \funcparam{realm}, -filling in \funcparam{hostlist} with a null terminated array of -pointers to hostnames. - -If \funcparam{realm} is unknown, the filled-in pointer is set to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_krbhst}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{char * const *}{hostlist} -\end{funcdecl} - -Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}. - -\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcout -\funcarg{char **}{lrealm} -\end{funcdecl} - -Retrieves the default realm to be used if no user-specified realm is -available (e.g. to interpret a user-typed principal name with the -realm omitted for convenience), filling in \funcparam{lrealm} with a -pointer to the default realm in allocated storage. - -It is the caller's responsibility for freeing the allocated storage -pointed to be \funcparam{lream} when it is finished with it. - -Returns system errors. - -\begin{funcdecl}{krb5_set_default_realm}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{char *}{realm} -\end{funcdecl} - -Sets the default realm to be used if no user-specified realm is -available (e.g. to interpret a user-typed principal name with the -realm omitted for convenience). (c.f. krb5_get_default_realm) - -If \funcparam{realm} is NULL, then the operating system default value -will used. - -Returns system errors. - -\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{const char *}{host} -\funcout -\funcarg{char ***}{realmlist} -\end{funcdecl} - -Figures out the Kerberos realm names for \funcparam{host}, filling in -\funcparam{realmlist} with a -pointer to an argv[] style list of names, terminated with a null pointer. - -If \funcparam{host} is NULL, the local host's realms are determined. - -If there are no known realms for the host, the filled-in pointer is set -to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_host_realm}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{char * const *}{realmlist} -\end{funcdecl} - -Frees the storage taken by a \funcparam{realmlist} returned by -\funcname{krb5_get_local_realm}. - -\begin{funcdecl}{krb5_get_realm_domain}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{const char *}{realm} -\funcout -\funcarg{char **}{domain} -\end{funcdecl} - -Determines the proper name of a realm. This is mainly so that a krb4 -principal can be converted properly into a krb5 one. If -\funcparam{realm} is null, the function will assume the default realm of -the host. The returned \funcparam{*domain} is allocated and must be -freed by the caller. - -\subsubsection{Disk based functions} -These functions all relate to disk based I/O. - -\begin{funcdecl}{krb5_lock_file}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{in}{fd} -\funcarg{int}{mode} -\end{funcdecl} - -Attempts to lock the file in the given \funcparam{mode}; returns 0 for a -successful lock, or an error code otherwise. - -The caller should arrange for the file referred by \funcparam{fd} to be -opened in such a way as to allow the required lock. - -Modes are given in {\tt } - -\begin{funcdecl}{krb5_unlock_file}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{int}{fd} -\end{funcdecl} - -Attempts to (completely) unlock the file. Returns 0 if successful, -or an error code otherwise. - - -\begin{funcdecl}{krb5_create_secure_file}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{const char *}{pathname} -\end{funcdecl} - -Creates a file named pathname which can only be read by the current -user. - -\begin{funcdecl}{krb5_sync_disk_file}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{FILE *}{fp} -\end{funcdecl} - -Assures that the changes made to the file pointed to by the file -handle -fp are forced out to disk. - -\subsubsection{Network based routines} - -These routines send and receive network data the specifics -of addresses and families on a given operating system. - -\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcout -\funcarg{krb5_address ***}{addr} -\end{funcdecl} - -Return all the protocol addresses of this host. - -Compile-time configuration flags will indicate which protocol family -addresses might be returned. -\funcparam{*addr} is filled in to point to an array of address pointers, -terminated by a null pointer. All the storage pointed to is allocated -and should be freed by the caller with \funcname{krb5_free_address} -when no longer needed. - -\begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{const krb5_address *}{adr} -\funcarg{krb5_const_pointer}{ptr} -\funcout -\funcarg{krb5_address **}{outaddr} -\end{funcdecl} - -Given an address \funcparam{adr} and an additional address-type specific -portion pointed to by -\funcparam{port} this routine -combines them into a freshly-allocated -\datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} and fills in -\funcparam{*outaddr} to point to this address. For IP addresses, -\funcparam{ptr} should point to a network-byte-order TCP or UDP port -number. Upon success, \funcparam{*outaddr} will point to an allocated -address which should be freed with \funcname{krb5_free_address}. - - -\begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{const krb5_data *}{send} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{krb5_data *}{receive} -\end{funcdecl} - -Send the message \funcparam{send} to a KDC for realm \funcparam{realm} and -return the response (if any) in \funcparam{receive}. - -If the message is sent and a response is received, 0 is returned, -otherwise an error code is returned. - -The storage for \funcparam{receive} is allocated and should be freed by -the caller when finished. - - -\begin{funcdecl}{krb5_net_read}{int}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{int}{fd} -\funcout -\funcarg{char *}{buf} -\funcin -\funcarg{int}{len} -\end{funcdecl} - -Like read(2), but guarantees that it reads as much as was requested -or returns -1 and sets errno. - -(make sure your sender will send all the stuff you are looking for!) -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_net_write}{int}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{int}{fd} -\funcarg{const char *}{buf} -\funcarg{int}{len} -\end{funcdecl} - -Like write(2), but guarantees that it writes as much as was requested -or returns -1 and sets errno. - -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_write_message}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_pointer}{fd} -\funcarg{krb5_data *}{data} -\end{funcdecl} - - -\funcname{krb5_write_message} writes data to the network as a message, -using the network connection pointed to by \funcparam{fd}. - -\begin{funcdecl}{krb5_read_message}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_pointer}{fd} -\funcout -\funcarg{krb5_data *}{data} -\end{funcdecl} - -Reads data from the network as a message, using the network connection -pointed to by fd. - -\subsubsection{Operating specific access functions} -These functions are involved with access control decisions and policies. - -\begin{funcdecl}{krb5_aname_to_localname}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_const_principal}{aname} -\funcarg{int}{lnsize} -\funcout -\funcarg{char *}{lname} -\end{funcdecl} - -Converts a principal name \funcparam{aname} to a local name suitable for use by -programs wishing a translation to an environment-specific name (e.g. -user account name). - -\funcparam{lnsize} specifies the maximum length name that is to be filled into -\funcparam{lname}. -The translation will be null terminated in all non-error returns. - -Returns system errors. - -\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_principal}{principal} -\funcarg{const char *}{luser} -\end{funcdecl} - -Given a Kerberos principal \funcparam{principal}, and a local username -\funcparam{luser}, -determine whether user is authorized to login to the account \funcparam{luser}. -Returns TRUE if authorized, FALSE if not authorized. - -\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{const char *}{hostname} -\funcarg{const char *}{sname} -\funcarg{krb5_int32}{type} -\funcout -\funcarg{krb5_principal *}{ret_princ} -\end{funcdecl} - -Given a hostname \funcparam{hostname} and a generic service name -\funcparam{sname}, this function generates a full principal name to be -used when authenticating with the named service on the host. The full -prinicpal name is returned in \funcparam{ret_princ}. - -The realm of the -principal is determined internally by calling \funcname{krb5_get_host_realm}. - -The \funcparam{type} argument controls how -\funcname{krb5_sname_to_principal} generates the principal name, -\funcparam{ret_princ}, for the named service, \funcparam{sname}. -Currently, two values are supported: KRB5_NT_SRV_HOST, and -KRB5_NT_UNKNOWN. - -If \funcparam{type} is set to -KRB5_NT_SRV_HOST, the hostname will be -canonicalized, i.e. a fully qualified lowercase hostname using -the primary name and the domain name, before \funcparam{ret_princ} is -generated in the form -"sname/hostname@LOCAL.REALM." Most applications should use -KRB5_NT_SRV_HOST. - -However, if \funcparam{type} is set to KRB5_NT_UNKNOWN, -while the generated principal name will have the form -"sname/hostname@LOCAL.REALM" the hostname will not be canonicalized -first. It will appear exactly as it was passed in \funcparam{hostname}. - -The caller should release \funcparam{ret_princ}'s storage by calling -\funcname{krb5_free_principal} when it is finished with the principal. - - - -\subsubsection{Miscellaneous operating specific functions} -These functions handle the other operating specific functions that do -not fall into any other major class. - -\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcout -\funcarg{krb5_context}{context} -\funcarg{krb5_int32 *}{timeret} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcout -\funcarg{krb5_int32 *}{seconds} -\funcarg{krb5_int32 *}{microseconds} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -{\raggedright The seconds portion is returned in \funcparam{*seconds}, the -microseconds portion in \funcparam{*microseconds}.} - -\begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{const char *}{prompt} -\funcarg{const char *}{prompt2} -\funcout -\funcarg{char *}{return_pwd} -\funcinout -\funcarg{unsigned int *}{size_return} -\end{funcdecl} - -Read a password from the keyboard. The first \funcparam{*size_return} -bytes of the password entered are returned in \funcparam{return_pwd}. -If fewer than \funcparam{*size_return} bytes are typed as a password, -the remainder of \funcparam{return_pwd} is zeroed. Upon success, the -total number of bytes filled in is stored in \funcparam{*size_return}. - -\funcparam{prompt} is used as the prompt for the first reading of a password. -It is printed to the terminal, and then a password is read from the -keyboard. No newline or spaces are emitted between the prompt and the -cursor, unless the newline/space is included in the prompt. - -If \funcparam{prompt2} is a null pointer, then the password is read -once. If \funcparam{prompt2} is set, then it is used as a prompt to -read another password in the same manner as described for -\funcparam{prompt}. After the second password is read, the two -passwords are compared, and an error is returned if they are not -identical. - -Echoing is turned off when the password is read. - -If there is an error in reading or verifying the password, an error code -is returned; else zero is returned. - - -\begin{funcdecl}{krb5_random_confounder}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{int}{size} -\funcout -\funcarg{krb5_pointer}{fillin} -\end{funcdecl} - -Given a length and a pointer, fills in the area pointed to by -\funcparam{fillin} with \funcparam{size} random octets suitable for use -in a confounder. - -\begin{funcdecl}{krb5_gen_replay_name}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{const krb5_address *}{inaddr} -\funcarg{const char *}{uniq} -\funcout -\funcarg{char **}{string} -\end{funcdecl} - -Given a \datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} -in \funcparam{inaddr}, this function unpacks its component address and -additional type, and uses them along with \funcparam{uniq} to allocate a -fresh string to represent the address and additional information. The -string is suitable for use as a replay cache tag. This string is -allocated and should be freed with \funcname{free} when the caller has -finished using it. When using IP addresses, the components in -\funcparam{inaddr{\ptsto}contents} must be of type -\datatype{ADDRTYPE_INET} and \datatype{ADDRTYPE_PORT}. - -% 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. diff --git a/doc/api/library.tex b/doc/api/library.tex deleted file mode 100644 index 713ce482f2..0000000000 --- a/doc/api/library.tex +++ /dev/null @@ -1,114 +0,0 @@ -\documentclass[twoside]{article} -\usepackage{fixunder,functions,fancyheadings} -\usepackage{krb5idx} -%\usepackage{hyperref} - -%\hypersetup{letterpaper, -% bookmarks=true, -%pdfpagemode=UseOutlines, -%} - -% -%\setlength{\oddsidemargin}{1in} -%\setlength{\evensidemargin}{1.00in} -%\setlength{\textwidth}{6.5in} -\setlength{\oddsidemargin}{0in} -\setlength{\evensidemargin}{1.50in} -\setlength{\textwidth}{5.25in} -\setlength{\marginparsep}{0.0in} -\setlength{\marginparwidth}{1.95 in} -\setlength{\topmargin}{-.5in} -\setlength{\textheight}{9in} -\setlength{\parskip}{.1in} -\setlength{\parindent}{2em} -\setlength{\footrulewidth}{0.4pt} -\setlength{\plainfootrulewidth}{0.4pt} -\setlength{\plainheadrulewidth}{0.4pt} -\makeindex -\newif\ifdraft -\draftfalse -% -% Far, far too inconvenient... it's still very draft-like anyway.... -% [tytso:19900921.0018EDT] -% -%\typein{Draft flag? (type \noexpand\draftfalse if not draft...)} -\ifdraft -\pagestyle{fancyplain} -\addtolength{\headwidth}{\marginparsep} -\addtolength{\headwidth}{\marginparwidth} -\makeatletter -\renewcommand{\sectionmark}[1]{\markboth {\uppercase{\ifnum \c@secnumdepth >\z@ - \thesection\hskip 1em\relax \fi #1}}{}}% -\renewcommand{\subsectionmark}[1]{\markright {\ifnum \c@secnumdepth >\@ne - \thesubsection\hskip 1em\relax \fi #1}} -\makeatother -\lhead[\thepage]{\fancyplain{}{\sl\rightmark}} -\rhead[\fancyplain{}{\sl\rightmark}]{\thepage} -\lfoot[]{{\bf DRAFT---DO NOT REDISTRIBUTE}} -\rfoot[{\bf DRAFT---DO NOT REDISTRIBUTE}]{} -\cfoot{\thepage} -\else\pagestyle{headings}\fi - -\def\internalfunc{NOTE: This is an internal function, which is not -necessarily intended for use by application programs. Its interface may -change at any time.\par} - -%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} -\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 -programming, maintenance, and porting. - -\ifdraft\sloppy\fi - -\subsection{Main functions} -\input{krb5.tex} - -\subsection{Credentials cache functions} -\input{ccache.tex} - -\subsection{Replay cache functions} -\input{rcache.tex} - -\subsection{Key table functions} -\input{keytab.tex} - -\subsection{Free functions} -\input{free.tex} - -\subsection{Operating-system specific functions} -\input{libos.tex} - -\appendix -\cleardoublepage -\printindex -\end{document} diff --git a/doc/api/rcache.tex b/doc/api/rcache.tex deleted file mode 100644 index 28bad36ab5..0000000000 --- a/doc/api/rcache.tex +++ /dev/null @@ -1,207 +0,0 @@ -The replay cache functions deal with verifying that AP_REQ's do not -contain duplicate authenticators; the storage must be non-volatile for -the site-determined validity period of authenticators. - -Each replay cache has a string ``name'' associated with it. The use of -this name is dependent on the underlying caching strategy (for -file-based things, it would be a cache file name). The -caching strategy uses non-volatile storage so that replay -integrity can be maintained across system failures. - -\begin{funcdecl}{krb5_auth_to_rep}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcin -\funcarg{krb5_tkt_authent *}{auth} -\funcout -\funcarg{krb5_donot_replay *}{rep} -\end{funcdecl} -Extract the relevant parts of \funcparam{auth} and fill them into the -structure pointed to by \funcparam{rep}. \funcparam{rep{\ptsto}client} -and \funcparam{rep{\ptsto}server} are set to allocated storage and -should be freed when \funcparam{*rep} is no longer needed. - -\begin{funcdecl}{krb5_rc_resolve_full}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache *}{id} -\funcin -\funcarg{char *}{string_name} -\end{funcdecl} - -\begin{sloppypar} -\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. -\end{sloppypar} - -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_resolve_type}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache *}{id} -\funcin -\funcarg{char *}{type} -\end{funcdecl} - -\internalfunc - -Looks up \funcparam{type} in the list of knows cache types and if found -attaches the operations to \funcparam{*id} which must be previously -allocated. - -If \funcparam{type} is not found, {\sc krb5_rc_type_notfound} is returned. - -\begin{funcdecl}{krb5_rc_register_type}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\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 *}{\funcin} -\funcarg{krb5_context}{context} -\end{funcdecl} - -\begin{sloppypar} -Returns the name of the default replay cache; this may be equivalent to -\funcnamenoparens{getenv}({\tt "KRB5RCACHE"}) with an appropriate fallback. -\end{sloppypar} - -\begin{funcdecl}{krb5_rc_default_type}{char *}{\funcin} -\funcarg{krb5_context}{context} -\end{funcdecl} - -Returns the type of the default replay cache. - -\begin{funcdecl}{krb5_rc_default}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\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_context}{context} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_deltat}{auth_lifespan} -\end{funcdecl} - -Creates/refreshes the replay cache identified by \funcparam{id} and sets its -authenticator lifespan to \funcparam{auth_lifespan}. If the -replay cache already exists, its contents are destroyed. - -Errors: permission errors, system errors - -\begin{funcdecl}{krb5_rc_recover}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache}{id} -\end{funcdecl} -Attempts to recover the replay cache \funcparam{id}, (presumably after a -system crash or server restart). - -Errors: error indicating that no cache was found to recover - -\begin{funcdecl}{krb5_rc_destroy}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Destroys the replay cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -Errors: permission errors. - -\begin{funcdecl}{krb5_rc_close}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Closes the replay cache \funcparam{id}, invalidates \funcparam{id}, -and releases any other resources acquired during use of the replay cache. -Requires that \funcparam{id} identifies a valid replay cache. - -Errors: permission errors - -\begin{funcdecl}{krb5_rc_store}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_donot_replay *}{rep} -\end{funcdecl} -Stores \funcparam{rep} in the replay cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -Returns KRB5KRB_AP_ERR_REPEAT if \funcparam{rep} is already in the -cache. May also return permission errors, storage failure errors. - -\begin{funcdecl}{krb5_rc_expunge}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache}{id} -\end{funcdecl} -Removes all expired replay information (i.e. those entries which are -older than then authenticator lifespan of the cache) from the cache -\funcparam{id}. Requires that \funcparam{id} identifies a valid replay -cache. - -Errors: permission errors. - -\begin{funcdecl}{krb5_rc_get_lifespan}{krb5_error_code}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache}{id} -\funcout -\funcarg{krb5_deltat *}{auth_lifespan} -\end{funcdecl} -Fills in \funcparam{auth_lifespan} with the lifespan of -the cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -\begin{funcdecl}{krb5_rc_resolve}{krb5_error_code}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache}{id} -\funcin -\funcarg{char *}{name} -\end{funcdecl} - -Initializes private data attached to \funcparam{id}. This function MUST -be called before the other per-replay cache functions. - -Requires that \funcparam{id} points to allocated space, with an -initialized \funcparam{id{\ptsto}ops} field. - -Since \funcname{krb5_rc_resolve} allocates memory, -\funcname{krb5_rc_close} must be called to free the allocated memory, -even if neither \funcname{krb5_rc_initialize} or -\funcname{krb5_rc_recover} were successfully called by the application. - -Returns: allocation errors. - - -\begin{funcdecl}{krb5_rc_get_name}{char *}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Returns the name (excluding the type) of the rcache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -\begin{funcdecl}{krb5_rc_get_type}{char *}{\funcin} -\funcarg{krb5_context}{context} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Returns the type (excluding the name) of the rcache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - - diff --git a/doc/api/tables.tex b/doc/api/tables.tex deleted file mode 100644 index b272a07b96..0000000000 --- a/doc/api/tables.tex +++ /dev/null @@ -1,79 +0,0 @@ -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 -\funcname{krb5_get_in_tkt}, \funcname{krb5_get_in_tkt_with_password}, and -\funcname{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} - -