path: root/doc/implement/libos-i.tex

The operating-system specific functions provide an interface between the
other parts of the \libname{libkrb5.a} libraries and the operating system.

Beware! Any of the functions below are allowed to be implemented as
macros.  Prototypes for functions can be found in {\tt
<krb5/libos-proto.h>}; other definitions (including macros, if used) are
in {\tt <krb5/libos.h>}.

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{description}
% These come from src/lib/osconfig.c
\item[extern char *\globalname{krb5_config_file}:] name of configuration file
\item[extern char *\globalname{krb5_trans_file}:] name of hostname/realm
name translation file
\item[extern char *\globalname{krb5_defkeyname}:] default name of key
table file
\item[extern char *\globalname{krb5_lname_file}:] name of aname/lname
translation database
\item[extern int \globalname{krb5_max_dgram_size}:] maximum allowable
datagram size
\item[extern int \globalname{krb5_max_skdc_timeout}:] maximum
per-message KDC reply timeout
\item[extern int \globalname{krb5_skdc_timeout_shift}:] shift factor
(bits) to exponentially back-off the KDC timeouts
\item[extern int \globalname{krb5_skdc_timeout_1}:] initial KDC timeout
\item[extern char *\globalname{krb5_kdc_udp_portname}:] name of KDC UDP port
\item[extern char *\globalname{krb5_default_pwd_prompt1}:] first prompt
for password reading.
\item[extern char *\globalname{krb5_default_pwd_prompt2}:] second prompt

\end{description}

\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_us_timeofday}{krb5_error_code}{\funcout}
\funcarg{krb5_int32 *}{seconds}
\funcarg{krb5_int32 *}{microseconds}
\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
microseconds portion in \funcparam{*microseconds}.

\begin{funcdecl}{krb5_net_read}{int}{\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.

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}
\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_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_error_code}{\funcin}
\funcarg{int}{size}
\funcout
\funcarg{krb5_pointer}{fillin}
\end{funcdecl}

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{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{const krb5_address *}{inaddr}
\funcarg{const char *}{uniq}
\funcout
\funcarg{char **}{string}
\end{funcdecl}

Given a \datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT}
in \funcparam{inaddr}, this function unpacks its component address and
additional type, and uses them along with \funcparam{uniq} to allocate a
fresh string to represent the address and additional information.  The
string is suitable for use as a replay cache tag.  This string is
allocated and should be freed with \funcname{free} when the caller has
finished using it.  When using IP addresses, the components in
\funcparam{inaddr\ptsto contents} must be of type
\datatype{ADDRTYPE_INET} and \datatype{ADDRTYPE_PORT}.

\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin}
\funcarg{const char *}{hostname}
\funcarg{const char *}{sname}
\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.
\funcparam{hostname} is placed into canonical form before being composed
into the returned principal \funcparam{ret_princ}.  The realm of the
principal is determined internally by calling \funcname{krb5_get_host_realm}.

The caller should release \funcparam{ret_princ}'s storage by calling
\funcname{krb5_free_principal} when it is finished with the principal.