%% krb5_auth_con_getcksumtype, krb5_auth_con_getivector,
%% krb5_auth_con_getrcache. -- Ezra
+\subsubsection{Principal access functions}
+
+Principals define a uniquely named client or server instance that
+participates in a network communication. The following functions allow
+one to create, modify and access portions of the
+\datatype{krb5_principal}.
+
+Other functions found in orther portions of the manual include
+\funcname{krb5_sname_to_principal}, \funcname{krb5_free_principal},
+
+While it is possible to directly access the data structure in the
+structure, it is recommended that the functions be used.
+
+\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{const char *}{name}
+\funcout
+\funcarg{krb5_principal *}{principal}
+\end{funcdecl}
+
+Converts a single-string representation \funcparam{name} of the
+principal name to the multi-part principal format used in the protocols.
+
+A single-string representation of a Kerberos name consists of one or
+more principal name components, separated by slashes, optionally
+followed by the ``@'' character and a realm name. If the realm name
+is not specified, the local realm is used.
+
+The slash and ``@'' characters may be quoted (i.e., included as part
+of a component rather than as a component separator or realm prefix)
+by preceding them with a backslash (``$\backslash$'') character.
+Similarly, newline, tab, backspace, and null characters may be
+included in a component by using $\backslash{}n$, $\backslash{}t$,
+$\backslash{}b$ or $\backslash{}0$, respectively.
+
+The realm in a Kerberos name may not contain the slash, colon or null
+characters.
+
+\funcparam{*principal} will point to allocated storage which should be freed by
+the caller (using \funcname{krb5_free_principal}) after use.
+
+\funcname{krb5_parse_name} returns KRB5_PARSE_MALFORMED if the string is
+ badly formatted, or ENOMEM if space for the return value can't be
+allocated.
+
+\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{principal}
+\funcout
+\funcarg{char **}{name}
+\end{funcdecl}
+
+Converts the multi-part principal name \funcparam{principal} from the
+format used in the protocols to a single-string representation of the
+name. The resulting single-string representation will use the format
+and quoting conventions described for \funcname{krb5_parse_name}
+above.
+
+\funcparam{*name} points to allocated storage and should be freed by the caller
+when finished.
+
+\funcname{krb5_unparse_name} returns {\sc KRB_PARSE_MALFORMED} if the principal
+does not contain at least 2 components, and system errors ({\sc ENOMEM} if
+unable to allocate memory).
+
+\begin{funcdecl}{krb5_unparse_name_ext}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{principal}
+\funcinout
+\funcarg{char **}{name}
+\funcarg{int *}{size}
+\end{funcdecl}
+
+\funcname{krb5_unparse_name_ext} is designed for applications which
+must unparse a large number of principals, and are concerned about the
+speed impact of needing to do a lot of memory allocations and
+deallocations. It functions similarly to \funcname{krb5_unparse_name}
+except if \funcparam{*name} is non-null, in which case, it is assumed
+to contain an allocated buffer of size \funcparam{*size} and this
+buffer will be resized with \funcname{realloc} to hold the unparsed
+name. Note that in this case,
+\funcparam{size} must not be null.
+
+If \funcparam{size} is non-null (whether or not \funcparam{*name} is
+null when the function is called), it will be filled in with the size
+of the unparsed name upon successful return.
+
+\begin{funcdecl}{krb5_princ_realm}{krb5_data}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\end{funcdecl}
+
+A macro which returns the realm of \funcparam{principal}.
+
+\begin{funcdecl}{krb5_princ_set_realm}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\funcparam{krb5_data *}{realm}
+\end{funcdecl}
+
+A macro which returns sets the realm of \funcparam{principal} to
+\funcparam{realm}.
+
+\begin{funcdecl}{krb5_princ_set_realm_data}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\funcparam{char *}{data}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which returns sets the data portion of the realm of
+\funcparam{principal} to \funcparam{data}.
+
+\begin{funcdecl}{krb5_princ_set_realm_length}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\funcparam{int}{length}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which returns sets the length \funcparam{principal} to
+\funcparam{length}.
+
+\begin{funcdecl}{krb5_princ_size}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which gives the number of elements in the principal.
+May also be used on the left size of an assignment.
+
+\begin{funcdecl}{krb5_princ_type}{void}{\funcinout}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which gives the type of the principal.
+May also be used on the left size of an assignment.
+
+\begin{funcdecl}{krb5_princ_data}{}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which gives the pointer to data portion of the principal.
+May also be used on the left size of an assignment.
+
+
+\begin{funcdecl}{krb5_princ_component}{}
+\funcparam{krb5_context}{context}
+\funcparam{krb5_principal}{principal}
+\funcparam{int}{i}
+\end{funcdecl}
+
+\internalfunc
+
+A macro which gives the pointer to ith element of the principal.
+May also be used on the left size of an assignment.
+
+\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{krb5_principal *}{princ}
+\funcin
+\funcarg{int}{rlen}
+\funcarg{const char *}{realm}
+\funcarg{char}{*s1, *s2, ..., 0}
+\end{funcdecl}
+\begin{funcdecl}{krb5_build_principal_va}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{krb5_principal *}{princ}
+\funcin
+\funcarg{int}{rlen}
+\funcarg{const char *}{realm}
+\funcarg{va_list}{ap}
+\end{funcdecl}
+
+\begin{sloppypar}
+\funcname{krb5_build_principal} and
+\funcname{krb5_build_principal_va}
+perform the same function; the former takes variadic arguments, while
+the latter takes a pre-computed varargs pointer.
+\end{sloppypar}
+
+Both functions take a realm name \funcparam{realm}, realm name length
+\funcparam{rlen}, and a list of null-terminated strings, and fill in a
+pointer to a principal structure \funcparam{princ}, making it point to a
+structure representing the named principal.
+The last string must be followed in the argument list by a null pointer.
+
+
+\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{krb5_principal *}{princ}
+\funcin
+\funcarg{int}{rlen}
+\funcarg{const char *}{realm}
+\funcarg{}{int len1, char *s1, int len2, char *s2, ..., 0}
+\end{funcdecl}
+
+\funcname{krb5_build_principal_ext} is similar to
+\funcname{krb5_build_principal} but it takes its components as a list of
+(length, contents) pairs rather than a list of null-terminated strings.
+A length of zero indicates the end of the list.
+
+\begin{funcdecl}{krb5_copy_principal}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{inprinc}
+\funcout
+\funcarg{krb5_principal *}{outprinc}
+\end{funcdecl}
+
+Copy a principal structure, filling in \funcparam{*outprinc} to point to
+the newly allocated copy, which should be freed with
+\funcname{krb5_free_principal}.
+
+\begin{funcdecl}{krb5_principal_compare}{krb5_boolean}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{princ1}
+\funcarg{krb5_const_principal}{princ2}
+\end{funcdecl}
+
+If the two principals are the same, return TRUE, else return FALSE.
+
+\begin{funcdecl}{krb5_realm_compare}{krb5_boolean}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{krb5_const_principal}{princ1}
+\funcarg{krb5_const_principal}{princ2}
+\end{funcdecl}
+
+If the realms of the two principals are the same, return TRUE, else
+return FALSE.
+
+
+\begin{funcdecl}{krb5_425_conv_principal}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{const char *}{name}
+\funcarg{const char *}{instance}
+\funcarg{const char *}{realm}
+\funcout
+\funcarg{krb5_principal *}{princ}
+\end{funcdecl}
+
+Build a principal \funcparam{princ} from a V4 specification made up of
+\funcparam{name}.\funcparam{instance}@\funcparam{realm}. The routine is
+site-customized to convert the V4 naming scheme to a V5 one. For
+instance, the V4 ``rcmd'' is changed to ``host''.
+
+The returned principal should be freed with
+\funcname{krb5_free_principal}.
+
\subsubsection{The application functions}
\begin{funcdecl}{krb5_encode_kdc_rep}{krb5_error_code}{\funcin}
Returns system errors, integrity errors.
-\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcin
-\funcarg{const char *}{name}
-\funcout
-\funcarg{krb5_principal *}{principal}
-\end{funcdecl}
-
-Converts a single-string representation \funcparam{name} of the
-principal name to the multi-part principal format used in the protocols.
-
-A single-string representation of a Kerberos name consists of one or
-more principal name components, separated by slashes, optionally
-followed by the ``@'' character and a realm name. If the realm name
-is not specified, the local realm is used.
-
-The slash and ``@'' characters may be quoted (i.e., included as part
-of a component rather than as a component separator or realm prefix)
-by preceding them with a backslash (``$\backslash$'') character.
-Similarly, newline, tab, backspace, and null characters may be
-included in a component by using $\backslash{}n$, $\backslash{}t$,
-$\backslash{}b$ or $\backslash{}0$, respectively.
-
-The realm in a Kerberos name may not contain the slash, colon or null
-characters.
-
-\funcparam{*principal} will point to allocated storage which should be freed by
-the caller (using \funcname{krb5_free_principal}) after use.
-
-\funcname{krb5_parse_name} returns KRB5_PARSE_MALFORMED if the string is
- badly formatted, or ENOMEM if space for the return value can't be
-allocated.
-
-\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcin
-\funcarg{krb5_const_principal}{principal}
-\funcout
-\funcarg{char **}{name}
-\end{funcdecl}
-
-Converts the multi-part principal name \funcparam{principal} from the
-format used in the protocols to a single-string representation of the
-name. The resulting single-string representation will use the format
-and quoting conventions described for \funcname{krb5_parse_name}
-above.
-
-\funcparam{*name} points to allocated storage and should be freed by the caller
-when finished.
-
-\funcname{krb5_unparse_name} returns {\sc KRB_PARSE_MALFORMED} if the principal
-does not contain at least 2 components, and system errors ({\sc ENOMEM} if
-unable to allocate memory).
-
-\begin{funcdecl}{krb5_unparse_name_ext}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcin
-\funcarg{krb5_const_principal}{principal}
-\funcinout
-\funcarg{char **}{name}
-\funcarg{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}{\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}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcout
-\funcarg{krb5_principal *}{princ}
-\funcin
-\funcarg{int}{rlen}
-\funcarg{const char *}{realm}
-\funcarg{va_list}{ap}
-\end{funcdecl}
-
-\begin{sloppypar}
-\funcname{krb5_build_principal} and
-\funcname{krb5_build_principal_va}
-perform the same function; the former takes variadic arguments, while
-the latter takes a pre-computed varargs pointer.
-\end{sloppypar}
-
-Both functions take a realm name \funcparam{realm}, realm name length
-\funcparam{rlen}, and a list of null-terminated strings, and fill in a
-pointer to a principal structure \funcparam{princ}, making it point to a
-structure representing the named principal.
-The last string must be followed in the argument list by a null pointer.
-
-
-\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcinout}
-\funcarg{krb5_context}{context}
-\funcout
-\funcarg{krb5_principal *}{princ}
-\funcin
-\funcarg{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}{\funcinout}
\funcarg{krb5_context}{context}
\funcin
If the two addresses are the same, return TRUE, else return FALSE.
-\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}{\funcinout}
\funcarg{krb5_context}{context}
\funcin
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}{\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_copy_ticket}{krb5_error_code}{\funcinout}
\funcarg{krb5_context}{context}
\funcin
\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
\end{description}
-\begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin}
+\subsubsection{Operating specific context}
+The \datatype{krb5_context} has space for operating system specific
+data. These functions are called from \funcname{krb5_init_context} and
+\funcname{krb5_free_context}, but are included here for completeness.
+
+\begin{funcdecl}{krb5_os_init_context}{krb5_error_code}{\funcinout}
\funcarg{krb5_context}{context}
-\funcarg{char *}{prompt}
-\funcarg{char *}{prompt2}
+\end{funcdecl}
+
+\internalfunc
+
+Initializes \funcparam{context{\ptsto}os_context} and establishes the
+location of the initial configuration files.
+
+\begin{funcdecl}{krb5_os_free_context}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\end{funcdecl}
+
+\internalfunc
+
+Frees the operating system specific portion of \funcparam{context}.
+
+\subsubsection{Configuration based functions}
+These functions allow access to configuration specific information. In
+some cases, the configuration may be overriden by program control.
+
+
+\begin{funcdecl}{krb5_set_config_files}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{const char **}{filenames}
+\end{funcdecl}
+
+Sets the list of configuration files to be examined in determining
+machine defaults. \funcparam{filenames} is an array of files to check in
+order. The array must have a NULL entry as the last element.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{const krb5_data *}{realm}
\funcout
-\funcarg{char *}{return_pwd}
-\funcinout
-\funcarg{int *}{size_return}
+\funcarg{char ***}{hostlist}
\end{funcdecl}
-Read a password from the keyboard. The first \funcparam{*size_return}
-bytes of the password entered are returned in \funcparam{return_pwd}.
-If fewer than \funcparam{*size_return} bytes are typed as a password,
-the remainder of \funcparam{return_pwd} is zeroed. Upon success, the
-total number of bytes filled in is stored in \funcparam{*size_return}.
+Figures out the Kerberos server names for the given \funcparam{realm},
+filling in \funcparam{hostlist} with a null terminated array of
+pointers to hostnames.
+
+If \funcparam{realm} is unknown, the filled-in pointer is set to NULL.
-\funcparam{prompt} is used as the prompt for the first reading of a password.
-It is printed to the terminal, and then a password is read from the
-keyboard. No newline or spaces are emitted between the prompt and the
-cursor, unless the newline/space is included in the prompt.
+The pointer array and strings pointed to are all in allocated storage,
+and should be freed by the caller when finished.
-If \funcparam{prompt2} is a null pointer, then the password is read
-once. If \funcparam{prompt2} is set, then it is used as a prompt to
-read another password in the same manner as described for
-\funcparam{prompt}. After the second password is read, the two
-passwords are compared, and an error is returned if they are not
-identical.
+Returns system errors.
-Echoing is turned off when the password is read.
+\begin{funcdecl}{krb5_free_krbhst}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{char * const *}{hostlist}
+\end{funcdecl}
-If there is an error in reading or verifying the password, an error code
-is returned; else zero is returned.
+Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}.
+
+\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{char **}{lrealm}
+\end{funcdecl}
+
+Retrieves the default realm to be used if no user-specified realm is
+available (e.g. to interpret a user-typed principal name with the
+realm omitted for convenience), filling in \funcparam{lrealm} with a
+pointer to the default realm in allocated storage.
+
+It is the caller's responsibility for freeing the allocated storage
+pointed to be \funcparam{lream} when it is finished with it.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_set_default_realm}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{char *}{realm}
+\end{funcdecl}
+
+Sets the default realm to be used if no user-specified realm is
+available (e.g. to interpret a user-typed principal name with the
+realm omitted for convenience). (c.f. krb5_get_default_realm)
+
+If \funcparam{realm} is NULL, then the operating system default value
+will used.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{const char *}{host}
+\funcout
+\funcarg{char ***}{realmlist}
+\end{funcdecl}
+
+Figures out the Kerberos realm names for \funcparam{host}, filling in
+\funcparam{realmlist} with a
+pointer to an argv[] style list of names, terminated with a null pointer.
+
+If \funcparam{host} is NULL, the local host's realms are determined.
+
+If there are no known realms for the host, the filled-in pointer is set
+to NULL.
+
+The pointer array and strings pointed to are all in allocated storage,
+and should be freed by the caller when finished.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_free_host_realm}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{char * const *}{realmlist}
+\end{funcdecl}
+
+Frees the storage taken by a \funcparam{realmlist} returned by
+\funcname{krb5_get_local_realm}.
+
+\begin{funcdecl}{krb5_get_realm_domain}{krb5_error_code}{\funcinout}
+\funcarg{krb5_context}{context}
+\funcin
+\funcarg{const char *}{realm}
+\funcout
+\funcarg{char **}{domain}
+\end{funcdecl}
+
+Determines the proper name of a realm. This is mainly so that a krb4
+principal can be converted properly into a krb5 one. If
+\funcparam{realm} is null, the function will assume the default realm of
+the host. The returned \funcparam{*domain} is allocated and must be
+freed by the caller.
+
+\subsubsection{Disk based functions}
+These functions all relate to disk based I/O.
\begin{funcdecl}{krb5_lock_file}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
handle
fp are forced out to disk.
-\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcin}
+\subsubsection{Network based routines}
+
+These routines send and receive network data the specifics
+of addresses and families on a given operating system.
+
+\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
\funcout
+\funcarg{krb5_address ***}{addr}
+\end{funcdecl}
+
+Return all the protocol addresses of this host.
+
+Compile-time configuration flags will indicate which protocol family
+addresses might be returned.
+\funcparam{*addr} is filled in to point to an array of address pointers,
+terminated by a null pointer. All the storage pointed to is allocated
+and should be freed by the caller with \funcname{krb5_free_address}
+when no longer needed.
+
+\begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
-\funcarg{krb5_int32 *}{timeret}
+\funcarg{const krb5_address *}{adr}
+\funcarg{krb5_const_pointer}{ptr}
+\funcout
+\funcarg{krb5_address **}{outaddr}
\end{funcdecl}
-Retrieves the system time of day, in seconds since the local system's
-epoch.
-[The ASN.1 encoding routines must convert this to the standard ASN.1
-encoding as needed]
+Given an address \funcparam{adr} and an additional address-type specific
+portion pointed to by
+\funcparam{port} this routine
+combines them into a freshly-allocated
+\datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} and fills in
+\funcparam{*outaddr} to point to this address. For IP addresses,
+\funcparam{ptr} should point to a network-byte-order TCP or UDP port
+number. Upon success, \funcparam{*outaddr} will point to an allocated
+address which should be freed with \funcname{krb5_free_address}.
-\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcin}
+
+\begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
+\funcarg{const krb5_data *}{send}
+\funcarg{const krb5_data *}{realm}
\funcout
-\funcarg{krb5_int32 *}{seconds}
-\funcarg{krb5_int32 *}{microseconds}
+\funcarg{krb5_data *}{receive}
\end{funcdecl}
-Retrieves the system time of day, in seconds since the local system's
-epoch.
-[The ASN.1 encoding routines must convert this to the standard ASN.1
-encoding as needed]
+Send the message \funcparam{send} to a KDC for realm \funcparam{realm} and
+return the response (if any) in \funcparam{receive}.
+
+If the message is sent and a response is received, 0 is returned,
+otherwise an error code is returned.
+
+The storage for \funcparam{receive} is allocated and should be freed by
+the caller when finished.
-{\raggedright The seconds portion is returned in \funcparam{*seconds}, the
-microseconds portion in \funcparam{*microseconds}.}
\begin{funcdecl}{krb5_net_read}{int}{\funcin}
\funcarg{krb5_context}{context}
Reads data from the network as a message, using the network connection
pointed to by fd.
-\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcout
-\funcarg{krb5_address ***}{addr}
-\end{funcdecl}
-
-Return all the protocol addresses of this host.
-
-Compile-time configuration flags will indicate which protocol family
-addresses might be returned.
-\funcparam{*addr} is filled in to point to an array of address pointers,
-terminated by a null pointer. All the storage pointed to is allocated
-and should be freed by the caller with \funcname{krb5_free_address}
-when no longer needed.
-
-
-\begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{const krb5_data *}{send}
-\funcarg{const krb5_data *}{realm}
-\funcout
-\funcarg{krb5_data *}{receive}
-\end{funcdecl}
-
-Send the message \funcparam{send} to a KDC for realm \funcparam{realm} and
-return the response (if any) in \funcparam{receive}.
-
-If the message is sent and a response is received, 0 is returned,
-otherwise an error code is returned.
-
-The storage for \funcparam{receive} is allocated and should be freed by
-the caller when finished.
-
-\begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{const krb5_data *}{realm}
-\funcout
-\funcarg{char ***}{hostlist}
-\end{funcdecl}
-
-Figures out the Kerberos server names for the given \funcparam{realm},
-filling in \funcparam{hostlist} with a null terminated array of
-pointers to hostnames.
-
-If \funcparam{realm} is unknown, the filled-in pointer is set to NULL.
-
-The pointer array and strings pointed to are all in allocated storage,
-and should be freed by the caller when finished.
-
-Returns system errors.
-
-\begin{funcdecl}{krb5_free_krbhst}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{char * const *}{hostlist}
-\end{funcdecl}
-
-Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}.
+\subsubsection{Operating specific access functions}
+These functions are involved with access control decisions and policies.
\begin{funcdecl}{krb5_aname_to_localname}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
Returns system errors.
-\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code}{\funcin}
+\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin}
+\funcarg{krb5_context}{context}
+\funcarg{krb5_principal}{principal}
+\funcarg{const char *}{luser}
+\end{funcdecl}
+
+Given a Kerberos principal \funcparam{principal}, and a local username
+\funcparam{luser},
+determine whether user is authorized to login to the account \funcparam{luser}.
+Returns TRUE if authorized, FALSE if not authorized.
+
+\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
+\funcarg{const char *}{hostname}
+\funcarg{const char *}{sname}
+\funcarg{krb5_int32}{type}
\funcout
-\funcarg{char **}{lrealm}
+\funcarg{krb5_principal *}{ret_princ}
\end{funcdecl}
-Retrieves the default realm to be used if no user-specified realm is
-available (e.g. to interpret a user-typed principal name with the
-realm omitted for convenience), filling in \funcparam{lrealm} with a
-pointer to the default realm in allocated storage.
+Given a hostname \funcparam{hostname} and a generic service name
+\funcparam{sname}, this function generates a full principal name to be
+used when authenticating with the named service on the host. The full
+prinicpal name is returned in \funcparam{ret_princ}.
-It is the caller's responsibility for freeing the allocated storage
-pointed to be \funcparam{lream} when it is finished with it.
+The realm of the
+principal is determined internally by calling \funcname{krb5_get_host_realm}.
-Returns system errors.
+The \funcparam{type} argument controls how
+\funcname{krb5_sname_to_principal} generates the principal name,
+\funcparam{ret_princ}, for the named service, \funcparam{sname}.
+Currently, two values are supported: KRB5_NT_SRV_HOST, and
+KRB5_NT_UNKNOWN.
-\begin{funcdecl}{krb5_set_default_realm}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{char *}{realm}
-\end{funcdecl}
+If \funcparam{type} is set to
+KRB5_NT_SRV_HOST, the hostname will be
+canonicalized, i.e. a fully qualified lowercase hostname using
+the primary name and the domain name, before \funcparam{ret_princ} is
+generated in the form
+"sname/hostname@LOCAL.REALM." Most applications should use
+KRB5_NT_SRV_HOST.
-Sets the default realm to be used if no user-specified realm is
-available (e.g. to interpret a user-typed principal name with the
-realm omitted for convenience). (c.f. krb5_get_default_realm)
+However, if \funcparam{type} is set to KRB5_NT_UNKNOWN,
+while the generated principal name will have the form
+"sname/hostname@LOCAL.REALM" the hostname will not be canonicalized
+first. It will appear exactly as it was passed in \funcparam{hostname}.
-If \funcparam{realm} is NULL, then the operating system default value
-will used.
+The caller should release \funcparam{ret_princ}'s storage by calling
+\funcname{krb5_free_principal} when it is finished with the principal.
-Returns system errors.
-\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin}
+
+\subsubsection{Miscellaneous operating specific functions}
+These functions handle the other operating specific functions that do
+not fall into any other major class.
+
+\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
-\funcarg{const char *}{host}
\funcout
-\funcarg{char ***}{realmlist}
+\funcarg{krb5_context}{context}
+\funcarg{krb5_int32 *}{timeret}
\end{funcdecl}
-Figures out the Kerberos realm names for \funcparam{host}, filling in
-\funcparam{realmlist} with a
-pointer to an argv[] style list of names, terminated with a null pointer.
-
-If \funcparam{host} is NULL, the local host's realms are determined.
+Retrieves the system time of day, in seconds since the local system's
+epoch.
+[The ASN.1 encoding routines must convert this to the standard ASN.1
+encoding as needed]
-If there are no known realms for the host, the filled-in pointer is set
-to NULL.
+\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcin}
+\funcarg{krb5_context}{context}
+\funcout
+\funcarg{krb5_int32 *}{seconds}
+\funcarg{krb5_int32 *}{microseconds}
+\end{funcdecl}
-The pointer array and strings pointed to are all in allocated storage,
-and should be freed by the caller when finished.
+Retrieves the system time of day, in seconds since the local system's
+epoch.
+[The ASN.1 encoding routines must convert this to the standard ASN.1
+encoding as needed]
-Returns system errors.
+{\raggedright The seconds portion is returned in \funcparam{*seconds}, the
+microseconds portion in \funcparam{*microseconds}.}
-\begin{funcdecl}{krb5_free_host_realm}{krb5_error_code}{\funcin}
+\begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
-\funcarg{char * const *}{realmlist}
+\funcarg{char *}{prompt}
+\funcarg{char *}{prompt2}
+\funcout
+\funcarg{char *}{return_pwd}
+\funcinout
+\funcarg{int *}{size_return}
\end{funcdecl}
-Frees the storage taken by a \funcparam{realmlist} returned by
-\funcname{krb5_get_local_realm}.
+Read a password from the keyboard. The first \funcparam{*size_return}
+bytes of the password entered are returned in \funcparam{return_pwd}.
+If fewer than \funcparam{*size_return} bytes are typed as a password,
+the remainder of \funcparam{return_pwd} is zeroed. Upon success, the
+total number of bytes filled in is stored in \funcparam{*size_return}.
-\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{krb5_principal}{principal}
-\funcarg{const char *}{luser}
-\end{funcdecl}
+\funcparam{prompt} is used as the prompt for the first reading of a password.
+It is printed to the terminal, and then a password is read from the
+keyboard. No newline or spaces are emitted between the prompt and the
+cursor, unless the newline/space is included in the prompt.
+
+If \funcparam{prompt2} is a null pointer, then the password is read
+once. If \funcparam{prompt2} is set, then it is used as a prompt to
+read another password in the same manner as described for
+\funcparam{prompt}. After the second password is read, the two
+passwords are compared, and an error is returned if they are not
+identical.
+
+Echoing is turned off when the password is read.
+
+If there is an error in reading or verifying the password, an error code
+is returned; else zero is returned.
-Given a Kerberos principal \funcparam{principal}, and a local username
-\funcparam{luser},
-determine whether user is authorized to login to the account \funcparam{luser}.
-Returns TRUE if authorized, FALSE if not authorized.
\begin{funcdecl}{krb5_random_confounder}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
\funcparam{fillin} with \funcparam{size} random octets suitable for use
in a confounder.
-\begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{const krb5_address *}{adr}
-\funcarg{krb5_const_pointer}{ptr}
-\funcout
-\funcarg{krb5_address **}{outaddr}
-\end{funcdecl}
-
-Given an address \funcparam{adr} and an additional address-type specific
-portion pointed to by
-\funcparam{port} this routine
-combines them into a freshly-allocated
-\datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} and fills in
-\funcparam{*outaddr} to point to this address. For IP addresses,
-\funcparam{ptr} should point to a network-byte-order TCP or UDP port
-number. Upon success, \funcparam{*outaddr} will point to an allocated
-address which should be freed with \funcname{krb5_free_address}.
-
\begin{funcdecl}{krb5_gen_replay_name}{krb5_error_code}{\funcin}
\funcarg{krb5_context}{context}
\funcarg{const krb5_address *}{inaddr}
% outputs char * when krb5_get_server_rcache expects krb5_data''
% (OpenVision Cambridge bug number 1582) causes the code of this
% function to change, the documentation above will have to be updated.
-
-\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin}
-\funcarg{krb5_context}{context}
-\funcarg{const char *}{hostname}
-\funcarg{const char *}{sname}
-\funcarg{krb5_int32}{type}
-\funcout
-\funcarg{krb5_principal *}{ret_princ}
-\end{funcdecl}
-
-Given a hostname \funcparam{hostname} and a generic service name
-\funcparam{sname}, this function generates a full principal name to be
-used when authenticating with the named service on the host. The full
-prinicpal name is returned in \funcparam{ret_princ}.
-
-The realm of the
-principal is determined internally by calling \funcname{krb5_get_host_realm}.
-
-The \funcparam{type} argument controls how
-\funcname{krb5_sname_to_principal} generates the principal name,
-\funcparam{ret_princ}, for the named service, \funcparam{sname}.
-Currently, two values are supported: KRB5_NT_SRV_HOST, and
-KRB5_NT_UNKNOWN.
-
-If \funcparam{type} is set to
-KRB5_NT_SRV_HOST, the hostname will be
-canonicalized, i.e. a fully qualified lowercase hostname using
-the primary name and the domain name, before \funcparam{ret_princ} is
-generated in the form
-"sname/hostname@LOCAL.REALM." Most applications should use
-KRB5_NT_SRV_HOST.
-
-However, if \funcparam{type} is set to KRB5_NT_UNKNOWN,
-while the generated principal name will have the form
-"sname/hostname@LOCAL.REALM" the hostname will not be canonicalized
-first. It will appear exactly as it was passed in \funcparam{hostname}.
-
-The caller should release \funcparam{ret_princ}'s storage by calling
-\funcname{krb5_free_principal} when it is finished with the principal.
projects / krb5.git / commitdiff