4.3BSD-Reno/share/man/cat3/krb_mk_req.0
KERBEROS(3) 4.0 KERBEROS(3)
NNAAMMEE
krb_mk_req, krb_rd_req, krb_kntoln, krb_set_key,
krb_get_cred, krb_mk_priv, krb_rd_priv, krb_mk_safe,
krb_rd_safe, krb_mk_err, krb_rd_err, krb_ck_repl - Kerberos
authentication library
SSYYNNOOPPSSIISS
##iinncclluuddee <<kkeerrbbeerroossIIVV//ddeess..hh>>
##iinncclluuddee <<kkeerrbbeerroossIIVV//kkrrbb..hh>>
eexxtteerrnn cchhaarr **kkrrbb__eerrrr__ttxxtt[[]];;
iinntt kkrrbb__mmkk__rreeqq((aauutthheenntt,,sseerrvviiccee,,iinnssttaannccee,,rreeaallmm,,cchheecckkssuumm))
KKTTEEXXTT aauutthheenntt;;
cchhaarr **sseerrvviiccee;;
cchhaarr **iinnssttaannccee;;
cchhaarr **rreeaallmm;;
uu__lloonngg cchheecckkssuumm;;
iinntt kkrrbb__rrdd__rreeqq((aauutthheenntt,,sseerrvviiccee,,iinnssttaannccee,,ffrroomm__aaddddrr,,aadd,,ffnn))
KKTTEEXXTT aauutthheenntt;;
cchhaarr **sseerrvviiccee;;
cchhaarr **iinnssttaannccee;;
uu__lloonngg ffrroomm__aaddddrr;;
AAUUTTHH__DDAATT **aadd;;
cchhaarr **ffnn;;
iinntt kkrrbb__kknnttoollnn((aadd,,llnnaammee))
AAUUTTHH__DDAATT **aadd;;
cchhaarr **llnnaammee;;
iinntt kkrrbb__sseett__kkeeyy((kkeeyy,,ccvvtt))
cchhaarr **kkeeyy;;
iinntt ccvvtt;;
iinntt kkrrbb__ggeett__ccrreedd((sseerrvviiccee,,iinnssttaannccee,,rreeaallmm,,cc))
cchhaarr **sseerrvviiccee;;
cchhaarr **iinnssttaannccee;;
cchhaarr **rreeaallmm;;
CCRREEDDEENNTTIIAALLSS **cc;;
lloonngg kkrrbb__mmkk__pprriivv((iinn,,oouutt,,iinn__lleennggtthh,,sscchheedduullee,,kkeeyy,,sseennddeerr,,rreecceeiivveerr))
uu__cchhaarr **iinn;;
uu__cchhaarr **oouutt;;
uu__lloonngg iinn__lleennggtthh;;
ddeess__ccbblloocckk kkeeyy;;
ddeess__kkeeyy__sscchheedduullee sscchheedduullee;;
ssttrruucctt ssoocckkaaddddrr__iinn **sseennddeerr;;
ssttrruucctt ssoocckkaaddddrr__iinn **rreecceeiivveerr;;
lloonngg kkrrbb__rrdd__pprriivv((iinn,,iinn__lleennggtthh,,sscchheedduullee,,kkeeyy,,sseennddeerr,,rreecceeiivveerr,,mmssgg__ddaattaa))
uu__cchhaarr **iinn;;
Printed 7/27/90 Kerberos 1
KERBEROS(3) 4.0 KERBEROS(3)
uu__lloonngg iinn__lleennggtthh;;
KKeeyy__sscchheedduullee sscchheedduullee;;
ddeess__ccbblloocckk kkeeyy;;
ssttrruucctt ssoocckkaaddddrr__iinn **sseennddeerr;;
ssttrruucctt ssoocckkaaddddrr__iinn **rreecceeiivveerr;;
MMSSGG__DDAATT **mmssgg__ddaattaa;;
lloonngg kkrrbb__mmkk__ssaaffee((iinn,,oouutt,,iinn__lleennggtthh,,kkeeyy,,sseennddeerr,,rreecceeiivveerr))
uu__cchhaarr **iinn;;
uu__cchhaarr **oouutt;;
uu__lloonngg iinn__lleennggtthh;;
ddeess__ccbblloocckk kkeeyy;;
ssttrruucctt ssoocckkaaddddrr__iinn **sseennddeerr;;
ssttrruucctt ssoocckkaaddddrr__iinn **rreecceeiivveerr;;
lloonngg kkrrbb__rrdd__ssaaffee((iinn,,lleennggtthh,,kkeeyy,,sseennddeerr,,rreecceeiivveerr,,mmssgg__ddaattaa))
uu__cchhaarr **iinn;;
uu__lloonngg lleennggtthh;;
ddeess__ccbblloocckk kkeeyy;;
ssttrruucctt ssoocckkaaddddrr__iinn **sseennddeerr;;
ssttrruucctt ssoocckkaaddddrr__iinn **rreecceeiivveerr;;
MMSSGG__DDAATT **mmssgg__ddaattaa;;
lloonngg kkrrbb__mmkk__eerrrr((oouutt,,ccooddee,,ssttrriinngg))
uu__cchhaarr **oouutt;;
lloonngg ccooddee;;
cchhaarr **ssttrriinngg;;
lloonngg kkrrbb__rrdd__eerrrr((iinn,,lleennggtthh,,ccooddee,,mmssgg__ddaattaa))
uu__cchhaarr **iinn;;
uu__lloonngg lleennggtthh;;
lloonngg ccooddee;;
MMSSGG__DDAATT **mmssgg__ddaattaa;;
DDEESSCCRRIIPPTTIIOONN
This library supports network authentication and various
related operations. The library contains many routines
beyond those described in this man page, but they are not
intended to be used directly. Instead, they are called by
the routines that are described, the authentication server
and the login program.
_k_r_b__e_r_r__t_x_t[] contains text string descriptions of various
Kerberos error codes returned by some of the routines below.
_k_r_b__m_k__r_e_q takes a pointer to a text structure in which an
authenticator is to be built. It also takes the name,
instance, and realm of the service to be used and an
optional checksum. It is up to the application to decide
how to generate the checksum. _k_r_b__m_k__r_e_q then retrieves a
ticket for the desired service and creates an authenticator.
The authenticator is built in _a_u_t_h_e_n_t and is accessible to
Printed 7/27/90 Kerberos 2
KERBEROS(3) 4.0 KERBEROS(3)
the calling procedure.
It is up to the application to get the authenticator to the
service where it will be read by _k_r_b__r_d__r_e_q. Unless an
attacker posesses the session key contained in the ticket,
it will be unable to modify the authenticator. Thus, the
checksum can be used to verify the authenticity of the other
data that will pass through a connection.
_k_r_b__r_d__r_e_q takes an authenticator of type KKTTEEXXTT,, a service
name, an instance, the address of the host originating the
request, and a pointer to a structure of type AAUUTTHH__DDAATT which
is filled in with information obtained from the authentica-
tor. It also optionally takes the name of the file in which
it will find the secret key(s) for the service. If the sup-
plied _i_n_s_t_a_n_c_e contains "*", then the first service key with
the same service name found in the service key file will be
used, and the _i_n_s_t_a_n_c_e argument will be filled in with the
chosen instance. This means that the caller must provide
space for such an instance name.
It is used to find out information about the principal when
a request has been made to a service. It is up to the
application protocol to get the authenticator from the
client to the service. The authenticator is then passed to
_k_r_b__r_d__r_e_q to extract the desired information.
_k_r_b__r_d__r_e_q returns zero (RD_AP_OK) upon successful authenti-
cation. If a packet was forged, modified, or replayed,
authentication will fail. If the authentication fails, a
non-zero value is returned indicating the particular problem
encountered. See _k_r_b._h for the list of error codes.
If the last argument is the null string (""), krb_rd_req
will use the file /etc/srvtab to find its keys. If the last
argument is NULL, it will assume that the key has been set
by _k_r_b__s_e_t__k_e_y and will not bother looking further.
_k_r_b__k_n_t_o_l_n converts a Kerberos name to a local name. It
takes a structure of type AUTH_DAT and uses the name and
instance to look in the database /etc/aname to find the
corresponding local name. The local name is returned and
can be used by an application to change uids, directories,
or other parameters. It is not an integral part of Ker-
beros, but is instead provided to support the use of Ker-
beros in existing utilities.
_k_r_b__s_e_t__k_e_y takes as an argument a des key. It then creates
a key schedule from it and saves the original key to be used
as an initialization vector. It is used to set the server's
key which must be used to decrypt tickets.
Printed 7/27/90 Kerberos 3
KERBEROS(3) 4.0 KERBEROS(3)
If called with a non-zero second argument, _k_r_b__s_e_t__k_e_y will
first convert the input from a string of arbitrary length to
a DES key by encrypting it with a one-way function.
In most cases it should not be necessary to call
_k_r_b__s_e_t__k_e_y. The necessary keys will usually be obtained and
set inside _k_r_b__r_d__r_e_q. _k_r_b__s_e_t__k_e_y is provided for those
applications that do not wish to place the application keys
on disk.
_k_r_b__g_e_t__c_r_e_d searches the caller's ticket file for a ticket
for the given service, instance, and realm; and, if a ticket
is found, fills in the given CREDENTIALS structure with the
ticket information.
If the ticket was found, _k_r_b__g_e_t__c_r_e_d returns GC_OK. If the
ticket file can't be found, can't be read, doesn't belong to
the user (other than root), isn't a regular file, or is in
the wrong mode, the error GC_TKFIL is returned.
_k_r_b__m_k__p_r_i_v creates an encrypted, authenticated message from
any arbitrary application data, pointed to by _i_n and
_i_n__l_e_n_g_t_h bytes long. The private session key, pointed to
by _k_e_y and the key schedule, _s_c_h_e_d_u_l_e, are used to encrypt
the data and some header information using _p_c_b_c__e_n_c_r_y_p_t.
_s_e_n_d_e_r and _r_e_c_e_i_v_e_r point to the Internet address of the two
parties. In addition to providing privacy, this protocol
message protects against modifications, insertions or
replays. The encapsulated message and header are placed in
the area pointed to by _o_u_t and the routine returns the
length of the output, or -1 indicating an error.
_k_r_b__r_d__p_r_i_v decrypts and authenticates a received
_k_r_b__m_k__p_r_i_v message. _i_n points to the beginning of the
received message, whose length is specified in _i_n__l_e_n_g_t_h.
The private session key, pointed to by _k_e_y, and the key
schedule, _s_c_h_e_d_u_l_e, are used to decrypt and verify the
received message. _m_s_g__d_a_t_a is a pointer to a _M_S_G__D_A_T
struct, defined in _k_r_b._h. The routine fills in the _a_p_p__d_a_t_a
field with a pointer to the decrypted application data,
_a_p_p__l_e_n_g_t_h with the length of the _a_p_p__d_a_t_a field, _t_i_m_e__s_e_c
and _t_i_m_e__5_m_s with the timestamps in the message, and _s_w_a_p
with a 1 if the byte order of the receiver is different than
that of the sender. (The application must still determine
if it is appropriate to byte-swap application data; the Ker-
beros protocol fields are already taken care of). The _h_a_s_h
field returns a value useful as input to the _k_r_b__c_k__r_e_p_l
routine.
The routine returns zero if ok, or a Kerberos error code.
Modified messages and old messages cause errors, but it is
up to the caller to check the time sequence of messages, and
Printed 7/27/90 Kerberos 4
KERBEROS(3) 4.0 KERBEROS(3)
to check against recently replayed messages using
_k_r_b__c_k__r_e_p_l if so desired.
_k_r_b__m_k__s_a_f_e creates an authenticated, but unencrypted mes-
sage from any arbitrary application data, pointed to by _i_n
and _i_n__l_e_n_g_t_h bytes long. The private session key, pointed
to by _k_e_y, is used to seed the _q_u_a_d__c_k_s_u_m() checksum algo-
rithm used as part of the authentication. _s_e_n_d_e_r and
_r_e_c_e_i_v_e_r point to the Internet address of the two parties.
This message does not provide privacy, but does protect (via
detection) against modifications, insertions or replays.
The encapsulated message and header are placed in the area
pointed to by _o_u_t and the routine returns the length of the
output, or -1 indicating an error. The authentication pro-
vided by this routine is not as strong as that provided by
_k_r_b__m_k__p_r_i_v or by computing the checksum using _c_b_c__c_k_s_u_m
instead, both of which authenticate via DES.
_k_r_b__r_d__s_a_f_e authenticates a received _k_r_b__m_k__s_a_f_e message.
_i_n points to the beginning of the received message, whose
length is specified in _i_n__l_e_n_g_t_h. The private session key,
pointed to by _k_e_y, is used to seed the quad_cksum() routine
as part of the authentication. _m_s_g__d_a_t_a is a pointer to a
_M_S_G__D_A_T struct, defined in _k_r_b._h . The routine fills in
these _M_S_G__D_A_T fields: the _a_p_p__d_a_t_a field with a pointer to
the application data, _a_p_p__l_e_n_g_t_h with the length of the
_a_p_p__d_a_t_a field, _t_i_m_e__s_e_c and _t_i_m_e__5_m_s with the timestamps in
the message, and _s_w_a_p with a 1 if the byte order of the
receiver is different than that of the sender. (The appli-
cation must still determine if it is appropriate to byte-
swap application data; the Kerberos protocol fields are
already taken care of). The _h_a_s_h field returns a value use-
ful as input to the _k_r_b__c_k__r_e_p_l routine.
The routine returns zero if ok, or a Kerberos error code.
Modified messages and old messages cause errors, but it is
up to the caller to check the time sequence of messages, and
to check against recently replayed messages using
_k_r_b__c_k__r_e_p_l if so desired.
_k_r_b__m_k__e_r_r constructs an application level error message
that may be used along with _k_r_b__m_k__p_r_i_v or _k_r_b__m_k__s_a_f_e. _o_u_t
is a pointer to the output buffer, _c_o_d_e is an application
specific error code, and _s_t_r_i_n_g is an application specific
error string.
_k_r_b__r_d__e_r_r unpacks a received _k_r_b__m_k__e_r_r message. _i_n points
to the beginning of the received message, whose length is
specified in _i_n__l_e_n_g_t_h. _c_o_d_e is a pointer to a value to be
filled in with the error value provided by the application.
_m_s_g__d_a_t_a is a pointer to a _M_S_G__D_A_T struct, defined in _k_r_b._h
Printed 7/27/90 Kerberos 5
KERBEROS(3) 4.0 KERBEROS(3)
. The routine fills in these _M_S_G__D_A_T fields: the _a_p_p__d_a_t_a
field with a pointer to the application error text,
_a_p_p__l_e_n_g_t_h with the length of the _a_p_p__d_a_t_a field, and _s_w_a_p
with a 1 if the byte order of the receiver is different than
that of the sender. (The application must still determine
if it is appropriate to byte-swap application data; the Ker-
beros protocol fields are already taken care of).
The routine returns zero if the error message has been suc-
cessfully received, or a Kerberos error code.
The _K_T_E_X_T structure is used to pass around text of varying
lengths. It consists of a buffer for the data, and a
length. krb_rd_req takes an argument of this type contain-
ing the authenticator, and krb_mk_req returns the authenti-
cator in a structure of this type. KTEXT itself is really a
pointer to the structure. The actual structure is of type
KTEXT_ST.
The _A_U_T_H__D_A_T structure is filled in by krb_rd_req. It must
be allocated before calling krb_rd_req, and a pointer to it
is passed. The structure is filled in with data obtained
from Kerberos. _M_S_G__D_A_T structure is filled in by either
krb_rd_priv, krb_rd_safe, or krb_rd_err. It must be allo-
cated before the call and a pointer to it is passed. The
structure is filled in with data obtained from Kerberos.
FFIILLEESS
/usr/include/kerberosIV/krb.h
/usr/lib/libkrb.a
/usr/include/kerberosIV/des.h
/usr/lib/libdes.a
/etc/kerberosIV/aname
/etc/kerberosIV/srvtab
/tmp/tkt[uid]
SSEEEE AALLSSOO
kerberos(1), des_crypt(3)
DDIIAAGGNNOOSSTTIICCSS
BBUUGGSS
The caller of _k_r_b__r_d__r_e_q, _k_r_b__r_d__p_r_i_v, _a_n_d _k_r_b__r_d__s_a_f_e must
check time order and for replay attempts. _k_r_b__c_k__r_e_p_l is
not implemented yet.
AAUUTTHHOORRSS
Clifford Neuman, MIT Project Athena
Steve Miller, MIT Project Athena/Digital Equipment Corpora-
tion
RREESSTTRRIICCTTIIOONNSS
COPYRIGHT 1985,1986,1989 Massachusetts Institute of
Printed 7/27/90 Kerberos 6
KERBEROS(3) 4.0 KERBEROS(3)
Technology
Printed 7/27/90 Kerberos 7