krb_sendmutual.3krb

来自「<B>Digital的Unix操作系统VAX 4.2源码</B>」· 3KRB 代码 · 共 350 行

.TH krb_sendmutual 3krb
.SH Name
krb_sendmutual, krb_recvmutual \- Kerberos mutual authentication routines
.SH Syntax
.nf
.nj
 \fB#include <krb.h>\fP
 \fB#include <des.h>\fP
.PP
 \fBint krb_sendmutual\fP (\fIoptions, msg_out, success, fd,
                              f_addr, l_addr, ad, schedule\fP)
.sp .5
 \fBlong\fP			\fIoptions\fP;
 \fBKTEXT\fP		\fImsg_out\fP;
 \fBint\fP			\fIsuccess\fP;
 \fBint\fP			\fIfd\fP;
 \fBstruct sockaddr_in\fP	\fI*f_addr\fP;
 \fBstruct sockaddr_in\fP	\fI*l_addr\fP;
 \fBAUTH_DAT\fP		\fI*ad\fP;
 \fBKey_schedule\fP		\fIschedule\fP;
.sp 1.5
 \fBint krb_recvmutual\fP (\fIoptions, fd, checksum, msg_in,
                              msg_data, cred, schedule, l_addr,
                              f_addr\fP)
.sp .5
 \fBlong\fP			\fIoptions\fP;
 \fBint\fP			\fIfd\fP;
 \fBu_long\fP			\fIchecksum\fP;
 \fBKTEXT\fP		\fImsg_in\fP;
 \fBMSG_DAT\fP		\fI*msg_data\fP;
 \fBCREDENTIALS\fP	\fI*cred\fP;
 \fBKey_schedule\fP		\fIschedule\fP;
 \fBstruct sockaddr_in\fP	\fI*l_addr\fP;
 \fBstruct sockaddr_in\fP	\fI*f_addr\fP;
.PP
.fi
.SH Arguments
.TP 9
.I options
defined in 
.PN /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, \fIfd\fP, or sent across the supplied file
descriptor, \fIfd\fP.  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, \fImsg_in\fP, \fImsg_out\fP.
.TP
.I 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.
.IP
The foreign principal is the principal to which the principal that calls a
.PN 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 \fIfd\fP parameter is not used if the KOPT_NORDWR option
is set. 
.TP
.I f_addr
the address of the socket that the foreign
principal uses to communicate with the local principal.
.TP
.I l_addr
the address of the socket that the local principal
uses to communicate with the foreign principal.
.TP
.I msg_out
If KOPT_NORDWR is sent as an option, \fImsg_out\fP 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, \fImsg_out\fP is not used and the mutual authentication
message is written to \fIfd\fP.
.TP
.I success
If success is not set to KSUCCESS, then the mutual
authentication message generated by 
.PN 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 \fIsuccess\fP is
set to KSUCCESS, then a mutual authentication message is
generated.
.TP
.I ad
a pointer to the AUTH_DAT structure that describes the authentication
association 
between the local and foreign
principals.  The \fIad\fP structure is output 
from 
.PN krb_rd_req
(see 
.PN kerberos(3krb) ) 
and
is used as input to 
.PN krb_sendmutual .
Space for the \fIad\fP
structure must be allocated.
.TP
.I checksum
input to 
.PN krb_recvmutual ,
it must have the same
value as the 
.I checksum
used as input to 
.PN krb_mk_req
(see
.PN kerberos(3krb) )
or to
.PN krb_sendauth
(see
.PN krb_sendauth(3krb) ).
The checksum is included in the ticket-authenticator pair produced by
.PN krb_mk_req
and sent by
.PN 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
.PN krb_sendmutual
in the mutual authentication message.  If the checksum input to 
.PN krb_recvmutual
matches the one sent back by
.PN krb_sendmutual ,
then the caller of
.PN krb_sendmutual
is authenticated to the caller of
.PN krb_recvmutual .
.TP
.I msg_in
If KOPT_NORDWR is sent as an option, then data in \fImsg_in\fP 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 \fImsg_in\fP is not used and the
mutual authentication message is read from \fIfd\fP.
.TP
.I msg_data
a structure returned by 
.PN krb_recvmutual
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 \fImsg_data\fP
structure.
.TP
.I cred
a pointer to a credentials structure that is input
to 
.PN krb_recvmutual .
The credentials structure that \fIcred\fP 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 
.PN krb_get_cred
(See
.PN kerberos(3krb) ).
.TP
.I schedule
the key schedule derived from the session key
between the local and foreign principals.  It is input to both
.PN krb_sendmutual
and
.PN krb_recvmutual ,
and it can be generated
from the session key with 
.PN des_key_sched
(see
.PN des_crypt(3krb) ).
.SH Description
.NXR "Kerberos routines" "krb_sendmutual"
.NXR "Kerberos routines" "krb_recvmutual"
The 
.PN 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
.PN krb_mk_req
and
.PN krb_rd_req .
If a principal "A" calls
.PN krb_mk_req
and sends the output to principal
"B", which uses 
.PN 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
.PN krb_mk_req
and
.PN krb_rd_req
are finished,
the
.PN krb_sendmutual(3krb)
calls are used.
.PP
.PN krb_sendmutual
and
.PN krb_recvmutual
can also be used with  
.PN krb_mk_req
and
.PN 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,
.PN krb_mk_req
and
.PN krb_rd_req
can be used as described above to authenticate "A" to "B".
.PN krb_sendmutual
and
.PN krb_recvmutual
can then be used with the KOPT_NORDWR option not set to authenticate "B" to "A".
.PP
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
.PN krb_sendmutual
and
.PN 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 
.PN krb_sendauth(3krb)
routines.
.PP
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
.PN des.h
and
.PN krb.h
files.
.IP krb_sendmutual
.PP
.PN 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, \fIsuccess\fP should
be set to KFAILURE, and 
.PN krb_sendmutual
produces a
message indicating authentication failure.  If it is set to
KSUCCESS, then
.PN krb_sendmutual
produces the data necessary to
authenticate "B" to "A".  If the option KOPT_NORDWR is set, the
data is written to buffer \fImsg_out\fP; otherwise, it is
written to file descriptor, \fIfd\fP.  
.PP
The following is a list of the return values and, if
they are error codes, their possible cause:
.IP SENDMUT_OPNOTSUP 18
The \fIoptions\fP bits sent to 
.PN krb_sendmutual
contain a bit
that is set but does not correspond to an option.
.IP SENDMUT_PARAM
The \fImsg_out\fP structure must have space within it
allocated to store the message.  Otherwise, SENDMUT_PARAM is returned
if the KOPT_NORDWR option is set.
.IP SENDMUT_MAKMSG
If there is an error in forming the mutual
authentication message itself, SENDMUT_MAKMSG is returned.
.IP SENDMUT_WR
If the message cannot be written to the file
descriptor \fIfd\fP, SENDMUT_WR is returned.
.IP KSUCCESS
If the message has been correctly formed, KSUCCESS
is returned.
.sp 2
.IP krb_recvmutual
.PP
The
.PN krb_recvmutual
routine
interprets the mutual authentication
message sent to principal "A" by principal "B".  If the KOPT_NORDWR option is 
set, 
.PN krb_recvmutual
reads from buffer \fImsg_in\fP, the message sent
from "B" to "A".  Otherwise, it reads the message from file descriptor, \fIfd\fP.
The \fIchecksum\fP sent as input to 
.PN krb_recvmutual
must be the
same checksum used as input to 
.PN 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:
.IP RECVMUT_OPNOTSUP 18
The \fIoptions\fP bits sent to 
.PN krb_recvmutual
contain a bit
that is set, but does not correspond to an option.
.IP RECVMUT_MSGLEN
The size of the \fImsg_in\fP buffer is incorrect.
.IP RECVMUT_RD
If the message cannot be read from the file descriptor \fIfd\fP, then
SENDMUT_RD is returned.
.IP RD_AP_VERSION
If the Kerberos version used to create the mutual
authentication message is not currently supported by 
.PN krb_recvmutual ,
then RD_AP_VERSION is returned.
.IP RD_AP_MSG_TYPE
If the message that is read from the file descriptor \fIfd\fP, or
input as \fImsg_in\fP is not a mutual authentication message,
RD_AP_MSG_TYPE is returned.
.IP 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.
.IP RD_AP_TIME
If the mutual authentication message is too
old, RD_AP_TIME is returned.
.IP KFAILURE
If principal "A" was not authenticated to principal "B", or if the mutual
authentication message fails to identify "B", KFAILURE
is returned.
.IP KSUCCESS
If principal "B" has been correctly authenticated to principal "A",
KSUCCESS is returned.
.SH Restrictions
.PN krb_sendmutual
and
.PN krb_recvmutual
will not work properly with
sockets that do not use blocking I/O.
.SH See Also
kerberos(3krb), krb_sendauth(3krb), des_crypt(3krb), krb_svc_init(3krb)