From: Ezra Peisach Date: Thu, 4 May 1995 18:40:12 +0000 (+0000) Subject: Reorganized some sections X-Git-Tag: krb5-1.0-beta5~33 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=4e85b1c6c73d6086b19ecb279fa26989af1061f3;p=krb5.git Reorganized some sections Added missing functions git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@5720 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/api/ChangeLog b/doc/api/ChangeLog index 9347f0c6f..dfc124b5e 100644 --- a/doc/api/ChangeLog +++ b/doc/api/ChangeLog @@ -1,7 +1,14 @@ +Thu May 4 14:29:45 1995 Ezra Peisach + + * krb5.tex: Reorganized into subsubsections. Added principal + access macros. + + * libos.tex: Added missing functions (os_context) and reorganized + into subsubsections. + Wed May 3 01:22:11 1995 Ezra Peisach - * krb5.tex (subsubsection{The krb5_auth_context}): Added - auth_context routines. + * krb5.tex: Added auth_context routines. * free.tex: Add krb5_xfree and krb5_free_data. diff --git a/doc/api/krb5.tex b/doc/api/krb5.tex index ca7709105..89f89dc4d 100644 --- a/doc/api/krb5.tex +++ b/doc/api/krb5.tex @@ -277,6 +277,274 @@ Sets the replay cache that is used by the authentication routines to \funcparam{ %% 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} @@ -1350,131 +1618,6 @@ The \funcparam{auth_context} flags specify whether timestamps 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 @@ -1494,15 +1637,6 @@ If \funcparam{addr} is listed in \funcparam{addrlist}, or 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 @@ -1617,18 +1751,6 @@ to the newly allocated copy, which should be freed with Copy a data structure, filling in \funcparam{*outdata} to point to the newly allocated copy, which should be freed with \funcname{krb5_free_data}. -\begin{funcdecl}{krb5_copy_principal}{krb5_error_code}{\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 @@ -1642,17 +1764,6 @@ 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 diff --git a/doc/api/libos.tex b/doc/api/libos.tex index 19a1c40bc..7b91631e4 100644 --- a/doc/api/libos.tex +++ b/doc/api/libos.tex @@ -29,38 +29,145 @@ for password reading. \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} @@ -109,32 +216,62 @@ Assures that the changes made to the file pointed to by the file handle fp are forced out to disk. -\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\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} @@ -183,63 +320,8 @@ using the network connection pointed to by \funcparam{fd}. Reads data from the network as a message, using the network connection pointed to by fd. -\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\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} @@ -259,75 +341,122 @@ The translation will be null terminated in all non-error returns. 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} @@ -340,24 +469,6 @@ Given a length and a pointer, fills in the area pointed to by \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} @@ -380,42 +491,3 @@ finished using it. When using IP addresses, the components in % 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.