krb_sendauth.3krb

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

then sends the message to
"B" where it is read from the communications channel by 
.PN krb_recvauth .
.PP
Next,
.PN 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 
.PN krb_recvauth , 
will contain
either an error code, a code indicating	success, or a mutual
authentication message.
.PN krb_recvauth
sends the response and returns to "B".  
.PN krb_sendauth
receives the
message from "B", tries to authenticate "B" if KOPT_DO_MUTUAL is set, and
then returns 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
method of distinguishing between the new authenticated initial message
exchange and an old unauthenticated initial message exchange.
.PP
The
.PN 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 \f(CWdes.h\fP and
\f(CWkrb.h\fP files.
.PP
The routines found in the 
.PN krb_sendauth(3krb) 
library are
.PN krb_sendauth
and
.PN krb_recvauth :
.IP krb_sendauth
.PP
The 
.PN krb_sendauth
function is designed to authenticate a
local principal, "A", to the principal specified by the
\fIf_service\fP, \fIf_instance\fP, and \fIf_realm\fP parameters, "B",
and to allow
the authentication of "B" to "A" as well.  
.PN krb_sendauth
uses file descriptor \fIfd\fP, to send the authentication
message that will authenticate "A" to principal "B".
It returns, in the \fItkt_authen\fP parameter, the
ticket-authenticator pair used to authenticate "A" to "B".  The
\fIversion_in\fP parameter contains an application-specific version
string which is transmitted to "B" along with the authentication
message.
.PP		
If mutual authentication is selected as an option, the file
descriptor, \fIfd\fP will be used to receive a mutual authentication
message from "B".
To allow the mutual authentication to take place, \fIl_addr\fP and
\fIf_addr\fP 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 
.PN krb_sendauth
as the \fIchecksum\fP parameter.  As the result
of mutual authentication, \fIcred\fP will be filled with data
describing the authentication information associated with "B", 
\fIschedule\fP will be set equal to the key_schedule of the
session key between "A" and "B", and \fImsg_data\fP will be set equal
to the mutual authentication message sent from "B" to "A". 
.PP
\fIfd\fP must be a file descriptor associated with a
blocking socket.  Otherwise, 
.PN krb_sendauth
will not function
correctly.
.PP
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
.PN krb_sendauth .
.PP
The following is a list of most of the error values from
.PN krb_sendauth .
Since 
.PN krb_sendauth
calls other section 3 Kerberos routines (
.PN 3krb ) 
to perform its function, some of the error codes
are references to the error codes of other functions:
.TP 18
SENDAUTH_OPNOTSUP
The \fIoptions\fP bits sent to 
.PN krb_sendauth
contain a bit
which is set, but does not correspond to an option.
.TP 18
SENDAUTH_WR
.PN krb_sendauth
could not write the authentication message
to "B" using \fIfd\fP.
.TP 18
KFAILURE
The
.PN /etc/krb.conf
file cannot be opened, or
.br
The 
.PN /etc/krb.conf
file (see
.PN krb.conf(5krb) )
is not formed properly, or
.br
An authentication message was sent from "A" to "B", but
"B" could not successfully identify "A", or
.br
A mutual authentication message was sent from "B" to
"A", but "A" could not successfully identify "B".
.TP 18
-1
Negative one is returned if each byte of the
session key does not have odd parity.
.TP 18
-2
Negative two is returned if the session key is a weak
key as defined by 
.PN des_is_weak_key
(see 
.PN des_crypt(3krb) ).
.TP 18
NO_TKT_FIL 
The ticket file does not exist.
.TP 18
TKT_FIL_ACC
The ticket file cannot be opened or the ticket file
cannot be accessed.
.TP 18
TKT_FIL_LCK
The ticket file could not be locked for access.
.TP 18
TKT_FIL_FMT
The ticket file format is incorrect.
.TP 18
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.
.TP 18
SKDC_CANT
A Kerberos server must be contacted in order
for
.PN 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
.PN /etc/krb.conf .
.TP 18
SKDC_RETRY
A Kerberos server needs to be contacted, but
none responded even after several retries.
.TP 18
INTK_PROT
Kerberos protocol error.
.TP 18
GC_NOTKT
Information concerning the foreign principal does not
exist in the ticket file.
.TP 18
RECVMUT_OPNOTSUP
The \fIoptions\fP bits sent to 
.PN krb_recvmutual
(see
.PN krb_sendmutual(3krb) )
contain a bit
which is set, but does not correspond to an option.
.TP 18
RECVMUT_RD
If the message cannot be read from the file descriptor
\fIfd\fP, SENDMUT_RD is returned.
.TP 18
RD_AP_VERSION
If the Kerberos version used to create the mutual
authentication message is not supported by
.PN krb_recvmutual ,
then RD_AP_VERSION is returned.
.TP 18
RD_AP_MSG_TYPE
If the message read from the file descriptor, \fIfd\fP,
is not a mutual authentication message,
RD_AP_MSG_TYPE is returned.
.TP 18
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.
.TP 18
RD_AP_TIME
Returned if the mutual authentication message is too old.
.IP krb_recvauth
.PP
The 
.PN krb_recvauth 
function is designed to wait for a message
from 
.PN krb_sendauth
on the file descriptor \fIfd\fP, receive the 
message and attempt to authenticate the foreign principal, "A",
to the local principal determined by the \fIl_service\fP and
\fIl_instance\fP parameters.  The \fIsrvtab_file\fP must contain the
private key of principal "B".  The 
\fItkt_authen_out\fP parameter
is filled with the ticket-authenticator pair sent within the
.PN krb_sendauth
message received by "B" from "A".  \fIad\fP is filled with
information that describes the authentication association
between "A" and "B".  \fIversion_out\fP is filled with the application
version string included in the 
.PN krb_sendauth
message.
.PP
If mutual authentication is selected as an option, the file
descriptor \fIfd\fP, will be used to send a mutual authentication
message to "A".  To allow the mutual authentication to take
place, \fIl_addr\fP and \fIf_addr\fP 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,
\fIschedule\fP will be set equal to the key_schedule of the
session key between "A" and "B".
.PP
\fIfd\fP must be a file descriptor that is associated with a
blocking socket.  Otherwise, 
.PN krb_recvauth 
will not function
correctly.
.PP
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 
.PN krb_recvauth .
.PP
The following is a list of most of the error values from
.PN krb_recvauth.  Since 
.PN krb_recvauth
calls other section 3 Kerberos routines (
.PN 3krb )
to perform its function, some of the error codes
are references to the error codes of other functions.
.TP 18
RECVAUTH_OPNOTSUP
The \fIoptions\fP bits sent to 
.PN krb_recvauth
contain a bit
which is set but does not correspond to an option.
.TP 18
RECVAUTH_RD
.PN krb_recvauth
could not read the authentication message
sent to "B" using \fIfd\fP.
.TP 18
RECVAUTH_TKTLEN
The length of the ticket-authenticator pair within
the 
.PN krb_sendauth
message is longer than the maximum
or less than or equal to 0.
.TP 18
RD_AP_VERSION
The versions of Kerberos used by the caller of 
.PN krb_sendauth
is incompatible with the 
.PN krb_recvauth
version.
.TP 18
RD_AP_MSG_TYPE
The ticket-authenticator pair given to 
.PN krb_recvauth
was not really a ticket-authenticator pair.
.TP 18
RD_AP_UNDEC
The ticket could not be decyphered.  This error can be
caused by a forged or modified message.
.TP 18
RD_AP_INCON
The message given to 
.PN krb_recvauth
contains an internal
inconsistency.  This could occur if the ticket
in the ticket-authenticator pair does not match
the authenticator.
.TP 18
RD_AP_BADD
The ticket-authenticator pair cannot be used to 
authenticate a principal from the address specified by
\fIf_addr\fP. 
.TP 18
RD_AP_TIME
The authenticator in the ticket-authenticator pair
is too old to be used to authenticate the foreign
principal.
.TP 18
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.
.TP 18
RD_AP_EXP
The ticket is too old to be used.
.TP 18
-1
Negative one is returned if the each byte of the
session key does not have odd parity.
.TP 18
-2
Negative two is returned if the session key is a weak
key as defined by 
.PN des_is_weak_key .
.TP 18
SENDMUT_OPNOTSUP
The options bits sent to 
.PN krb_sendmutual
contains a bit
which is set but does not correspond to an option.
.TP 18
SENDMUT_MAKMSG
If there is an error in forming the mutual
authentication message itself, SENDMUT_MAKMSG is
returned.
.TP 18
SENDMUT_WR
If the mutual authentication message cannot be
written to the file descriptor \fIfd\fP, SENDMUT_WR is
returned.
.SH Restrictions
.PN krb_sendauth
and
.PN krb_recvauth
will not work properly on sockets set to nonblocking I/O mode.
.SH See Also
kerberos(3krb), krb_sendmutual(3krb), krb_svc_init(3krb), des_crypt(3krb,
krb_get_lrealm(3krb), krb_set_tkt_string(3krb), krb.conf(5krb).