krb_sendmutual(3krb) 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)
long options;
KTEXT msg_out;
int success;
int fd;
struct sockaddr_in *f_addr;
struct sockaddr_in *l_addr;
AUTH_DAT *ad;
Key_schedule schedule;
int krb_recvmutual (options, fd, checksum, msg_in,
msg_data, cred, schedule, l_addr,
f_addr)
long options;
int fd;
u_long checksum;
KTEXT msg_in;
MSG_DAT *msg_data;
CREDENTIALS *cred;
Key_schedule schedule;
struct sockaddr_in *l_addr;
struct sockaddr_in *f_addr;
Arguments
options defined in There is only one option currently supported, KOPT_NORDWR. If this option is not set, the mutual authentication infor-
mation is read either from the supplied file descriptor, fd, or sent across 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 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 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 (see and is used as input to Space for the ad structure must be allocated.
checksum input to it must have the same value as the checksum used as input to (see or to (see The checksum is included in the ticket-
authenticator pair produced by and sent by 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 in the mutual
authentication message. If the checksum input to matches the one sent back by then the caller of is authenticated to the caller
of
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 mes-
sage is read from fd.
msg_data a structure returned by 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 The credentials structure that cred points to must be the credentials struc-
ture that includes the ticket that the local principal uses to authenticate the foreign principal. This credential structure is
usually obtained through the use of (See
schedule the key schedule derived from the session key between the local and foreign principals. It is input to both and and it can be
generated from the session key with (see
Description
The routines are designed to be used by applications which communicate over the network, support "on-the-wire" protocols in which authenti-
cation information can be placed, and require both parties in the communications process to be authenticated to the other (mutual authenti-
cation). They are best used with and If a principal "A" calls and sends the output to principal "B", which uses to interpret the data suc-
cessfully, 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 and are finished, the calls are used.
and can also be used with and 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, and can be used as described above to authenticate "A" to "B". and 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 unauthenti-
cated initial message exchange. This is not a recommended use for and If you do not want to modify the "on-the-wire" protocol of an appli-
cation, yet want to authenticate the application, then use the 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 and files.
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 produces a message indicating authentication failure. If it is set to KSUC-
CESS, then 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 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_WR If the message cannot be written to the file descriptor fd, SENDMUT_WR is returned.
KSUCCESS If the message has been correctly formed, KSUCCESS is returned.
krb_recvmutual
The routine interprets the mutual authentication message sent to principal "A" by principal "B". If the KOPT_NORDWR option is set, 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 must be the same checksum used as input to 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 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_RD If 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 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_TIME If the mutual authentication message is too old, RD_AP_TIME is returned.
KFAILURE If principal "A" was not authenticated to principal "B", or if the mutual authentication message fails to identify "B",
KFAILURE is returned.
KSUCCESS If principal "B" has been correctly authenticated to principal "A", KSUCCESS is returned.
Restrictions
and will not work properly with sockets that do not use blocking I/O.
See Also
kerberos(3krb), krb_sendauth(3krb), des_crypt(3krb), krb_svc_init(3krb)
krb_sendmutual(3krb)