168 lines
4.1 KiB
Groff
168 lines
4.1 KiB
Groff
.\"
|
|
.\" $Header: /local/cvsfiles/kerberos/src/appl/rkinit/man/rkinit.3,v 1.1 1991/12/03 23:21:29 eichin Exp $
|
|
.\" $Source: /local/cvsfiles/kerberos/src/appl/rkinit/man/rkinit.3,v $
|
|
.\" $Author: eichin $
|
|
.\"
|
|
.\"
|
|
.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)
|