krb_sendmutual(3krb)krb_sendmutual(3krb)Name
krb_sendmutual, krb_recvmutual - Kerberos mutual authentication rou‐
tines
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 authenti‐
cation information 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 princi‐
pal, 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 buf‐
fer 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 authentica‐
tion message generated by is a message indicating failure.
This parameter is useful if the initial attempt to authenti‐
cate the foreign principal failed. Since this initial authen‐
tication 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 mes‐
sage is generated.
ad a pointer to the AUTH_DAT structure that describes the authen‐
tication 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 for‐
eign principal. It serves as a secret piece of data that can
only be known to the foreign principal if the foreign princi‐
pal 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 authentica‐
tion message is read from fd.
msg_data a structure returned by that is filled with the mutual authen‐
tication message sent to the local principal as well as infor‐
mation about the status of the message. Space must be allo‐
cated for the msg_data structure.
cred a pointer to a credentials structure that is input to The cre‐
dentials 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 (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 authentica‐
tion information can be placed, and require both parties in the commu‐
nications process to be authenticated to the other (mutual authentica‐
tion). They are best used with and If a principal "A" calls and sends
the output to principal "B", which uses to interpret the data success‐
fully, 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" com‐
municate 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 unauthenticated ini‐
tial message exchange. This is not a recommended use for and If you do
not want to modify the "on-the-wire" protocol of an application, 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 mes‐
sage indicating authentication failure. If it is set to KSUCCESS, 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 allo‐
cated 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 authenti‐
cation message itself, SENDMUT_MAKMSG is returned.
SENDMUT_WR If the message cannot be written to the file descrip‐
tor 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 prin‐
cipal "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 inte‐
gral part of proving the identity of principal "B" to "A". The follow‐
ing 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 descrip‐
tor 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 Alsokerberos(3krb), krb_sendauth(3krb), des_crypt(3krb), krb_svc_init(3krb)krb_sendmutual(3krb)