.\" 
.\" $Header: /home/cvs.crypt/src/eBones/lib/librkinit/rkinit.3,v 1.1.1.1 1995/09/16 10:43:33 mark Exp $
.\" $Source: /home/cvs.crypt/src/eBones/lib/librkinit/rkinit.3,v $
.\" $Author: mark $
.\"
.\"
.TH RKINIT 3 "November 12, 1989"
.SH NAME
rkinit, rkinit_errmsg
.SH SYNOPSIS
.nf
.nj
.ft B
#include <rkinit.h>
#include <rkinit_err.h>
.PP
.ft B
int rkinit(host, r_krealm, info, timeout)
  char *host;
  char *r_krealm;
  rkinit_info *info;
  int timeout;
.PP
.ft B
char *rkinit_errmsg(string)
  char *string;
.fi
.ft R
.SH DESCRIPTION
This library contains the calls necessary to interface with the
.I rkinit 
system of remote ticket establishment.  See 
.IR rkinit (1)
for more information on 
.I rkinit
.PP
.I rkinit.h
is the header file that contains information that all clients
will need to use.  
.PP
.I rkinit_err.h 
is the 
.I com_err 
error table header file.  See
.IR com_err (3)
for more information about 
.I com_err.
.PP
.IR rkinit ()
takes as arguments the name of the host on which you wish to
establish tickets, the kerberos realm of the remote host, a
fully initialized rkinit_info structure, and a boolean value 
telling 
whether or not 
.IR rkinit () 
should time out if the transaction
fails to complete after a certain about of time.  
This call does not know about about default values, so
something must be filled in for everything except for the ticket
filename in the rkinit_info structure described below.

.nf
.nj
.ft B
This is the rkinit_info type:

typedef struct {
    char aname[ANAME_SZ + 1];
    char inst[INST_SZ + 1];
    char realm[REALM_SZ + 1];
    char sname[ANAME_SZ + 1];
    char sinst[INST_SZ + 1];
    char username[9];           /* max local name length + 1 */
    char tktfilename[MAXPATHLEN + 1];
    long lifetime;
} rkinit_info;
.fi
.ft R

.I aname
is the name part of the kerberos principal for which tickets are
being requested.  

.I inst
is the instance part.

.I realm
is the realm part.

.I sname
is the service name of the key that will appear in the remote
initial ticket (for example, "krbtgt").

.I sname
is the service instance.

.I username
is the name of the local user on the remote host who will own
the ticket file.

.I tktfilename
is the name of the file on the remote host in which the
tickets will be stored.  This is the only field in the structure
for which a blank value is filled in.  If this value is left
blank, the server will figure out what to call the ticket file
by using the kerberos library default as determined by 
.I TKT_FILE
as defined in 
.IR krb.h .

.I lifetime
is the lifetime of the tickets in the usual five minute
intervals.  It is possible with this routine, as with 
.IR krb_get_in_tkt (3)
to request tickets with zero lifetime.

.IR rkinit (), 
while it is running, opens a socket, changes the name
of the default kerberos ticket file, and changes the signal
handler for the ALRM signal (if timeout != 0).  rkinit()
restores all these values when it exits whether it exits with
an error or not, so clients using the rkinit library need not
worry about this information.

.IR rkinit_errmsg ()
takes a string as its only argument.  Passing
other than NULL to this routine should be done 
by only the rkinit library and server.  
Doing this sets the current rkinit
error message.  Calling 
.IR rkinit_errmsg () 
with NULL as the argument returns the current rkinit error
message.
Although the rkinit library uses 
.IR com_err (3)
for error handling, the error messages returned by 
.IR com_err ()
may not be specific enough.  A client could report the error
message returned by rkinit as follows:


.nf
.nj
.ft B
if (status = rkinit(host, r_krealm, &info, timeout)) {
    com_err(argv[0], status, "while obtaining remote tickets:");
    fprintf(stderr, "%s\\n", rkinit_errmsg(0));
    exit(1);
}
.fi
.ft R

.SH SEE ALSO
kerberos(1), kerberos(3), rkinit(1), rkinitd(8)

.SH DIAGNOSTICS
.IR rkinit ()
is usually good about reporting error messages to the client.
It will probably not handle uninitialized variables well,
however.  Make sure that things like the realm of the remote
host and the lifetime of the tickets have been properly
initialized before calling 
.IR rkinit ().


.SH AUTHOR
Emanuel Jay Berkenbilt (MIT-Project Athena)