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}
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}
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
\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.
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}
\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
\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}
\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
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}
\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}
\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.
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
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
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
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.
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}
\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},
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
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.
% 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}
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
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}
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}
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}
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
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}
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}
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}
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}
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}
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}
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
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.
\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
\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}
% 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
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
\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}
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}
\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}
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}
\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
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}
(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}
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}
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}
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}
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}
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}
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}
projects / krb5.git / commitdiff