\begindata{text, 268651928}
\textdsversion{12}
\template{default}
\majorheading{The New Auth Package}


This package consists of two important components: a ticket cache mananger 
(ktc) and a configuration file manager (afsconf).  They're both bundled into 
the same library for stupid historical reasons, and should be decoupled into 
separate libraries shortly.


\heading{Kerberos Ticket Cache}


The Kerberos ticket cache manager provides a programmer's interface to a cache 
of Kerberos tickets.  Eventually it will be smart enough to convert a 
ticket-granting ticket into a desired ticket on its own, but for now, it only 
functions to remember the tickets provided to it.


The current user is a partially-undefined concept in here, and may vary from 
implementation to implementation.  One implementation might be two processes 
represent the same user if they have the same Unix UID field.  Another might 
be that two processes represent the same user if they have the same AFS PAG 
field.  The general idea should be that two processes should represent the 
same user if the same person typing at the computer has control over these 
various processes.


The interface to the ticket cache contains the following definitions in 
<afs/auth.h>:


\example{#define	MAXKTCTICKETLEN	    224

#define	MAXKTCNAMELEN	    64


struct ktc_encryptionKey \{

    char data[8];

\};


struct ktc_token \{

    long startTime;

    long endTime;

    struct ktc_encryptionKey sessionKey;

    short kvno;

    int ticketLen;

    char ticket[MAXKTCTICKETLEN];

\};


struct ktc_principal \{

    char name[MAXKTCNAMELEN];

    char instance[MAXKTCNAMELEN];

    char cell[MAXKTCNAMELEN];

\};


#define	KTC_ERROR	1	/* an unexpected error was encountered */

#define	KTC_TOOBIG	2	/* a buffer was too small for the response */

#define	KTC_INVAL	3	/* an invalid argument was passed in */

#define	KTC_NOENT	4	/* no such entry */}



A ktc_principal structure represents a principal in the Kerberos 
authentication system; this is how authenticated individuals are represented. 
 The ktc_token structure represents the authentication information associated 
with a principal.  Finally, the ktc_encryptionKey structure represents the 
standard encryption key used by our authentication system.


The procedures listed below make up the Kerberos ticket cache interface.


\bold{ktc_SetToken} (aserver, atoken, aclient)

struct ktc_principal *aserver, *aclient;

struct ktc_token *atoken;


This procedure sets the token associated with the current user when 
referencing the server specified by \italic{aserver} to be \italic{atoken}. 
 The parameter \italic{aclient} is optional, and if present, describes the 
identity the user will be authenticated as when using this ticket.  This 
function returns 0 if no error occurs, otherwise it returns an error from the 
list above.


\bold{ktc_GetToken}(aserver, atoken, atokenLen, aclient)

struct ktc_principal *aserver, *aclient;

int atokenLen;

struct ktc_token *atoken;


This procedure retrieves the token associated with the service aserver for 
this user.  It stores the token in the space provided by atoken, while 
atokenLen gives the size of this space (to allow for the possibility of 
increasing the maximum token size in the future).  The aclient parameter is 
optional (it should be null if not specified), and provides a buffer into 
which the ticket cache manager should provide the principal's identity 
corresponding to the ticket.  This function returns 0 if no error occurs, 
otherwise it returns an error from the list above.


\bold{ktc_ForgetToken}(aserver)

struct ktc_principal *aserver;


This procedure discards all tickets for the specified server and the current 
user from the ticket cache.  This function returns 0 if no error occurs, 
otherwise it returns an error from the list above.


\bold{ktc_ForgetAllTokens}()


This procedure discards all tickets for all servers held by the current user 
from the ticket cache.  The function returns 0 if no error occurs, otherwise 
it returns an error from the list above.


\bold{ktc_ListToken}(aprevIndex, aindex, aserver)

int aprevIndex, *aindex;

struct ktc_principal *aserver;


This function enumerate the services associated with all of the tickets held 
by the current user.  To begin, one calls ktc_ListToken with aprevIndex being 
0, and aindex pointing to a long integer.  The structure pointed to by aserver 
will be set to the name of the first service associated with this user.  In 
succeeding calls, one provides the preceding call's returned value of *aindex 
as the next calls value for aprevIndex.  A return value of KTC_NOENT indicates 
that no further tickets exist in the ticket cache for this user.


\heading{Configuration Manager}


The configuration manager parses those configuration files typically found in 
the directory /usr/vice/etc on AFS clients.  It provides an interface by which 
a caller can provide a cell name and a service name, and obtain a set of port 
address at which the service can be obtained for the specified cell.  The 
ports are located via the file /etc/services (on Unix), but also have the 
defaults given below, to ease installation at sites where the default port 
addresses are available.  The addresses are returned as Unix 
\italic{sockaddr_in} structures.  One can obtain the set of hosts without 
specifying a service, by providing a null pointer for the service name.


To use this package, you first open the configuration directory, obtaining a 
handle of type \italic{struct afsconf_dir}.  You can then obtain the local 
cell name via \italic{afsconf_GetLocalCell}, as well as getting detailed 
information about a particular cell (given its name) via 
\italic{afsconf_GetCellInfo}.  You can obtain the name of all of the cells in 
the database by calling \italic{afsconf_CellApply}.  Finally, when you are 
finished looking up your configuration information, you simply close the 
configuration handle with \italic{afsconf_Close}.


struct afsconf_dir *\bold{afsconf_Open}(adir)

char *adir;


This function takes one parameter, the name of the directory containing the 
configuration files "ThisCell" and "CellServDB".


\bold{afsconf_CellApply}(adir, aproc, arock)

struct afsconf_dir *adir;

int (*aproc)();

char *arock;


This function calls the procedure provided (in \italic{aproc}) on each cell in 
the system.  The first parameter to \italic{aproc} is of type \italic{struct 
afsconf_cell}, and describes the particular cell.  The second parameter is 
\italic{arock}, and is simply passed through directly for the programmer's 
convenience.  The third parameter is \italic{adir}, again passed through for 
the programmer's convenience.


If the function specified by \italic{aproc} returns a non-zero return value, 
\italic{afsconf_CellApply} terminates immediately and returns the non-zero 
return code.


\bold{afsconf_GetCellInfo}(adir, acellName, aservice, acellInfo)

struct afsconf_dir *adir;

char *aservice;

char *acellName;

struct afsconf_cell *acellInfo;


This call takes a cell name (a null means use the local cell), and a service 
name, and returns the set of servers that provide that service in the 
specified cell in the structure pointed at by *\italic{acellInfo}.


\bold{afsconf_GetLocalCell}(adir, aname, alen)

register struct afsconf_dir *adir;

char *aname;

long *alen;


This function returns the local cell name in the buffer pointed to by 
\italic{aname}.  The \italic{alen} parameter gives the size of the buffer; an 
error will be returned if the cell name does not fit within this buffer.


\bold{afsconf_Close}(adir)

struct afsconf_dir *adir;


This function discards the storage associated with an open cofiguration 
directory.  Do not use \italic{adir} after calling this function.


\bold{afsconf_GetKeys}(adir, akeys)

struct afsconf_dir *adir;

struct afsconf_keys *akeys;


This function returns all of the file system keys stored in the file KeyFile.


\bold{afsconf_ResetKeys}(adir)

struct afsconf_dir *adir;


This function discards all of the keys store in the file KeyFile in the 
specified configuration directory.


\bold{afsconf_AddKey}(adir, akvno, akey)

struct afsconf_dir *adir;

long akvno;

char akey[8];


This function adds the specified key version / key pair to the KeyFile 
associated with the specified configuration directory.


\bold{afsconf_DeleteKey}(adir, akvno)

struct afsconf_dir *adir;

long akvno;


This function removes the key with the specified key version number from the 
KeyFile associated with the specified configuration directory.  It returns 
AFSCONF_NOTFOUND if no key with the specified key version number can be 
located.


\bold{afsconf_SuperUser}(adir, acall)

struct afsconf_dir *adir;

struct rx_call *acall;


This function returns true if the user authenticated on the specified RX call 
is listed in the super-user file in the specified configuration directory, and 
false otherwise.  If the "noauth" flag (described below) is set on the 
configuration directory, then this function always returns TRUE.


\bold{afsconf_AddUser}(adir, aname)

struct afsconf_dir *adir;

char *aname;


This function adds the user named \typewriter{aname} to the list of 
super-users for the file system.


\bold{afsconf_GetNthUser}(adir, an, abuffer, abufferLen)

struct afsconf_dir *adir;

long an;

char *abuffer;

long abufferLen;


This function returns the \typewriter{an}'th user name from the super-user 
list stored in the specified configuration directory.  It returns 0 on 
success, non-zero on failure.  To enumerate all of the super users in the 
system, one starts an at 0, and continues until the call fails.


\bold{afsconf_DeleteUser}(adir, auser)

struct afsconf_dir *adir;

register char *auser;


This function deletes the specified user from the list of super users in the 
configuration directory \italic{adir}.  It returns 0 even if the user wasn't 
found in the list, but returns non-zero if something went wrong writing out 
the updated configuration file.


\bold{afsconf_GetNoAuthFlag}(adir)

struct afsconf_dir *adir;


This function returns the \italic{noauth} flag in the configuration directory 
adir.  This flag, when set, forces all calls to \typewriter{afsconf_SuperUser} 
to return true, indicating that the calling user is a member of the super user 
set.


\bold{afsconf_SetNoAuthFlag}(adir, aflag)

struct afsconf_dir *adir;

int aflag;


This function sets the \italic{noauth} flag to \italic{aflag}.  This flag, 
when set, forces all calls to \typewriter{afsconf_SuperUser} to return true, 
indicating that the calling user is a member of the super user set.


The afsconf calls often return information concerning the servers in a 
particular cell, and when they do, they do so in an afsconf_cell structure. 
 These structures look like this:


\example{struct afsconf_cell \{

    char name[MAXCELLCHARS];    /*Cell name*/

    short numServers;           /*Num active servers for the cell*/

    struct sockaddr_in hostAddr[MAXHOSTSPERCELL]; /* server addresses */

    char hostName[MAXHOSTSPERCELL][MAXHOSTCHARS]; /* server names */

\};


/* default configuration dirs for clients and servers */

#define	AFSCONF_CLIENTNAME  "/usr/vice/etc"

#define	AFSCONF_SERVERNAME  "/usr/afs/etc"}


When afsconf calls return information concerning keys, they do so in the 
following afsconf_keys structure, containing a set of afsconf_key 
sub-structures:


\example{struct afsconf_key \{

    long kvno;		/* key version number */

    char key[8];		/* the key itself */

\};


struct afsconf_keys \{

    long nkeys;		/* number of valid slots */

    struct afsconf_key key[AFSCONF_MAXKEYS];

\};}


Below are the default port asisgnments used by the afsconf module.  These 
ports may be overridden by entries in the Unix /etc/services file.


\example{"afs",		7000,

"afscb",		7001,

"afsprot",		7002,

"afsvldb",		7003,

"afskauth",		7004,

"afsvol",		7005,

"afserror",		7006,

"afsnanny",		7007,}


That's all, folks.

\enddata{text,268651928}