krb_sendmutual(3krb)

Name

krb_sendmutual, krb_recvmutual − Kerberos mutual authentication routines

Syntax

#include <krb.h>
#include <des.h>

int krb_sendmutual (options, msg_out, success, fd,
                              f_addr, l_addr, ad, schedule)
longoptions;
KTEXTmsg_out;
intsuccess;
intfd;
struct sockaddr_in*f_addr;
struct sockaddr_in*l_addr;
AUTH_DAT*ad;
Key_scheduleschedule;
int krb_recvmutual (options, fd, checksum, msg_in,
                              msg_data, cred, schedule, l_addr,
                              f_addr)
longoptions;
intfd;
u_longchecksum;
KTEXTmsg_in;
MSG_DAT*msg_data;
CREDENTIALS*cred;
Key_scheduleschedule;
struct sockaddr_in*l_addr;
struct sockaddr_in*f_addr;

Arguments

options defined in /usr/include/krb.h. There is only one option currently supported, KOPT_NORDWR. If this option is not set, the mutual authentication information is read either from the supplied file descriptor, fd, or sent accross the supplied file descriptor, fd. If it is specified, then no data is read from or written to the file descriptor; instead, data is read from and written to the buffers supplied as parameters, msg_in, msg_out.

fd the file descriptor used to send data to the foreign principal, or it is the file descriptor from which data from the foreign principal can be read.

The foreign principal is the principal to which the principal that calls a krb_sendmutual(3krb) routine, the local principal, is attempting to mutually authenticate itself. The file descriptor must be associated with a socket that uses blocking I/O. The fd parameter is not used if the KOPT_NORDWR option is set.

f_addr the address of the socket that the foreign principal uses to communicate with the local principal.

l_addr the address of the socket that the local principal uses to communicate with the foreign principal.

msg_out If KOPT_NORDWR is sent as an option, msg_out is used as a buffer to store the mutual authentication data that should be sent to the foreign principal. If KOPT_NORDWR is not set, msg_out is not used and the mutual authentication message is written to fd.

success If success is not set to KSUCCESS, then the mutual authentication message generated by krb_sendmutual is a message indicating failure. This parameter is useful if the initial attempt to authenticate the foreign principal failed. Since this initial authentication attempt failed, then the attempt to authenticate the local principal to the foreign principal also must fail. If success is set to KSUCCESS, then a mutual authentication message is generated.

ad a pointer to the AUTH_DAT structure that describes the authentication association between the local and foreign principals. The ad structure is output from krb_rd_req (see kerberos(3krb)) and is used as input to krb_sendmutual. Space for the ad structure must be allocated.

checksum input to krb_recvmutual, it must have the same value as the checksum used as input to krb_mk_req (see kerberos(3krb)) or to krb_sendauth (see krb_sendauth(3krb)). The checksum is included in the ticket-authenticator pair produced by krb_mk_req and sent by krb_sendauth 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 was authenticated as the foreign principal. It is included by krb_sendmutual in the mutual authentication message. If the checksum input to krb_recvmutual matches the one sent back by krb_sendmutual, then the caller of krb_sendmutual is authenticated to the caller of krb_recvmutual.

msg_in If KOPT_NORDWR is sent as an option, then data in msg_in is read as if it contained the mutual authentication bits sent to the local principal by the foreign principal. If KOPT_NORDWR is not set, then msg_in is not used and the mutual authentication message is read from fd.

msg_data a structure returned by krb_recvmutal that is filled with the mutual authentication message sent to the local principal as well as information about the status of the message. Space must be allocated for the msg_data structure.

cred a pointer to a credentials structure that is input to krb_recvmutual. The credentials structure that cred points to must be the credentials structure that includes the ticket that the local principal uses to authenticate the foreign principal. This credential structure is usually obtained through the use of krb_get_cred (See kerberos(3krb)).

schedule the key schedule derived from the session key between the local and foreign principals. It is input to both krb_sendmutual and krb_recvmutual, and it can be generated from the session key with des_key_sched (see des_crypt(3krb)).

Description

The krb_sendmutual(3krb) routines are designed to be used by applications which communicate over the network, support "on-the-wire" protocols in which authentication information can be placed, and require both parties in the communications process to be authenticated to the other (mutual authentication). They are best used with krb_mk_req and krb_rd_req. If a principal "A" calls krb_mk_req and sends the output to principal "B", which uses krb_rd_req to interpret the data successfully, then "B" will have authenticated principal "A". But, principal "A" will not know that the message it sent was really received by "B". To prove the identity of principal "B" to principal "A" after the calls to krb_mk_req and krb_rd_req are finished, the krb_sendmutual(3krb) calls are used.

krb_sendmutual and krb_recvmutual can also be used with krb_mk_req and krb_rd_req by applications which cannot tolerate additions to their "on-the-wire" protocols. After the communications channel between "A" and "B" is established, but before "A" and "B" communicate and before the "on-the-wire" protocol of the applications comes into effect, krb_mk_req and krb_rd_req can be used as described above to authenticate "A" to "B". krb_sendmutual and krb_recvmutual can then be used with the KOPT_NORDWR option not set to authenticate "B" 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 way to distinguish between the new authenticated initial message exchange and an old unauthenticated initial message exchange. This is not a recommended use for krb_sendmutual and krb_recvmutual. If you do not want to modify the "on-the-wire" protocol of an application, yet want to authenticate the application, then use the krb_sendauth(3krb) routines.

The routines of this library make extensive use of the following locally defined data types: KTEXT, AUTH_DAT, CREDENTIALS, Key_schedule, and MSG_DAT. For more specific information on the definitions of these data types, see the des.h and krb.h files.

krb_sendmutual

krb_sendmutual is used to produce and possibly send the data that will authenticate principal "B" to principal "A". If the authentication of principal "A" did not succeed, success should be set to KFAILURE, and krb_sendmutual produces a message indicating authentication failure. If it is set to KSUCCESS, then krb_sendmutual produces the data necessary to authenticate "B" to "A". If the option KOPT_NORDWR is set, the data is written to buffer msg_out; otherwise, it is written to file descriptor, fd.

The following is a list of the return values and, if they are error codes, their possible cause:

SENDMUT_OPNOTSUP
The options bits sent to krb_sendmutal contain a bit that is set but does not correspond to an option.

SENDMUT_PARAM
The msg_out structure must have space within it allocated to store the message. Otherwise, SENDMUT_PARAM is returned if the KOPT_NORDWR option is set.

SENDMUT_MAKMSG
If there is an error in forming the mutual authentication message itself, SENDMUT_MAKMSG is returned.

SENDMUT_WRIf the message cannot be written to the file descriptor fd, SENDMUT_WR is returned.

KSUCCESSIf the message has been correctly formed, KSUCCESS is returned.

krb_recvmutual

The krb_recvmutual routine interprets the mutual authentication message sent to principal "A" by principal "B". If the KOPT_NORDWR option is set, krb_recvmutual reads from buffer msg_in, the message sent from "B" to "A". Otherwise, it reads the message from file descriptor, fd. The checksum sent as input to krb_recvmutual must be the same checksum used as input to krb_mk_req. The checksum is an integral part of proving the identity of principal "B" to "A". The following is a list of the return values and, if they are error codes, their possible cause:

RECVMUT_OPNOTSUP
The options bits sent to krb_recvmutal contain a bit that is set, but does not correspond to an option.

RECVMUT_MSGLEN
The size of the msg_in buffer is incorrect.

RECVMUT_RDIf the message cannot be read from the file descriptor fd, then SENDMUT_RD is returned.

RD_AP_VERSION
If the Kerberos version used to create the mutual authentication message is not currently supported by krb_recvmutual, then RD_AP_VERSION is returned.

RD_AP_MSG_TYPE
If the message that is read from the file descriptor fd, or input as msg_in is not a mutual authentication message, RD_AP_MSG_TYPE is returned.

RD_AP_MODIFIED
If the message has been modified between principals "B" and "A", or if was incorrectly produced, then RD_AP_MODIFIED is returned.

RD_AP_TIMEIf the mutual authentication message is too old, RD_AP_TIME is returned.

KFAILUREIf principal "A" was not authenticated to principal "B", or if the mutual authentication message fails to identify "B", KFAILURE is returned.

KSUCCESSIf principal "B" has been correctly authenticated to principal "A", KSUCCESS is returned.

Restrictions

krb_sendmutal and krb_recvmutal will not work properly with sockets that do not use blocking I/O.

Museum