krb_sendauth(3krb) krb_sendauth(3krb)
Name
krb_sendauth, krb_recvauth - Kerberos authentication library routines.
Syntax
#include <krb.h>
#include <des.h>
#include <netinet/in.h>
int krb_sendauth (options, fd, tkt_authen, f_service,
f_inst, f_realm, checksum, msg_data,
cred, schedule, l_addr, f_addr,
version_in)
long options;
int fd;
KTEXT tkt_authen;
char *f_service;
char *f_instance;
char *f_realm;
u_long checksum;
MSG_DAT *msg_data;
CREDENTIALS *cred;
Key_schedule schedule;
struct sockaddr_in *l_addr;
struct sockaddr_in *f_addr;
char *version_in;
int krb_recvauth (options, fd, tkt_authen_out, l_service,
l_instance, f_addr, l_addr, ad,
srvtab_file, schedule, version_out)
long options;
int fd;
KTEXT tkt_authen_out;
char *l_service;
char *l_instance;
struct sockaddr_in *f_addr;
struct sockaddr_in *l_addr;
AUTH_DAT *ad;
char *srvtab_file;
Key_schedule schedule;
char *version_out;
Arguments
options Defined in To specify multiple options, construct the options argument as a bitwise-OR of the desired options. The options are as
follows:
KOPT_DONT_MK_REQ
will not use the function (see to produce the ticket-authenticator pair, authen_tkt. Instead, the ticket-authenticator
pair is read from the argument, tkt_authen.
KOPT_DONT_CANON
will not convert the instance name, f_instance, to canonical form. If KOPT_DONT_CANON is not set, the instance name used
is the output from (see with argument f_instance as input.
KOPT_DO_MUTUAL
and provide authentication on both ends of the network connection. Otherwise, the caller of is authenticated to the call-
er of but the caller of is not authenticated to the caller of For mutual authentication to occur, both and must be called
with this option set.
f_service
Character pointer to the primary name of the foreign principal. The local principal is the principal that calls the above rou-
tines. The foreign principal is the principal with which the local principal is attempting to communicate. If KOPT_DONT_MK_REQ is
set and KOPT_DO_MUTUAL is not, then f_service should be set equal to the NULL pointer.
f_instance
Character pointer to the instance name of the foreign principal. If KOPT_DONT_MK_REQ is set and KOPT_DO_MUTUAL is not, then
f_instance should be set equal to the NULL pointer.
f_realm Character pointer to the realm name of the foreign principal. If the f_realm parameter is set equal to the NULL pointer, then the
local realm is used as the f_realm. If KOPT_DONT_MK_REQ is set and KOPT_DO_MUTUAL is not, then f_service should be set equal to
the NULL pointer.
l_service
Character pointer to the primary name of the local principal.
l_instance
Character pointer to the instance name of the local principal.
fd The file descriptor used to send data to the foreign principal, or the file descriptor from which data from the foreign principal
can be read. In either case, the file descriptor must be associated with a socket that uses blocking I/O.
tkt_authen
Pointer to the text structure in which the Kerberos library routines build the ticket-authenticator pair. This structure is
designed to be included within the message sent to the foreign principal to authenticate the local principal's identity to the for-
eign principal. This structure can be either input to or output from depending on whether KOPT_DONT_MK_REQ is set or not set. In
either case, storage must be allocated for tkt_authen.
tkt_authen_out
Pointer to the ticket-authenticator pair that reads from within the message. The message is sent by to the local principal to
authenticate the foreign principal to the local principal. Storage must be allocated for tkt_authen_out.
checksum
Input to checksum is packaged in the message that is sent to the foreign principal. It serves as a secret piece of data that can
only be known to the foreign principal if the foreign principal is authenticated as the foreign principal. It is used to facili-
tate mutual authentication, so if the KOPT_DO_MUTUAL is not set, the value of this argument is inconsequential. If both
KOPT_DONT_MK_REQ and KOPT_DO_MUTUAL are set, then the checksum parameter must be equal to the checksum value used by in the cre-
ation of the ticket-authenticator pair, authen_tkt.
msg_data
Pointer to a structure which is filled with the mutual authentication message sent by and interpreted by The message sent from to
the message that includes the ticket-authenticator pair, authenticates only the caller of to the caller of An additional message,
the one returned by inside msg_data, must be sent by and interpreted by in order to authenticate the caller of to the caller of If
the KOPT_DO_MUTUAL option is set, space must be allocated for the msg_data structure. Otherwise, since no message will be sent
from to the msg_data parameter should be set equivalent to the NULL pointer.
cred a pointer to a credentials structure that is output from The credentials structure includes the ticket that the local principal
uses to authenticate to the foreign principal as well as other authentication information associated with the foreign principal.
If the KOPT_DO_MUTUAL option is set, space must be allocated for the cred structure and the cred structure will be filled in by
Otherwise, the cred structure will not be filled in by so the cred parameter should be set equivalent to the NULL pointer.
schedule
a key schedule, derived from the session key between the local and foreign principals, that is output from and If the
KOPT_DO_MUTUAL option is set, the key schedule will be filled in; otherwise, the key schedule will not be filled. In any case,
space must be allocated for the key schedule.
f_addr the address of the socket that the foreign principal is using to communicate with the local principal. If the KOPT_DO_MUTUAL
option is not set on a call to then the f_addr parameter should be set equivalent to the NULL pointer. f_addr should never be set
to NULL on a call to
l_addr the address of the socket that the local principal is using to communicate with the foreign principal. If the KOPT_DO_MUTUAL
option is not set, the l_addr parameter should be set equivalent to the NULL pointer.
ad a pointer to the AUTH_DAT structure that describes the authentication association between the local and foreign principals. Since
it is output from space for the ad structure must be allocated.
srvtab_file
path name of the file that contains the key of the principal obtaining a ticket. If this value is set equal to a string of zero
length, the default service table file (srvtab) value is used. If this value is set equal to the NULL pointer, then the key of the
service is not read from the srvtab file, but is read from storage space internal to the libraries. The srvtab_file parameter can-
not be set to the NULL string on the first call to The default srvtab file value is set to although this value can be changed by a
call to the function (see
version_in
An application-specific version string input to This argument allows the caller of to pass an application-specific version string,
within the message format, that the caller of can use to match against its own version string. The version string can be up to
KRB_SENDAUTH_VLEN characters long and, in addition, it can be set equal to the NULL string.
version_out
An application-specific version string output from This argument allows the caller of to receive the application-specific version
string included in the message that was sent by the foreign principal. The version string can be up to KRB_SENDAUTH_VLEN charac-
ters long.
Description
The routines are designed to be used by applications that communicate over a network, require the authentication of both parties across the
communications path, and which support "on-the-wire" protocols that have no room for authentication information. The routines are designed
to perform only the authentication of the first message sent between such applications. Therefore, the routines should be used before any
other communication occurs between the authenticating principals.
After the communications channel between the applications has been established, but before any communication takes place, and before the
"on-the-wire" protocol of the application comes into effect, creates a message which can authenticate the caller of "A", to the caller of
"B". then sends the message to "B" where it is read from the communications channel by
Next, attempts to authenticate "A" by producing a response to "A" which, depending upon the value of KOPT_DO_MUTUAL and the success of the
authentication of "A" by will contain either an error code, a code indicating success, or a mutual authentication message. sends the
response and returns to "B". receives the message from "B", tries to authenticate "B" if KOPT_DO_MUTUAL is set, and then returns to "A".
Since the authentication information is sent between the applications before the "on-the-wire" protocol of the application comes into
effect, the application must develop some method of distinguishing between the new authenticated initial message exchange and an old unau-
thenticated initial message exchange.
The routines make extensive use of the locally defined data types KTEXT, MSG_DAT, CREDENTIALS, and Key_schedule. For specific information
on the definitions of these data types, see the des.h and krb.h files.
The routines found in the library are and
krb_sendauth
The function is designed to authenticate a local principal, "A", to the principal specified by the f_service, f_instance, and f_realm
parameters, "B", and to allow the authentication of "B" to "A" as well. uses file descriptor fd, to send the authentication message that
will authenticate "A" to principal "B". It returns, in the tkt_authen parameter, the ticket-authenticator pair used to authenticate "A" to
"B". The version_in parameter contains an application-specific version string which is transmitted to "B" along with the authentication
message.
If mutual authentication is selected as an option, the file descriptor, fd will be used to receive a mutual authentication message from
"B". To allow the mutual authentication to take place, l_addr and f_addr must be set equal to the address of the sockets which the local
and foreign principals use to communicate. A value known only to "A" must be input to as the checksum parameter. As the result of mutual
authentication, cred will be filled with data describing the authentication information associated with "B", schedule will be set equal to
the key_schedule of the session key between "A" and "B", and msg_data will be set equal to the mutual authentication message sent from "B"
to "A".
fd must be a file descriptor associated with a blocking socket. Otherwise, will not function correctly.
If "A" has been correctly authenticated to "B" and mutual authentication was not chosen as an option, or if "A" has been correctly authen-
ticated to "B", and "B" correctly authenticated to "A" and mutual authentication was chosen as an option, then KSUCCESS is returned by
The following is a list of most of the error values from Since calls other section 3 Kerberos routines ( to perform its function, some of
the error codes are references to the error codes of other functions:
SENDAUTH_OPNOTSUP The options bits sent to contain a bit which is set, but does not correspond to an option.
SENDAUTH_WR could not write the authentication message to "B" using fd.
KFAILURE The file cannot be opened, or
The file (see is not formed properly, or
An authentication message was sent from "A" to "B", but "B" could not successfully identify "A", or
A mutual authentication message was sent from "B" to "A", but "A" could not successfully identify "B".
-1 Negative one is returned if each byte of the session key does not have odd parity.
-2 Negative two is returned if the session key is a weak key as defined by (see
NO_TKT_FIL The ticket file does not exist.
TKT_FIL_ACC The ticket file cannot be opened or the ticket file cannot be accessed.
TKT_FIL_LCK The ticket file could not be locked for access.
TKT_FIL_FMT The ticket file format is incorrect.
AD_NOTGT There is no ticket-granting-ticket in the ticket file that can be used to ask for a ticket to communicate with the for-
eign principal.
SKDC_CANT A Kerberos server must be contacted in order for to perform its function, but the attempt cannot be made because a socket
cannot be opened or bound, or there is no Kerberos server listed in
SKDC_RETRY A Kerberos server needs to be contacted, but none responded even after several retries.
INTK_PROT Kerberos protocol error.
GC_NOTKT Information concerning the foreign principal does not exist in the ticket file.
RECVMUT_OPNOTSUP The options bits sent to (see contain a bit which is set, but does not correspond to an option.
RECVMUT_RD If the message cannot be read from the file descriptor fd, SENDMUT_RD is returned.
RD_AP_VERSION If the Kerberos version used to create the mutual authentication message is not supported by then RD_AP_VERSION is
returned.
RD_AP_MSG_TYPE If the message read from the file descriptor, fd, is not a mutual authentication message, RD_AP_MSG_TYPE is returned.
RD_AP_MODIFIED If the mutual authentication message has been modified between the "B" and "A" or it was in some way incorrectly pro-
duced, RD_AP_MODIFIED is returned.
RD_AP_TIME Returned if the mutual authentication message is too old.
krb_recvauth
The function is designed to wait for a message from on the file descriptor fd, receive the message and attempt to authenticate the foreign
principal, "A", to the local principal determined by the l_service and l_instance parameters. The srvtab_file must contain the private key
of principal "B". The tkt_authen_out parameter is filled with the ticket-authenticator pair sent within the message received by "B" from
"A". ad is filled with information that describes the authentication association between "A" and "B". version_out is filled with the
application version string included in the message.
If mutual authentication is selected as an option, the file descriptor fd, will be used to send a mutual authentication message to "A". To
allow the mutual authentication to take place, l_addr and f_addr must be set equal to the address of the sockets that the local and foreign
principals are using to communicate. As the result of mutual authentication, schedule will be set equal to the key_schedule of the session
key between "A" and "B".
fd must be a file descriptor that is associated with a blocking socket. Otherwise, will not function correctly.
If "A" has been correctly authenticated to "B" and mutual authentication was not chosen as an option, or if mutual authentication is an
option and "A" has been correctly authenticated to "B" and "B" has sent a mutual authentication message to "B", then KSUCCESS is returned
by
The following is a list of most of the error values from calls other section 3 Kerberos routines ( to perform its function, some of the
error codes are references to the error codes of other functions.
RECVAUTH_OPNOTSUP The options bits sent to contain a bit which is set but does not correspond to an option.
RECVAUTH_RD could not read the authentication message sent to "B" using fd.
RECVAUTH_TKTLEN The length of the ticket-authenticator pair within the message is longer than the maximum or less than or equal to 0.
RD_AP_VERSION The versions of Kerberos used by the caller of is incompatible with the version.
RD_AP_MSG_TYPE The ticket-authenticator pair given to was not really a ticket-authenticator pair.
RD_AP_UNDEC The ticket could not be decyphered. This error can be caused by a forged or modified message.
RD_AP_INCON The message given to contains an internal inconsistency. This could occur if the ticket in the ticket-authenticator pair
does not match the authenticator.
RD_AP_BADD The ticket-authenticator pair cannot be used to authenticate a principal from the address specified by f_addr.
RD_AP_TIME The authenticator in the ticket-authenticator pair is too old to be used to authenticate the foreign principal.
RD_AP_NYV The time at which the ticket of the ticket-authenticator pair was created is too far ahead of the time of the local host
of the local principal.
RD_AP_EXP The ticket is too old to be used.
-1 Negative one is returned if the each byte of the session key does not have odd parity.
-2 Negative two is returned if the session key is a weak key as defined by
SENDMUT_OPNOTSUP The options bits sent to contains a bit which is set but does not correspond to an option.
SENDMUT_MAKMSG If there is an error in forming the mutual authentication message itself, SENDMUT_MAKMSG is returned.
SENDMUT_WR If the mutual authentication message cannot be written to the file descriptor fd, SENDMUT_WR is returned.
Restrictions
and will not work properly on sockets set to nonblocking I/O mode.
See Also
kerberos(3krb), krb_sendmutual(3krb), krb_svc_init(3krb), des_crypt(3krb, krb_get_lrealm(3krb), krb_set_tkt_string(3krb), krb.conf(5krb).
krb_sendauth(3krb)