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)
longoptions;
intfd;
KTEXTtkt_authen;
char*f_service;
char*f_instance;
char*f_realm;
u_longchecksum;
MSG_DAT*msg_data;
CREDENTIALS*cred;
Key_scheduleschedule;
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)
longoptions;
intfd;
KTEXTtkt_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_scheduleschedule;
char*version_out;

Arguments

options Defined in /usr/include/krb.h. 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
krb_sendauth will not use the krb_mk_req function (see kerberos(3krb)) to produce the ticket-authenticator pair, authen_tkt. Instead, the ticket-authenticator pair is read from the argument, tkt_authen.

KOPT_DONT_CANON
krb_sendauth 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 krb_get_phost (see krb_get_lrealm(3krb)) with argument f_instance as input.

KOPT_DO_MUTUAL
krb_sendauth and krb_recvauth provide authentication on both ends of the network connection. Otherwise, the caller of krb_sendauth is authenticated to the caller of krb_recvauth, but the caller of krb_recvauth is not authenticated to the caller of krb_sendauth. For mutual authentication to occur, both krb_sendauth and krb_recvauth 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 routines. 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 krb_sendauth message sent to the foreign principal to authenticate the local principal’s identity to the foreign principal. This structure can be either input to krb_sendauth or output from krb_sendauth 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 krb_recvauth reads from within the krb_sendauth message. The krb_sendauth message is sent by krb_sendauth to the local principal to authenticate the foreign principal to the local principal. Storage must be allocated for tkt_authen_out.

checksum
Input to krb_sendauth; checksum is packaged in the krb_sendauth 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 facilitate 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 krb_mk_req in the creation of the ticket-authenticator pair, authen_tkt.

msg_data
Pointer to a structure which is filled with the mutual authentication message sent by krb_recvauth and interpreted by krb_sendauth. The message sent from krb_sendauth to krb_recvauth, the message that includes the ticket-authenticator pair, authenticates only the caller of krb_sendauth to the caller of krb_recvauth. An additional message, the one returned by krb_sendauth inside msg_data, must be sent by krb_recvauth and interpreted by krb_sendauth in order to authenticate the caller of krb_recvauth to the caller of krb_sendauth. 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 krb_recvauth to krb_sendauth, the msg_data parameter should be set equivalent to the NULL pointer.

cred a pointer to a credentials structure that is output from krb_sendauth. 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 krb_sendauth. Otherwise, the cred structure will not be filled in by krb_sendauth, 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 krb_sendauth and krb_recvauth. 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 krb_sendauth, 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 krb_recvauth.

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 krb_recvauth, 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, srvtab_file[0]=’\0’, 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 cannot be set to the NULL string on the first call to krb_sendauth. The default srvtab file value is set to /etc/srvtab although this value can be changed by a call to the krb_set_srvtab_string function (see krb_set_tkt_string(3krb)).

version_in
An application-specific version string input to krb_sendauth. This argument allows the caller of krb_sendauth to pass an application-specific version string, within the krb_sendauth message format, that the caller of krb_recvauth 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 krb_recvauth. This argument allows the caller of krb_recvauth to receive the application-specific version string included in the krb_sendauth message that was sent by the foreign principal. The version string can be up to KRB_SENDAUTH_VLEN characters long.

Description

The krb_sendauth(3krb) routines are designed to be used by applications that communicate over a network, require the authentication of both parties accross the communications path, and which support "on-the-wire" protocols that have no room for authentication information. The krb_sendauth(3krb) routines are designed to perform only the authentication of the first message sent between such applications. Therefore, the krb_sendauth(3krb) 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, krb_sendauth creates a message which can authenticate the caller of krb_sendauth, "A", to the caller of krb_recvauth, "B". krb_sendauth then sends the message to "B" where it is read from the communications channel by krb_recvauth.

Next, krb_recvauth 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 krb_recvauth, will contain either an error code, a code indicating success, or a mutual authentication message. krb_recvauth sends the response and returns to "B". krb_sendauth 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 unauthenticated initial message exchange.

The krb_sendauth(3krb) 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 krb_sendauth(3krb) library are krb_sendauth and krb_recvauth:

krb_sendauth

The krb_sendauth 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. krb_sendauth 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 krb_sendauth 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, krb_sendauth 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 authenticated to "B", and "B" correctly authenticated to "A" and mutual authentication was chosen as an option, then KSUCCESS is returned by krb_sendauth.

The following is a list of most of the error values from krb_sendauth. Since krb_sendauth calls other section 3 Kerberos routines ( 3krb) 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 krb_sendauth contain a bit which is set, but does not correspond to an option.

SENDAUTH_WR krb_sendauth could not write the authentication message to "B" using fd.

KFAILURE The /etc/krb.conf file cannot be opened, or
The /etc/krb.conf file (see krb.conf(5krb)) 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 des_is_weak_key (see des_crypt(3krb)).

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 foreign principal.

SKDC_CANT A Kerberos server must be contacted in order for krb_sendauth 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 /etc/krb.conf.

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 krb_recvmutal (see krb_sendmutual(3krb)) 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 krb_recvmutual, then RD_AP_VERSION is returned.

RD_AP_MSG_TYPE
If the message read from the file descriptor, fd, is not a mutual authentcation 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 produced, RD_AP_MODIFIED is returned.

RD_AP_TIME Returned if the mutual authentication message is too old.

krb_recvauth

The krb_recvauth function is designed to wait for a message from krb_sendauth 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 krb_sendauth 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 krb_sendauth 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, krb_recvauth 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 krb_recvauth.

The following is a list of most of the error values from krb_recvauth.Since krb_recvauth calls other section 3 Kerberos routines ( 3krb) 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 krb_recvauth contain a bit which is set but does not correspond to an option.

RECVAUTH_RD krb_recvauth could not read the authentication message sent to "B" using fd.

RECVAUTH_TKTLEN
The length of the ticket-authenticator pair within the krb_sendauth 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 krb_sendauth is incompatible with the krb_recvauth version.

RD_AP_MSG_TYPE
The ticket-authenticator pair given to krb_recvauth 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 krb_recvauth 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 des_is_weak_key.

SENDMUT_OPNOTSUP
The options bits sent to krb_sendmutal 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

krb_sendauth and krb_recvauth will not work properly on sockets set to nonblocking I/O mode.

Museum