TF_UTIL(3)

NAME
tf_init, tf_get_pname, tf_get_pinst, tf_get_cred, tf_close - Routines for manipulating a Kerberos ticket file

SYNOPSIS
#include <kerberosIV/krb.h>

extern char *krb_err_txt[];

tf_init(tf_name, rw)
char *tf_name;
int rw;

tf_get_pname(pname)
char *pname;

tf_get_pinst(pinst)
char *pinst;

tf_get_cred(c)
CREDENTIALS *c;

tf_close()

DESCRIPTION
This group of routines are provided to manipulate the Kerberos tickets file. A ticket file has the following format:

principal's name          (null-terminated string)
principal's instance      (null-terminated string)
CREDENTIAL_1
CREDENTIAL_2
  ...
CREDENTIAL_n
EOF

Where "CREDENTIAL_x" consists of the following fixed-length
fields from the CREDENTIALS structure (defined in <krb.h>):

	char		service[ANAME_SZ]
	char		instance[INST_SZ]
	char		realm[REALM_SZ]
	des_cblock	session
	int		lifetime
	int		kvno
	KTEXT_ST	ticket_st
	long		issue_date

tf_init must be called before the other ticket file routines. It takes the name of the ticket file to use, and a read/write flag as arguments. It tries to open the ticket file, checks the mode and if everything is okay, locks the file. If it's opened for reading, the lock is shared. If it's opened for writing, the lock is exclusive. KSUCCESS is returned if all went well, otherwise one of the following:

NO_TKT_FIL	- file wasn't there
TKT_FIL_ACC	- file was in wrong mode, etc.
TKT_FIL_LCK	- couldn't lock the file, even after a retry

The tf_get_pname reads the principal's name from a ticket file. It should only be called after tf_init has been called. The principal's name is filled into the pname parameter. If all goes well, KSUCCESS is returned. If tf_init wasn't called, TKT_FIL_INI is returned. If the principal's name was null, or EOF was encountered, or the name was longer than ANAME_SZ, TKT_FIL_FMT is returned.

The tf_get_pinst reads the principal's instance from a ticket file. It should only be called after tf_init and tf_get_pname have been called. The principal's instance is filled into the pinst parameter. If all goes well, KSUCCESS is returned. If tf_init wasn't called, TKT_FIL_INI is returned. If EOF was encountered, or the name was longer than INST_SZ, TKT_FIL_FMT is returned. Note that, unlike the principal name, the instance name may be null.

The tf_get_cred routine reads a CREDENTIALS record from a ticket file and fills in the given structure. It should only be called after tf_init, tf_get_pname, and tf_get_pinst have been called. If all goes well, KSUCCESS is returned. Possible error codes are:

TKT_FIL_INI	- tf_init wasn't called first
TKT_FIL_FMT	- bad format
EOF		- end of file encountered

tf_close closes the ticket file and releases the lock on it.

SEE ALSO
krb(3)

DIAGNOSTICS

BUGS
The ticket file routines have to be called in a certain order.

AUTHORS
Jennifer Steiner, MIT Project Athena
Bill Bryant, MIT Project Athena

RESTRICTIONS
Copyright 1987 Massachusetts Institute of Technology