RKINIT(3)

NAME
rkinit, rkinit_errmsg

SYNOPSIS
#include <rkinit.h>
#include <rkinit_err.h>

int rkinit(host, r_krealm, info, timeout)
  char *host;
  char *r_krealm;
  rkinit_info *info;
  int timeout;

char *rkinit_errmsg(string)
  char *string;

DESCRIPTION
This library contains the calls necessary to interface with the rkinit system of remote ticket establishment. See rkinit(1) for more information on rkinit

rkinit.h is the header file that contains information that all clients will need to use.

rkinit_err.h is the com_err error table header file. See com_err(3) for more information about com_err.

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 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.
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;
aname is the name part of the kerberos principal for which tickets are being requested. inst is the instance part. realm is the realm part. sname is the service name of the key that will appear in the remote initial ticket (for example, "krbtgt"). sname is the service instance. username is the name of the local user on the remote host who will own the ticket file. 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 TKT_FILE as defined in krb.h. lifetime is the lifetime of the tickets in the usual five minute intervals. It is possible with this routine, as with krb_get_in_tkt(3) to request tickets with zero lifetime. 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. 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 rkinit_errmsg() with NULL as the argument returns the current rkinit error message. Although the rkinit library uses com_err(3) for error handling, the error messages returned by com_err() may not be specific enough. A client could report the error message returned by rkinit as follows:
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);
}

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

DIAGNOSTICS
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 rkinit().

AUTHOR
Emanuel Jay Berkenbilt (MIT-Project Athena)