kerberos.3krb

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

KFAILURE
.PN /etc/krb.conf
file (see
.PN krb.conf(5krb) )
cannot be opened, or it is not properly formed.
.TP 15
NO_TKT_FIL
The ticket file does not exist.
.TP 15
TKT_FIL_ACC
The ticket file cannot be opened or the ticket file cannot be accessed.
.TP 15
TKT_FIL_LCK
The ticket file could not be locked for access.
.TP 15
TKT_FIL_FMT
The ticket file format is incorrect.
.TP 15
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 15
SKDC_CANT
A Kerberos server must be contacted so that
.PN krb_mk_req
can perform its function, but the attempt cannot be made because a socket
cannot be opened or bound, or because there is no Kerberos server listed in
.PN /etc/krb.conf .
.TP 15
SKDC_RETRY
A Kerberos server needs to be contacted, but none responded even after several
attempts.
.TP 15
INTK_PROT
Kerberos protocol error.
.TP 15
KSUCCESS
All went well.
.sp 1 
.IP krb_rd_req
.PP
This routine is used to read the authentication data produced by principal "A"
with
.PN krb_mk_req
and sent by "A" to principal "B".  It takes as input the primary name and instance name
of the local principal "B", as well as the authentication data sent to "B", the address
of the machine from which "A" sent the ticket-authenticator pair, and the name of the
file in which to find the key of the local principal.
If the authentication attempt is successful,
.PN krb_rd_req
will fill the \fIad\fP structure with data about the authenticated association 
between "A" and "B".
.PP
The \f(CWkrb_rd_req\fP routine returns zero (RD_AP_OK) upon successful
authentication.  If a packet was forged, modified, or replayed,
then
authentication fails.
.PP
The following is a list of the error values returned from 
.PN krb_mk_req
and their possible causes:
.TP 16
RD_AP_VERSION
The versions of 
Kerberos
used by the caller of
.PN krb_mk_req
is incompatible with the
.PN krb_rd_req
version.
.TP 16
RD_AP_MSG_TYPE
The ticket-authenticator pair given to
.PN krb_rd_req
was not actually a ticket-authenticator pair.
.TP 16
RD_AP_UNDEC
The ticket was indecipherable.  This error can be caused by a forged or a
modified message.
.TP 16
RD_AP_INCON
The message given to
.PN krb_rd_req
contains an internal inconsistency.  This could occur if the ticket in the
ticket-authenticator pair does not match the authenticator.
.TP 16
RD_AP_BADD
The ticket-authenticator pair cannot be used from the address, \fIf_hostaddr\fP.
.TP 16
RD_AP_TIME
The authenticator in the ticket-authenticator pair is too old to be used to 
authenticate the foreign principal.
.TP 16
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 16
RD_AP_EXP
The ticket is too old to be used.
.ig ++
.IP krb_kntoln
Converts a Kerberos name to a local name.  The routine and uses the
\fIpname\fP and \fIpinst\fP fields of the AUTH_DAT structure to
reference the database 
.PN /etc/aname  
and find the corresponding local name (\fIlname\fP) of the service.  The
local name is returned and can be used by an application to change
uids, directories, or other parameters.  The
.PN krb_kntoln
routine is provided to support the use of Kerberos in existing utilities.
.++
.ig ++
.IP krb_set_key
Uses a Data Encryption Standard (DES) key (\fI*key\fP) to create a key
schedule and saves the original key to be used by the application as an
initialization vector. It is used to set the key that the server uses
to decrypt tickets.
.IP
If called with a non-zero second argument (\fIcvt\fP),
.PN krb_set_key
converts the input from a string of arbitrary length to a DES key by
encrypting it with a one-way function.
.IP
In most cases it should not be necessary to call
.PN krb_set_key .
The necessary keys are usually obtained and set inside
.PN krb_rd_req.  
The
.PN krb_set_key
routine is provided for applications that do not wish to place the
application keys on disk.
.++
.sp 1
.IP krb_get_cred
.PP
Searches the caller's ticket file for
the authentication information associated with the principal specified by the
\fIf_service\fP, \fIf_instance\fP, and \fIf_realm\fP. 
If
.PN krb_get_cred
finds information in the ticket file, it fills a credentials structure
with the information and returns the status, GC_OK.
.PP
The following is a list of the error values returned from
.PN krb_mk_req
and their possible causes:
.TP 15
NO_TKT_FIL
The ticket file does not exist.
.TP 15
TKT_FIL_ACC
The ticket file cannot be opened or the ticket file cannot be accessed.
.TP 15
TKT_FIL_LCK
The ticket file could not be locked for access.
.TP 15
TKT_FIL_FMT
The ticket file format is incorrect.
.TP 15
GC_NOTKT
Information concerning the principal does not exist in the ticket file.
.sp 1
.IP krb_mk_safe
.PP
Creates an authenticated but unencrypted message from text pointed to
by \fIin\fP, of a length indicated by \fIin_length\fP. The routine uses
the private session key (\fI*key\fP) to seed the checksum
algorithm, \f(CWdes_quad_cksum\fP, that it uses as part of the authentication
process. (For more information about
.PN des_quad_cksum ,
see the 
.PN des_crypt(3krb)
reference page.)  The
.PN krb_mk_safe
routine also uses the arguments \fIl_addr\fP and \fIf_addr\fP for
authentication purposes.
.PP
A safe message does not provide privacy, but does provide protection
against modifications in addition to providing authentication.  The encapsulated message
and header produced by \f(CWkrb_mk_safe\fP are placed in the area
pointed to by \fIout\fP. The routine returns the length of
the output or a negative one (\-1), indicating an error.
.sp 1
.IP krb_rd_safe
.PP
Authenticates a received
.PN krb_mk_safe
message and writes the appropriate fields in the message data structure
\fBMSG_DAT\fP. The argument \fIin\fP points to the beginning of the
received message. The argument \fIin_length\fP specifies the length of
the message. The \f(CWkrb_rd_safe\fP routine uses the private session
key (\fI*key\fP) to seed the 
.PN des_quad_cksum
routine (see the
.PN des_crypt(3krb)
reference page) as part of its 
authentication process. The routine fills in the following
\fBMSG_DAT\fP fields: 
.PP
.TS
tab(@);
l c
l l.
MSG_DAT Field@Description
.sp 4p
\f(CWapp_data\fR@Pointer to the application data
\f(CWapp_length\fR@Length of the \f(CWapp_data\fP
\f(CWtime_sec\fR@Timestamp of the message in seconds
\f(CWtime_5ms\fR@Timestamp of the message in 5-millisecond units
\f(CWswap\fR@T{
A 1 if the byte order of the receiver is different from that of
the sender
T}
.TE 
.PP
Note that the application must still determine if it is appropriate to
byte-swap application data; the Kerberos protocol fields are already
taken care of.
.PP
The
.PN krb_rd_safe
routine returns RD_AP_OK if the message, \fIin\fP, is authenticated and has
not been modified when it was sent between the foreign and the local
principal.  It is up to
the caller to check the time sequence of messages and to check against
recently replayed messages.
The following is a list of the error values returned by
.PN krb_rd_req
and their possible causes:
.TP 16
-1
A system call used by 
.PN krb_rd_safe
returned an error.
.TP 16
RD_AP_VERSION
The Kerberos version of the
.PN krb_mk_safe
code that generated message, \fIin\fP, is not supported by the
.PN krb_rd_safe
version used.
.TP 16
RD_AP_MSG_TYPE
The message, \fIin\fP, is not really a message produced by
.PN krb_mk_safe .
.TP 16
RD_AP_MODIFIED
The address of the machine from which \fIin\fP was sent does not match the
address of the machine on which the
.PN krb_mk_safe
message, \fIin\fP, was generated, or
.br
The message was modified when it was sent from the foreign to the local
principal, or
.br
The message, \fIin\fP, is too small to be the message produced by
.PN krb_mk_req .
.TP 16
RD_AP_TIME
The difference between the time at which the message, \fIin\fP, was produced
by
.PN krb_mk_req
and the time at which it was read by
.PN krb_rd_req
is too large.  The time difference must be within five minutes.
.ig ++
.IP krb_mk_err
Constructs an application level error message that may be used along
with the
.PN krb_mk_priv
and the
.PN krb_mk_safe
routines. The argument \fIout\fP is a pointer to the output buffer,
\fIcode\fP is an application specific error code, and \fIstring\fP
is an application specific error string.
.IP krb_rd_err
Routine unpacks a received
.PN krb_mk_err
message and writes the appropriate fields in the message structure
\fBMSG_DAT\fP. The argument \fIin\fP points to the beginning of the
received message. The message length is specified by \fIin_length\fP.
The argument \fIcode\fP is a pointer to a value to be filled in with
the error value provided by the application. The argument
\fI*msg_data\fP is a pointer to the structure MSG_DAT. The routine
writes the following \fBMSG_DAT\fP fields:
.PP
.TS
tab(@);
c c
l l.
MSG_DAT Field@Description
.sp 4p
\f(CWapp_data\fR@Pointer to the application data
\f(CWapp_length\fR@Length of the \f(CWapp_data\fP
\f(CWswap\fR@T{
A 1 if the byte order of the receiver is different from that of the
sender
T}
.TE 
.PP
.IP 
The 
.PN krb_rd_err
routine returns zero if the error message has been successfully received,
or a Kerberos error code.
.++
.SH Restrictions
The caller of the functions,
.PN krb_rd_req
and
.PN krb_rd_safe ,
must check the time
order of messages and protect against replay attempts. 
.SH Files
.TP
.PN /usr/include/krb.h
.TP
.PN /usr/lib/libkrb.a
.TP
.PN /usr/include/des.h
.TP
.PN /usr/lib/libdes.a
.TP
.PN /etc/srvtab
.SH See Also
des_crypt(3krb), krb_sendmutual(3krb), krb_sendauth(3krb), krb_svc_init(3krb),
krb_set_tkt_string(3krb), krb.conf(5krb)