crypto/kerberosIV/man/tf_util.3

   1 .\" $Id: tf_util.3,v 1.2 1996/06/12 21:29:29 bg Exp $
   2 .\" Copyright 1989 by the Massachusetts Institute of Technology.
   3 .\"
   4 .\" For copying and distribution information,
   5 .\" please see the file <mit-copyright.h>.
   6 .\"
   7 .TH TF_UTIL 3 "Kerberos Version 4.0" "MIT Project Athena"
   8 .SH NAME
   9 tf_init, tf_get_pname, tf_get_pinst, tf_get_cred, tf_close \
  10 \- Routines for manipulating a Kerberos ticket file
  11 .SH SYNOPSIS
  12 .nf
  13 .nj
  14 .ft B
  15 #include <krb.h>
  16 .PP
  17 .ft B
  18 extern char *krb_err_txt[];
  19 .PP
  20 .ft B
  21 tf_init(tf_name, rw)
  22 char *tf_name;
  23 int rw;
  24 .PP
  25 .ft B
  26 tf_get_pname(pname)
  27 char *pname;
  28 .PP
  29 .ft B
  30 tf_get_pinst(pinst)
  31 char *pinst;
  32 .PP
  33 .ft B
  34 tf_get_cred(c)
  35 CREDENTIALS *c;
  36 .PP
  37 .ft B
  38 tf_close()
  39 .PP
  40 .fi
  41 .SH DESCRIPTION
  42 This group of routines are provided to manipulate the Kerberos tickets
  43 file.  A ticket file has the following format:
  44 .nf
  45 .in +4
  46 .sp
  47 principal's name          (null-terminated string)
  48 principal's instance      (null-terminated string)
  49 CREDENTIAL_1
  50 CREDENTIAL_2
  51   ...
  52 CREDENTIAL_n
  53 EOF
  54 .sp
  55 .in -4
  56 .LP
  57 Where "CREDENTIAL_x" consists of the following fixed-length
  58 fields from the CREDENTIALS structure (defined in <krb.h>):
  59 .nf
  60 .sp
  61 .in +4
  62         char            service[ANAME_SZ]
  63         char            instance[INST_SZ]
  64         char            realm[REALM_SZ]
  65         des_cblock      session
  66         int             lifetime
  67         int             kvno
  68         KTEXT_ST        ticket_st
  69         long            issue_date
  70 .in -4
  71 .sp
  72 .fi
  73 .PP
  74 .I tf_init
  75 must be called before the other ticket file
  76 routines.
  77 It takes the name of the ticket file to use,
  78 and a read/write flag as arguments.
  79 It tries to open the ticket file, checks the mode and if
  80 everything is okay, locks the file.  If it's opened for
  81 reading, the lock is shared.  If it's opened for writing,
  82 the lock is exclusive.
  83 KSUCCESS is returned if all went well, otherwise one of the
  84 following:
  85 .nf
  86 .sp
  87 NO_TKT_FIL      - file wasn't there
  88 TKT_FIL_ACC     - file was in wrong mode, etc.
  89 TKT_FIL_LCK     - couldn't lock the file, even after a retry
  90 .sp
  91 .fi
  92 .PP
  93 The
  94 .I tf_get_pname
  95 reads the principal's name from a ticket file.
  96 It should only be called after tf_init has been called.  The
  97 principal's name is filled into the
  98 .I pname
  99 parameter.  If all goes
 100 well, KSUCCESS is returned.
 101 If tf_init wasn't called, TKT_FIL_INI
 102 is returned.
 103 If the principal's name was null, or EOF was encountered, or the
 104 name was longer than ANAME_SZ, TKT_FIL_FMT is returned.
 105 .PP
 106 The
 107 .I tf_get_pinst
 108 reads the principal's instance from a ticket file.
 109 It should only be called after tf_init and tf_get_pname
 110 have been called.
 111 The principal's instance is filled into the
 112 .I pinst
 113 parameter.
 114 If all goes
 115 well, KSUCCESS is returned.
 116 If tf_init wasn't called, TKT_FIL_INI
 117 is returned.
 118 If EOF was encountered, or the
 119 name was longer than INST_SZ, TKT_FIL_FMT is returned.
 120 Note that, unlike the principal name, the instance name may be null.
 121 .PP
 122 The
 123 .I tf_get_cred
 124 routine reads a CREDENTIALS record from a ticket file and
 125 fills in the given structure.
 126 It should only be called after
 127 tf_init, tf_get_pname, and tf_get_pinst have been called.
 128 If all goes well, KSUCCESS is returned.  Possible error codes
 129 are:
 130 .nf
 131 .sp
 132 TKT_FIL_INI     - tf_init wasn't called first
 133 TKT_FIL_FMT     - bad format
 134 EOF             - end of file encountered
 135 .sp
 136 .fi
 137 .PP
 138 .I tf_close
 139 closes the ticket file and releases the lock on it.
 140 .SH "SEE ALSO"
 141 krb(3)
 142 .SH DIAGNOSTICS
 143 .SH BUGS
 144 The ticket file routines have to be called in a certain order.
 145 .SH AUTHORS
 146 Jennifer Steiner, MIT Project Athena
 147 .br
 148 Bill Bryant, MIT Project Athena
 149 .SH RESTRICTIONS
 150 Copyright 1987 Massachusetts Institute of Technology