$#KKClient DLL API Reference

ChangePassword
DeleteAllSessions
GetTicketForService
GetTicketGrantingTicket
GetUserName
ListTickets
SetKrbdllMode
SetUserName
TgtExist
SetTicketLifeTime

About KClient.dll

$#KGetTicketForService()

BOOL CALLBACK GetTicketForService (lpszService,  lpTicket,  lpdwLen)
LPSTR  lpszService		/*  name of service		*/
LPSTR  lpTicket 		/*  address of ticket buffer	*/
LPDWORD  lpdwLen		/*  address ticket length		*/

The GetTicketForService function will acquire a ticket for the specified service, copy the service ticket into the buffer specified by lpTicket, and copy the length of the ticket into lpdwLen.

Parameter	Description
lpszService 	Points to a null-terminated string specifying the service for which to acquire a ticket.

lpTicket	Points to a buffer into which the ticket will be copied.

lpdwLen	Points to a DWORD into which the length of the ticket will be copied.

Returns
TRUE if the ticket is successfully acquired.  FALSE otherwise.

Comments
If a ticket granting ticket is not already present, one will be acquired.  If a ticket granting ticket is already present, but its credentials have expired, a new ticket granting ticket will be acquired.   If GetTicketForService has to acquire a ticket granting ticket, the user will be prompted for her password via a dialog that resides in KClient.dll.  

Note that the calling application must issue a WSAStartup() call to the Windows Sockets stack before the first call to either GetTicketForService,  GetTicketGrantingTicket, or ChangePassword. The WSAStartup() call need only be made once.  A corresponding WSACleanup() should be issued by the calling application before exiting.  

$#KDeleteAllSessions()

BOOL CALLBACK DeleteAllSessions (void)

The DeleteAllSessions function will destroy all existing tickets.

Returns
TRUE if successful.  FALSE otherwise. 

$#KSetUserName()

BOOL CALLBACK SetUserName (lpszUserName)
LPSTR  lpszUserName	/* user name		*/

Parameter		Description
lpszUserName		Points to a null-terminated string specifying the user name (NetID) of the user.

The SetUserName function specifies the user name (NetID) that will be used during authentication.  Any existing tickets will be destroyed when SetUserName is called.   This use of this call is optional, as KClient.dll can set the user name on-the-fly from the password dialog box.

Returns
TRUE if successful.  FALSE otherwise.

$#KListTickets()

BOOL CALLBACK ListTickets (hWndListBox)
HWND hWndListBox		/* handle of listbox	*/

The ListTickets function displays a list of all acquired tickets by placing them into a listbox.  The listbox must have already been created by the calling application.

Parameter	Description
hWndListBox	Handle of listbox created by calling application.

Returns
TRUE if successful.  FALSE otherwise.

Comments
You will probably want to use the LBS_USETABSTOPS style (which expands tab characters in strings) when creating the listbox in your calling application, as the information about each ticket contains tabs.   ListTickets is uses the Windows Kerberos call lsh_klist(), but has the advantage of not requiring the calling application to build with with Kerberos header files or libraries.

$#KSetKrbdllMode()

void CALLBACK SetKrbdllMode (bMode)
BOOL  bMode		/*  krbdll.dll debug mode	*/

The SetKrbdllMode function will toggle the "debug mode" of the MIT Windows Kerberos DLL.

Parameter	Description
bMode	TRUE if debug mode is enabled.  FALSE if disabled.

Returns
No return value.

Comments
The MIT Windows Kerberos DLL is capable of generating a significant number of informational messages (via MessageBoxes) when executing some Kerberos calls.  Enabling or disabling this "debug mode" on the fly can assist in troubleshooting.

$#KAbout KClient.dll

KClient.dll is a Windows Dynamic Link Library that provides a subset of the Cornell developed Macintosh KClient Kerberos API, and can be used by Mandarin Windows clients for easy Kerberos authentication.   KClient.dll translates "KClient Kerberos API calls" into "stock Kerberos calls."  KClient.dll makes kerberizing an application easy, negating the need to build with any Kerberos header files or libraries.  Service tickets,  ticket granting tickets, expired credentials, and username/password dialogs are managed by KClient.dll.

$#KGetTicketGrantingTicket()

BOOL CALLBACK GetTicketGrantingTicket (void)

The GetTicketGrantingTicket function will acquire a Ticket Granting Ticket from the Kerberos server.  This function does not need to be called from a kerberized application, since GetTicketForService will automatically call GetTicketGrantingTicket when needed.  This function is provided as a quick diagnostic test for KView, and is documented here for completeness. 

Returns
TRUE if successful.  FALSE otherwise. 

Comments
Note that the calling application must issue a WSAStartup() call to the Windows Sockets stack before the first call to either GetTicketGrantingTicket,  GetTicketForService, or ChangePassword. The WSAStartup() call need only be made once.  A corresponding WSACleanup() should issued by the calling application before exiting.  

$#KSetTicketLifeTime

void CALLBACK SetTicketLifeTime (iLifeTime)
int  iLifeTime		/*  lifetime of ticket	*/

The SetTicketLifeTime function will set the length of time it takes for a ticket to expire (the lifetime of the ticket).

Parameter	Description
int		lifetime of ticket

Returns
No return value.

Comments
The "time units" of iLifeTime are a bit unusual, as they are not seconds, minutes, or hours; but  instead use the MIT Kerberos convention of 5 minutes as a " time unit".  That is, an iLifeTime value of 96 would 96*5, or 480 minutes (8 hours).  SetTicketLifeTime will not change the lifetime of currently acquired tickets, but does specify the lifetime to be used on new tickets.

$#KTgtExist

BOOL CALLBACK TgtExist (void)

The TgtExist function will check to see if there is a live (non-expired) Ticket Granting Ticket in the ticket store.  

Returns
TRUE if a live (non-expired) Ticket Granting Ticket exists.  FALSE otherwise.

$#KGetUserName

BOOL CALLBACK GetUserName (lpszUserName)
LPSTR  lpszUserName	/* user name		*/

Parameter		Description
lpszUserName	Address of buffer into which the user name (NetID) will be copied.

The GetUserName function copies the user name (NetID) into the buffer specified by lpszUserName.

Returns
TRUE if successful.  FALSE if no user name has yet been specified.

$#KChangePassword

BOOL CALLBACK ChangePassword (void)

The ChangePassword function changes a user's password on the Kerberos server.  This function uses a dialog box within KClient, instead of the Leash Change Password dialog found in krbv4win.dll, and invokes lsh_changepwd() in krbv4win.dll to actually change the password.  The new password must be at least 6 characters long, contain at least 1 digit, and contain at least 1 letter. 

Returns
TRUE if successful.  FALSE otherwise.

Comments
Note that the calling application must issue a WSAStartup() call to the Windows Sockets stack before the first call to either ChangePassword, GetTicketForService,  or GetTicketGrantingTicket. The WSAStartup() call need only be made once.  A corresponding WSACleanup() should be issued by the calling application before exiting.