LoginLogoutNotification.html [plain text]
<!-- #bbinclude "header.template"
#PAGETITLE#="Kerberos Login and Logout Plugin API"
#BASEHREF#=""
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<BASE HREF="http://web.mit.edu/macdev/KfM/KerberosFramework/KerberosLogin/Documentation/LoginLogoutNotification.html">
<META NAME="keywords" CONTENT="#KEYWORDS#">
<META NAME="description" CONTENT="#DESCRIPTION#">
<TITLE>Kerberos Login and Logout Plugin API</TITLE>
<STYLE TYPE="text/css">
@import url(../../../Common/Documentation/templates/site.css);
</STYLE>
</HEAD>
<BODY>
<DIV ID="menu">
<IMG SRC="../../../Common/Documentation/graphics/Kerberos.jpg" ALT="Kerberos for Macintosh Logo">
<HR>
<P><A HREF="../../../Common/Documentation/index.html">Home</A></P>
<P><A HREF="http://web.mit.edu/kerberos/">MIT Kerberos</A></P>
<P><A HREF="http://web.mit.edu/ist/">MIT IS&T</A></P>
<HR>
<P><A HREF="../../../Common/Documentation/news.html">News</A></P>
<P><A HREF="../../../Common/Documentation/documentation.html">Documentation</A></P>
<P><A HREF="../../../Common/Documentation/developer.html">Developer Resources</A></P>
<P><A HREF="../../../Common/Documentation/license.html">License</A></P>
<HR>
<P><A HREF="../../../Common/Documentation/download.html">Download</A></P>
<P><A HREF="../../../Common/Documentation/support.html">Support</A></P>
<P><A HREF="../../../Common/Documentation/contact.html">Contact Us</A></P>
</DIV>
<DIV ID="body">
<!-- end bbinclude -->
<!-- #bbinclude "icon.template" #ICON#="../../../Common/Documentation/graphics/ThreeHeadsAndKey.gif"
#TEXT#="<H2>Kerberos Login and Logout Plugin API</H2>" -->
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0>
<TR VALIGN=middle>
<TD ALIGN=center> <IMG CLASS=icon SRC="../../../Common/Documentation/graphics/ThreeHeadsAndKey.gif" ALT="An icon image (description text to the right)" WIDTH=32 HEIGHT=32> </TD>
<TD ALIGN=left> <H2>Kerberos Login and Logout Plugin API</H2> </TD>
</TR>
</TABLE>
<!-- end bbinclude -->
<P CLASS=small><I>This documentation applies to Mac OS X 10.2 and later.</I></P>
<H3><A NAME="Purpose"></A>Purpose of login and logout plugins</H3>
<P>Login and logout plugins are called whenever a user logs in or logs out. They can be used, for example, to communicate with other authentication systems which require
Kerberos tickets, or to automatically mount network volumes which require Kerberos authentication.</P>
<P>Login and logout plugins are invoked by the Kerberos Login API whenever any of the login and logout functions in the Kerberos Login API is called.</P>
<HR>
<H3><A NAME="Configuration"></A>Configuration of login and logout plugins</H3>
<P>In order to activate a login and logout plugin, the <CODE>libdefaults</CODE> section in the <code>edu.mit.Kerberos</code> file has to include a <CODE>login_logout_notification</CODE> line:</P>
<PRE><CODE>
[libdefaults]
...
login_logout_notification = "PluginName"
</CODE></PRE>
<P>On that line, <CODE>PluginName,</CODE> should be a unique string describing the plugin. The string must not be longer than 127 characters, and must end in "<code>.loginLogout</code>".</P>
<P>The plugin file itself has to be located in the directory <CODE>/Library/Kerberos Plug-Ins/</CODE> (note space and hyphen) - you may have to create this directory if it doesn't already exist.
<HR>
<H3><A NAME="Format"></A>Format of login and logout plugins</H3>
<P>A login and logout plugin imust be a Mach-O bundle with a name ending in "<CODE>.loginLogout</CODE>".</P>
<P>The plugin must export three functions, which are detailed in the next section.</P>
<P>The plugin can contain any other code, data, or resources, but be mindful that it can be executed by arbitrary applications, and therefore should be careful not to affect the application's resources or resource handling.</P>
<HR>
<H3><A NAME="Functions"></A>Functions exported by a login/logout plugin</H3>
<P>All three of these functions must be exported by every login/logout plugin. All functions use C linkage and standard Mach-O calling conventions.</P>
<P>The functions and related type declarations are specified in the <CODE>/System/Library/Frameworks/Kerberos.framework/Headers/KLLoginLogoutNotification.h</CODE> header file.</P>
<H3>KerberosLoginNotification_InitializePlugin</H3>
<PRE><CODE>
OSErr KerberosLoginNotification_InitializePlugin (
KLN_APIVersion inAPIVersion);
</CODE></PRE>
<P>This function is called by the Kerberos Login API when the plugin is loaded. The function must return <CODE>noErr</CODE> only if the plugin understands the API version passed in <CODE>inAPIVersion</CODE>; otherwise, it should return <CODE>paramErr</CODE>.</P>
<P>If this function returns anything but <CODE>noErr</CODE>, the other functions will not be called.</P>
<P>For example, a plugin which only understands the version 1 of the API (which is the current version), would do this:<P>
<PRE><CODE>
KLStatus KerberosLoginNotification_InitializePlugin (
KLPT_APIVersion inAPIVersion)
{
if (inAPIVersion == kKLN_APIVersion1) {
return noErr;
} else {
return paramErr;
}
}
</CODE></PRE>
<H3>KerberosLoginNotification_Login</H3>
<PRE><CODE>
KLStatus KerberosLoginNotification_Login (
KLN_LoginType inLoginType,
const char* inCredentialsCache);
</CODE></PRE>
<P>This function is called when a user is logging in. When the plugin is called, the ticket-granting tickets for the user have already been acquired and stored in a credentials cache.</P>
<P>On input, <CODE>inLoginType</CODE> is either <CODE>kKLN_DialogLogin</CODE> or <CODE>kKLN_PasswordLogin</CODE>. If it is <CODE>kKLN_DialogLogin</CODE>, the plugin is running in a context where it is safe to display user interface. If it is <CODE>kKLN_PasswordLogin</CODE>, then the plugin is running in a context where it is impossible to display user interface (for example, a faceless background application), and must not attempt to do so.</P>
<P>On input, <CODE>inCredentialsCache</CODE> points to a C string which is the name of the credentials cache in which the ticket granting tickets for the user being logged in have been stored. The plugin can open this credentials cache with the <A HREF="../../CredentialsCache/Documentation/index.html">Credentials Cache API</A> function <CODE>cc_context_open_ccache()</CODE> and use the tickets to acquire additional Kerberos tickets.</P>
<P>If the plugin wants to abort the login process, it must return an error other than <CODE>noErr</CODE>. The Kerberos Login library will then abort the login process, destroy any tickets that may have been acquired, and display an error dialog to the user, using the plugin's errors to convert the error returned to a string.</P>
<P>If the plugin returns <CODE>noErr</CODE>, the Kerberos Login library will proceed with login.</P>
<P>For example, the following code displays a confirmation dialog to the user when the plugin can display a dialog, and posts a notification if it can't display a dialog. This plugin demonstrates the use of the CredentialsCache API to get information about the user being logged in:
<PRE><CODE>
KLStatus KerberosLoginNotification_Login (
KLN_LoginType inLoginType,
const char* inCredentialsCache)
{
switch (inLoginType) {
case kKLN_DialogLogin:
AlertStdAlertParamRec alertParam;
alertParam.movable = false;
alertParam.helpButton = false;
alertParam.filterProc = nil;
alertParam.defaultText = "\pLogin";
alertParam.cancelText = "\pCancel";
alertParam.otherText = nil;
alertParam.defaultButton = kAlertStdAlertOKButton;
alertParam.cancelButton = kAlertStdAlertCancelButton;
alertParam.position = kWindowAlertPositionParentWindow;
SInt16 item;
OSErr err = StandardAlert (kAlertNoteAlert,
"\pAre you sure you want to login?", "\pMake sure noone is looking over your shoulder.",
&alertParam, &item);
if ((err == noErr) && (item == kAlertStdAlertOKButton)) {
return noErr;
} else {
return 22221;
}
case kKLN_PasswordLogin:
static NMRec notification;
static Str255 principal;
notification.qType = nmType;
notification.nmStr = principal;
notification.nmResp = (NMUPP) -1;
cc_context_t ccContext = nil;
cc_ccache_t ccache = nil;
cc_string_t ccPrincipal = nil;
cc_int32 ccErr = cc_initialize (&ccContext, ccapi_version_3, nil, nil);
if (ccErr == ccNoError) {
ccErr = cc_context_open_ccache (ccContext, inCredentialsCache, &ccache);
}
if (ccErr == ccNoError) {
ccErr = cc_ccache_get_principal (ccache, cc_credentials_v4, &ccPrincipal);
}
if (ccErr == ccNoError) {
CopyCStringToPascal (ccPrincipal -> data, principal);
NMInstall (¬ification);
}
if (ccPrincipal != nil) {
cc_string_release (ccPrincipal);
}
if (ccache != nil) {
cc_ccache_release (ccache);
}
if (ccContext != nil) {
cc_context_release (ccContext);
}
}
return noErr;
}
</CODE></PRE>
<H3>KerberosLoginNotification_Logout</H3>
<PRE><CODE>
void KerberosLoginNotification_Logout (
const char* inCredentialsCache);
</CODE></PRE>
<P>This function is called by the Kerberos Login API whenever a user is logging out. The plugin can perform and logout-time cleanup necessary, such as unmounting server volumes. This function must not attempt to display user interface, because it can be called from contexts in which that is not permitted, such as faceless background applications.</P>
<P>On input, <CODE>inCredentialsCache</CODE> points to a C string which is the name of the credentials cache in which the tickets for the userlogging out have been stored. The plugin can open this credentials cache with the <A HREF="../../CredentialsCache/Documentation/index.html">Credentials Cache API</A> function <CODE>cc_context_open_ccache()</CODE> and use the tickets; the plugin doesn't need to destroy any tickets, as they will be destroyed soon after the plugin returns.</P>
<P>If the plugin performs some cleanup on logout, it should be prepared to handle the case where no cleanup is necessary. For example, if the plugin cancels login, as in the above example, then the Kerberos Login library destroys the cache containing the new ticket granting ticket. In the process of destroying that cache, plugin's logout procedure is called, but since the login procedure aborted, the cleanup might not be necessary.</P>
<P>The following code demonstrates posting a notification from the logout procedure, and using the CredentialsCache API to determine the principal of the user being logged out.</P>
<PRE><CODE>
void KerberosLoginNotification_Logout (
const char* inCredentialsCache)
{
static NMRec notification;
static Str255 principal;
notification.qType = nmType;
notification.nmStr = principal;
notification.nmResp = (NMUPP) -1;
cc_context_t ccContext = nil;
cc_ccache_t ccache = nil;
cc_string_t ccPrincipal = nil;
cc_int32 ccErr = cc_initialize (&ccContext, ccapi_version_4, nil, nil);
if (ccErr == ccNoError) {
ccErr = cc_context_open_ccache (ccContext, inCredentialsCache, &ccache);
}
if (ccErr == ccNoError) {
ccErr = cc_ccache_get_principal (ccache, cc_credentials_v4, &ccPrincipal);
}
if (ccErr == ccNoError) {
CopyCStringToPascal (ccPrincipal -> data, principal);
NMInstall (¬ification);
}
if (ccPrincipal != nil) {
cc_string_release (ccPrincipal);
}
if (ccache != nil) {
cc_ccache_release (ccache);
}
if (ccContext != nil) {
cc_context_release (ccContext);
}
}
</CODE></PRE>
<HR>
<H3><A NAME="Errors"></A>Error handling in login and logout plugins</H3>
<P><CODE>KerberosLoginNotification_Login()</CODE> is allowed to return private error codes. This error code will be propagated into the Kerberos Login API, which in turn calls <CODE>KLGetErrorString()</CODE> to translate the error into a message for the user. The private error codes must not conflict with any existing Mac OS error codes.<P>
<P>In order to allow the Kerberos Login API to translate the plugin's error codes into user messages, the plugin should register its errors with the <A HREF="../../KerberosErrors/Documentation/index.html">KerberosErrors API</A>. After that, errors returned by the plugin will be mapped to the strings in the plugin's error table.</P>
<P><!-- #bbinclude "footer.template" -->
</DIV>
<DIV ID="footer">
<P>
Copyright 2005 Massachusetts Institute of Technology.<BR>
Last updated on $Date: 2005/05/04 18:24:28 $ <BR>
Last modified by $Author: lxs $
</P>
</DIV>
<!-- Begin MIT-use only web reporting counter -->
<IMG SRC="http://counter.mit.edu/tally" WIDTH=1 HEIGHT=1 ALT="">
<!-- End MIT-use only web reporting counter -->
</BODY></HTML>
<!-- end bbinclude -->