KERBEROS(3)                                           KERBEROS(3)


NAME
       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 - Ker-
       beros authentication library



SYNOPSIS
       #include <kerberosIV/des.h>
       #include <kerberosIV/krb.h>

       extern char *krb_err_txt[];

       int krb_mk_req(authent,service,instance,realm,checksum)
       KTEXT authent;
       char *service;
       char *instance;
       char *realm;
       u_long checksum;

       int krb_rd_req(authent,service,instance,from_addr,ad,fn)
       KTEXT authent;
       char *service;
       char *instance;
       u_long from_addr;
       AUTH_DAT *ad;
       char *fn;

       int krb_kntoln(ad,lname)
       AUTH_DAT *ad;
       char *lname;

       int krb_set_key(key,cvt)
       char *key;
       int cvt;

       int krb_get_cred(service,instance,realm,c)
       char *service;
       char *instance;
       char *realm;
       CREDENTIALS *c;

       long krb_mk_priv(in,out,in_length,schedule,key,sender,receiver)
       u_char *in;
       u_char *out;
       u_long in_length;
       des_cblock key;
       des_key_schedule schedule;
       struct sockaddr_in *sender;
       struct sockaddr_in *receiver;

       long krb_rd_priv(in,in_length,schedule,key,sender,receiver,msg_data)
       u_char *in;
       u_long in_length;
       Key_schedule schedule;



MIT Project Athena     Kerberos Version 4.0                     1





KERBEROS(3)                                           KERBEROS(3)


       des_cblock key;
       struct sockaddr_in *sender;
       struct sockaddr_in *receiver;
       MSG_DAT *msg_data;

       long krb_mk_safe(in,out,in_length,key,sender,receiver)
       u_char *in;
       u_char *out;
       u_long in_length;
       des_cblock key;
       struct sockaddr_in *sender;
       struct sockaddr_in *receiver;

       long krb_rd_safe(in,length,key,sender,receiver,msg_data)
       u_char *in;
       u_long length;
       des_cblock key;
       struct sockaddr_in *sender;
       struct sockaddr_in *receiver;
       MSG_DAT *msg_data;

       long krb_mk_err(out,code,string)
       u_char *out;
       long code;
       char *string;

       long krb_rd_err(in,length,code,msg_data)
       u_char *in;
       u_long length;
       long code;
       MSG_DAT *msg_data;

DESCRIPTION
       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.

       krb_err_txt[] contains text string descriptions of various
       Kerberos error codes returned  by  some  of  the  routines
       below.

       krb_mk_req 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.  krb_mk_req then retrieves a
       ticket for the desired service and creates an  authentica-
       tor.   The authenticator is built in authent and is acces-
       sible to the calling procedure.

       It is up to the application to get  the  authenticator  to



MIT Project Athena     Kerberos Version 4.0                     2





KERBEROS(3)                                           KERBEROS(3)


       the  service  where it will be read by krb_rd_req.  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.

       krb_rd_req takes an authenticator of type KTEXT, a service
       name, an instance, the address of the host originating the
       request,  and  a  pointer  to a structure of type AUTH_DAT
       which is filled in  with  information  obtained  from  the
       authenticator.   It  also optionally takes the name of the
       file in which it will find the secret key(s) for the  ser-
       vice.   If  the  supplied  instance contains "*", then the
       first service key with the same service name found in  the
       service  key  file will be used, and the instance 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 krb_rd_req to extract the desired information.

       krb_rd_req returns zero (RD_AP_OK) upon successful authen-
       tication.   If a packet was forged, modified, or replayed,
       authentication will fail.  If the authentication fails,  a
       non-zero value is returned indicating the particular prob-
       lem encountered.  See krb.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 krb_set_key and will not bother looking fur-
       ther.

       krb_kntoln 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.

       krb_set_key  takes as an argument a des key.  It then cre-
       ates 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.

       If called with a  non-zero  second  argument,  krb_set_key
       will  first  convert  the input from a string of arbitrary
       length to a DES  key  by  encrypting  it  with  a  one-way



MIT Project Athena     Kerberos Version 4.0                     3





KERBEROS(3)                                           KERBEROS(3)


       function.

       In   most  cases  it  should  not  be  necessary  to  call
       krb_set_key.  The necessary keys will usually be  obtained
       and  set  inside  krb_rd_req.  krb_set_key is provided for
       those applications that do not wish to place the  applica-
       tion keys on disk.

       krb_get_cred  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 struc-
       ture with the ticket information.

       If the ticket was found, krb_get_cred 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.

       krb_mk_priv creates an  encrypted,  authenticated  message
       from  any arbitrary application data, pointed to by in and
       in_length bytes long.  The private session key, pointed to
       by key and the key schedule, schedule, are used to encrypt
       the data and some header information  using  pcbc_encrypt.
       sender  and  receiver point to the Internet address of the
       two parties.  In addition to providing privacy, this  pro-
       tocol  message  protects against modifications, insertions
       or replays.   The  encapsulated  message  and  header  are
       placed  in  the  area  pointed  to  by out and the routine
       returns the length of the  output,  or  -1  indicating  an
       error.

       krb_rd_priv   decrypts   and   authenticates   a  received
       krb_mk_priv message.  in points to the  beginning  of  the
       received  message, whose length is specified in in_length.
       The private session key, pointed to by key,  and  the  key
       schedule,  schedule,  are  used  to decrypt and verify the
       received message.  msg_data is  a  pointer  to  a  MSG_DAT
       struct,  defined  in  krb.h.   The  routine  fills  in the
       app_data field with a pointer to the decrypted application
       data,  app_length  with  the length of the app_data field,
       time_sec and time_5ms with the timestamps in the  message,
       and  swap  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 applica-
       tion data; the Kerberos protocol fields are already  taken
       care  of).  The hash field returns a value useful as input
       to the krb_ck_repl 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
       krb_ck_repl if so desired.



MIT Project Athena     Kerberos Version 4.0                     4





KERBEROS(3)                                           KERBEROS(3)


       krb_mk_safe creates an authenticated, but unencrypted mes-
       sage from any arbitrary application data, pointed to by in
       and  in_length  bytes  long.   The  private  session  key,
       pointed to by key, is used to seed the quad_cksum() check-
       sum algorithm used as part of the authentication.   sender
       and receiver point to the Internet address of the two par-
       ties.  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 out and the routine
       returns the length of the  output,  or  -1  indicating  an
       error.  The authentication provided by this routine is not
       as strong as that provided by krb_mk_priv or by  computing
       the  checksum  using  cbc_cksum  instead,  both  of  which
       authenticate via DES.


       krb_rd_safe authenticates a received krb_mk_safe  message.
       in  points to the beginning of the received message, whose
       length is specified in  in_length.   The  private  session
       key,  pointed  to by key, is used to seed the quad_cksum()
       routine as part of  the  authentication.   msg_data  is  a
       pointer  to a MSG_DAT struct, defined in krb.h .  The rou-
       tine fills in these MSG_DAT  fields:  the  app_data  field
       with  a  pointer  to the application data, app_length with
       the length of the app_data field,  time_sec  and  time_5ms
       with  the  timestamps in the message, and swap 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 Kerberos
       protocol  fields  are  already  taken  care of).  The hash
       field returns a value useful as input to  the  krb_ck_repl
       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
       krb_ck_repl if so desired.

       krb_mk_err  constructs  an application level error message
       that may be used along with  krb_mk_priv  or  krb_mk_safe.
       out is a pointer to the output buffer, code is an applica-
       tion specific error code, and  string  is  an  application
       specific error string.


       krb_rd_err  unpacks  a  received  krb_mk_err  message.  in
       points to the beginning of  the  received  message,  whose
       length  is specified in in_length.  code is a pointer to a
       value to be filled in with the error value provided by the
       application.   msg_data  is a pointer to a MSG_DAT struct,
       defined in krb.h .  The routine  fills  in  these  MSG_DAT
       fields:   the   app_data  field  with  a  pointer  to  the



MIT Project Athena     Kerberos Version 4.0                     5





KERBEROS(3)                                           KERBEROS(3)


       application error text, app_length with the length of  the
       app_data field, and swap 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 Kerberos  protocol  fields
       are already taken care of).

       The  routine  returns  zero  if the error message has been
       successfully received, or a Kerberos error code.

       The KTEXT 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  con-
       taining  the  authenticator,  and  krb_mk_req  returns the
       authenticator in a structure of this type.   KTEXT  itself
       is  really a pointer to the structure.   The actual struc-
       ture is of type KTEXT_ST.

       The AUTH_DAT 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.  MSG_DAT structure is filled in by
       either krb_rd_priv, krb_rd_safe, or krb_rd_err.   It  must
       be  allocated  before  the  call  and  a  pointer to it is
       passed.  The structure is filled  in  with  data  obtained
       from Kerberos.


FILES
       /usr/include/kerberosIV/krb.h
       /usr/lib/libkrb.a
       /usr/include/kerberosIV/des.h
       /usr/lib/libdes.a
       /etc/aname
       /etc/kerberosIV/srvtab
       /tmp/tkt[uid]

SEE ALSO
       kerberos(1), des_crypt(3)

BUGS
       The  caller  of  krb_rd_req,  krb_rd_priv, and krb_rd_safe
       must  check  time   order   and   for   replay   attempts.
       krb_ck_repl is not implemented yet.

AUTHORS
       Clifford Neuman, MIT Project Athena
       Steve  Miller, MIT Project Athena/Digital Equipment Corpo-
       ration

RESTRICTIONS
       COPYRIGHT 1985,1986,1989 Massachusetts Institute of  Tech-
       nology




MIT Project Athena     Kerberos Version 4.0                     6