From 70b4bc672a4fdffc763cc51dc008ce4df027ba9a Mon Sep 17 00:00:00 2001 From: John Kohl Date: Thu, 31 May 1990 22:05:24 +0000 Subject: [PATCH] add all the functions use \libname git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@978 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/api/libos.tex | 250 +++++++++++++++++++++++++++++++++++++- doc/implement/libos-i.tex | 250 +++++++++++++++++++++++++++++++++++++- 2 files changed, 498 insertions(+), 2 deletions(-) diff --git a/doc/api/libos.tex b/doc/api/libos.tex index 81d40fbbf..00a768cd7 100644 --- a/doc/api/libos.tex +++ b/doc/api/libos.tex @@ -1,2 +1,250 @@ 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 } + + +\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. diff --git a/doc/implement/libos-i.tex b/doc/implement/libos-i.tex index 81d40fbbf..00a768cd7 100644 --- a/doc/implement/libos-i.tex +++ b/doc/implement/libos-i.tex @@ -1,2 +1,250 @@ 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 } + + +\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. -- 2.26.2