path: root/doc/api/krb5.tex

The main functions deal with the nitty-gritty details: verifying
tickets, creating authenticators, and the like.

\begin{funcdecl}{krb5_encode_kdc_rep}{krb5_error_code}{\funcin}
\funcarg{const krb5_msgtype}{type}
\funcarg{const krb5_enc_kdc_rep_part *}{encpart}
\funcarg{krb5_encrypt_block *}{eblock}
\funcarg{const krb5_keyblock *}{client_key}
\funcinout
\funcarg{krb5_kdc_rep *}{dec_rep}
\funcout
\funcarg{krb5_data **}{enc_rep}
\end{funcdecl}

\internalfunc

Takes KDC rep parts in \funcparam{*rep} and \funcparam{*encpart}, and
formats it into \funcparam{*enc_rep}, using message type
\funcparam{type} and encryption key \funcparam{client_key} and
encryption block \funcparam{eblock}.

\funcparam{enc_rep{\ptsto}data} will point to  allocated storage upon
non-error return; the caller should free it when finished.

Returns system errors.

\begin{funcdecl}{krb5_decode_kdc_rep}{krb5_error_code}{\funcin}
\funcarg{krb5_data *}{enc_rep}
\funcarg{const krb5_keyblock *}{key}
\funcarg{const krb5_enctype}{etype}
\funcout
\funcarg{krb5_kdc_rep **}{dec_rep}
\end{funcdecl}

\internalfunc

Takes a KDC_REP message and decrypts encrypted part using
\funcparam{etype} and \funcparam{*key}, putting result in \funcparam{*dec_rep}.
The pointers in \funcparam{dec_rep}
are all set to allocated storage which should be freed by the caller
when finished with the response (by using \funcname{krb5_free_kdc_rep}).


If the response isn't a KDC_REP (tgs or as), it returns an error from
the decoding routines (usually ISODE_50_LOCAL_ERR_BADDECODE).

Returns errors from encryption routines, system errors.

\begin{funcdecl}{krb5_kdc_rep_decrypt_proc}{krb5_error_code}{\funcin}
\funcarg{const krb5_keyblock *}{key}
\funcarg{krb5_const_pointer}{decryptarg}
\funcinout
\funcarg{krb5_kdc_rep *}{dec_rep}
\end{funcdecl}

Decrypt the encrypted portion of \funcparam{dec_rep}, using the
encryption key \funcparam{key}.  \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}
\funcarg{const krb5_keyblock *}{srv_key}
\funcinout
\funcarg{krb5_ticket *}{dec_ticket}
\end{funcdecl}

\internalfunc

Takes unencrypted \funcparam{dec_ticket} and
\funcparam{dec_ticket{\ptsto}enc_part2}, encrypts with
the encryption system specified by \funcparam{eblock} using
\funcparam{srv_key}, and places result in 
\funcparam{dec_ticket{\ptsto}enc_part}.
The string \funcparam{dec_ticket{\ptsto}enc_part} will be allocated
before formatting.

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}
\funcarg{const krb5_keyblock *}{srv_key}
\funcinout
\funcarg{krb5_ticket *}{dec_ticket}
\end{funcdecl}

\internalfunc

Takes encrypted \funcparam{dec_ticket{\ptsto}enc_part}, encrypts with
\funcparam{dec_ticket{\ptsto}etype}
using \funcparam{srv_key}, and places result in
\funcparam{dec_ticket{\ptsto}enc_part2}.  The storage of
\funcparam{dec_ticket{\ptsto}enc_part2} will be allocated before return.

Returns errors from encryption routines, system errors

\begin{funcdecl}{krb5_send_tgs}{krb5_error_code}{\funcin}
\funcarg{const krb5_flags}{options}
\funcarg{const krb5_ticket_times *}{timestruct}
\funcarg{const krb5_enctype}{etype}
\funcarg{const krb5_cksumtype}{sumtype}
\funcarg{krb5_const_principal}{sname}
\funcarg{krb5_address * const *}{addrs}
\funcarg{krb5_authdata * const *}{authorization_data}
\funcarg{krb5_pa_data * const *}{padata}
\funcarg{const krb5_data *}{second_ticket}
\funcinout
\funcarg{krb5_creds *}{usecred}
\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{timestruct} values are used for from, till, and rtime in the
KRB_TGS_REQ.
\funcparam{etype} is used for etype in the KRB_TGS_REQ.
\funcparam{sumtype} is used for the checksum in the AP_REQ in the KRB_TGS_REQ.
\funcparam{sname} is used for sname in the KRB_TGS_REQ.
\funcparam{addrs}, if non-NULL, is used for addresses in the KRB_TGS_REQ.
\funcparam{authorization_data}, if non-NULL, is used for
\funcparam{authorization_data} in the KRB_TGS_REQ.  
\funcparam{padata}, if non-NULL, is combined with any other supplied
pre-authentication data for the KRB_TGS_REQ.
\funcparam{second_ticket}, if required by options, is used for the 2nd
ticket in the KRB_TGS_REQ.
\funcparam{usecred} 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 response is placed into \funcparam{*rep}.
\funcparam{rep{\ptsto}response.data} is set to point at allocated storage
which should be freed by the caller when finished.

Returns system errors.

\begin{funcdecl}{krb5_get_cred_from_kdc}{krb5_error_code}{\funcin}
\funcarg{krb5_ccache}{ccache}
\funcinout
\funcarg{krb5_creds *}{creds}
\funcout			
\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
\funcparam{creds{\ptsto}second_ticket} if needed by the ticket flags.

\funcparam{ccache} is used to fetch initial TGT's to start the authentication
path to the server.

Credentials are requested from the KDC for the server's realm.  Any
TGT credentials obtained in the process of contacting the KDC are
returned in an array of credentials; \funcparam{tgts} is filled in to
point to an array of pointers to credential structures (if no TGT's were
used, the pointer is zeroed).  TGT's may be returned even if no useful
end ticket was obtained.

The returned credentials are NOT cached.

If credentials are obtained, \funcparam{creds} is filled in with the results;
\funcparam{creds{\ptsto}ticket} and
\funcparam{creds{\ptsto}keyblock{\ptsto}key} are set to allocated storage,
which should be freed by the caller when finished.

Returns errors, system errors.


\begin{funcdecl}{krb5_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}
\funcarg{const krb5_flags}{options}
\funcarg{krb5_ccache}{ccache}
\funcinout
\funcarg{krb5_creds *}{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: 
\begin{itemize}
\item {\bf The server} identified by \funcparam{creds{\ptsto}server} 
\item {\bf The options} in \funcparam{options}
Valid options are KRB5_GC_USER_USER and KRB5_GC_GC_CACHED
\item {\bf The expiration date} specified in
\funcparam{creds{\ptsto}times.endtime}  
\item {\bf The session key type} specified in
\funcparam{creds{\ptsto}keyblock.keytype} if it is non-zero.
\end{itemize}

If \funcparam{options} specifies KRB5_GC_CACHED,
\funcname{krb5_get_credentials} will only search the credentials cache
for a ticket.  

If \funcparam{options} specifies KRB5_GC_USER_USER, then
\funcname{krb5_get_credentials} will get credentials for a user to user
authentication.  In a user to user authentication, the secret key for
the server 
is the session key from the server's ticket-granting-ticket
(TGT).  The TGT is passed from the server to the client over the
network --- this is safe since the TGT is encrypted in a key
known only by the Kerberos server --- and the client must pass
this TGT to \funcname{krb5_get_credentials} in
\funcparam{creds{\ptsto}second_ticket}.  The Kerberos server will use
this TGT to construct a user to user ticket which can be verified by
the server by using the session key from its TGT.

The effective {\bf expiration date} is the minimen of the following:
\begin{itemize}
\item The expiration date as specified in
\funcparam{creds{\ptsto}times.endtime} 
\item The requested start time plus the maximum lifetime of the
server as specified by the server's entry in the
Kerberos database.
\item The requested start time plus the maximum lifetime of tickets
allowed in the local site, as specified by the KDC.
This is currently a compile-time option,
KRB5_KDB_MAX_LIFE in config.h, and is by default 1 day.
\end{itemize}

If any special authorization data needs to be included in the ticket,
--- for example, restrictions on how the ticket can be used --- 
they should be specified in \funcparam{creds{\ptsto}authdata}.   If there
is no special authorization data to be passed,
\funcparam{creds{\ptsto}authdata} should be NULL.

Any returned ticket and intermediate ticket-granting tickets are
stored in \funcparam{ccache}.

Returns errors from encryption routines, system errors.

\begin{funcdecl}{krb5_get_in_tkt}{krb5_error_code}{\funcin}
\funcarg{const krb5_flags}{options}
\funcarg{krb5_address * const *}{addrs}
\funcarg{const krb5_preauthtype}{pre_auth_type}
\funcarg{const krb5_enctype}{etype}
\funcarg{const krb5_keytype}{keytype}
\funcfuncarg{krb5_error_code}{(*key_proc)}
	\funcarg{const krb5_keytype}{type}
	\funcarg{krb5_keyblock **}{key}
	\funcarg{krb5_const_pointer}{keyseed}
	\funcarg{krb5_pa_data **}{padata}
\funcendfuncarg
\funcarg{krb5_const_pointer}{keyseed}
\funcfuncarg{krb5_error_code}{(*decrypt_proc)}
	\funcarg{const krb5_keyblock *}{key}
	\funcarg{krb5_const_pointer}{decryptarg}
	\funcarg{krb5_kdc_rep *}{dec_rep}
\funcendfuncarg
\funcarg{krb5_const_pointer}{decryptarg}
\funcinout
\funcarg{krb5_creds *}{creds}
\funcarg{krb5_ccache}{ccache}
\funcarg{krb5_kdc_rep **}{ret_as_reply}
\end{funcdecl}

All-purpose initial ticket routine, usually called via
\funcname{krb5_get_in_tkt_with_password} or
\funcname{krb5_get_in_tkt_with_skey}.


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
method (valid preauthentication methods are listed in Table
\ref{padata-types}).
\funcname{krb5_get_in_tkt} requests encryption type
\funcparam{etype} (valid encryption types are ETYPE_DES_CBC_CRC and
ETYPE_RAW_DES_CBC),
using \funcparam{creds{\ptsto}times.starttime},
\funcparam{creds{\ptsto}times.endtime},
\funcparam{creds{\ptsto}times.renew_till} 
as from, till, and rtime.  \funcparam{creds{\ptsto}times.renew_till} is
ignored unless the RENEWABLE option is requested.

\funcparam{key_proc} is called, with \funcparam{keytype},
\funcparam{keyseed} and\funcparam{padata} as arguments, to fill in \funcparam{key} to be used for
decryption.  The valid key types for \funcparam{keytype} are
KEYTYPE_NULL,\footnote{See RFC section 6.3.1} and
KEYTYPE_DES.\footnote{See RFC section 6.3.4}  However, KEYTYPE_DES is
the only key type supported by MIT kerberos.
The content of  \funcparam{keyseed} 
depends on the \funcparam{key_proc} being used. %nlg - need a ref here
The \funcparam{padata} passed
to \funcparam{key_proc} is the preauthentication data returned by the
KDC as part of the reply to the initial ticket request.  It may
contain an element of type KRB5_PADATA_PW_SALT, which
\funcparam{key_proc} should use to determine what salt to use when
generating the key.  \funcparam{key_proc} should fill in
\funcparam{key} with a key for the client, or return an error code.

\funcparam{decrypt_proc} is called to perform the decryption of the
response (the encrypted part is in
\funcparam{dec_rep{\ptsto}enc_part}; the decrypted part should be
allocated and filled into
\funcparam{dec_rep{\ptsto}enc_part2}.
\funcparam{decryptarg} is passed on to \funcparam{decrypt_proc}, and
its content depends on the \funcparam{decrypt_proc} being used.

If \funcparam{addrs} is non-NULL, it is used for the addresses
requested.  If it is null, the system standard addresses are used.

If \funcparam{ret_as_reply} is non-null, it is filled in with a
pointer to a structure containing the reply packet from the KDC.  Some
programs may find it useful to have direct access to this information.
For example, it can be used to obtain the pre-authentication data
passed back from the KDC.  The caller is responsible for freeing this
structure by using \funcname{krb5_free_kdc_rep}.

A succesful call will place the ticket in the credentials cache
\funcparam{ccache} and fill in \funcparam{creds} with the ticket
information used/returned.

Returns system errors, preauthentication errors, encryption errors.

% XXX Right now, uses creds->addresses before it's copied into from
% the reply -- it's passed to krb5_obtain_padata.  I think that's
% wrong, and it should be using either addrs or the result of
% krb5_os_localaddr instead.  If I'm wrong, then this spec has to be
% updated to document that creds->addresses is used.  On the other
% hand, if I'm right, then the bug in get_in_tkt needs to be fixed.
% See ov-cambridge PR 1525.

\begin{funcdecl}{krb5_get_in_tkt_with_password}{krb5_error_code}{\funcin}
\funcarg{const krb5_flags}{options}
\funcarg{krb5_address * const *}{addrs}
\funcarg{const krb5_preauthtype}{pre_auth_type}
\funcarg{const krb5_enctype}{etype}
\funcarg{const krb5_keytype}{keytype}
\funcarg{const char *}{password}
\funcarg{krb5_ccache}{ccache}
\funcinout
\funcarg{krb5_creds *}{creds}
\funcarg{krb5_kdc_rep **}{ret_as_reply}
\end{funcdecl}

Attempts to get an initial ticket using the null-terminated string
\funcparam{password}.  If \funcparam{password} is NULL, the password
is read from the terminal.

The password is converted into a key using the appropriate
string-to-key conversion function for the specified
\funcparam{keytype}, and using any salt data returned by the KDC in
response to the authentication request.

See \funcname{krb5_get_in_tkt} for documentation of the
\funcparam{options}, \funcparam{addrs}, \funcparam{pre_auth_type},
\funcparam{etype}, \funcparam{keytype}, \funcparam{ccache},
\funcparam{creds} and \funcparam{ret_as_reply} arguments.

Returns system errors, preauthentication errors, encryption errors.

\begin{funcdecl}{krb5_get_in_tkt_with_skey}{krb5_error_code}{\funcin}
\funcarg{const krb5_flags}{options}
\funcarg{krb5_address * const *}{addrs}
\funcarg{const krb5_preauthtype}{pre_auth_type}
\funcarg{const krb5_enctype}{etype}
\funcarg{const krb5_keyblock *}{key}
\funcarg{krb5_ccache}{ccache}
\funcinout
\funcarg{krb5_creds *}{creds}
\funcarg{krb5_kdc_rep **}{ret_as_reply}
\end{funcdecl}

Attempts to get an initial ticket using \funcparam{key}.  If
\funcparam{key} is NULL, an appropriate key is retrieved from the
system key store (e.g., \filename{/etc/v5srvtab}).

See \funcname{krb5_get_in_tkt} for documentation of the
\funcparam{options}, \funcparam{addrs}, \funcparam{pre_auth_type},
\funcparam{etype}, \funcparam{ccache}, \funcparam{creds} and
\funcparam{ret_as_reply} arguments.

Returns system errors, preauthentication errors, encryption errors.

\begin{funcdecl}{krb5_mk_req}{krb5_error_code}{\funcin}
\funcarg{krb5_const_principal}{server}
\funcarg{const krb5_flags}{ap_req_options}
\funcarg{const krb5_checksum *}{checksum}
\funcarg{krb5_ccache}{ccache}
\funcout
\funcarg{krb5_data *}{outbuf}
\end{funcdecl}

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
\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.

\funcparam{checksum} specifies the checksum to be used in the
authenticator.  If it is null, no checksum is included.

% XXX Not sure if it's legal in the protocol for no checksum to be
% included, or if so, how the server reacts to a request with no
% checksum.

\funcparam{outbuf} should point to an existing \datatype{krb5_data}
structure.  \funcparam{outbuf{\ptsto}length} and
\funcparam{outbuf{\ptsto}data} will be filled in on success, and the latter
should be freed by the caller when it is no longer needed; if an error
is returned, however, no storage is allocated and {\tt
outbuf{\ptsto}data} does not need to be freed.

Returns system errors, error getting credentials for
\funcparam{server}.

\begin{funcdecl}{krb5_mk_req_extended}{krb5_error_code}{\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}
\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},
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
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.

During this call, the structure elements in \funcparam{creds} may be
freed and reallocated.  Hence all of the structure elements which are
pointers should point to allocated memory, and there should be no other
pointers aliased to the same memory, since it may be deallocated during
this procedure call.

\funcparam{sequence}, if non-zero, specifies the initial sequence number
which the caller will use for KRB_SAFE or KRB_PRIV messages.

\funcparam{newkey}, if non-NULL, will be filled in upon return with a 
sub-session key that the caller can use to protect future KRB_SAFE or
KRB_PRIV messages.  When the caller is finished with the key, it should
be freed with \funcname{krb5_free_keyblock}.  \funcparam{newkey} will
not be filled in if an error is returned by
\funcname{krb5_mk_req_extended}.

If \funcparam{ap_req_options} specifies AP_OPTS_USE_SESSION_KEY, then
\funcparam{creds{\ptsto}ticket} must contain the appropriate
ENC-TKT-IN-SKEY ticket.

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.)

Returns system errors, errors contacting the KDC, KDC errors getting
a new ticket for the authenticator.

\begin{funcdecl}{krb5_generate_subkey}{krb5_error_code}{\funcin}
\funcarg{const krb5_keyblock *}{key}
\funcout
\funcarg{krb5_keyblock **}{subkey}
\end{funcdecl}

Generates a pseudo-random sub-session key using the encryption system's
random key functions, based on the input \funcparam{key}.

\funcparam{subkey} is filled in to point to the generated subkey, unless
an error is returned.  The returned key (i.e., \funcparam{*subkey}) is
allocated and should be freed by the caller with
\funcname{krb5_free_keyblock} when it is no longer needed.

\begin{funcdecl}{krb5_rd_req}{krb5_error_code}{\funcin}
\funcarg{const krb5_data *}{inbuf}
\funcarg{krb5_const_principal}{server}
\funcarg{const krb5_address *}{sender_addr}
\funcarg{const char *}{fetchfrom}
\funcfuncarg{krb5_error_code}{(*keyproc)}
	\funcarg{krb5_pointer}{keyprocarg}
	\funcarg{krb5_principal}{principal}
	\funcarg{krb5_kvno}{vno}
	\funcarg{krb5_keyblock **}{key}
\funcendfuncarg
\funcarg{krb5_pointer}{keyprocarg}
\funcinout
\funcarg{krb5_rcache}{rcache}
\funcout
\funcarg{krb5_tkt_authent **}{authdat}
\end{funcdecl}

Parses a KRB_AP_REQ message, returning its contents.  Upon successful
return,
\funcparam{*authdat} will be modified to point to allocated storage
containing the ticket and authenticator information.  The caller is
responsible for deallocating this space by using
\funcname{krb5_free_tkt_authent}.

\funcparam{inbuf} should contain the KRB_AP_REQ message to be parsed.

\funcparam{server} specifies the expected server's name for the ticket.
If \funcparam{server} is NULL, then any server name will be accepted if
the appropriate key can be found, and the caller should verify that the
server principal matches some trust criterion.

\funcparam{sender_addr} specifies the address(es) expected to be present
in the ticket.

\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}.



 then \funcparam{fetchfrom} is checked; if
it is non-NULL, it specifies a the name of the key store from which to
retrieve the decription key.  If \funcparam{fetchfrom} is NULL, then
the default key store is consulted.

\funcparam{rcache} specifies a replay detection cache used to store
authenticators and server names.  If \funcparam{rcache} is NULL, then no
replay detection is performed.

Returns system errors, encryption errors, replay errors.

\begin{funcdecl}{krb5_rd_req_simple}{krb5_error_code}{\funcin}
\funcarg{const krb5_data *}{inbuf}
\funcarg{krb5_const_principal}{server}
\funcarg{const krb5_address *}{sender_addr}
\funcout
\funcarg{krb5_tkt_authent **}{authdat}
\end{funcdecl}

Similar to \funcname{krb5_rd_req}, but with some arguments replaced by
defaults.

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!  

A replay cache name derived from the first component of the service
name is used.

The default key store is consulted to find the service key.

Returns system errors, encryption errors, replay errors.


\begin{funcdecl}{krb5_rd_req_decoded}{krb5_error_code}{\funcin}
\funcarg{const krb5_ap_req *}{req}
\funcarg{krb5_const_principal}{server}
\funcarg{const krb5_address *}{sender_addr}
\funcarg{const char *}{fetchfrom}
\funcfuncarg{krb5_error_code}{(*keyproc)}
	\funcarg{krb5_pointer}{keyprocarg}
	\funcarg{krb5_principal}{principal}
	\funcarg{krb5_kvno}{vno}
	\funcarg{krb5_keyblock **}{key}
\funcendfuncarg
\funcarg{krb5_pointer}{keyprocarg}
\funcarg{krb5_rcache}{rcache}
\funcout
\funcarg{krb5_tkt_authent **}{authdat}
\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}
\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}.

When successfull, \funcparam{outbuf{\ptsto}length} and
\funcparam{outbuf{\ptsto}data} are filled in with the length of the
AP_REQ message and allocated data holding it.
\funcparam{outbuf{\ptsto}data} should be freed by the
caller when it is no longer needed.

Returns system errors.

\begin{funcdecl}{krb5_rd_rep}{krb5_error_code}{\funcin}
\funcarg{const krb5_data *}{inbuf}
\funcarg{const krb5_keyblock *}{kblock}
\funcout
\funcarg{krb5_ap_rep_enc_part **}{repl}
\end{funcdecl}

Parses and decrypts an AP_REP message from \funcparam{*inbuf}, filling in
\funcparam{*repl} with a pointer to  allocated storage containing the
values from the message.  The caller is responsible for freeing this
structure with \funcname{krb5_free_ap_rep_enc_part}.

The key in \funcparam{*kblock} is used to decrypt the message.

Returns system errors, encryption errors, replay errors.

\begin{funcdecl}{krb5_mk_error}{krb5_error_code}{\funcin}
\funcarg{const krb5_error *}{dec_err}
\funcout
\funcarg{krb5_data *}{enc_err}
\end{funcdecl}

Formats the error structure \funcparam{*dec_err} into an error buffer
\funcparam{*enc_err}.

The error buffer storage (\funcparam{enc_err{\ptsto}data}) is
allocated, and should be freed by the caller when finished.

Returns system errors.

\begin{funcdecl}{krb5_rd_error}{krb5_error_code}{\funcin}
\funcarg{const krb5_data *}{enc_errbuf}
\funcout
\funcarg{krb5_error **}{dec_error}
\end{funcdecl}

Parses an error protocol message from \funcparam{enc_errbuf} and fills in 
\funcparam{*dec_error} with a pointer to allocated storage containing
the error message.  The caller is reponsible for free this structure by
using \funcname{krb5_free_error}.

Returns system errors.

\begin{funcdecl}{krb5_generate_seq_number}{krb5_error_code}{\funcin}
\funcarg{const krb5_keyblock *}{key}
\funcout
\funcarg{krb5_int32 *}{seqno}
\end{funcdecl}

Generates a pseudo-random sequence number suitable for use as an initial
sequence number for the KRB_SAFE and KRB_PRIV message processing
routines.

\funcparam{key} parameterizes the choice of the random sequence number,
which is filled into \funcparam{*seqno} upon return.

\begin{funcdecl}{krb5_sendauth}{krb5_error_code}
\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}
\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}
\end{funcdecl}

\funcname{krb5_sendauth} provides a convenient means for client and
server programs to send authenticated messages to one another through
network connections.  \funcname{krb5_sendauth} sends an authenticated
ticket from the client program to the server program using the network
connection specified by \funcparam{fd}.  In the MIT Unix implementation,
\funcparam{fd} should be a pointer to a file descriptor describing the
network socket.  This can be changed in other implementations, however,
if the routines \funcname{krb5_read_message},
\funcname{krb5_write_message}, \funcname{krb5_net_read}, and
\funcname{krb5_net_write} are changed.

The paramter \funcparam{appl_version} is a string describing the
application protocol version which the client is expecting to use for
this exchange.  If the server is using a different application protocol,
an error will be returned.

The parameters \funcparam{client} and \funcparam{server} specify the
kerberos principals for the client and the server.  They are
ignored if \funcparam{credsp} is non-null.  Otherwise,
\funcparam{server} must be non-null, but \funcparam{client} may be
null, in which case the client principal used is the one in the
credential cache's default principal.

The \funcparam{ap_req_options} parameters specifies the options which
should be passed to \funcname{krb5_mk_req}.  Valid options are listed
in Table \ref{ap-req-options}.  If \funcparam{ap_req_options}
specifies MUTUAL_REQUIRED, then \funcname{krb5_sendauth} will perform
a mutual authentication exchange, and if \funcparam{rep_result} is
non-null, it will be filled in with the result of the mutual
authentication exchange; the caller should free
\funcparam{*rep_result} with
\funcname{krb5_free_ap_rep_enc_part} when done with it.

The \funcparam{checksump} parameter is optional; if it is non-null,
then the checksum structure will be sent to the server as part of the
authenticated ticket exchange.

If \funcparam{credsp} is non-null, then \funcparam{credsp{\ptsto}client} and
\funcparam{credsp{\ptsto}server} must be filled in, and either
the other structure fields should be filled in with valid credentials,
or \funcparam{credsp{\ptsto}ticket.length} should be zero.  If
\funcparam{credsp{\ptsto}ticket.length} is non-zero, then
\funcparam{credsp} will be used as-is as the credentials to send to
the server, and \funcparam{ccache} is ignored; otherwise,
\funcparam{ccache} is used as described below, and \funcparam{credsp}
is filled in with the retrieved credentials.

\funcname{ccache} specifies the credential cache to use when one is
needed (i.e., when \funcname{credsp} is null or
\funcparam{credsp{\ptsto}ticket.length} is zero).  When a credential
cache is not needed, \funcname{ccache} is ignored.  When a credential
cache is needed and \funcname{ccache} is null, the default credential
cache is used.  Note that if the credential cache is needed and does
not contain the needed credentials, they will be retrieved from the
KDC and stored in the credential cache.

If non-null, \funcparam{sequence} is filled in with the sequence number
which the client should use for sending or receiving messages generated
using \funcname{krb5_mk_safe} and \funcname{krb5_mk_priv}.  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}
\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_keyblock **}{key}
\funcendfuncarg
\funcarg{krb5_pointer}{keyprocarg}
\funcarg{char *}{rc_type}
\funcarg{krb5_int32}{flags}
\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
server programs to send authenticated messages to one another through
network connections.  \funcname{krb5_sendauth} is the matching routine
to \funcname{krb5_recvauth} for the server.  \funcname{krb5_recvauth}
will engage in an authentication dialogue with the
client program running \funcname{krb5_sendauth} to authenticate the
client to the server.  In addition, if requested by the client,
\funcname{krb5_recvauth} will provide mutual authentication to
prove to the client that the server represented by
\funcname{krb5_recvauth} is legitimate. 

\funcparam{fd} is a pointer to the network connection.  As in
\funcname{krb5_sendauth}, in the MIT Unix implementation
\funcparam{fd} is a pointer to a file descriptor.

The parameter \funcparam{appl_version} is a string describing the
application protocol version which the server is expecting to use for
this exchange.  If the client is using a different application protocol,
an error will be returned and the authentication exchange will be
aborted.

If \funcparam{server} is non-null, then \funcname{krb5_recvauth}
verifies that the server principal requested by the client matches
\funcparam{server}.  If not, an error will be returned and the
authentication exchange will be aborted.

If \funcparam{sender_addr} is non-null, then \funcname{krb5_recvauth}
verifies that the address(es) specified is/are present in the
credentials sent by the client.  If not, an error will be returned and
the authentication exchange will be aborted.

The parameters \funcparam{fetchfrom}, \funcparam{keyproc}, and
\funcparam{keyprocarg} are used by \funcname{krb5_rd_req} to obtain the
server's private key.

\funcparam{rc_type} is a string which determins which type of replay
cache \funcname{krb5_recvauth} should use.  If it is null, the default
replay cache type will be used.  \funcname{krb5_recvauth} uses a
standard convention for determining the name of the replay cache to be
used.

The \funcparam{flags} argument allows the caller to modify the behavior of
\funcname{krb5_recvauth}.  For non-library callers, \funcparam{flags}
should be 0. 

% XXX Note that if the bug I submitted entitled ``"flags" argument
% should not have been added to krb5_recvauth'' (OpenVision Cambridge
% bug number 1585) causes code changes, this will have to be updated.

All of the output paramters are optional and they are only filled in
if they are non-null.  \funcparam{sequence} is filled in with the
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{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}
\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}
\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
receiver's address is not known, it may be replaced by NULL.
\funcparam{sender_addr}, however, is mandatory.

\funcparam{safe_flags} selects whether sequence numbers or timestamps
should be used to identify the message.  Valid flags are listed below.

\begin{tabular}{ll}
\multicolumn{1}{c}{Symbol} & Meaning \\
KRB5_SAFE_NOTIME		& Don't use timestamps \\
KRB5_SAFE_DOSEQUENCE	& Use sequence numbers \\
\end{tabular}

If timestamps are to be used (i.e., if KRB5_SAFE_NOTIME is not set in
\funcparam{safe_flags}), an entry
describing the message will be entered in the replay cache
\funcparam{rcache} so that the caller may detect if this message is sent
back to him by an attacker.  If KRB5_SAFE_NOTIME is set,
\funcparam{rcache} is not used.

If sequence numbers are to be used (i.e., if KRB5_SAFE_DOSEQUENCE is
set in \funcparam{safe_flags}), then \funcparam{seq_number} will be
placed in the protected message as its sequence number.  Otherwise,
\funcparam{seq_number} is unused.

The functions \funcname{krb5_gen_replay_name} and
\funcname{krb5_get_server_rcache} can be used to open a replay cache
appropriate to use as \funcparam{rcache}.

The \funcparam{outbuf} buffer storage (i.e.,
\funcparam{outbuf{\ptsto}data}) is allocated, and should be freed by
the caller when finished.

Returns system errors, encryption errors.

\begin{funcdecl}{krb5_rd_safe}{krb5_error_code}{\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}
\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.
 
\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 \funcparam{sender_addr} parameter is mandatory; it
specifies the address of the sender.  If the address of the sender in
the message does not match \funcparam{sender_addr}, the error
KRB5KRB_AP_ERR_BADADDR will be returned.

If \funcparam{recv_addr} is non-NULL, then the address of the receiver
in the message much match it.  If it is null, the receiver address in
the message will be checked against the list of local addresses as
returned by \funcname{krb5_os_localaddr}.

The \funcparam{outbuf} buffer storage (i.e.,
\funcparam{outbuf{\ptsto}data} is allocated storage which the caller
should free when it is no longer needed.

If \funcparam{safe_flags} indicates that sequence numbers are to be
used (i.e., if KRB5_SAFE_DOSEQUENCE is set in it),
\funcparam{seq_number} is compared to the sequence number for the
message, and KRB5_KRB_AP_ERR_BADORDER is returned if it does not
match.  Otherwise, \funcparam{seq_number} is not used.

If timestamps are to be used (i.e., if KRB5_SAFE_NOTIME is not set in
\funcparam{safe_flags}), then four additional checks are performed:
\begin{itemize}
\item The timestamp in the message must be within the permitted clock
	skew (which is usually five minutes), or KRB5KRB_AP_ERR_SKEW
	is returned.
\item The address in the message must match \funcparam{sender_addr},
	or KRB5KRB_AP_ERR_BADADDR is returned.
\item If \funcparam{recv_addr} is supplied, then it must match
	the receiver address in the message (if \funcparam{recv_addr}
	is null, this check is not done), or KRB5KRB_AP_ERR_BADADDR is
	returned.
\item The message must not be a replayed message, according to
	\funcparam{rcache}.
\end{itemize}
If NOTIME is specified, then \funcparam{sender_addr},
\funcparam{recv_addr} and \funcparam{rcache} are not used.

% XXX The text above might change -- the address checks might move
% outside of the NOTIME restriction.  See PR 1576.

The function \funcname{krb5_get_server_rcache} and the service-name
portion of the server principal name can be used to open a
replay cache appropriate to use as \funcparam{rcache}.

Returns system errors, integrity errors.

\begin{funcdecl}{krb5_mk_priv}{krb5_error_code}{\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}
\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{outbuf} function as in \funcname{krb5_mk_safe}.

As in \funcname{krb5_mk_safe}, \funcparam{recv_addr} is optional; if
the receiver's address is not known, it may be replaced by NULL.
\funcparam{sender_addr}, however, is mandatory.

\funcparam{etype} specifies the encryption type to use;
\funcparam{key} specifies the encryption key.  If \funcparam{i_vector}
is non-null, it is used as an initialization vector for the encryption
(if encryption type \funcparam{etype} supports initialization vectors)
and its contents are replaced with the last block of encrypted data
upon return.

\funcparam{priv_flags} 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 \\
\end{tabular}

Returns system errors, encryption errors.

\begin{funcdecl}{krb5_rd_priv}{krb5_error_code}{\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}
\end{funcdecl}

Parses a KRB_PRIV message from \funcparam{inbuf}, placing the data in
\funcparam{*outbuf} after decrypting it.  Behaves similarly to
\funcname{krb5_rd_safe}, but the message is decrypted rather than
integrity-checked.

\funcparam{inbuf}, \funcparam{sender_addr}, \funcparam{recv_addr},
\funcparam{seq_number}, \funcparam{rcache} and \funcparam{outbuf}
function as in \funcname{krb5_rd_safe}.


The \funcparam{sender_addr} parameter is mandatory;  it
specifies the address of the sender.  If the address of the sender in
the message does not match \funcparam{sender_addr}, the error
KRB5KRB_AP_ERR_BADADDR will be returned.

If \funcparam{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}.

\funcparam{key} specifies the key to be used for decryption of the
message.  If \funcparam{i_vector} is non-null, it is used as an
initialization vector for the decryption (if the encryption type of
the message supports initialization vectors) and its contents are
replaced with the last block of encrypted data in the message.

\funcparam{priv_flags} specifies whether timestamps and sequence
numbers are to be used; it functions as the \funcparam{safe_flags}
argument of \funcname{krb5_rd_safe} (but expects KRB5_PRIV_ flags
rather than KRB5_SAFE_ flags).

Returns system errors, integrity errors.

\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcin}
\funcarg{const char *}{name}
\funcout
\funcarg{krb5_principal *}{principal}
\end{funcdecl}

Converts a single-string representation \funcparam{name} of the
principal name to the multi-part principal format used in the protocols.

A single-string representation of a Kerberos name consists of one or
more principal name components, separated by slashes, optionally
followed by the ``@'' character and a realm name.  If the realm name
is not specified, the local realm is used.

The slash and ``@'' characters may be quoted (i.e., included as part
of a component rather than as a component separator or realm prefix)
by preceding them with a backslash (``$\backslash$'') character.
Similarly, newline, tab, backspace, and null characters may be
included in a component by using $\backslash{}n$, $\backslash{}t$,
$\backslash{}b$ or $\backslash{}0$, respectively.

The realm in a Kerberos name may not contain the slash, colon or null
characters.

\funcparam{*principal} will point to allocated storage which should be freed by
the caller (using \funcname{krb5_free_principal}) after use.

\funcname{krb5_parse_name} returns KRB5_PARSE_MALFORMED if the string is
 badly formatted, or ENOMEM if space for the return value can't be
allocated.

\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcin}
\funcarg{krb5_const_principal}{principal}
\funcout
\funcarg{char **}{name}
\end{funcdecl}

Converts the multi-part principal name \funcparam{principal} from the
format used in the protocols to a single-string representation of the
name.  The resulting single-string representation will use the format
and quoting conventions described for \funcname{krb5_parse_name}
above.

\funcparam{*name} points to allocated storage and should be freed by the caller
when finished.

\funcname{krb5_unparse_name} returns KRB_PARSE_MALFORMED if the principal
does not contain at least 2 components, and system errors (ENOMEM if
unable to allocate memory).

\begin{funcdecl}{krb5_unparse_name_ext}{krb5_error_code}{\funcin}
\funcarg{krb5_const_principal}{principal}
\funcinout
\funcarg{char **}{name}
\funcarg{int *}{size}
\end{funcdecl}

\funcname{krb5_unparse_name_ext} is designed for applications which
must unparse a large number of principals, and are concerned about the
speed impact of needing to do a lot of memory allocations and
deallocations.  It functions similarly to \funcname{krb5_unparse_name}
except if \funcparam{*name} is non-null, in which case, it is assumed
to contain an allocated buffer of size \funcparam{*size} and this
buffer will be resized with \funcname{realloc} to hold the unparsed
name.  Note that in this case,
\funcparam{size} must not be null.  

If \funcparam{size} is non-null (whether or not \funcparam{*name} is
null when the function is called), it will be filled in with the size
of the unparsed name upon successful return.

\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcout}
\funcarg{krb5_principal *}{princ}
\funcin
\funcarg{int}{rlen}
\funcarg{const char *}{realm}
\funcarg{char}{*s1, *s2, ..., 0}
\end{funcdecl}
\begin{funcdecl}{krb5_build_principal_va}{krb5_error_code}{\funcout}
\funcarg{krb5_principal *}{princ}
\funcin
\funcarg{int}{rlen}
\funcarg{const char *}{realm}
\funcarg{va_list}{ap}
\end{funcdecl}

\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.

Both functions take a realm name \funcparam{realm}, realm name length
\funcparam{rlen}, and a list of null-terminated strings, and fill in a
pointer to a principal structure \funcparam{princ}, making it point to a
structure representing the named principal.
The last string must be followed in the argument list by a null pointer.


\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcout}
\funcarg{krb5_principal *}{princ}
\funcin
\funcarg{int}{rlen}
\funcarg{const char *}{realm}
\funcarg{}{int len1, char *s1, int len2, char *s2, ..., 0}
\end{funcdecl}

\funcname{krb5_build_principal_ext} is similar to
\funcname{krb5_build_principal} but it takes its components as a list of
(length, contents) pairs rather than a list of null-terminated strings.
A length of zero indicates the end of the list.

\begin{funcdecl}{krb5_address_search}{krb5_boolean}{\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}
\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}
\end{funcdecl}

If the two principals are the same, return TRUE, else return FALSE.

\begin{funcdecl}{krb5_fulladdr_order}{int}{\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}
\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}
\funcarg{const krb5_keyblock *}{from}
\funcout
\funcarg{krb5_keyblock **}{to}
\end{funcdecl}

Copy a keyblock, filling in \funcparam{*to} to point to the newly
allocated copy, which should be freed with
\funcname{krb5_free_keyblock}. 

\begin{funcdecl}{krb5_copy_keyblock_contents}{krb5_error_code}{\funcin}
\funcarg{const krb5_keyblock *}{from}
\funcout
\funcarg{krb5_keyblock *}{to}
\end{funcdecl}

Copy a keyblock 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}
\funcarg{const krb5_creds *}{incred}
\funcout
\funcarg{krb5_creds **}{outcred}
\end{funcdecl}

Copy a credentials structure, filling in \funcparam{*outcred} to point
to the newly allocated copy, which should be freed with
\funcname{krb5_free_creds}.

\begin{funcdecl}{krb5_copy_data}{krb5_error_code}{\funcin}
\funcarg{const krb5_data *}{indata}
\funcout
\funcarg{krb5_data **}{outdata}
\end{funcdecl}

Copy a data structure, filling in \funcparam{*outdata} to point to the
newly allocated copy, which should be freed with \funcname{krb5_free_data}.

\begin{funcdecl}{krb5_copy_principal}{krb5_error_code}{\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}
\funcout
\funcarg{krb5_donot_replay *}{rep}
\end{funcdecl}
Extract the relevant parts of \funcparam{auth} and fill them into the
structure pointed to by \funcparam{rep}.  \funcparam{rep{\ptsto}client}
and \funcparam{rep{\ptsto}server} are set to allocated storage and
should be freed when \funcparam{*rep} is no longer needed.

\begin{funcdecl}{krb5_get_server_rcache}{krb5_error_code}{\funcin}
\funcarg{const krb5_data *}{piece}
\funcout
\funcarg{krb5_rcache *}{ret_rcache}
\end{funcdecl}
Generate a replay cache name, allocate space for its handle, and open
it.  \funcparam{piece} is used to distinguish this replay cache from
others currently in use on the system.  Typically, \funcparam{piece}
is the first component of the principal name for the client or server
which is calling \funcname{krb5_get_server_rcache}.

Upon successful return, \funcparam{ret_rcache} is filled in to contain a
handle to an open rcache, which should be closed with
\funcname{krb5_rc_close}.