From 497619fa22f0afaabe106a80b3d9d8606d8b04d1 Mon Sep 17 00:00:00 2001 From: Ezra Peisach Date: Wed, 3 May 1995 05:57:32 +0000 Subject: [PATCH] Up to date API specs Still needed: a) Some formatting fixing b) Final check of all prototypes git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@5698 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/api/ChangeLog | 16 + doc/api/ccache.tex | 6 +- doc/api/krb5.tex | 965 +++++++++++++++++++++++++------------------- doc/api/libos.tex | 63 ++- doc/api/library.tex | 11 +- doc/api/rcache.tex | 24 ++ 6 files changed, 658 insertions(+), 427 deletions(-) diff --git a/doc/api/ChangeLog b/doc/api/ChangeLog index 831c3f270..5b4a1f580 100644 --- a/doc/api/ChangeLog +++ b/doc/api/ChangeLog @@ -1,5 +1,21 @@ +Wed May 3 01:22:11 1995 Ezra Peisach + + * rcache.tex: Add krb5_rc_get_type, krb5_rc_resolve_type. + + * krb5.tex: API changes finished. + +Tue May 2 15:26:11 1995 Ezra Peisach (epeisach@kangaroo.mit.edu) + + * ccache.tex: krb5_cc_gen_new instead of krb5_cc_generate_new. + Sun Apr 30 15:37:31 1995 Ezra Peisach + * errors.tex: Formatting fixes + + * intro.tex: Formatting fixes + + * Makefile: Add free.tex to list. + * rcache.tex: Update to current API specs. * ccache.tex: Update to current API specs. diff --git a/doc/api/ccache.tex b/doc/api/ccache.tex index 8f2fd25ca..79fb927b7 100644 --- a/doc/api/ccache.tex +++ b/doc/api/ccache.tex @@ -17,7 +17,7 @@ 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_generate_new}{krb5_error_code}{\funcinout} +\begin{funcdecl}{krb5_cc_gen_new}{krb5_error_code}{\funcinout} \funcarg{krb5_context}{context} \funcin \funcarg{krb5_cc_ops *}{ops} @@ -91,7 +91,7 @@ Destroys the credentials cache identified by \funcparam{id}, invalidates 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_generate_new}. +\funcname{krb5_cc_gen_new}. Errors: permission errors. @@ -105,7 +105,7 @@ Closes the credentials cache \funcparam{id}, invalidates 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_generate_new}. +\funcname{krb5_cc_resolve} or \funcname{krb5_cc_gen_new}. \begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcinout} diff --git a/doc/api/krb5.tex b/doc/api/krb5.tex index ab7b93d6b..5914a26ae 100644 --- a/doc/api/krb5.tex +++ b/doc/api/krb5.tex @@ -1,6 +1,90 @@ The main functions deal with the nitty-gritty details: verifying tickets, creating authenticators, and the like. +\begin{funcdecl}{krb5_init_context}{krb5_error_code}{\funcinout} +\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_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. + +Valid flags that may be set with \funcname{krb5_auth_con_setflags}: + +\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} + +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_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 listed above. + + +%\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_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}. + \begin{funcdecl}{krb5_encode_kdc_rep}{krb5_error_code}{\funcin} \funcarg{const krb5_msgtype}{type} \funcarg{const krb5_enc_kdc_rep_part *}{encpart} @@ -24,7 +108,9 @@ non-error return; the caller should free it when finished. Returns system errors. -\begin{funcdecl}{krb5_decode_kdc_rep}{krb5_error_code}{\funcin} +\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} @@ -42,11 +128,13 @@ when finished with the response (by using \funcname{krb5_free_kdc_rep}). If the response isn't a KDC_REP (tgs or as), it returns an error from -the decoding routines (usually ISODE_50_LOCAL_ERR_BADDECODE). +the decoding routines. Returns errors from encryption routines, system errors. -\begin{funcdecl}{krb5_kdc_rep_decrypt_proc}{krb5_error_code}{\funcin} +\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 @@ -54,7 +142,8 @@ Returns errors from encryption routines, system errors. \end{funcdecl} Decrypt the encrypted portion of \funcparam{dec_rep}, using the -encryption key \funcparam{key}. \funcparam{decryptarg} is ignored. +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. @@ -62,8 +151,10 @@ The result is in allocated storage pointed to by This function is suitable for use as the \funcparam{decrypt_proc} argument to \funcname{krb5_get_in_tkt}. -\begin{funcdecl}{krb5_encrypt_tkt_part}{krb5_error_code}{ \funcin} -\funcarg{const krb5_encrypt_block *}{eblock} +\begin{funcdecl}{krb5_encrypt_tkt_part}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin +\funcarg{krb5_encrypt_block *}{eblock} \funcarg{const krb5_keyblock *}{srv_key} \funcinout \funcarg{krb5_ticket *}{dec_ticket} @@ -71,6 +162,7 @@ argument to \funcname{krb5_get_in_tkt}. \internalfunc +\begin{sloppypar} Takes unencrypted \funcparam{dec_ticket} and \funcparam{dec_ticket{\ptsto}enc_part2}, encrypts with the encryption system specified by \funcparam{eblock} using @@ -78,13 +170,16 @@ the encryption system specified by \funcparam{eblock} using \funcparam{dec_ticket{\ptsto}enc_part}. The string \funcparam{dec_ticket{\ptsto}enc_part} will be allocated before formatting. +\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}{\funcin} +\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} @@ -92,7 +187,7 @@ encrypted stuff. \internalfunc -Takes encrypted \funcparam{dec_ticket{\ptsto}enc_part}, encrypts with +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 @@ -100,8 +195,10 @@ using \funcparam{srv_key}, and places result in Returns errors from encryption routines, system errors -\begin{funcdecl}{krb5_send_tgs}{krb5_error_code}{\funcin} -\funcarg{const krb5_flags}{options} +\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} @@ -111,7 +208,7 @@ Returns errors from encryption routines, system errors \funcarg{krb5_pa_data * const *}{padata} \funcarg{const krb5_data *}{second_ticket} \funcinout -\funcarg{krb5_creds *}{usecred} +\funcarg{krb5_creds *}{in_cred} \funcout \funcarg{krb5_response *}{rep} \end{funcdecl} @@ -119,7 +216,7 @@ Returns errors from encryption routines, system errors \internalfunc Sends a request to the TGS and waits for a response. -\funcparam{options} is used for the options in the KRB_TGS_REQ. +\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. @@ -132,9 +229,9 @@ KRB_TGS_REQ. pre-authentication data for the KRB_TGS_REQ. \funcparam{second_ticket}, if required by options, is used for the 2nd ticket in the KRB_TGS_REQ. -\funcparam{usecred} is used for the ticket and session key in the KRB_AP_REQ header in the KRB_TGS_REQ. +\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{usecred{\ptsto}server}'s realm. +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 @@ -142,17 +239,19 @@ which should be freed by the caller when finished. Returns system errors. -\begin{funcdecl}{krb5_get_cred_from_kdc}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_get_cred_from_kdc}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} +\funcarg{krb5_creds *}{in_cred} \funcout -\funcarg{krb5_creds ***}{tgts } +\funcarg{krb5_cred **}{out_cred} +\funcarg{krb5_creds ***}{tgts} \end{funcdecl} -Retrieve credentials for principal \funcparam{creds{\ptsto}client}, -server \funcparam{creds{\ptsto}server}, -ticket flags \funcparam{creds{\ptsto}ticket_flags}, possibly + +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 @@ -175,35 +274,31 @@ which should be freed by the caller when finished. Returns errors, system errors. -\begin{funcdecl}{krb5_free_tgt_creds}{void}{\funcin} -\funcarg{krb5_creds **}{tgts} -\end{funcdecl} - -Frees the TGT credentials \funcparam{tgts} returned by -\funcname{krb5_get_cred_from_kdc}. - -\begin{funcdecl}{krb5_get_credentials}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_get_credentials}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{const krb5_flags}{options} \funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} +\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{creds{\ptsto}client}, with following information: +\funcparam{in_creds{\ptsto}client}, with following information: \begin{itemize} -\item {\bf The server} identified by \funcparam{creds{\ptsto}server} -\item {\bf The options} in \funcparam{options} -Valid options are KRB5_GC_USER_USER and KRB5_GC_GC_CACHED +\item {\bf The 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{creds{\ptsto}times.endtime} +\funcparam{in_creds{\ptsto}times.endtime} \item {\bf The session key type} specified in -\funcparam{creds{\ptsto}keyblock.keytype} if it is non-zero. +\funcparam{in_creds{\ptsto}keyblock.keytype} if it is non-zero. \end{itemize} If \funcparam{options} specifies KRB5_GC_CACHED, -\funcname{krb5_get_credentials} will only search the credentials cache +then \funcname{krb5_get_credentials} will only search the credentials cache for a ticket. If \funcparam{options} specifies KRB5_GC_USER_USER, then @@ -215,14 +310,14 @@ is the session key from the server's ticket-granting-ticket network --- this is safe since the TGT is encrypted in a key known only by the Kerberos server --- and the client must pass this TGT to \funcname{krb5_get_credentials} in -\funcparam{creds{\ptsto}second_ticket}. The Kerberos server will use +\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 minimen of the following: +The effective {\bf expiration date} is the minimum of the following: \begin{itemize} \item The expiration date as specified in -\funcparam{creds{\ptsto}times.endtime} +\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. @@ -234,28 +329,32 @@ KRB5_KDB_MAX_LIFE in config.h, and is by default 1 day. If any special authorization data needs to be included in the ticket, --- for example, restrictions on how the ticket can be used --- -they should be specified in \funcparam{creds{\ptsto}authdata}. If there +they should be specified in \funcparam{in_creds{\ptsto}authdata}. If there is no special authorization data to be passed, -\funcparam{creds{\ptsto}authdata} should be NULL. +\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}{\funcin} +\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 *}{pre_auth_types} +\funcarg{const krb5_preauthtype *}{ptypes} \funcfuncarg{krb5_error_code}{(*key_proc)} + \funcarg{krb5_context}{context} \funcarg{const krb5_keytype}{type} - \funcarg{krb5_pa_data *}{salt} + \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} @@ -267,21 +366,21 @@ Returns errors from encryption routines, system errors. \funcarg{krb5_kdc_rep **}{ret_as_reply} \end{funcdecl} -All-purpose initial ticket routine, usually called via +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} or -\funcname{krb5_get_in_tkt_with_skey}. +\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{pre_auth_type}, the preauthentication +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{etype} (valid encryption types are ETYPE_DES_CBC_CRC and +\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}, @@ -289,7 +388,7 @@ using \funcparam{creds{\ptsto}times.starttime}, 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{keytype}, +\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 @@ -316,13 +415,17 @@ its content depends on the \funcparam{decrypt_proc} being used. If \funcparam{addrs} is non-NULL, it is used for the addresses requested. If it is null, the system standard addresses are used. -If \funcparam{ret_as_reply} is non-null, it is filled in with a +If \funcparam{ret_as_reply} is non-NULL, it is filled in with a pointer to a structure containing the reply packet from the KDC. Some programs may find it useful to have direct access to this information. For example, it can be used to obtain the pre-authentication data 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. @@ -337,7 +440,9 @@ Returns system errors, preauthentication errors, encryption errors. % hand, if I'm right, then the bug in get_in_tkt needs to be fixed. % See ov-cambridge PR 1525. -\begin{funcdecl}{krb5_get_in_tkt_with_password}{krb5_error_code}{\funcin} +\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} @@ -351,7 +456,8 @@ Returns system errors, preauthentication errors, encryption errors. 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. +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 @@ -365,7 +471,9 @@ See \funcname{krb5_get_in_tkt} for documentation of the Returns system errors, preauthentication errors, encryption errors. -\begin{funcdecl}{krb5_get_in_tkt_with_keytab}{krb5_error_code}{\funcin} +\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} @@ -388,7 +496,9 @@ See \funcname{krb5_get_in_tkt} for documentation of the Returns system errors, preauthentication errors, encryption errors. -\begin{funcdecl}{krb5_get_in_tkt_with_skey}{krb5_error_code}{\funcin} +\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} @@ -411,10 +521,15 @@ See \funcname{krb5_get_in_tkt} for documentation of the Returns system errors, preauthentication errors, encryption errors. -\begin{funcdecl}{krb5_mk_req}{krb5_error_code}{\funcin} -\funcarg{krb5_const_principal}{server} +\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{const krb5_checksum *}{checksum} +\funcarg{char *}{service} +\funcarg{char *}{hostname} +\funcarg{krb5_data *}{in_data} +\funcinout \funcarg{krb5_ccache}{ccache} \funcout \funcarg{krb5_data *}{outbuf} @@ -422,19 +537,24 @@ Returns system errors, preauthentication errors, encryption errors. Formats a KRB_AP_REQ message into \funcparam{outbuf}. -\funcparam{server} specifies the principal of the server to receive the -message; if credentials are not present in the credentials cache +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 -AP_OPTS_USE_SESSION_KEY and -AP_OPTS_MUTUAL_REQUIRED. +Valid options are: -\funcparam{checksum} specifies the checksum to be used in the -authenticator. If it is null, no checksum is included. +\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 @@ -450,16 +570,13 @@ outbuf{\ptsto}data} does not need to be freed. Returns system errors, error getting credentials for \funcparam{server}. -\begin{funcdecl}{krb5_mk_req_extended}{krb5_error_code}{\funcin} +\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{const krb5_checksum *}{checksum} -\funcarg{const krb5_flags}{kdc_options} -\funcarg{krb5_int32}{sequence} -\funcarg{krb5_keyblock **}{newkey} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_authenticator *}{authentp} +\funcarg{krb5_data *}{in_data} +\funcarg{krb5_creds *}{in_creds} \funcout \funcarg{krb5_data *}{outbuf} \end{funcdecl} @@ -467,53 +584,38 @@ Returns system errors, error getting credentials for Formats a KRB_AP_REQ message into \funcparam{outbuf}, with more complete options than \funcname{krb5_mk_req}. -\funcparam{outbuf}, \funcparam{ap_req_options}, \funcparam{checksum}, +\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{creds} is used to supply the credentials (ticket and session +\funcparam{in_creds} is used to supply the credentials (ticket and session key) needed to form the request. -If \funcparam{creds{\ptsto}ticket} has no data (length == 0), then a -ticket is obtained from either \funcparam{ccache} or the TGS, and the -resulting ticket is stored in the \funcparam{creds} structure. -\funcparam{kdc_options} specifies the options -for the ticket to be used. If a ticket with appropriate flags is not -found in -\funcparam{ccache}, then these options are passed on in a request to an -appropriate KDC. +If \funcparam{in_creds{\ptsto}ticket} has no data (length == 0), then an +error is returned. -During this call, the structure elements in \funcparam{creds} may be +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. -\funcparam{sequence}, if non-zero, specifies the initial sequence number -which the caller will use for KRB_SAFE or KRB_PRIV messages. -\funcparam{newkey}, if non-NULL, will be filled in upon return with a -sub-session key that the caller can use to protect future KRB_SAFE or -KRB_PRIV messages. When the caller is finished with the key, it should -be freed with \funcname{krb5_free_keyblock}. \funcparam{newkey} will -not be filled in if an error is returned by -\funcname{krb5_mk_req_extended}. +If \funcparam{ap_req_options} specifies AP_OPTS_USE_SUBKEY, then a +subkey will be generated if need be by \funcname{krb5_generate_subkey}. -If \funcparam{ap_req_options} specifies AP_OPTS_USE_SESSION_KEY, then -\funcparam{creds{\ptsto}ticket} must contain the appropriate -ENC-TKT-IN-SKEY ticket. - -If \funcparam{authentp} is non-NULL, \funcname{krb5_mk_req_extended} -will store -a copy of the authenticator there, with the principal and checksum fields -nulled out, unless an error is returned. (This is to prevent pointer -sharing problems; the caller -shouldn't need these fields anyway, since the caller supplied them.) +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}{\funcin} +\begin{funcdecl}{krb5_generate_subkey}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{const krb5_keyblock *}{key} \funcout \funcarg{krb5_keyblock **}{subkey} @@ -527,137 +629,126 @@ 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}{\funcin} +\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{const krb5_address *}{sender_addr} -\funcarg{const char *}{fetchfrom} -\funcfuncarg{krb5_error_code}{(*keyproc)} - \funcarg{krb5_pointer}{keyprocarg} - \funcarg{krb5_principal}{principal} - \funcarg{krb5_kvno}{vno} - \funcarg{krb5_keytype}{keytype} - \funcarg{krb5_keyblock **}{key} -\funcendfuncarg -\funcarg{krb5_pointer}{keyprocarg} +\funcarg{krb5_keytab}{keytab} \funcinout -\funcarg{krb5_rcache}{rcache} +\funcarg{krb5_flags *}{ap_req_options} \funcout -\funcarg{krb5_tkt_authent **}{authdat} +\funcarg{krb5_ticket **}{ticket} \end{funcdecl} Parses a KRB_AP_REQ message, returning its contents. Upon successful -return, -\funcparam{*authdat} will be modified to point to allocated storage -containing the ticket and authenticator information. The caller is -responsible for deallocating this space by using -\funcname{krb5_free_tkt_authent}. +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. -\funcparam{sender_addr} specifies the address(es) expected to be present -in the ticket. +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{keyproc} specifies a procedure to generate a decryption key for the -ticket. If \funcparam{keyproc} is non-NULL, \funcparam{keyprocarg} is -passed to it, and the result is used as a decryption key. If -\funcparam{keyproc} is NULL, then the decryption key is taken from a key store -\footnote{i.e., srvtab file in Kerberos V4 parlance} specified by -\funcparam{fetchfrom}. If \funcparam{fetchfrom} is NULL, then the -default key store is consulted; otherwise, \funcparam{fetchfrom} -specifies the name of the key store, using the format as specified by -\funcname{krb5_kt_resolve}. +\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. - then \funcparam{fetchfrom} is checked; if -it is non-NULL, it specifies a the name of the key store from which to -retrieve the decription key. If \funcparam{fetchfrom} is NULL, then -the default key store is consulted. +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. -\funcparam{rcache} specifies a replay detection cache used to store -authenticators and server names. If \funcparam{rcache} is NULL, then no -replay detection is performed. +If the remote_addr portion of the \funcparam{auth_context} is set, +then this routine checks if the request came from the right client. -Returns system errors, encryption errors, replay errors. +\funcparam{sender_addr} specifies the address(es) expected to be present +in the ticket. -\begin{funcdecl}{krb5_rd_req_simple}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{inbuf} -\funcarg{krb5_const_principal}{server} -\funcarg{const krb5_address *}{sender_addr} -\funcout -\funcarg{krb5_tkt_authent **}{authdat} -\end{funcdecl} +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. -Similar to \funcname{krb5_rd_req}, but with some arguments replaced by -defaults. +Various other checks are made of the decoded data, including, +cross-realm policy, clockskew and ticket validation times. -The \funcparam{inbuf}, \funcparam{server}, \funcparam{sender_addr} and -\funcparam{authdat} arguments are as in \funcname{krb5_rd_req}, with -the exception that {\tt server} should be specified. If -\funcparam{server} is null, then any server name will be accepted as -long as a service key can be found for that service. It is then the -caller's responsibility to check the actual server that was -authenticated by looking in the \funcparam{authdat} structure. Also, -if -\funcparam{server} is null, replay cache protection is {\em not} -provided! +The keyblock, subkey, and sequence number of the request are all stored +in the \funcparam{auth_context} for future use. -A replay cache name derived from the first component of the service -name is used. +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. -The default key store is consulted to find the service key. +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}{\funcin} +\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} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const char *}{fetchfrom} -\funcfuncarg{krb5_error_code}{(*keyproc)} - \funcarg{krb5_pointer}{keyprocarg} - \funcarg{krb5_principal}{principal} - \funcarg{krb5_kvno}{vno} - \funcarg{krb5_keytype}{keytype} - \funcarg{krb5_keyblock **}{key} -\funcendfuncarg -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_rcache}{rcache} +\funcinout +\funcarg{krb5_keytab}{keytab} \funcout -\funcarg{krb5_tkt_authent **}{authdat} +\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}{\funcin} -\funcarg{const krb5_ap_rep_enc_part *}{repl} -\funcarg{const krb5_keyblock *}{kblock} +\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 -\funcparam{*repl}, encrypted using \funcparam{*kblock}. +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 successfull, \funcparam{outbuf{\ptsto}length} and \funcparam{outbuf{\ptsto}data} are filled in with the length of the AP_REQ message and allocated data holding it. \funcparam{outbuf{\ptsto}data} should be freed by the -caller when it is no longer needed. +caller when it is no longer needed. + +If the flags in \funcparam{auth_context} indicate that a sequence number +should be used (KRB5_AUTH_CONTEXT_DO_SEQUENCE or +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}{\funcin} +\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} -\funcarg{const krb5_keyblock *}{kblock} \funcout \funcarg{krb5_ap_rep_enc_part **}{repl} \end{funcdecl} @@ -667,11 +758,15 @@ Parses and decrypts an AP_REP message from \funcparam{*inbuf}, filling in values from the message. The caller is responsible for freeing this structure with \funcname{krb5_free_ap_rep_enc_part}. -The key in \funcparam{*kblock} is used to decrypt the message. +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}{\funcin} +\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} @@ -685,7 +780,9 @@ allocated, and should be freed by the caller when finished. Returns system errors. -\begin{funcdecl}{krb5_rd_error}{krb5_error_code}{\funcin} +\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} @@ -693,12 +790,14 @@ Returns system errors. Parses an error protocol message from \funcparam{enc_errbuf} and fills in \funcparam{*dec_error} with a pointer to allocated storage containing -the error message. The caller is reponsible for free this structure by +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}{\funcin} +\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} @@ -712,21 +811,23 @@ routines. 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_checksum *}{checksump} +\funcarg{krb5_data *}{in_data} +\funcarg{krb5_creds *}{in_creds} \funcinout -\funcarg{krb5_creds *}{credsp} \funcarg{krb5_ccache}{ccache} \funcout -\funcarg{krb5_int32 *}{sequence} -\funcarg{krb5_keyblock **}{newkey} \funcarg{krb5_error **}{error} \funcarg{krb5_ap_rep_enc_part **}{rep_result} +\funcarg{krb5_creds **}{out_creds} \end{funcdecl} \funcname{krb5_sendauth} provides a convenient means for client and @@ -747,7 +848,7 @@ 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{credsp} is non-null. Otherwise, +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. @@ -762,67 +863,48 @@ authentication exchange; the caller should free \funcparam{*rep_result} with \funcname{krb5_free_ap_rep_enc_part} when done with it. -The \funcparam{checksump} parameter is optional; if it is non-null, -then the checksum structure will be sent to the server as part of the -authenticated ticket exchange. - -If \funcparam{credsp} is non-null, then \funcparam{credsp{\ptsto}client} and -\funcparam{credsp{\ptsto}server} must be filled in, and either +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{credsp{\ptsto}ticket.length} should be zero. If -\funcparam{credsp{\ptsto}ticket.length} is non-zero, then -\funcparam{credsp} will be used as-is as the credentials to send to +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{credsp} -is filled in with the retrieved credentials. +\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{credsp} is null or -\funcparam{credsp{\ptsto}ticket.length} is zero). When a credential +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 non-null, \funcparam{sequence} is filled in with the sequence number -which the client should use for sending or receiving messages generated -using \funcname{krb5_mk_safe} and \funcname{krb5_mk_priv}. If mutual -authentication is used and \funcparam{rep_result} is non-null, the -sequence number for the server is available to the caller in +If mutual authentication is used and \funcparam{rep_result} is non-null, +the sequence number for the server is available to the caller in \funcparam{*rep_result->seq_number}. (If mutual authentication is not used, there is no way to negotiate a sequence number for the server.) -The \funcparam{newkey} parameter functions as described for -\funcname{krb5_mk_req_extended}. - If an error occurs during the authenticated ticket exchange 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} +\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{krb5_address *}{sender_addr} -\funcarg{krb5_pointer}{fetchfrom} -\funcfuncarg{krb5_error_code}{(*keyproc)} - \funcarg{krb5_pointer}{keyprocarg} - \funcarg{krb5_principal}{principal} - \funcarg{krb5_kvno}{vno} - \funcarg{krb5_keytype}{keytype} - \funcarg{krb5_keyblock **}{key} -\funcendfuncarg -\funcarg{krb5_pointer}{keyprocarg} \funcarg{char *}{rc_type} \funcarg{krb5_int32}{flags} +\funcarg{krb5_keytab}{keytab} \funcout -\funcarg{krb5_int32 *}{sequence} -\funcarg{krb5_principal *}{client} \funcarg{krb5_ticket **}{ticket} -\funcarg{krb5_authenticator **}{authent} \end{funcdecl} \funcname{krb5_recvauth} provides a convenient means for client and @@ -851,20 +933,18 @@ verifies that the server principal requested by the client matches \funcparam{server}. If not, an error will be returned and the authentication exchange will be aborted. -If \funcparam{sender_addr} is non-null, then \funcname{krb5_recvauth} -verifies that the address(es) specified is/are present in the -credentials sent by the client. If not, an error will be returned and -the authentication exchange will be aborted. - -The parameters \funcparam{fetchfrom}, \funcparam{keyproc}, and -\funcparam{keyprocarg} are used by \funcname{krb5_rd_req} to obtain the +The parameters \funcparam{server}, \funcparam{auth_context}, +and \funcparam{keytab} are used by \funcname{krb5_rd_req} to obtain the server's private key. -\funcparam{rc_type} is a string which determins which type of replay -cache \funcname{krb5_recvauth} should use. If it is null, the default -replay cache type will be used. \funcname{krb5_recvauth} uses a -standard convention for determining the name of the replay cache to be -used. +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. +%\funcparam{rc_type} is a string which determins which type of replay +%cache \funcname{krb5_recvauth} should use. If it is null, the default +%replay cache type will be used. \funcname{krb5_recvauth} uses a +%standard convention for determining the name of the replay cache to be +%used. The \funcparam{flags} argument allows the caller to modify the behavior of \funcname{krb5_recvauth}. For non-library callers, \funcparam{flags} @@ -874,72 +954,56 @@ should be 0. % should not have been added to krb5_recvauth'' (OpenVision Cambridge % bug number 1585) causes code changes, this will have to be updated. -All of the output paramters are optional and they are only filled in -if they are non-null. \funcparam{sequence} is filled in with the -sequence number which the server should use (if desired) for sending -messages using \funcname{krb5_mk_safe} and -\funcname{krb5_mk_priv}. The client's sequence number is passed back -as part of the authenticator structure which is filled in if -\funcparam{authent} is non-null (\funcparam{authent} should be freed -with \funcname{krb5_free_authenticator} when it is no longer needed). +\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. -\funcparam{client} is filled in with the client principal which -initiated the authenticated connection, and should be freed with -\funcname{krb5_free_principal} when it is no longer needed. - -\funcparam{ticket} is filled in with the data from the ticket sent by -the client, and should be freed with \funcname{krb5_free_ticket} when -it is no longer needed. - -\begin{funcdecl}{krb5_mk_safe}{krb5_error_code}{\funcin} +\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} -\funcarg{const krb5_cksumtype}{sumtype} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_fulladdr *}{sender_addr} -\funcarg{const krb5_fulladdr *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{safe_flags} -\funcarg{krb5_rcache}{rcache} \funcout \funcarg{krb5_data *}{outbuf} +\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. -\funcparam{sumtype} specifies the checksum type; \funcparam{key} -specifies the key which might be used to seed the checksum; -\funcparam{sender_addr} and \funcparam{recv_addr} specify the full -addresses (host and port) of the sender and receiver. The host -portion of \funcparam{sender_addr} is used to form the addresses used -in the KRB_SAFE message. \funcparam{recv_addr} is optional; if the +Portions \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{sender_addr}, however, is mandatory. +\funcparam{local_addr}, however, is mandatory. -\funcparam{safe_flags} selects whether sequence numbers or timestamps -should be used to identify the message. Valid flags are listed below. +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_SAFE_NOTIME & Don't use timestamps \\ -KRB5_SAFE_DOSEQUENCE & Use sequence numbers \\ +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_SAFE_NOTIME is not set in -\funcparam{safe_flags}), an entry -describing the message will be entered in the replay cache -\funcparam{rcache} so that the caller may detect if this message is sent -back to him by an attacker. If KRB5_SAFE_NOTIME is set, -\funcparam{rcache} is not used. - -If sequence numbers are to be used (i.e., if KRB5_SAFE_DOSEQUENCE is -set in \funcparam{safe_flags}), then \funcparam{seq_number} will be -placed in the protected message as its sequence number. Otherwise, -\funcparam{seq_number} is unused. +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_NOTIME is not set, +the \funcparam{*auth_context} replay cache is not used. -The functions \funcname{krb5_gen_replay_name} and -\funcname{krb5_get_server_rcache} can be used to open a replay cache -appropriate to use as \funcparam{rcache}. +If sequence numbers are to be used (i.e., if either +KRB5_AUTH_CONTEXT_DO_SEQUENCE or KRB5_AUTH_CONTEXT_RET_SEQUENEC 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 @@ -947,133 +1011,117 @@ the caller when finished. Returns system errors, encryption errors. -\begin{funcdecl}{krb5_rd_safe}{krb5_error_code}{\funcin} +\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} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const krb5_address *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{safe_flags} -\funcinout -\funcarg{krb5_rcache}{rcache} \funcout \funcarg{krb5_data *}{outbuf} +\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. -\funcparam{key} specifies the key to be used for verifying the -integrity of the message. +The keyblock used for verifying the integrity of the message is taken +from the \funcparam{*auth_context} local_subkey, remote_subkey, or +keyblock. The keyblock is chosen in the above order by the first one +which is not NULL. -\funcparam{sender_addr} and \funcparam{recv_addr} specify the full -addresses (host and port) of the sender and receiver, and must be of -type \datatype{ADDRTYPE_ADDRPORT}. +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{sender_addr} parameter is mandatory; it +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{sender_addr}, the error +the message does not match \funcparam{remote_addr}, the error KRB5KRB_AP_ERR_BADADDR will be returned. -If \funcparam{recv_addr} is non-NULL, then the address of the receiver +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}. +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 \funcparam{safe_flags} indicates that sequence numbers are to be -used (i.e., if KRB5_SAFE_DOSEQUENCE is set in it), -\funcparam{seq_number} is compared to the sequence number for the -message, and KRB5_KRB_AP_ERR_BADORDER is returned if it does not -match. Otherwise, \funcparam{seq_number} is not used. +If 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_SAFE_NOTIME is not set in -\funcparam{safe_flags}), then four additional checks are performed: +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 address in the message must match \funcparam{sender_addr}, - or KRB5KRB_AP_ERR_BADADDR is returned. -\item If \funcparam{recv_addr} is supplied, then it must match - the receiver address in the message (if \funcparam{recv_addr} - is null, this check is not done), or KRB5KRB_AP_ERR_BADADDR is - returned. \item The message must not be a replayed message, according to \funcparam{rcache}. \end{itemize} -If NOTIME is specified, then \funcparam{sender_addr}, -\funcparam{recv_addr} and \funcparam{rcache} are not used. - -% XXX The text above might change -- the address checks might move -% outside of the NOTIME restriction. See PR 1576. - -The function \funcname{krb5_get_server_rcache} and the service-name -portion of the server principal name can be used to open a -replay cache appropriate to use as \funcparam{rcache}. Returns system errors, integrity errors. -\begin{funcdecl}{krb5_mk_priv}{krb5_error_code}{\funcin} +\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} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const krb5_address *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{priv_flags} -\funcarg{krb5_rcache}{rcache} -\funcinout -\funcarg{krb5_pointer}{i_vector} \funcout \funcarg{krb5_data *}{outbuf} +\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{userdata}, \funcparam{server_addr}, \funcparam{recv_addr}, -\funcparam{seq_number}, \funcparam{priv_flags}, \funcparam{rcache} and +\funcparam{inbuf}, \funcparam{auth_context}, +\funcparam{outdata} and \funcparam{outbuf} function as in \funcname{krb5_mk_safe}. -As in \funcname{krb5_mk_safe}, \funcparam{recv_addr} is optional; if +As in \funcname{krb5_mk_safe}, the remote_addr part of the \funcparam{auth_context} is optional; if the receiver's address is not known, it may be replaced by NULL. -\funcparam{sender_addr}, however, is mandatory. +The local_addr, however, is mandatory. -\funcparam{etype} specifies the encryption type to use; -\funcparam{key} specifies the encryption key. If \funcparam{i_vector} +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 encryption type \funcparam{etype} supports initialization vectors) +(if the chosen encryption type supports initialization vectors) and its contents are replaced with the last block of encrypted data upon return. -\funcparam{priv_flags} selects whether sequence numbers or timestamps +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_PRIV_NOTIME & Don't use timestamps \\ -KRB5_PRIV_DOSEQUENCE & Use sequence numbers \\ +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}{\funcin} +\begin{funcdecl}{krb5_rd_priv}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_auth_context}{aith_context} +\funcin \funcarg{const krb5_data *}{inbuf} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const krb5_address *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{priv_flags} -\funcinout -\funcarg{krb5_pointer}{i_vector} -\funcarg{krb5_rcache}{rcache} \funcout \funcarg{krb5_data *}{outbuf} +\funcarg{krb5_data *}{outdata} \end{funcdecl} Parses a KRB_PRIV message from \funcparam{inbuf}, placing the data in @@ -1081,35 +1129,38 @@ Parses a KRB_PRIV message from \funcparam{inbuf}, placing the data in \funcname{krb5_rd_safe}, but the message is decrypted rather than integrity-checked. -\funcparam{inbuf}, \funcparam{sender_addr}, \funcparam{recv_addr}, -\funcparam{seq_number}, \funcparam{rcache} and \funcparam{outbuf} +\funcparam{inbuf}, \funcparam{auth_context}, +\funcparam{outdata} and \funcparam{outbuf} function as in \funcname{krb5_rd_safe}. -The \funcparam{sender_addr} parameter is mandatory; it +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 \funcparam{sender_addr}, the error +the message does not match the remote_addr, the error KRB5KRB_AP_ERR_BADADDR will be returned. -If \funcparam{recv_addr} is non-NULL, then the address of the receiver -in the message much match it. If it is null, the receiver address in -the message will be checked against the list of local addresses as -returned by \funcname{krb5_os_localaddr}. +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}. -\funcparam{key} specifies the key to be used for decryption of the -message. If \funcparam{i_vector} is non-null, it is used as an -initialization vector for the decryption (if the encryption type of -the message supports initialization vectors) and its contents are -replaced with the last block of encrypted data in the message. +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. -\funcparam{priv_flags} specifies whether timestamps and sequence -numbers are to be used; it functions as the \funcparam{safe_flags} -argument of \funcname{krb5_rd_safe} (but expects KRB5_PRIV_ flags -rather than KRB5_SAFE_ flags). +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. -\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{const char *}{name} \funcout \funcarg{krb5_principal *}{principal} @@ -1140,7 +1191,9 @@ the caller (using \funcname{krb5_free_principal}) after use. badly formatted, or ENOMEM if space for the return value can't be allocated. -\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_const_principal}{principal} \funcout \funcarg{char **}{name} @@ -1155,11 +1208,13 @@ above. \funcparam{*name} points to allocated storage and should be freed by the caller when finished. -\funcname{krb5_unparse_name} returns KRB_PARSE_MALFORMED if the principal -does not contain at least 2 components, and system errors (ENOMEM if +\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}{\funcin} +\begin{funcdecl}{krb5_unparse_name_ext}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{krb5_const_principal}{principal} \funcinout \funcarg{char **}{name} @@ -1180,14 +1235,18 @@ If \funcparam{size} is non-null (whether or not \funcparam{*name} is null when the function is called), it will be filled in with the size of the unparsed name upon successful return. -\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcout} +\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcout \funcarg{krb5_principal *}{princ} \funcin \funcarg{int}{rlen} \funcarg{const char *}{realm} \funcarg{char}{*s1, *s2, ..., 0} \end{funcdecl} -\begin{funcdecl}{krb5_build_principal_va}{krb5_error_code}{\funcout} +\begin{funcdecl}{krb5_build_principal_va}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcout \funcarg{krb5_principal *}{princ} \funcin \funcarg{int}{rlen} @@ -1195,9 +1254,12 @@ of the unparsed name upon successful return. \funcarg{va_list}{ap} \end{funcdecl} -\funcname{krb5_build_principal} and \funcname{krb5_build_principal_va} +\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 @@ -1206,7 +1268,9 @@ structure representing the named principal. The last string must be followed in the argument list by a null pointer. -\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcout} +\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcout \funcarg{krb5_principal *}{princ} \funcin \funcarg{int}{rlen} @@ -1219,7 +1283,9 @@ The last string must be followed in the argument list by a null pointer. (length, contents) pairs rather than a list of null-terminated strings. A length of zero indicates the end of the list. -\begin{funcdecl}{krb5_address_search}{krb5_boolean}{\funcin} +\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} @@ -1227,21 +1293,27 @@ A length of zero indicates the end of the list. If \funcparam{addr} is listed in \funcparam{addrlist}, or \funcparam{addrlist} is null, return TRUE. If not listed, return FALSE. -\begin{funcdecl}{krb5_address_compare}{krb5_boolean}{\funcin} +\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_principal_compare}{krb5_boolean}{\funcin} -\funcarg{krb5_const_principal}{p1} -\funcarg{krb5_const_principal}{p2} +\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_fulladdr_order}{int}{\funcin} +\begin{funcdecl}{krb5_fulladdr_order}{int}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{const krb5_fulladdr *}{addr1} \funcarg{const krb5_fulladdr *}{addr2} \end{funcdecl} @@ -1249,7 +1321,9 @@ If the two principals are the same, return TRUE, else return FALSE. Return an ordering on the two full addresses: 0 if the same, $< 0$ if first is less than 2nd, $> 0$ if first is greater than 2nd. -\begin{funcdecl}{krb5_address_order}{int}{\funcin} +\begin{funcdecl}{krb5_address_order}{int}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{const krb5_address *}{addr1} \funcarg{const krb5_address *}{addr2} \end{funcdecl} @@ -1257,7 +1331,44 @@ $< 0$ if first is less than 2nd, $> 0$ if first is greater than 2nd. Return an ordering on the two addresses: 0 if the same, $< 0$ if first is less than 2nd, $> 0$ if first is greater than 2nd. -\begin{funcdecl}{krb5_copy_keyblock}{krb5_error_code}{\funcin} +\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} @@ -1267,17 +1378,33 @@ Copy a keyblock, filling in \funcparam{*to} to point to the newly allocated copy, which should be freed with \funcname{krb5_free_keyblock}. -\begin{funcdecl}{krb5_copy_keyblock_contents}{krb5_error_code}{\funcin} +\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 a keyblock from \funcparam{from} to \funcparam{to}, including +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_creds}{krb5_error_code}{\funcin} +\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} @@ -1287,7 +1414,9 @@ Copy a credentials structure, filling in \funcparam{*outcred} to point to the newly allocated copy, which should be freed with \funcname{krb5_free_creds}. -\begin{funcdecl}{krb5_copy_data}{krb5_error_code}{\funcin} +\begin{funcdecl}{krb5_copy_data}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin \funcarg{const krb5_data *}{indata} \funcout \funcarg{krb5_data **}{outdata} @@ -1296,30 +1425,50 @@ to the newly allocated copy, which should be freed with Copy a data structure, filling in \funcparam{*outdata} to point to the newly allocated copy, which should be freed with \funcname{krb5_free_data}. -\begin{funcdecl}{krb5_copy_principal}{krb5_error_code}{\funcin} +\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_auth_to_rep}{krb5_error_code}{\funcin} -\funcarg{krb5_tkt_authent *}{auth} +\begin{funcdecl}{krb5_copy_ticket}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcin +\funcarg{const krb5_ticket *}{from} \funcout -\funcarg{krb5_donot_replay *}{rep} +\funcarg{krb5_ticket **}{pto} \end{funcdecl} -Extract the relevant parts of \funcparam{auth} and fill them into the -structure pointed to by \funcparam{rep}. \funcparam{rep{\ptsto}client} -and \funcparam{rep{\ptsto}server} are set to allocated storage and -should be freed when \funcparam{*rep} is no longer needed. -\begin{funcdecl}{krb5_get_server_rcache}{krb5_error_code}{\funcin} +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_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_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} diff --git a/doc/api/libos.tex b/doc/api/libos.tex index 901c74643..19a1c40bc 100644 --- a/doc/api/libos.tex +++ b/doc/api/libos.tex @@ -3,7 +3,7 @@ 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 +}; other definitions (including macros, if used) are in {\tt }. The following global symbols are provided in \libname{libos.a}. If you @@ -11,9 +11,6 @@ wish to substitute for any of them, you must substitute for all of them (they are all declared and initialized in the same object file): \begin{description} % These come from src/lib/osconfig.c -\item[extern char *\globalname{krb5_config_file}:] name of configuration file -\item[extern char *\globalname{krb5_trans_file}:] name of hostname/realm -name translation file \item[extern char *\globalname{krb5_defkeyname}:] default name of key table file \item[extern char *\globalname{krb5_lname_file}:] name of aname/lname @@ -33,6 +30,7 @@ for password reading. \end{description} \begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{char *}{prompt} \funcarg{char *}{prompt2} \funcout @@ -64,7 +62,8 @@ Echoing is turned off when the password is read. If there is an error in reading or verifying the password, an error code is returned; else zero is returned. -\begin{funcdecl}{krb5_lock_file}{krb5_error_code}{\funcvoid} +\begin{funcdecl}{krb5_lock_file}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{FILE *}{filep} \funcarg{char *}{pathname} \funcarg{int}{mode} @@ -80,7 +79,8 @@ file. The implementation may use whichever is more convenient. Modes are given in {\tt } -\begin{funcdecl}{krb5_unlock_file}{krb5_error_code}{\funcvoid} +\begin{funcdecl}{krb5_unlock_file}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{FILE *}{filep} \funcarg{char *}{pathname} \end{funcdecl} @@ -93,6 +93,7 @@ The caller should arrange that both \funcparam{filep} and use whichever is more convenient. \begin{funcdecl}{krb5_create_secure_file}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{const char *}{pathname} \end{funcdecl} @@ -100,6 +101,7 @@ 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} @@ -107,7 +109,10 @@ Assures that the changes made to the file pointed to by the file handle fp are forced out to disk. -\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcout} +\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} +\funcout +\funcarg{krb5_context}{context} \funcarg{krb5_int32 *}{timeret} \end{funcdecl} @@ -116,7 +121,9 @@ epoch. [The ASN.1 encoding routines must convert this to the standard ASN.1 encoding as needed] -\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcout} +\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} +\funcout \funcarg{krb5_int32 *}{seconds} \funcarg{krb5_int32 *}{microseconds} \end{funcdecl} @@ -126,10 +133,11 @@ epoch. [The ASN.1 encoding routines must convert this to the standard ASN.1 encoding as needed] -The seconds portion is returned in \funcparam{*seconds}, the -microseconds portion in \funcparam{*microseconds}. +{\raggedright The seconds portion is returned in \funcparam{*seconds}, the +microseconds portion in \funcparam{*microseconds}.} \begin{funcdecl}{krb5_net_read}{int}{\funcin} +\funcarg{krb5_context}{context} \funcarg{int}{fd} \funcout \funcarg{char *}{buf} @@ -144,6 +152,7 @@ or returns -1 and sets errno. 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} @@ -155,6 +164,7 @@ 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} @@ -164,6 +174,7 @@ Only useful on stream sockets and pipes. 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} @@ -172,7 +183,9 @@ using the network connection pointed to by \funcparam{fd}. Reads data from the network as a message, using the network connection pointed to by fd. -\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcout} +\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} +\funcout \funcarg{krb5_address ***}{addr} \end{funcdecl} @@ -187,6 +200,7 @@ when no longer needed. \begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{const krb5_data *}{send} \funcarg{const krb5_data *}{realm} \funcout @@ -203,6 +217,7 @@ The storage for \funcparam{receive} is allocated and should be freed by the caller when finished. \begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{const krb5_data *}{realm} \funcout \funcarg{char ***}{hostlist} @@ -220,12 +235,14 @@ 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_aname_to_localname}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_const_principal}{aname} \funcarg{int}{lnsize} \funcout @@ -242,7 +259,8 @@ The translation will be null terminated in all non-error returns. Returns system errors. -\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code} +\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcout \funcarg{char **}{lrealm} \end{funcdecl} @@ -257,7 +275,22 @@ 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} @@ -278,6 +311,7 @@ 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} @@ -285,6 +319,7 @@ Frees the storage taken by a \funcparam{realmlist} returned by \funcname{krb5_get_local_realm}. \begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin} +\funcarg{krb5_context}{context} \funcarg{krb5_principal}{principal} \funcarg{const char *}{luser} \end{funcdecl} @@ -295,6 +330,7 @@ determine whether user is authorized to login to the account \funcparam{luser}. Returns TRUE if authorized, FALSE if not authorized. \begin{funcdecl}{krb5_random_confounder}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{int}{size} \funcout \funcarg{krb5_pointer}{fillin} @@ -305,6 +341,7 @@ Given a length and a pointer, fills in the area pointed to by in a confounder. \begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{const krb5_address *}{adr} \funcarg{krb5_const_pointer}{ptr} \funcout @@ -322,6 +359,7 @@ number. Upon success, \funcparam{*outaddr} will point to an allocated address which should be freed with \funcname{krb5_free_address}. \begin{funcdecl}{krb5_gen_replay_name}{krb5_error_code}{\funcin} +\funcarg{krb5_context}{context} \funcarg{const krb5_address *}{inaddr} \funcarg{const char *}{uniq} \funcout @@ -344,6 +382,7 @@ finished using it. When using IP addresses, the components in % function to change, the documentation above will have to be updated. \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} diff --git a/doc/api/library.tex b/doc/api/library.tex index 800b279a2..f26ca77bd 100644 --- a/doc/api/library.tex +++ b/doc/api/library.tex @@ -83,16 +83,19 @@ programming, maintenance, and porting. \subsection{Main functions} \input{krb5.tex} -\section{Credentials cache functions} +\subsection{Credentials cache functions} \input{ccache.tex} -\section{Replay cache functions} +\subsection{Replay cache functions} \input{rcache.tex} -\section{Key table functions} +\subsection{Key table functions} \input{keytab.tex} -\section{Operating-system specific functions} +\subsection{Free routines} +\input{free.tex} + +\subsection{Operating-system specific functions} \input{libos.tex} \appendix diff --git a/doc/api/rcache.tex b/doc/api/rcache.tex index 55347cb7c..28bad36ab 100644 --- a/doc/api/rcache.tex +++ b/doc/api/rcache.tex @@ -39,6 +39,22 @@ Before the cache can be used \funcname{krb5_rc_initialize} or 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} @@ -180,4 +196,12 @@ Returns: allocation errors. 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. + -- 2.26.2