kerberos.3krb

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

.TH kerberos 3krb
.SH Name
kerberos \- Kerberos authentication library routines
.SH Syntax
.nf
.nj
 \fB#include <des.h>
 #include <krb.h>\fP
.PP
 \fBint krb_mk_req\fP(\fItkt_authen_out, f_service, f_instance,
                         f_realm, checksum\fP)
 \fBKTEXT\fP	\fItkt_authen_out;\fP
 \fBchar\fP		\fI*f_service;\fP
 \fBchar\fP		\fI*f_instance;\fP
 \fBchar\fP		\fI*f_realm;\fP
 \fBu_long\fP		\fIchecksum;\fP
.PP
 \fBint krb_rd_req\fP(\fItkt_authen_in, l_service, l_instance,
                         f_hostaddr, ad, srvtab_file\fP)
 \fBKTEXT\fP	\fItkt_authen_in;\fP
 \fBchar\fP		\fI*l_service;\fP
 \fBchar\fP		\fI*l_instance;\fP
 \fBu_long\fP		\fIf_hostaddr;\fP
 \fBAUTH_DAT\fP	\fI*ad;\fP
 \fBchar\fP		\fI*srvtab_file;\fP
.ig ++
.PP
 \fBint krb_kntoln\fP(\fIad,lname\fP)
 \fBAUTH_DAT\fP	\fI*ad;\fP
 \fBchar\fP		\fI*lname;\fP
.++
.ig ++
.PP
 \fBint krb_set_key\fP(\fIkey,cvt\fP)
	\fBchar\fP		\fI*key;\fP
	\fBint\fP		\fIcvt;\fP
.++
.PP
 \fBint krb_get_cred\fP(\fIf_service, f_instance, 
                          f_realm, cred\fP)
 \fBchar\fP		\fI*f_service;\fP
 \fBchar\fP		\fI*f_instance;\fP
 \fBchar\fP		\fI*f_realm;\fP
 \fBCREDENTIALS\fP	\fI*cred;\fP
.ig ++
.PP
 \fBlong krb_mk_priv\fP(\fIin, out, in_length, schedule,\fP
                        \fIkey, sender, receiver\fP)
 \fBu_char\fP			\fI*in;\fP
 \fBu_char\fP			\fI*out;\fP
 \fBu_long\fP			\fIin_length;\fP
 \fBC_Block\fP	\fI*key;\fP
 \fBKey_schedule\fP		\fIschedule;\fP
 \fBstruct	sockaddr_in\fP	\fI*sender;\fP
 \fBstruct	sockaddr_in\fP	\fI*receiver;\fP
.PP
 \fBlong krb_rd_priv\fP(\fIin, in_length, schedule, key,\fP
                        \fIsender, receiver, msg_data\fP)
 \fBu_char\fP			\fI*in;\fP
 \fBu_long\fP			\fIin_length;\fP
 \fBKey_schedule\fP		\fIschedule;\fP
 \fBC_Block\fP		\fI*key;\fP
 \fBstruct	sockaddr_in\fP	\fI*sender;\fP
 \fBstruct	sockaddr_in\fP	\fI*receiver;\fP
 \fBMSG_DAT\fP		\fI*msg_data;\fP
.++
.PP
 \fBlong	krb_mk_safe\fP(\fIin, out, in_length, key,\fP
                               \fIl_addr, f_addr\fP)
 \fBu_char\fP		\fI*in;\fP
 \fBu_char\fP		\fI*out;\fP
 \fBu_long\fP			\fIin_length;\fP
 \fBC_Block\fP		\fI*key;\fP
 \fBstruct 	sockaddr_in\fP	\fI*l_addr;\fP
 \fBstruct	sockaddr_in\fP	\fI*f_addr;\fP
.PP
 \fBlong	krb_rd_safe\fP(\fIin, in_length, key, f_addr,\fP
                               \fIl_addr, msg_data\fP)
 \fBu_char\fP		\fI*in;\fP
 \fBu_long\fP			\fIin_length;\fP
 \fBC_Block\fP		\fI*key;\fP
 \fBstruct	sockaddr_in\fP	\fI*f_addr;\fP
 \fBstruct	sockaddr_in\fP 	\fI*l_addr;\fP
 \fBMSG_DAT\fP		\fI*msg_data;\fP
.PP
.fi
.SH Arguments
.TP 10
.I f_service
Character pointer to the primary name of the foreign principal.  The local
principal is the principal that calls the routines listed above.  The 
local principal tries to 
communicate with the foreign principal. 
.TP
.I f_instance
Character pointer to the instance name of the foreign principal.
.TP
.I f_realm
Character pointer to the realm name of the foreign principal.
.TP
.I l_service
Character pointer to the primary name of the local principal.
.TP
.I l_instance
Character pointer to the instance name of the local principal.
.TP
.I tkt_authen_out
Pointer to the text structure in which the Kerberos library routines
build the ticket-authenticator pair.  This structure is designed to be
sent to the foreign principal to authenticate the local principal's 
identity to the foreign principal.  Storage must be allocated 
for \fItkt_authen_out\fP.
.TP
.I tkt_authen_in
Pointer to the ticket-authenticator pair that the Kerberos library uses to authenticate
the foreign principal to the local principal.  The data in this structure must
have been generated by a call to
.PN krb_mk_req
by the foreign principal and transmitted by the foreign principal to the local principal.
.TP
.I checksum
The \fIchecksum\fP parameter is input to
.PN krb_mk_req .
It is packaged with the ticket-authenticator pair that is sent to the foreign principal.
The \fIchecksum\fP serves as a secret piece of data that can be known only 
to the foreign principal if
the foreign principal is authenticated as the foreign principal.  It is used to facilitate
mutual authentication with
.PN krb_sendmutual
and
.PN krb_recvmutual . 
See 
.PN krb_sendmutual(3krb)
for information about these two routines.
.TP
.I f_hostaddr
Address of the machine from which the foreign principal sent 
the \fItkt_authen_in\fP data.
.TP
.I f_addr
Address of the socket that the foreign principal is using to communicate with the local
principal.
.TP
.I l_addr
Address of the socket that the local principal is using to communicate with 
the foreign principal.
.TP
.I ad
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 .
You must allocate space for the \fIad\fP structure.
.TP
.I srvtab_file 
The path name of the file that contains the key of the 
principal obtaining a
ticket. 
If this value is set equal to a string of zero length,
.PN srvtab_file[0] ='\\\\0', 
the default service table (srvtab) file is used.  If
this value is set equal to the NULL 
pointer, then the key of the
service is not read from the srvtab file, but is read from storage
space internal to the libraries.  The \fIsrvtab_file\fP parameter
cannot be set equal to the NULL string on the first call to
.PN krb_rd_req .
The default srvtab file value is set to
.PN /etc/srvtab ,
although this value can be changed by a call to the
.PN krb_set_srvtab_string
function.  (See the
.PN krb_set_tkt_string(3krb)
reference page).
.TP
.I key
Pointer to the C_Block input to
.PN krb_mk_safe
and
.PN krb_rd_safe .
It contains a Data Encryption Standard (DES) key.  The
key that is usually used is the session key between the local and foreign principal.
.TP
.I cred
A pointer to a credentials structure that is allocated by the caller of
.PN krb_get_cred
and filled with data by
.PN krb_get_cred .
The credentials structure includes the ticket that the local principal
uses to authenticate the foreign principal.  It also includes other
authentication information associated with the foreign principal.
.TP
.I in
Character pointer to the user data that must be included in a safe message.
.TP
.I out
Character pointer to the safe message output by
.PN krb_mk_safe .
The \fIin\fP parameter may not overlap with \fIout\fP. 
.TP
.I in_length
Length of the user data, \fIin\fP. 
.TP
.I msg_data
The \fImsg_data\fP parameter is a pointer to a MSG_DAT structure which must be
allocated by the caller of
.PN krb_rd_safe
and which is filled by
.PN krb_rd_safe
with information about the safe message.  A pointer to the user data sent within
the safe message is also included in \fImsg_data\fP.
.SH Description
.NXR "Kerberos routines" "kerberos 3"
.NXR "Kerberos routines" "krb_mk_req"
.NXR "Kerberos routines" "krb_rd_req"
.NXR "Kerberos routines" "krb_get_cred"
.NXR "Kerberos routines" "krb_mk_safe"
.NXR "Kerberos routines" "krb_rd_safe"
The
.PN krb_mk_req
calls are designed to be used by two principals that are attempting to
authenticate themselves for the first time as well as by two principals
that have authenticated once, but wish to authenticate all data passed
between them.
.PP
The
.PN krb_mk_req
and
.PN krb_rd_req
routines are designed to be used by applications that communicate over a 
network, require the
authentication of both parties across the communication path, and support
"on-the-wire"
protocols in which authentication data can be placed. 
These routines perform only the authentication of the first message sent between
such applications.
.PN krb_mk_req
creates a ticket-authenticator pair that can be included in the "on-the-wire" protocol
of an application, and
.PN krb_rd_req
reads the ticket-authenticator pair.
.PP
The
.PN krb_mk_safe
and
.PN krb_rd_safe
routines are used by applications that require that every message passed between
them be authenticated and free from unauthorized modifications, and whose "on-the-wire"
protocol has no room for authentication data.  These routines only provide for
the 
authentication and integrity protection of a message if the first authenticated
message has already been sent by the
.PN krb_mk_req/krb_rd_req
pair or the
.PN krb_sendauth/krb_recvauth
pair.  See
.PN krb_sendauth(3krb)
for more information about the latter pair.
.PP
The 
.PN krb_mk_safe
routine encapsulates user data inside the
.PN krb_mk_safe
"on-the-wire" message authentication protocol. 
.PN krb_rd_safe
can interpret the message authentication protocol and the message, and return the
data encapsulated by
.PN krb_mk_safe .
Since any application which is modified to use 
.PN krb_mk_safe
or
.PN krb_rd_safe
must encapsulate its "on-the-wire" protocol within the "on-the-wire" protocol
of
.PN krb_mk_safe , 
the application must develop a method of distinguishing between the old and new
"on-the-wire" protocols.
.PP
The
.PN des_quad_cksum
routine (see
.PN des_crypt(3krb) )
can be used to provide some of the guarantees of the
.PN krb_mk_safe
and
.PN krb_rd_safe
routines without encapsulating the protocol of the application. 
.PP
The routines of this library make extensive use of the following locally
defined data types: KTEXT, AUTH_DAT, CREDENTIALS, C_Block, and
MSG_DAT.  For specific information on the definitions of these data types, see
the
.PN des.h
and
.PN krb.h
files.
.SH Routines and Structures
.IP krb_mk_req
.PP
Used to produce the data necessary to authenticate a principal "A" to a
principal "B".  It takes as input a checksum and the primary name, instance name,
and realm name of the service to which the principal "A" is attempting to
authenticate itself.  
.PN krb_mk_req
outputs a text structure in which the ticket to communicate with principal "B"
and an authenticator have been combined to form a ticket-authenticator pair.
.PP
The application "A" must pass the ticket-authenticator pair to the principal "B"
where it can be read by
.PN krb_rd_req .
Once the ticket-authenticator pair has been read and verified, "A" has been 
authenticated to "B".  Unless an attacker possesses the session key contained in
the ticket, the attacker will be unable to modify or replay the ticket-authenticator
pair.
.PP
The checksum can be used with
.PN krb_sendmutual
and
.PN krb_recvmutual
to provide for the authentication of "B" to "A" after
.PN krb_rd_req
authenticates "A" to "B".  Although the checksum value can be any value known
only to "A", it is recommended that the checksum value used differ every time
.PN krb_mk_req
is called.
The following is a list of the return values from
.PN krb_mk_req
and, if they are error codes, their possible cause:
.TP 15