From 247711357f91e1370267110dc7e3fd814079e443 Mon Sep 17 00:00:00 2001 From: Ezra Peisach Date: Wed, 3 May 1995 15:38:47 +0000 Subject: [PATCH] * krb5.tex (subsubsection{The krb5_auth_context}): Added auth_context routines. * free.tex: Add krb5_xfree and krb5_free_data. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@5710 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/api/ChangeLog | 5 + doc/api/free.tex | 17 +-- doc/api/krb5.tex | 256 ++++++++++++++++++++++++++++++++++++++++------ 3 files changed, 238 insertions(+), 40 deletions(-) diff --git a/doc/api/ChangeLog b/doc/api/ChangeLog index 5b4a1f580..9347f0c6f 100644 --- a/doc/api/ChangeLog +++ b/doc/api/ChangeLog @@ -1,5 +1,10 @@ Wed May 3 01:22:11 1995 Ezra Peisach + * krb5.tex (subsubsection{The krb5_auth_context}): Added + auth_context routines. + + * free.tex: Add krb5_xfree and krb5_free_data. + * rcache.tex: Add krb5_rc_get_type, krb5_rc_resolve_type. * krb5.tex: API changes finished. diff --git a/doc/api/free.tex b/doc/api/free.tex index da0b85e75..02733b702 100644 --- a/doc/api/free.tex +++ b/doc/api/free.tex @@ -2,20 +2,21 @@ 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_auth_con_free}{krb5_auth_con_free}{\funcinout} -\funcarg{krb5_context}{context} -\funcarg{krb5_auth_context *}{auth_context} +\begin{funcdecl}{krb5_xfree}{void}{\funcinout} +\funcarg{void *}{ptr} \end{funcdecl} -Frees the auth_context \funcparam{auth_context} returned by -\funcname{krb5_auth_con_init}. +Frees the pointer \funcarg{ptr}. This is a wrapper macro to +\funcname{free} that is designed to keep lint ``happy.'' -\begin{funcdecl}{krb5_free_context}{void}{\funcinout} +\begin{funcdecl}{krb5_free_data}{void}{\funcinout} \funcarg{krb5_context}{context} +\funcarg{krb5_data *}{val} \end{funcdecl} -Frees the context returned by \funcname{krb5_init_context}. Internally -calls \funcname{krb5_os_free_context}. +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} diff --git a/doc/api/krb5.tex b/doc/api/krb5.tex index 5914a26ae..ca7709105 100644 --- a/doc/api/krb5.tex +++ b/doc/api/krb5.tex @@ -1,6 +1,15 @@ 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}{\funcinout} \funcarg{krb5_context *}{context} \end{funcdecl} @@ -13,6 +22,44 @@ 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 +contex, 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 @@ -41,6 +88,14 @@ 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}. + \begin{funcdecl}{krb5_auth_con_setflags}{krb5_error_code}{\funcinout} \funcarg{krb5_context}{context} \funcarg{krb5_auth_context *}{auth_context} @@ -52,38 +107,177 @@ 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_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} +\begin{funcdecl}{krb5_auth_con_setaddrs}{krb5_error_code}{\funcinout} \funcarg{krb5_context}{context} +\funcarg{krb5_auth_context *}{auth_context} \funcin -\funcarg{const krb5_enctype *}{etypes} +\funcarg{krb5_address *}{local_addr} +\funcarg{krb5_address *}{remote_addr} \end{funcdecl} -Sets the desired default encryption type \funcparam{etypes} for the context -if valid. +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. -Returns {\sc enomem}, {\sc krb5_prog_etype_nosupp}. +\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} -\begin{funcdecl}{krb5_get_default_in_tkt_etypes}{krb5_error_code}{\funcinout} +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_setaddrs}{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_enctype **}{etypes} +\funcarg{krb5_keyblock **}{keyblock} \end{funcdecl} -Retrieves the default encryption types from the context and stores them -in \funcarg{etypes} which should be freed by the caller. +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}. -Returns {\sc enomem}. +\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 local_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_getkey}{krb5_error_code}{\funcinout} +\funcarg{krb5_context}{context} +\funcarg{krb5_auth_context *}{auth_context} +\funcout +\funcarg{krb5_keyblock **}{keyblock} +\end{funcdecl} + +Retrieves the remote_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_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_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_set_initivector}{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_set_rcache}{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{The application functions} \begin{funcdecl}{krb5_encode_kdc_rep}{krb5_error_code}{\funcin} \funcarg{const krb5_msgtype}{type} @@ -737,8 +931,8 @@ AP_REQ message and allocated data holding it. 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 +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}. @@ -940,11 +1134,6 @@ 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. -%\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} @@ -987,11 +1176,13 @@ 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_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} \\ + &\ to \funcparam{*outdata} \\ \end{tabular} If timestamps are to be used (i.e., if KRB5_AUTH_CONTEXT_DO_TIME is @@ -1088,9 +1279,10 @@ integrity-protected rather than just integrity-protected. \funcparam{outdata} and \funcparam{outbuf} function as in \funcname{krb5_mk_safe}. -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. -The local_addr, however, is mandatory. +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} -- 2.26.2