.\"
.\" This source code is no longer held under any constraint of USA
.\" `cryptographic laws' since it was exported legally.  The cryptographic
.\" functions were removed from the code and a "Bones" distribution was
.\" made.  A Commodity Jurisdiction Request #012-94 was filed with the
.\" USA State Department, who handed it to the Commerce department.  The
.\" code was determined to fall under General License GTDA under ECCN 5D96G,
.\" and hence exportable.  The cryptographic interfaces were re-added by Eric
.\" Young, and then KTH proceeded to maintain the code in the free world.
.\"
.\"Copyright (C) 1989 by the Massachusetts Institute of Technology
.\"
.\"Export of this software from the United States of America is assumed
.\"to require a specific license from the United States Government.
.\"It is the responsibility of any person or organization contemplating
.\"export to obtain such a license before exporting.
.\"
.\"WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
.\"distribute this software and its documentation for any purpose and
.\"without fee is hereby granted, provided that the above copyright
.\"notice appear in all copies and that both that copyright notice and
.\"this permission notice appear in supporting documentation, and that
.\"the name of M.I.T. not be used in advertising or publicity pertaining
.\"to distribution of the software without specific, written prior
.\"permission.  M.I.T. makes no representations about the suitability of
.\"this software for any purpose.  It is provided "as is" without express
.\"or implied warranty.
.\"
.\"	$OpenBSD: tf_util.3,v 1.4 1998/02/25 15:51:43 art Exp $
.TH TF_UTIL 3 "Kerberos Version 4.0" "MIT Project Athena"
.SH NAME
tf_init, tf_get_pname, tf_get_pinst, tf_get_cred, tf_close \
\- Routines for manipulating a Kerberos ticket file
.SH SYNOPSIS
.nf
.nj
.ft B
#include <kerberosIV/krb.h>
.PP
.ft B
extern char *krb_err_txt[];
.PP
.ft B
tf_init(tf_name, rw)
char *tf_name;
int rw;
.PP
.ft B
tf_get_pname(pname)
char *pname;
.PP
.ft B
tf_get_pinst(pinst)
char *pinst;
.PP
.ft B
tf_get_cred(c)
CREDENTIALS *c;
.PP
.ft B
tf_close()
.PP
.fi
.SH DESCRIPTION
This group of routines are provided to manipulate the Kerberos tickets
file.  A ticket file has the following format:
.nf
.in +4
.sp
principal's name          (null-terminated string)
principal's instance      (null-terminated string)
CREDENTIAL_1
CREDENTIAL_2
  ...
CREDENTIAL_n
EOF
.sp
.in -4
.LP
Where "CREDENTIAL_x" consists of the following fixed-length
fields from the CREDENTIALS structure (defined in <krb.h>):
.nf
.sp
.in +4
	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
.in -4
.sp
.fi
.PP
.I 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:
.nf
.sp
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
.sp
.fi
.PP
The
.I 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 
.I 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.
.PP
The
.I 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 
.I 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.
.PP
The
.I 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:
.nf
.sp
TKT_FIL_INI	- tf_init wasn't called first
TKT_FIL_FMT	- bad format
EOF		- end of file encountered
.sp
.fi
.PP
.I tf_close
closes the ticket file and releases the lock on it.
.SH "SEE ALSO"
krb(3)
.SH DIAGNOSTICS
.SH BUGS
The ticket file routines have to be called in a certain order.
.SH AUTHORS
Jennifer Steiner, MIT Project Athena
.br
Bill Bryant, MIT Project Athena
.SH RESTRICTIONS
Copyright 1987 Massachusetts Institute of Technology