.\" .\" $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 #include .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)