The operating-system specific functions provide an interface between the
-other parts of the {\tt libkrb5.a} libraries and the operating system.
+other parts of the \libname{libkrb5.a} libraries and the operating system.
+
+Beware! Any of these are allowed to be implemented as macros.
+
+The following global symbols are provided in \libname{libos.a}. If you
+wish to substitute for any of them, you must substitute for all of them
+(they are all declared and initialized in the same object file):
+\begin{itemize}
+\item extern char *\globalname{krb5_default_pwd_prompt1}
+\item extern char *\globalname{krb5_default_pwd_prompt2}
+\item more to come...
+\end{itemize}
+
+\begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin}
+\funcarg{char *}{prompt}
+\funcarg{char *}{prompt2}
+\funcout
+\funcarg{char *}{return_pwd}
+\funcinout
+\funcarg{int *}{size_return}
+\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}.
+
+\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.
+
+\begin{funcdecl}{krb5_lock_file}{krb5_error_code}{\funcvoid}
+\funcarg{FILE *}{filep}
+\funcarg{char *}{pathname}
+\funcarg{int}{mode}
+\end{funcdecl}
+
+Attempts to lock the file in the given \funcparam{mode}; returns 0 for a
+successful lock, or an error code otherwise.
+
+The caller should arrange that both \funcparam{filep} and
+\funcparam{pathname} refer to the same
+file. The implementation may use whichever is more convenient.
+
+Modes are given in {\tt <krb5/libos.h>}
+
+
+\begin{funcdecl}{krb5_unlock_file}{krb5_error_code}{\funcvoid}
+\funcarg{FILE *}{filep}
+\funcarg{char *}{pathname}
+\end{funcdecl}
+
+Attempts to (completely) unlock the file. Returns 0 if successful,
+or an error code otherwise.
+
+The caller should arrange that both \funcparam{filep} and
+\funcparam{pathname} refer to the same file. The implementation may
+use whichever is more convenient.
+
+\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcout}
+\funcarg{krb5_int32 *}{timeret}
+\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]
+
+\begin{funcdecl}{krb5_ms_timeofday}{krb5_error_code}{\funcout}
+\funcarg{int32 *}{seconds}
+\funcarg{int16 *}{milliseconds}
+\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]
+
+The seconds portion is returned in \funcparam{*seconds}, the
+milliseconds portion in \funcparam{*milliseconds}.
+
+\begin{funcdecl}{krb5_net_read}{\funcin}
+\funcarg{int}{fd}
+\funcout
+\funcarg{char *}{buf}
+\funcin
+\funcarg{int}{len}
+\end{funcdecl}
+
+Like read(2), but guarantees that it reads as much as was requested
+or returns -1 and sets errno.
+
+(make sure your sender will send all the stuff you are looking for!)
+Only useful on stream sockets and pipes.
+
+\begin{funcdecl}{krb5_net_write}{int}{\funcin}
+\funcarg{int}{fd}
+\funcarg{const char *}{buf}
+\funcarg{int}{len}
+\end{funcdecl}
+
+Like write(2), but guarantees that it writes as much as was requested
+or returns -1 and sets errno.
+
+(make sure your sender will send all the stuff you are looking for!)
+Only useful on stream sockets and pipes.
+
+\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\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_data *}{send}
+\funcarg{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_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
+pointer to an argv[] style list of names, terminated with a null
+pointer.
+
+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{char **}{hostlist}
+\end{funcdecl}
+
+Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}.
+
+\begin{funcdecl}{krb5_aname_to_localname}{krb5_error_code}{\funcin}
+\funcarg{krb5_principal}{aname}
+\funcarg{int}{lnsize}
+\funcout
+\funcarg{char *}{lname}
+\end{funcdecl}
+
+Converts a principal name \funcparam{aname} to a local name suitable for use by
+programs wishing a translation to an environment-specific name (e.g.
+user account name).
+
+\funcparam{lnsize} specifies the maximum length name that is to be filled into
+\funcparam{lname}.
+The translation will be null terminated in all non-error returns.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code}{\funcin}
+\funcarg{int}{lnsize}
+\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).
+
+\funcparam{lnsize} specifies the maximum length name that is to be filled into
+\funcparam{lrealm}.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin}
+\funcarg{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{char **}{realmlist}
+\end{funcdecl}
+
+Frees the storage taken by a \funcparam{realmlist} returned by
+\funcname{krb5_get_local_realm}.
+
+\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin}
+\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_random_confounder}{krb5_confounder}{\funcvoid}
+\end{funcdecl}
+
+Generate a random confounder.
The operating-system specific functions provide an interface between the
-other parts of the {\tt libkrb5.a} libraries and the operating system.
+other parts of the \libname{libkrb5.a} libraries and the operating system.
+
+Beware! Any of these are allowed to be implemented as macros.
+
+The following global symbols are provided in \libname{libos.a}. If you
+wish to substitute for any of them, you must substitute for all of them
+(they are all declared and initialized in the same object file):
+\begin{itemize}
+\item extern char *\globalname{krb5_default_pwd_prompt1}
+\item extern char *\globalname{krb5_default_pwd_prompt2}
+\item more to come...
+\end{itemize}
+
+\begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin}
+\funcarg{char *}{prompt}
+\funcarg{char *}{prompt2}
+\funcout
+\funcarg{char *}{return_pwd}
+\funcinout
+\funcarg{int *}{size_return}
+\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}.
+
+\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.
+
+\begin{funcdecl}{krb5_lock_file}{krb5_error_code}{\funcvoid}
+\funcarg{FILE *}{filep}
+\funcarg{char *}{pathname}
+\funcarg{int}{mode}
+\end{funcdecl}
+
+Attempts to lock the file in the given \funcparam{mode}; returns 0 for a
+successful lock, or an error code otherwise.
+
+The caller should arrange that both \funcparam{filep} and
+\funcparam{pathname} refer to the same
+file. The implementation may use whichever is more convenient.
+
+Modes are given in {\tt <krb5/libos.h>}
+
+
+\begin{funcdecl}{krb5_unlock_file}{krb5_error_code}{\funcvoid}
+\funcarg{FILE *}{filep}
+\funcarg{char *}{pathname}
+\end{funcdecl}
+
+Attempts to (completely) unlock the file. Returns 0 if successful,
+or an error code otherwise.
+
+The caller should arrange that both \funcparam{filep} and
+\funcparam{pathname} refer to the same file. The implementation may
+use whichever is more convenient.
+
+\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcout}
+\funcarg{krb5_int32 *}{timeret}
+\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]
+
+\begin{funcdecl}{krb5_ms_timeofday}{krb5_error_code}{\funcout}
+\funcarg{int32 *}{seconds}
+\funcarg{int16 *}{milliseconds}
+\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]
+
+The seconds portion is returned in \funcparam{*seconds}, the
+milliseconds portion in \funcparam{*milliseconds}.
+
+\begin{funcdecl}{krb5_net_read}{\funcin}
+\funcarg{int}{fd}
+\funcout
+\funcarg{char *}{buf}
+\funcin
+\funcarg{int}{len}
+\end{funcdecl}
+
+Like read(2), but guarantees that it reads as much as was requested
+or returns -1 and sets errno.
+
+(make sure your sender will send all the stuff you are looking for!)
+Only useful on stream sockets and pipes.
+
+\begin{funcdecl}{krb5_net_write}{int}{\funcin}
+\funcarg{int}{fd}
+\funcarg{const char *}{buf}
+\funcarg{int}{len}
+\end{funcdecl}
+
+Like write(2), but guarantees that it writes as much as was requested
+or returns -1 and sets errno.
+
+(make sure your sender will send all the stuff you are looking for!)
+Only useful on stream sockets and pipes.
+
+\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\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_data *}{send}
+\funcarg{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_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
+pointer to an argv[] style list of names, terminated with a null
+pointer.
+
+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{char **}{hostlist}
+\end{funcdecl}
+
+Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}.
+
+\begin{funcdecl}{krb5_aname_to_localname}{krb5_error_code}{\funcin}
+\funcarg{krb5_principal}{aname}
+\funcarg{int}{lnsize}
+\funcout
+\funcarg{char *}{lname}
+\end{funcdecl}
+
+Converts a principal name \funcparam{aname} to a local name suitable for use by
+programs wishing a translation to an environment-specific name (e.g.
+user account name).
+
+\funcparam{lnsize} specifies the maximum length name that is to be filled into
+\funcparam{lname}.
+The translation will be null terminated in all non-error returns.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code}{\funcin}
+\funcarg{int}{lnsize}
+\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).
+
+\funcparam{lnsize} specifies the maximum length name that is to be filled into
+\funcparam{lrealm}.
+
+Returns system errors.
+
+\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin}
+\funcarg{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{char **}{realmlist}
+\end{funcdecl}
+
+Frees the storage taken by a \funcparam{realmlist} returned by
+\funcname{krb5_get_local_realm}.
+
+\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin}
+\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_random_confounder}{krb5_confounder}{\funcvoid}
+\end{funcdecl}
+
+Generate a random confounder.
projects / krb5.git / commitdiff