Macintosh Development |
[Home]
[About Us]
[People]
[Information Systems]
[Kerberos for Macintosh]
[Applications]
[Miscellaneous Documentation]
|
KerberosLoginLib API |
Table of Contents
- KLApplicationOptions
- KLPrincipal
- KLLoginOptions
- KLStatus
- KLKerberosVersion
- KLDefaultLoginOption
- KLLoginMode
- KLDialogIdentifier
- KLIndex
- KLLifetime
- KLTime
- KLSize
- KLRefCon
- KLBoolean
- Kerberos Version Constants
- Dialog Identifier Constants
- Login Dialog Item Numbers
- Change Password Dialog Item Numbers
- Option Identifier Constants
- Realm Index Constants
- High-Level Login Functions
- Low-Level Login Functions
- Low-Level Change Password Functions
- Application Defined Functions
- Application Configuration Functions
- Library Configuration Functions
- Realms Configuration Functions
- KLPrincipal Functions
- KLLoginOptions Functions
- Miscellaneous Functions
- Internal Use Functions
Types
KLApplicationOptions
typedef struct { KLEventFilterUPP eventFilter; KLRefCon eventFilterAppData; SInt16 realmsPopupMenuID; SInt16 loginModeMenuID; } KLApplicationOptions;
KLPrincipal
struct KLPrincipal;
KLPrincipal
is an opaque structure. Use theKLPrincipal
manipulation functions to get information about the principal contained in the structure.KLPrincipal
should be capable of retaining and reproducing both Kerberos v4 and v5 representations of the fully qualified principal.nil
is an acceptable value for aKLPrincipal
.KLLoginOptions
struct
KLLoginOptions;
KLLoginOptions is an opaque structure. Use the KLLoginOptions manipulation functions to get information about the options contained in the structure. KLLoginOptions is used to determine ticket options for logging (eg: ticket lifetime).
KLStatus
The Kerberos Login Library error code type (an integer type).
KLKerberosVersion
A Kerberos version. One of KLEKerberosVersion (an integer type).
KLDefaultLoginOption
One of KLEDefaultLoginOptions, used to set default login options (an integer type). See KLGetDefaultLoginOptions or KLSetDefaultLoginOptions.
KLLoginMode
One of KLELoginMode (an integer type). Used to specifiy if the login dialog will come up in basic or advanced mode.
KLDialogIdentifier
One of KLEDialogIdentifiers (an integer type). Used to tell the error dialog which dialog the error is for.
KLIndex
An index into the realm list (an integer type).
KLLifetime
The ticket lifetime in seconds (an integer type).
KLTime
Unix time (seconds since 1/1/1970 00:00:00 GMT) (an integer type).
KLSize
The size of a buffer (for KLGetDefaultLoginOptions or KLSetDefaultLoginOptions) or the size of the realm list (returned by CountKerberosRealms). An integer type.
KLRefCon
The application refCon which is returned to your application event filter (an integer type). Pass in a pointer to your globals.
KLBoolean
A Boolean value (an integer type). 0 is false, everything else is true.
Constants
Kerberos Version Constants
These are used by the KLPrincipal and cache manipulation functions to specify protocol versions of Kerberos for credentials and principals. The Kerberos version is either represented as a bitfield of the versions (ie: kerberosVersion_V4 & kerberosVersion_V5 is represents both versions) or as one of two magic values. kerberosVersion_Any refers to one or more Kerberos version and kerberosVersion_All refers to all Kerberos versions which are valid for the current realm (ie: in a version 4-only realm, kerberosVersion_All would be equivalent to kerberosVersion_V4).
enum KLEKerberosVersion { kerberosVersion_Any = 0, kerberosVersion_V4 = 1, kerberosVersion_V5 = 2, kerberosVersion_All = 0xFFFFFFFF };Dialog Identifier Constants
These are used by Kerberos Login Event Filter functions to identify which dialog they were called from.
enum KLELoginDialogIdentifers {loginLibrary_LoginDialog,
loginLibrary_ChangePasswordDialog };
Login Dialog Item Numbers
These constants are used by Kerberos Login Event Filter functions to identify dialog items in the Login Dialog if necessary.
enum KLELoginDialogItems { loginDialog_Username, loginDialog_Password, loginDialog_Realm, loginDialog_TicketLifetime, loginDialog_ForwardableTicket };
Change Password Dialog Item Numbers
These constants are used by Kerberos Login Event Filter functions to identify dialog items in the Change Password Dialog if necessary.
enum KLEChangePasswordDialogItems { changePasswordDialog_OldPassword, changePasswordDialog_NewPassword, changePasswordDialog_VerifyPassword };
Option Identifier Constants
These constants are the configuration option flags used by
KLGetLoginOption()
andKLSetLoginOption()
. For further descriptions of them, see Library Configuration Functions.enum KLEDefaultLoginOptions { /* Dialog state options */ loginOption_AdvancedLoginMode = 'adv ', loginOption_ExpandedDialog = 'expn', loginOption_ShowTicketLifetime = 'life', loginOption_ShowForwardableTicket = 'forw', /* Initial values and ranges */ loginOption_RememberPrincipal = 'prin', loginOption_RememberExtras = 'extr', loginOption_MinimalTicketLifetime = '-lif', loginOption_MaximalTicketLifetime = '+lif', loginOption_DefaultTicketLifetime = '0lif', loginOption_LongTicketLifetimeDisplay = 'hms ', loginOption_DefaultForwardableTicket = '0fwd' };
Realm Index Constants
These constants are the configuration option flags used by
KLInsertKerberosRealm()
enum KLERealmListIndexes { realmList_Start = 0, realmList_End = 0xFFFF };
Login Library Behavior
Principal specified No principal specified
Valid tickets exist for it No valid tickets exist for it Valid tickets exist in system default cache No valid tickets in system default cache
KLAcquireTickets()
(primarily for applications that need service tickets)
- No user interface displayed
- No new tickets obtained
- System default cache unchanged
- Name of credential cache corresponding to principal is returned
- Displays user interface (with non-editable principal)
- New tickets obtained
- Credential cache corresponding to principal is made system default if no other tickets exist in cache collection
- Name of new credential cache corresponding to principal is returned
- No user interface displayed
- No new tickets obtained
- System default cache unchanged
- Name of system default cache is returned
- Displays user interface(with editable principal)
- New tickets obtained
- Credential cache corresponding to principal is made system default
- Name of new credential cache corresponding to principal is returned
KLAcquireNewTickets()
(primarily for management applications)
- Displays user interface (with non-editable principal)
- New tickets obtained, replacing existing tickets
- System default cache unchanged
- Name of new credential cache corresponding to principal is returned
- Displays user interface (with non-editable principal)
- New tickets obtained
- Credential cache corresponding to principal is made system default if no other tickets exist in cache collection
- Name of new credential cache corresponding to principal is returned
- Displays user interface(with editable principal)
- New tickets obtained - if they are for a principal already in the cache, they replace the existing tickets
- Name of new credential cache corresponding to principal is returned
- Displays user interface(with editable principal)
- New tickets obtained - if they are for a principal already in the cache, they replace the existing tickets
- Credential cache corresponding to principal is made system default
- Name of new credential cache corresponding to principal is returned
KLAcquireTicketsWithPassword()
behaves identically toKLAcquireTickets()
with "principal specified," but the user interface is never displayed under any conditions.
KLAcquireNewTicketsWithPassword()
behaves identically toKLAcquireNewTickets()
with "principal specified," but the user interface is never displayed under any conditions.
KLAcquireTickets...()
does not set the system default cache when principal is non-nil because it's called when applications want service tickets, and we don't want the system default changing constantly. It will set the system default if there are no existing credential caches.
KLAcquireNewTickets...()
does not set the system default cache because we want to allow explicit renews that don't change the defaults.So if an explicit renew wants to change the defaults, it must call
KLAcquireNewTickets...()
and a default cache changing function.
__SecretGetTicketsForOnlyOneKerberosVersion()
will not set the system defaults because we want to be careful where the new tickets go. The calling function is responsible for making the combined cache the correct default. [this shouldn't be here but I didn't know where else to put it]Originally the Login Library API was going to change the "application default cache" as well, however, Kerberos 5 doesn't have the concept of application default caches -- only context default caches. The only way the Login API could have changed these is if the caller passed in the current Kerberos v5 context, and we decided it would be bad to have the Login API depend on Kerberos 5 structures. So instead a credentials cache name is returned by functions that attempt to acquire tickets, and it is up to the caller to change the application or context defaults using that information.
Terminology Notes
The multiple uses of the word "cache" may be confusing. We have tried to distinguish between them by using different phrases. They are:
"cache collection" - the conglomeration of all credential caches
"credentials cache" - a single set of credentials for a specific principal and Kerberos version
"system default cache" - a credentials cache that an application/service/context will use by default after the first time it is launched/created (in Kerberos v4, the application default cache will be set to the system default cache when the application is first launched; in v5 a context's default cache will be set the system default cache when the context is first created)
High-Level Login Functions
KLAcquireTickets
KLStatus KLAcquireTickets ( KLPrincipal inPrincipal, KLPrincipal *outPrincipal char **outCredCacheName);
Requires:
The
KLAcquireTickets()
function requires the following:
- the function is called at a time when the AppleEvent Manager is available, i.e. system task time (as defined by Technote 1104) from an AppleEvent-aware application
Effects:
The
KLAcquireTickets()
function attempts to insure that a valid ticket-granting ticket is available in the cache collection, prompting the user to obtain a new one if necessary. Its main purpose is to be used by client applications that want to make sure some tickets exist before using a Kerberos service.The name of the principal for which tickets are obtained (or found) is returned in
outPrincipal
.The name of the cache into which tickets are placed (or which is found if no new tickets are obtained) is returned in
outCredCacheName
so that the caller can change the application/context default cache if desired. This returned name can be used in Credential Cache API, Kerberos 4, or Kerberos 5 calls.If
inPrincipal
is notnil
(a principal is specified),
- and no valid tickets for that principal are in the cache collection,
KLAcquireTickets()
presents the user interface as specified byKLLoginDialogBegin()
for obtaining user information and then attempts to acquire tickets with that information. If successful and no tickets at all were previously in the cache, the cache containing those tickets is made the system default cache;- or, valid tickets for that principal are available in the cache collection, no user interface is displayed.
If
inPrincipal
isnil
(no principal is specified),
- and no valid tickets for any user are in the system default cache,
KLAcquireTickets()
presents the user interface as specified byKLLoginDialogBegin()
for obtaining user information and then attempts to acquire tickets with that information. If successful, the credentials cache corresponding to that principal is made the system default cache.- or, valid tickets are available in the system default cache, no user interface is displayed and the system default cache name is returned.
KLAcquireTickets()
does not necessarily present the user interface. If you always want to bring up the user interface, useKLAcquireNewTickets()
orKLLoginDialogBegin()
, etc.
KLAcquireTickets()
will take care of presenting error dialogs to the user as necessary (for problems such as unknown principal, incorrect password, etc.). You do not need to callKLHandleError()
after this function.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, either both v4 and v5 ticket-granting tickets will be available in the cache collection (and the credentials cache containing them will possibly be set as the system default cache, as specified above) upon return, or
KLAcquireTickets()
will return an error code.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, and valid tickets for only one version but not the other are available in the cache collection,
KLAcquireTickets()
will treat this as the same as the no valid tickets case -- new tickets will be obtained for both Kerberos versions, replacing the current "orphan" ones.If only one of Kerberos v4 and Kerberos v5 is available for the realm of the principal, either a ticket-granting ticket for the appropriate version will be available in the cache collection (and the credentials cache containing them will be possibly set as the system default cache) as specified above upon return, or
KLAcquireTickets()
will return an error code.
Results:
If
KLAcquireTickets()
returnsklNoErr
, then:
- tickets are available in the cache collection;
- if
outPrincipal
is notnil
, a newKLPrincipal
is returned in*outPrincipal
. The returnedKLPrincipal
should be freed using theKLDisposePrincipal()
function. IfoutPrincipal
isnil
, nothing is returned.- if
outCredCacheName
is notnil
, a C string containing one of the following is returned in*outCredCacheName
: the name of the credentials cache corresponding to the principal; or if no principal was specified and no new tickets were necessary, it is the name of the system default credentials cache. The returned string should be freed using theKLDisposeString()
function. IfoutCredCacheName
isnil
, nothing is returned.Otherwise,
outPrincipal
andoutCredCacheName
are unchanged andKLAcquireTickets()
returns one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klUserCanceledErr
The user cancelled the dialog.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
klDialogAlreadyExistsErr
The login dialog is already up.
klNotInForegroundErr
The dialog is not in the foreground (Metrowerks debugger at fault?)
klNoAppearanceErr
Appearance Manager is unavailable.
klFatalDialogErr
The dialog failed to load because the resources are corrupt or missing.
KLAcquireNewTickets
KLStatus KLAcquireNewTickets ( KLPrincipal inPrincipal, KLPrincipal *outPrincipal char **outCredCacheName);
Requires:
The
KLAcquireNewTickets()
function requires the following:
- the function is called at a time when the AppleEvent Manager is available, i.e. system task time (as defined by Technote 1104) from an AppleEvent-aware application
Effects:
The
KLAcquireNewTickets()
function always attempts to get a new valid ticket-granting ticket, either for a new principal or replacing (renewing) the existing tickets for a principal already in the cache collection. The user interface for obtaining user information as specified byKLLoginDialogBegin()
is always displayed. The main purpose of this function is to be used by administrative applications that want to provide a way to login new principals or renew existing tickets.The name of the principal for which tickets are obtained is returned in
outPrincipal
.The name of the cache into which tickets are placed is returned in
outCredCacheName
so that the caller can change the application/context default cache if desired. This returned name can be used in Credential Cache API, Kerberos 4, or Kerberos 5 calls.If
inPrincipal
is notnil
(a principal is specified),
- and no valid tickets for that principal are in the cache collection,
KLAcquireNewTickets()
presents the user interface and then attempts to acquire tickets with that information. If successful, a valid ticket-granting ticket for that principal is placed in the cache collection. If successful and there are no other tickets in the cache collection, the credentials cache corresponding to that principal is made the system default cache.- or, valid tickets for that principal are available in the cache collection,
KLAcquireNewTickets()
presents the user interface and then attempts to acquire tickets with that information. If successful, the principal's existing tickets are replaced by a new ticket-granting ticket (possibly with a different lifetime and different ticket properties). No change is made to the system default cache. If unsuccessful, the principal's existing tickets are unchanged.If
inPrincipal
isnil
(no principal is specified),
KLAcquireNewTickets()
presents the user interface and attempts to acquire tickets with that information. If successful, a valid ticket-granting ticket for that principal is placed in the cache collection. If the user enters a principal with tickets already in the cache collection, that principal's existing tickets are replaced by a new ticket-granting ticket (possibly with a different lifetime and different ticket properties) by a successful login attempt, or left alone if an unsuccessful attempt is made. If successful and there are no other tickets in the cache collection, the credentials cache corresponding to that principal is made the system default cache. If unsuccessful, no changes to the cache collection are made.
KLAcquireNewTickets()
will take care of presenting error dialogs to the user as necessary (for problems such as unknown principal, incorrect password, etc.). You do not need to callKLHandleError()
after this function.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal,
KLAcquireNewTickets()
will either return an error code, or both new v4 and new v5 ticket-granting tickets will be available in the cache collection and possibly set the credentials cache containing them to be the system default cache (as specified above) upon return ofKLAcquireNewTickets()
.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, and valid tickets for only one version but not the other are available in the cache collection,
KLAcquireNewTickets()
will treat this as the same as the no valid tickets case -- new tickets will be obtained for both Kerberos versions, replacing the current "orphan" ones.If only one of Kerberos v4 and Kerberos v5 is available for the realm of the principal,
KLAcquireNewTickets()
will either return an error code, or an appropriate new ticket-granting ticket will be available in the credentials cache and possibly set the credentials cache containing them to be the system default cache (as specified above) upon return ofKLAcquireNewTickets()
.Results:
If
KLAcquireNewTickets()
returnsklNoErr
, then:
- new tickets are available in the cache collection;
- if
outPrincipal
is notnil
, a newKLPrincipal
is returned in*outPrincipal
. The returnedKLPrincipal
should be freed using theKLDisposePrincipal()
function. IfoutPrincipal
isnil
, nothing is returned.- if
outCredCacheName
is notnil
, a C string containing the the name of the credentials cache into which new tickets were placed is returned in*outCredCacheName
. The returned string should be freed using theKLDisposeString()
function. IfoutCredCacheName
isnil
, nothing is returned.Otherwise,
outPrincipal
andoutCredCacheName
are unchanged andKLAcquireNewTickets()
returns one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klUserCanceledErr
The user cancelled the dialog.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
klDialogAlreadyExistsErr
The login dialog is already up.
klNotInForegroundErr
The dialog is not in the foreground (Metrowerks debugger at fault?)
klNoAppearanceErr
Appearance Manager is unavailable.
klFatalDialogErr
The dialog failed to load because the resources are corrupt or missing.
KLDestroyTickets
KLStatus KLDestroyTickets ( KLPrincipal inPrincipal);
Requires:
The
KLDestroyTickets()
function requires the following:
- the function is called from system task time (as defined by Technote 1104)
Effects:
KLDestroyTickets()
removes all tickets, both for v4 and v5, for the principal specified in theinPrincipal
structure from the cache collection. If inPrincipal is nil (no principal is specified),KLDestroyTickets()
removes all tickets in the system default cache.If the credentials cache removed was the system default cache,
KLDestroyTickets()
sets the system default cache to another credentials cache (exactly which credentials cache is implementation dependent; in the MIT Kerberos for Macintosh implementation, the defaults are switched as per the Credentials Cache API).Results:
If
KLDestroyTickets()
returnsklNoErr
, then credentials for the specified principal (or system default cache) were located in the cache collection and successfully removed.Otherwise, the cache collection is unchanged, and
KLDestroyTickets()
returns one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klPrincipalDoesNotExistErr
The KLPrincipal passed in does not correspond to any cache in the cache collection.
klSystemDefaultDoesNotExistErr
There is no system default cache (the cache collection is empty).
KLChangePassword
KLStatus KLChangePassword ( KLPrincipal inPrincipal);
Requires:
The
KLChangePassword()
function requires the following:
- the function is called at a time when the AppleEvent Manager is available, i.e. system task time (as defined by Technote 1104) from an AppleEvent-aware application
Effects:
The
KLChangePassword()
function attempts to change the password of the principal specified byinPrincipal
.
KLChangePassword()
creates and displays a movable modal Kerberos change password dialog with the user interface as specified byKLChangePasswordDialogBegin()
.
KLChangePassword()
will take care of presenting error dialogs to the user as necessary (for problems such as unknown principal, incorrect password, etc.). You do not need to callKLHandleError()
after this function.
KLChangePassword()
will either return an error code, or the principal's Kerberos password will have been changed.Results:
If
KLChangePassword()
returnsklNoErr
, then the principal's password has been changed.Otherwise,
KLChangePassword()
returns one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klUserCanceledErr
The user cancelled the dialog.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
klDialogAlreadyExistsErr
The password dialog is already up.
klNotInForegroundErr
The application is not in the foreground (Metrowerks debugger at fault?)
klNoAppearanceErr
Appearance Manager is unavailable.
klFatalDialogErr
The dialog failed to load because the resources are corrupt or missing.
Low-Level Login Functions
KLAcquireTicketsWithPassword
KLStatus KLAcquireTicketsWithPassword ( KLPrincipal inPrincipal, KLLoginOptions inLoginOptions, const char *inPassword, char **outCredCacheName);
Requires:
The
KLAcquireTicketsWithPassword()
function requires the following:
inPassword
points to a null-terminated C string;- the function is called from system task time (as defined by Technote 1104)
Effects:
The
KLAcquireTicketsWithPassword()
function attempts to insure that the cache collection contains a valid ticket-granting ticket for the Kerberos principal specified byinPrincipal
.KLAcquireTicketsWithPassword()
never displays user interface and can be called at system task time from background applications unless your site uses hardware preauth. If your site uses hardware preauth,KLAcquireTicketsWithPassword()
will display a prompter dialog (this may be fixed in a future release... send us mail requesting that this be fixed to escalate this issue).The name of the cache into which tickets are placed is returned in
outCredCacheName
so that the caller can change the application/context default cache if desired. This returned name can be used in Credential Cache API, Kerberos 4, or Kerberos 5 calls. The returned string must be freed by KLDisposeString(). If you pass in nil to this argument, the credentials cache name will not be allocated for you.If no valid ticket-granting ticket for the specified principal is available in the cache collection, then
KLAcquireTicketsWithPassword()
will use the password ininPassword
to attempt to acquire the tickets with the properties specified byinLoginOptions
. If inLoginOptions is nil, the defaults (as specified byKLSetDefaultLoginOption
()) are used. If successful, and if no tickets at all were previously in the cache collection, the credentials cache corresponding to the principal is made the system default cache. If not successful, the cache collection is unchanged.If a valid ticket-granting ticket for the specified principal already exists in the cache collection, no action is taken beyond setting
outCredCacheName
.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, either both v4 and v5 ticket-granting tickets will be available in the cache collection (and possibly made the system default cache, as above) upon return, or
KLAcquireTicketsWithPassword()
will return an error code.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, and valid tickets for only one version but not the other are available in the cache collection,
KLAcquireTicketsWithPassword()
will treat this as the same as the no valid tickets case -- new tickets will be obtained for both Kerberos versions, replacing the current "orphan" ones.If only one of Kerberos v4 and Kerberos v5 is available for the realm of the principal, either a ticket-granting ticket for the appropriate Kerberos version will be available in the cache collection (and possibly made the system default cache, as above) upon return, or
KLAcquireTicketsWithPassword()
will return an error code.Results:
If
KLAcquireTicketsWithPassword()
returnsklNoErr
, then:
- tickets for the desired principal are available in the cache collection;
- if
outCredCacheName
is notnil
, a C string containing one of the following is returned in*outCredCacheName
: the name of the credentials cache into which new tickets were placed; or if no new tickets were necessary because credentials for the principal were already in the cache collection, it is the name of the credentials cache corresponding to the principal; or if no principal was specified and no new tickets were necessary, it is the name of the system default credentials cache. The returned string should be freed using theKLDisposeString()
function. IfoutCredCacheName
isnil
, nothing is returned.Otherwise,
KLAcquireTicketsWithPassword()
returns one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klUserCanceledErr
The user cancelled the dialog (only with hardware preauth).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klRealmDoesNotExistErr
The specified realm does not exist.
klDialogAlreadyExistsErr
The prompter dialog is already up (only with hardware preauth).
klNotInForegroundErr
The dialog is not in the foreground (Metrowerks debugger at fault?) (only with hardware preauth)
klNoAppearanceErr
Appearance Manager is unavailable (only with hardware preauth).
klFatalDialogErr
Dialog failed to load because the resources are corrupt or missing (only with hardware preauth).
Any Kerberos5Lib error
Use KLHandleError () or KLGetErrorString () to report these errors to the user.
Any Kerberos4Lib error
Use KLHandleError () or KLGetErrorString () to report these errors to the user.
KLAcquireNewTicketsWithPassword
KLStatus KLAcquireNewTicketsWithPassword ( KLPrincipal inPrincipal, KLLoginOptions inLoginOptions, const char *inPassword, char **outCredCacheName);
Requires:
The
KLAcquireNewTicketsWithPassword()
function requires the following:
inPassword
points to a nul-terminated C string;- the function is called from system task time (as defined by Technote 1104)
Effects:
The
KLAcquireNewTicketsWithPassword()
function attempts to get a new valid ticket-granting ticket, either for a new principal or replacing (renewing) the existing tickets for a principal already in the cache collection.KLAcquireNewTicketsWithPassword()
never displays user interface and can be called at system task time from background applications unless your site uses hardware preauth. If your site uses hardware preauth,KLAcquireNewTicketsWithPassword()
will display a prompter dialog (this may be fixed in a future release... send us mail requesting that this be fixed to escalate this issue).The name of the cache into which tickets are placed is returned in
outCredCacheName
so that the caller can change the application/context default cache if desired. This returned name can be used in Credential Cache API, Kerberos 4, or Kerberos 5 calls. The returned string must be freed by KLDisposeString (). If you pass in nil to this argument, the credentials cache name will not be allocated for you.If no valid ticket-granting ticket for the specified principal is available in the cache collection, then
KLAcquireNewTicketsWithPassword()
will use the password ininPassword
to attempt to acquire the tickets with the properties specified byinLoginOptions
.If no valid ticket-granting ticket for the specified principal is available in the cache collection, then
KLAcquireNewTicketsWithPassword()
will use the password ininPassword
to attempt to acquire the tickets with the properties specified byinLoginOptions
. If inLoginOptions is nil, the defaults (as specified byKLSetDefaultLoginOption
()) are used. If successful, and if no tickets at all were previously in the cache collection, the credentials cache corresponding to the principal is made the system default cache. If not successful, the cache collection is unchanged.
KLAcquireNewTicketsWithPassword()
never changes the system default cache.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, either both new v4 and new v5 ticket-granting tickets will be available in the credentials cache upon return, or
KLAcquireNewTicketsWithPassword()
will return an error code.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, and valid tickets for only one version but not the other are available in the cache collection,
KLAcquireNewTicketsWithPassword()
will treat this as the same as the no valid tickets case -- new tickets will be obtained for both Kerberos versions, replacing the current "orphan" ones.If only one of Kerberos v4 and Kerberos v5 is available for the realm of the principal, either a ticket-granting ticket for the appropriate Kerberos version will be available in the cache collection upon return, or
KLAcquireNewTicketsWithPassword()
will return an error code.Results:
If
KLAcquireNewTicketsWithPassword()
returnsklNoErr
, then:
- new tickets for the desired principal are available in the cache collection.
- if
outCredCacheName
is notnil
, a C string containing the the name of the credentials cache into which new tickets were placed is returned in*outCredCacheName
. The returned string should be freed using theKLDisposeString()
function. IfoutCredCacheName
isnil
, nothing is returned.Otherwise,
KLAcquireNewTicketsWithPassword()
returns one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klUserCanceledErr
The user cancelled the dialog (only with hardware preauth).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klRealmDoesNotExistErr
The specified realm does not exist.
klDialogAlreadyExistsErr
The prompter dialog is already up (only with hardware preauth).
klNotInForegroundErr
The dialog is not in the foreground (Metrowerks debugger at fault?) (only with hardware preauth)
klNoAppearanceErr
Appearance Manager is unavailable (only with hardware preauth).
klFatalDialogErr
Dialog failed to load because the resources are corrupt or missing (only with hardware preauth).
Any Kerberos5Lib error
Use KLHandleError () or KLGetErrorString () to report these errors to the user.
Any Kerberos4Lib error
Use KLHandleError () or KLGetErrorString () to report these errors to the user.
KLLastChangedTime
KLStatus KLLastChangedTime ( KLTime *outLastChangedTime);
Requires:
The
KLLastChangedTime ()
function requires the following:
- Kerberos Login Library API 2.1 (part of Kerberos for Macintosh 3.5) or later
- the function is called from system task time (as defined by Technote 1104)
Effects:
KLLastChangedTime()
returns the last time the state or validity of the cache collection changed in seconds since GMT midnight January 1, 1970.
KLLastChangedTime()
should be used by applications which wish to frequently callKLCacheHasValidTickets()
,KLTicketStartTime()
orKLExpirationTime()
. The time returned byKLLastChangedTime()
will change if and only if the validity, start or expiration times of the cache collection changes. Your application can check this time to determine when you should call one ofKLCacheHasValidTickets()
,KLTicketStartTime()
orKLExpirationTime()
.
KLCacheHasValidTickets()
,KLTicketStartTime()
andKLExpirationTime()
are O(n) where n is the number of caches in the cache collection. Calling them frequently may negatively impact the performance of your application.KLLastChangedTime()
is O(1), so your application can safely call it as often as every 1/60 of a second.If an error code is returned,
outLastChangedTime
is unchanged.Results:
If no errors occur,
klNoErr
is returned. Other possible errors are:
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
KLCacheHasValidTickets
KLStatus KLCacheHasValidTickets ( KLPrincipal inPrincipal, KLKerberosVersion inKerberosVersion, KLBoolean *outFoundValidTickets, KLPrincipal *outPrincipal, char **outCredCacheName);
Requires:
The
KLCacheHasValidTickets()
function requires the following:
- the function is called from system task time (as defined by Technote 1104)
outFoundValidTickets
is a valid pointer (otherwise klParameterErr is returned).Effects:
KLCacheHasValidTickets()
looks in the cache collection to see if it contains valid ticket-granting tickets.If
inPrincipal
is notnil
(a principal is specified),KLCacheHasValidTickets()
returns inoutFoundValidTickets
whether there are valid tickets of the version specified byinKerberosVersion
in the cache collection for that principal. If outPrincipal is not
nil
, the principal is returned in outPrincipal. IfoutCredCacheName
is notnil
, the name of the credentials cache corresponding to that principal is returned inoutCredCacheName
.If
inPrincipal
isnil
(no principal is specified),KLCacheHasValidTickets()
returns inoutFoundValidTickets
whether or not any valid tickets of the version specified byinKerberosVersion
are in the system default cache. If outPrincipal is notnil
, the principal of the system default credentials cache is returned in outPrincipal. IfoutCredCacheName
is notnil
, the name of the system default credentials cache is returned inoutCredCacheName
.If outPrincipal is nil, nothing is returned in it.
If
outCredCacheName
isnil
, nothing is returned in it.
inKerberosVersion
is kerberosVersion_All: If and only if valid tickets of all the versions of Kerberos supported by inPrincipal's realm (or the realm of the system default cache's principal if inPrincipal == nil) exist for inPrincipal, thenoutFoundValidTickets
is filled out astrue
.
inKerberosVersion
is kerberosVersion_Any: If and only if valid tickets of any version of Kerberos supported by inPrincipal's realm (or the realm of the system default cache's principal if inPrincipal == nil) exist for inPrincipal, thenoutFoundValidTickets
is filled out astrue
.
inKerberosVersion
is one or more specific versions of Kerberos 'OR'ed together as a bitfield: if and only if valid tickets of the specified version(s) of Kerberos exist for inPrincipal (the system default cache's principal if inPrincipal == nil), thenoutFoundValidTickets
is filled out astrue
.If no valid tickets are found of the version specified by
inKerberosVersion
(either no tickets for the principal exist, tickets do not exist for all the requested Kerberos versions, a ticket is expired, or a ticket is for an IP address different from the current one),outFoundValidTickets
is filled out asfalse
and one of klNoCredentialsErr, klCredentialsExpiredErr, or klCredentialsBadAddressErr is returned.
If an error code is returned, outPrincipal and
outCredCacheName
are unchanged. For compatibility,outFoundValidTickets
is set to false.Results:
If no errors while searching the cache collection occurs,
klNoErr
is returned. Other possible errors are:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klInvalidVersionErr
Invalid Kerberos version.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klPrincipalDoesNotExistErr
The KLPrincipal passed in does not correspond to any cache in the cache collection.
klSystemDefaultDoesNotExistErr
There is no system default cache (the cache collection is empty).
klCredentialsExpiredErr
The credentials for the specified KLPrincipal (or system default) are expired.
klCredentialsBadAddressErr
The credentials for the specified KLPrincipal (or system default) contain a different IP address from the current one.
klNoCredentialsErr
There are no credentials for the specified KLPrincipal (or no system default).
klRealmDoesNotExistErr
The specified realm does not exist.
KLTicketStartTime
KLStatus KLTicketStartTime ( KLPrincipal inPrincipal, KLKerberosVersion inKerberosVersion, KLTime *outStartTime);
Requires:
The
KLTicketStartTime()
function requires the following:
- Kerberos Login Library API 2.1 (part of Kerberos for Macintosh 3.5) or later
- the function is called from system task time (as defined by Technote 1104)
Effects:
KLTicketStartTime()
looks in the cache collection to return the maximum absolute start time of any valid ticket-granting tickets of the Kerberos version specified byinKerberosVersion
. If KLCacheHasValidTickets() would have returned false for the same inPrincipal andinKerberosVersion
,KLTicketStartTime
() returns klNoCredentialsErr or klCredentialsExpiredErr.If a principal is specified by
inPrincipal
,KLTicketStartTime()
returns the maximum absolute start time for that principal.If no is specified by
inPrincipal
,KLTicketStartTime()
returns the maximum absolute start time for the tickets in the system default cache (if one exists).If valid ticket-granting tickets exist,
outStartTime
is filled out with the absolute time the ticket-granting ticket first became valid in seconds since GMT midnight January 1, 1970.If tickets for multiple versions of Kerberos exist for the principal and
inKerberosVersion
is kerberosVersion_All or the aforementioned versions of Kerberos 'OR'ed together as a bitfield, the greater of the times for the two ticket-granting tickets is returned. IfinKerberosVersion
is kerberosVersion_Any, the minimum of the two expiration times is returned. Otherwise, the time for the specified version is returned.If an error occurs,
outStartTime
is unchanged.Results:
If no errors while searching the cache collection occurs,
klNoErr
is returned. Other possible errors are:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klInvalidVersionErr
Invalid Kerberos version.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klPrincipalDoesNotExistErr
The KLPrincipal passed in does not correspond to any cache in the cache collection.
klSystemDefaultDoesNotExistErr
There is no system default cache (the cache collection is empty).
klNoCredentialsErr
The credentials for the specified KLPrincipal and inKerberosVersion do not exist.
klCredentialsExpiredErr
The credentials for the specified KLPrincipal (or system default) are no longer valid.
klCredentialsBadAddressErr
The credentials for the specified KLPrincipal (or system default) contain a different IP address from the current one.
klRealmDoesNotExistErr
The specified realm does not exist.
KLTicketExpirationTime
KLStatus KLTicketExpirationTime ( KLPrincipal inPrincipal, KLKerberosVersion inKerberosVersion, KLTime *outExpirationTime);
Requires:
The
KLTicketExpirationTime()
function requires the following:
- the function is called from system task time (as defined by Technote 1104)
Effects:
KLTicketExpirationTime()
looks in the cache collection to return the minimum absolute expiration time of any valid ticket-granting tickets of the Kerberos version specified byinKerberosVersion
. If KLCacheHasValidTickets() would have returned false for the same inPrincipal andinKerberosVersion
, KLTicketExpirationTime() returns klNoCredentialsErr or klCredentialsExpiredErr.If a principal is specified by
inPrincipal
,KLTicketExpirationTime()
returns the minimum absolute expiration time for that principal.If no is specified by
inPrincipal
,KLTicketExpirationTime()
returns the minimum absolute expiration time for the tickets in the system default cache (if one exists).If valid ticket-granting tickets exist,
outExpirationTime
is filled out with the absolute time the ticket-granting ticket is valid until (as opposed to the relative length of time the ticket will remain valid) in seconds since GMT midnight January 1, 1970.If tickets for multiple versions of Kerberos exist for the principal and
inKerberosVersion
is kerberosVersion_All or the aforementioned versions of Kerberos 'OR'ed together as a bitfield, the minimum of the times for the two ticket-granting tickets is returned. IfinKerberosVersion
is kerberosVersion_Any, the maximum of the ticket times is returned. Otherwise, the time for the specified version is returned.If an error occurs,
outExpirationTime
is unchanged.Results:
If no errors while searching the cache collection occurs,
klNoErr
is returned. Other possible errors are:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klInvalidVersionErr
Invalid Kerberos version.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klPrincipalDoesNotExistErr
The KLPrincipal passed in does not correspond to any cache in the cache collection.
klSystemDefaultDoesNotExistErr
There is no system default cache (the cache collection is empty).
klNoCredentialsErr
The credentials for the specified KLPrincipal and inKerberosVersion do not exist.
klCredentialsExpiredErr
The credentials for the specified KLPrincipal (or system default) are no longer valid.
klCredentialsBadAddressErr
The credentials for the specified KLPrincipal (or system default) contain a different IP address from the current one.
klRealmDoesNotExistErr
The specified realm does not exist.
KLSetSystemDefaultCache
KLStatus KLSetSystemDefaultCache ( KLPrincipal inPrincipal);
Requires:
The
KLSetSystemDefaultCache()
function requires the following:
- the function is called from system task time (as defined by Technote 1104)
Effects:
KLSetSystemDefaultCache()
sets the system (global) default credentials cache to be the credentials cache which corresponds to the principal specified ininPrincipal
, that is, to be the credentials cache that an application/service/context will use by default after the first time it is launched/created (in Kerberos v4, the application default cache will be set to the system default cache when the application is first launched; in v5 a context's default cache will be set the system default cache when the context is first created).If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, the system default is set to the credentials cache corresponding to the specified principal for both v4 and v5.
If only one of Kerberos v4 and Kerberos v5 is available for the realm of the principal, the appropriate version's system default is set to the credentials cache corresponding to the specified principal.
Results:
If there is a credentials cache corresponding to the specified principal and that credentials cache is set successfully as the system default,
klNoErr
is returned. Other possible errors are:
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klPrincipalDoesNotExistErr
The KLPrincipal passed in does not correspond to any cache in the cache collection.
klRealmDoesNotExistErr
The specified realm does not exist.
KLHandleError
KLStatus KLHandleError ( KLStatus inError, KLDialogIdentifier inDialogIdentifier, KLBoolean inShowAlert);
Requires:
The
KLHandleError()
function requires that:
- it is called at System Task time (as defined by Technote 1104) from an AppleEvent-aware application
- it is called between calls to
KLLoginDialogBegin()
andKLLoginDialogEnd()
.Effects:
The
KLHandleError()
function handles errors that occur while attempting to acquire tickets or change passwords. After you callKLLoginDialogHandleEvents()
orKLChangePasswordDialogHandleEvents()
to process events in a dialog, you use the information from the dialog to acquire tickets or change password for the user. If an error occurs while you are acquiring the tickets or changing the password, you must callKLHandleError()
with an appropriate error code. This will ensure that the Login Library will behave correctly on subsequent calls -- for example, if the user typed an incorrect password, the password will be selected on the next call toKLLoginDialogHandleEvents()
orKLChangePasswordDialogHandleEvents()
.In general, you should call
KLHandleError()
withinShowAlert
set totrue
, in which case Login Library will display an appropriate error message to the user. However, if for some reason you need to provide different user feedback, you should passfalse
ininShowAlert
. In either case, you must callKLHandleError()
with an appropriate error code.
KLHandleError()
can distinguish which of the two dialogs it was called from by using theinDialogIdentifier
parameter (see the Dialog Identifier Constants above) .Valid input values for
inError
are any error code returned by any Login Library function. Usually you only want to pass the error codes from KLAcquire*TicketsWithPassword() and KLChangePasswordWithPasswords().Results:
KLHandleError()
returnsklNoErr
if no error occurs, or one of the following error codes:
klParameterErr
Invalid option passed into function (check your error code).
klMemFullErr
Out of memory.
KLGetErrorString
KLStatus KLGetErrorString ( KLStatus inError, char **outString);
Requires:
The
KLHandleError()
function requires that:
- inError be an error returned from a Kerberos Login Library function.
Effects:
The
KLGetErrorString ()
function takes a Kerberos Login Library error code and returns a C string containing a user-presentable message explaining the error. This is the same error message as would have been presented by KLHandleError (). You will need to dispose of the string with KLDisposeString () after you are through using it.Results:
KLGetErrorString()
returnsklNoErr
if no error occurs, or one of the following error codes:
klParameterErr
Invalid option passed into function (check your error code).
klMemFullErr
Out of memory.
KLCancelAllDialogs
KLStatus
KLCancelAllDialogs(void);
Effects:
The KLCancelAllDialogs
()
function cancels all the login library dialogs on the screen when the function is called. This function should be called from an application event handler when a quit AppleEvent comes in. Note that if a Kerberos operation is in progress, the dialogs will cancel when the operation completes.You should not expect the dialogs to be gone when KLCancelAllDialogs() returns to the caller. You should instead wait until KLAcquireTickets() or the relevant KClient call that popped up the dialog returns before calling ExitToShell().
Results:
KLCancelAllDialogs
()
returnsklNoErr
if no error occurs, or one of the following error codes:
klDialogDoesNotExist
No dialogs to cancel.
Low-Level Password Dialog Functions
KLChangePasswordWithPasswords
KLStatus KLChangePasswordWithPasswords ( KLPrincipal inPrincipal, const char *inOldPassword, const char *inNewPassword);
Requires:
The
KLChangePasswordWithPasswords()
function requires the following:
- the function is called from system task time (as defined by Technote 1104)
Effects:
The
KLChangePasswordWithPasswords()
function attempts to change the Kerberos password for the principal specified byinPrincipal
.KLChangePasswordWithPasswords()
never displays user interface and can be called at system task time from background applications.Results:
If
KLChangePasswordWithPasswords()
returnsklNoErr
, then the password for the desired principal has been changed.Otherwise, the principal's passwords unchanged and
KLChangePasswordWithPasswords()
returns one of the following error codes:
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klBadPasswordErr
Password incorrect or nil.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klPasswordChangeFailedErr
Change password operation failed.
Application-Defined Functions
Kerberos Login Event Filter
KLBoolean MyKerberosLoginEventFilter ( EventRecord *inEvent, KLRefCon inAppData);
Requires:
- Mac OS 8 or 9 (deprecated on Mac OS X)
A Kerberos Login event filter function is guaranteed that
inEvent
points to a valid event record, possibly just a null eventinAppData
is the application data, as set by the last call toKLSetApplicationOptions()
.- it is called at System Task time (as defined by Technote 1104) from an AppleEvent-aware application
Effects:
A Kerberos Login event filter function is allowed to do anything that makes sense for the application to do, except to make modifications to the Login or Change Password dialog. It can cancel the dialogs by calling KLCancelAllDialogs () if it receives a quit event. The event filter function must handle suspend, resume and update events.
A Kerberos Login event filter function should not assume anything about the current resource file; if it needs to use resources, it must set the current resource file and restore it before returning.
A Kerberos Login event filter function must not add or remove menus or popup menus; failure to comply will result in Login library menu enabling/disabling code getting confused, and potentially leaving system menus (such as the Applications menu) incorrectly disabled.
Results:
Returns
true
if the event was handled,false
otherwise.KerberosLoginIdleCallback
void KerberosLoginIdleCallback ( KLRefCon inAppData);
Requires:
- Mac OS 10.1 or greater (KfM 4.0 or greater)
- Mach-O object formation (installing a PEF KerberosLoginIdleCallback will cause a crash)
A KerberosLoginIdleCallback function is guaranteed that
inAppData
is the application data, as set by the last call toKLSetIdleCallback()
.Effects:
A KerberosLoginIdleCallback function is allowed to do anything that makes sense for the application to do. Most importantly, it can call
WaitNextEvent()
or receive Carbon/Cocoa events. It can cancel the dialogs by calling KLCancelAllDialogs () if it receives a quit event.A KerberosLoginIdleCallback function should not assume anything about the current resource file; if it needs to use resources, it must set the current resource file and restore it before returning.
A KerberosLoginIdleCallback function should not block on resources in the callback. This will hurt performance and possibly have confusing side effects. For example, verify that there is an event in the queue before calling
WaitNextEvent()
.A Kerberos Login event filter function must not manipulate the controlling terminal (ie: stdin, stdout and stderr). The Kerberos Login library may be in the middle of reading a password from the controlling terminal.
Application Configuration Functions
KLSetApplicationOptions
KLStatus KLSetApplicationOptions ( const KLApplicationOptions* inAppOptions);
Requires:
- Mac OS 8 or 9 (deprecated on Mac OS X)
- the event filter function passed in
inAppOptions -> eventFilter
is a valid Universal Procedure Pointer to a valid Kerberos Login function (ornil
).Effects:
The
KLSetApplicationOptions()
function sets the options used byKLAcquireTickets()
,KLAcquireNewTickets()
,KLLoginDialogBegin()
, andKLLoginDialogHandleEvents()
for the current process.The meanings of the fields are
eventFilter
is used as the event filter wheneverKLLoginDialogHandleEvents()
is called from the calling application (either explicitly or implicitly)eventFilterAppData
is a value passed to the subsequent calls to the event filter; it is not interpreted by the Login Library and its use is entirely up to the applicationrealmsPopupMenuID
is the menu ID for the realms pop-up menu, if 0 is passed in, a default ID will be usedloginModeMenuID
is the menu ID for the login mode pop-up menu, if 0 is passed in, a default ID will be usedResults:
KLSetApplicationOptions()
returnsklNoErr
if no error occurs, or one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
KLGetApplicationOptions
KLStatus KLGetApplicationOptions ( KLApplicationOptions *outAppOptions);
Requires:
- Mac OS 8 or 9 (deprecated on Mac OS X)
outAppOptions
points to a validKLApplicationOptions
parameter.Effects:
The
KLGetApplicationOptions()
function gets the Login Library application options for the current process.See
KLSetApplicationOptions()
for a description of the meanings of each field.Results:
KLGetApplicationOptions()
returnsklNoErr
if no error occurs, or one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
KLSetIdleCallback
KLStatus KLSetIdleCallback ( const KLIdleCallback inIdleCallback, const KLRefCon inIdleRefCon);
Requires:
- Mac OS X 10.1 or later (KfM 4.0 or later)
- the idling function passed in
inIdleCallback
is a Mach-O function pointer to a valid KerberosLoginIdleCallback function (orNULL
).Effects:
The
KLSetIdleCallback()
function sets the idling callback which is called while your application waits for the Login dialog. If you wish to cancel the login dialogs from your application, you should callKLCancelAllDialogs()
from the callback function.The meanings of the fields are
inIdleCallback
is used as the idle function whenever your application is waiting for KerberosLoginServer (the application which presents the login dialog. Pass in NULL to remove the idle callback.inIdleRefCon
is a value passed to the subsequent calls to the idle callback; it is not interpreted by the Login Library and its use is entirely up to the applicationResults:
KLSetIdleCallback()
returnsklNoErr
if no error occurs, or one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
KLGetIdleCallback
KLStatus KLGetIdleCallback ( KLIdleCallback* outIdleCallback, KLRefCon* outIdleRefCon);
Requires:
- Mac OS X 10.1 or later (KfM 4.0 or later)
outIdleCallback
andoutIdleRefCon
are pointers to valid data or NULL.Effects:
The
KLGetIdleCallback()
function returns the idling callback which will be called while your application waits for the Login dialog.The meanings of the fields are
outIdleCallback
is used as the idle function whenever your application is waiting for KerberosLoginServer (the application which presents the login dialog. A value of NULL indicates no idle callback is installed.outIdleRefCon
is a value passed to the subsequent calls to the idle callback; it is not interpreted by the Login Library and its use is entirely up to the applicationResults:
KLGetIdleCallback()
returnsklNoErr
if no error occurs, or one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
Library Configuration Functions
Library configuration consists of a set of options and their values; all options are global. The options and their types and allowed values are:
loginOption_LoginName
Type: char *
This option determines what name is used in the username field in the login dialog by default. Pass in a C string with ioBufferSize set to the length of the string (not including the NUL at the end). When getting this option you will need to NUL-terminate the buffer after calling KLGetDefaultLoginOption.
loginOption_LoginInstance
Type: char *
This option determines what instance is used in the instance field in the login dialog by default. Pass in a C string with ioBufferSize set to the length of the string (not including the NUL at the end). When getting this option you will need to NUL-terminate the buffer after calling KLGetDefaultLoginOption.
loginOption_AdvancedLoginMode
Type: KLLoginMode
Range: 1, 2
This option determines whether the login dialog popup group box initial value is "Basic" (loginMode_Basic) or "Advanced" (loginMode_Advanced).
loginOption_ShowTicketLifetime
Type: KLBoolean
Range: 0, 1
This option determines whether the ticket lifetime slider is shown.
loginOption_ShowForwardableTicket
Type: KLBoolean
Range: 0, 1
This option determines whether the forwardable ticket checkbox is shown.
loginOption_ShowProxiableTicket
Type: KLBoolean
Range: 0, 1
This option determines whether the proxiable ticket checkbox is shown.
loginOption_RememberPrincipal
Type: KLBoolean
Range: 0, 1
This option determines whether principal (username, instance, and selected realm) will be remembered between successful logins. The remembered principal can be overridden by an application by passing the username, etc. toKLLoginDialogBegin()
,KLAcquireTickets()
, orKLAcquireNewTickets()
loginOption_RememberExtras
Type: KLBoolean
Range: 0, 1
This option determines whether "extra" settings, such as the values of the Forwardable Tickets checkbox and Ticket Lifetime slider, will be remembered between successful logins.
loginOption_MinimalTicketLifetime
Type: KLLifetime
Range: 0 .. 2^32 - 1
This option determines the left end of the ticket lifetime slider range in seconds.
loginOption_MaximalTicketLifetime
Type: KLLifetime
Range: 0 .. 2^32 - 1
This option determines the right end of the ticket lifetime slider range in seconds.
loginOption_DefaultTicketLifetime
Type: KLLifetime
Range: minimal ticket lifetime .. maximal ticket lifetime
This option determines the default value of the ticket lifetime slider in seconds.
loginOption_LongTicketLifetimeDisplay
Type: KLBoolean
Range: 0, 1
This option determines whether the ticket lifetime caption displays time in long format (xx hours, yy minutes, zz seconds) or short format (xx:yy:zz). Value of 0 means short lifetime display, value of 1 means long lifetime display
loginOption_DefaultForwardableTicket
Type: KLBoolean
Range: 0, 1
This option determines the default value of the forwardable ticket checkbox.
loginOption_DefaultProxiableTicket
Type: KLBoolean
Range: 0, 1
This option determines the default value of the proxiable ticket checkbox.
KLGetDefaultLoginOption
KLStatus KLGetLoginOption ( KLDefaultLoginOption inOption, void *ioBuffer, KLSize *ioBufferSize);
Requires:
ioBuffer
points to a buffer with at least*ioBufferSize
bytes of storage, orioBuffer
isnil
.Effects:
Returns the size and the value of the specified library option.
If
ioBuffer
is notnil
,inOption
is a valid option, andioBufferSize
is sufficient to hold the value of the option (1 byte for KLBoolean values, 4 bytes for KLLifetime or KLLoginMode values), the value is put inioBuffer
and its actual size is returned inioBufferSize
.If
ioBuffer
isnil
andinOption
is a valid option, the size of the option is put returned inioBufferSize
.If
inOption
is not a valid option, orioBufferSize
is too small,ioBuffer
andioBufferSize
are unchanged.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klPreferencesWriteErr
The preferences file is locked.
klBufferTooSmallErr
The buffer passed in is too small to hold the login option.
klInvalidOptionErr
The requested login option does not exist.
KLSetDefaultLoginOption
KLStatus KLSetLoginOption ( KLDefaultLoginOption inOption, void *inBuffer, KLSize inBufferSize);
Requires:
ioBuffer
points to a buffer with at leastinBufferSize
bytes of storageEffects:
If
inOption
is a valid option,inBufferSize
is the correct size forinOption
, and value ininBuffer
is in the valid range ofinOption
, then value ofinOption
is set to the value ininBuffer
. Otherwise, no option values are changed.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klPreferencesWriteErr
The preferences file is locked.
klBufferTooSmallErr
The buffer passed in is too small to hold the login option.
klBufferTooLargeErr
The buffer passed in is too large to refer to this login option.
klInvalidOptionErr
The requested login option does not exist.
klBadOptionValueErr
The login option you have specified is invalid.
Realms Configuration Functions
The functions below manipulate the list of realms displayed by the Login Library in pop-up menu of the login dialog. This list may be a subset of the realms listed in the Kerberos configuration file. The "default realm" is the realm that is selected in the pop-up menu by default.
KLFindKerberosRealmByName
KLStatus
KLFindKerberosRealmByName( char *inRealmName, KLIndex *outIndex );
Requires:
inRealmName
is a null-terminated C stringEffects:
Finds the realm with the name inRealmName in the realm list and returns the index.
Realm indices are 0-based.
Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
KLGetKerberosRealm
KLStatus KLGetKerberosRealm ( KLIndex inIndex, char **outRealmName);
Effects:
Reads the name of the realm with index
inIndex
in the realm list and returns it as a C string inoutRealmName
. The returned string should be freed using theKLDisposeString()
function.Realm indices are 0-based.
Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
KLSetKerberosRealm
KLStatus KLSetKerberosRealm ( KLIndex inIndex, const char *inRealmName);
Requires:
inRealmName
is a nul-terminated C stringEffects:
Sets the name of the realm with index
inIndex
in the realm list to the name specified ininRealmName
. Realm indices are 0-based.Note: If another realm with the name
inRealmName
is already in the list,KLSetKerberosRealm
removes the old entry before setting the entry atinIndex
. Because the old entry may be beforeinIndex
in the list, the realm name may actually be placed at a different index (one less thaninIndex
). As a result, you should either make sure you are setting only one realm of each name, or you should not useinIndex
after callingKLSetKerberosRealm
.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klPreferencesWriteErr
The preferences file is locked.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
KLRemoveKerberosRealm
KLStatus KLRemoveKerberosRealm ( KLIndex inIndex);
Effects:
Removes the realm specified by the index
inIndex
from the realm list. Realm indices are 0-based.Note: Kerberos Login Library does not support removing the Kerberos default realm (ie: the
default_realm
in thelib_defaults
section of the Kerberos Preferences). If you attempt to remove the Kerberos default realm from the realm list, it will be added back to the beginning of the realm list. If you want to remove this realm, please change the Kerberos default realm.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klPreferencesWriteErr
The preferences file is locked.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
KLInsertKerberosRealm
KLStatus KLInsertKerberosRealm ( KLIndex inInsertBeforeIndex, const char *inRealmName);
Requires:
inRealmName
is a nul-terminated C stringEffects:
Inserts a realm with the name specified in
inRealmName
before indexinInsertBeforeIndex
, or at the end ifinInsertBeforeIndex
is equal toKLCountKerberosRealms()
. Realm indices are 0-based.Note: If another realm with the name
inRealmName
is already in the list,KLInsertKerberosRealm
moves the realm before indexinInsertBeforeIndex
. Because the old realm may be before this index in the list, the new realm may actually be placed at a different index (two less thaninInsertBeforeIndex
). As a result, you should either make sure you are adding only one realm of each name, or you should not useinInsertBeforeIndex
after callingKLInsertKerberosRealm
.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klPreferencesWriteErr
The preferences file is locked.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
KLRemoveAllKerberosRealms
KLStatus KLRemoveAllKerberosRealms (void);
Effects:
Clears the entire realm list except for the Kerberos configuration default realm.
Note: Kerberos Login Library does not support removing the Kerberos default realm (ie: the
default_realm
in thelib_defaults
section of the Kerberos Preferences). If you attempt to remove the Kerberos default realm from the realm list, it will be added to the beginning of the realm list. If you want to remove this realm, please change the Kerberos default realm.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klPreferencesWriteErr
The preferences file is locked.
KLCountKerberosRealms
KLSize KLCountKerberosRealms (void);
Effects:
Returns the total number of realms in the list.
KLGetKerberosDefaultRealm
KLStatus KLGetKerberosDefaultRealm( KLIndex *outIndex);
Effects:
Returns the index of the default realm in the login dialog box in
outIndex
. If there are no realms in the list, function returns aklEmptyRealmListErr
error andoutIndex
is unchanged.Realm indices are 0-based.
Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
KLGetKerberosDefaultRealmByName
KLStatus KLGetKerberosDefaultRealm ( char **outRealmName);
Effects:
Returns the name of the default realm in the login dialog box as a C string in
outRealmName
. The returned string should be freed using theKLDisposeString()
function. If there are no realms in the list, function returns aklEmptyRealmListErr
error andoutRealmName
is unchanged.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
KLSetKerberosDefaultRealm
KLStatus KLSetKerberosDefaultRealm ( KLIndex inIndex);
Effects:
Sets the default realm in the login dialog box to be the realm specified by
inIndex
. ReturnsnoErr
if the index passed in is valid, orparamErr
if the index is invalid (i.e. the index is out of range).Realm indices are 0-based.
Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klPreferencesWriteErr
The preferences file is locked.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
KLSetKerberosDefaultRealmByName
KLStatus KLSetKerberosDefaultRealmByName ( const char *inRealmName);
Requires:
inRealmName
is a null-terminated C stringEffects:
Sets the default realm in the login dialog box to be the realm specified by
inRealmName
. ReturnsnoErr
if the name passed in is valid, orparamErr
if the name is invalid (i.e. the index is not among the known realms).Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klPreferencesWriteErr
The preferences file is locked.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
KLPrincipal Functions
KLCreatePrincipalFromTriplet
KLStatus KLCreatePrincipalFromTriplet( const char *inName, const char *inInstance, const char *inRealm, KLPrincipal *outPrincipal);
Requires:
inName
,inInstance
,inRealm
point to C strings;Effects:
Creates a new
KLPrincipal
to be used with other Login Library API functions from the triplet provided.The returned
KLPrincipal
should be freed using theKLDisposePrincipal()
function.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
Any error returned by a principal translation plugin
A principal translation returned an error.
Note that this function may return error codes reported by a principal translation function. Therefore, your code should expect to get an unknown error code, and be able to handle it gracefully -- by calling
KLGetErrorString()
.KLCreatePrincipalFromString
KLStatus KLCreatePrincipalFromString( const char *inFullPrincipal, KLKerberosVersion inKerberosVersion, KLPrincipal *outPrincipal);
Requires:
inFullPrincipal
points to a C string;Effects:
Creates a new
KLPrincipal
to be used with other Login Library API functions from the string provided. The "string" form of a principal is "user/instance@realm" (for the v5 case) or "user.instance@realm".The
inKerberosVersion
parameter should be eitherkerberosVersion_V4
orkerberosVersion_V5
, specifying whether the string contains a Kerberos v4 or Kerberos v5 principal (this affects how it is parsed).The returned
KLPrincipal
should be freed using theKLDisposePrincipal()
function.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klInvalidVersionErr
Invalid Kerberos version passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
KLGetTripletFromPrincipal
KLStatus KLGetTripletFromPrincipal( KLPrincipal inPrincipal, char **outName, char **outInstance, char **outRealm);
Requires:
inPrincipal
is a validKLPrincipal
structure;Effects:
Returns three C strings representing a Kerberos triplet equivalent to the
KLPrincipal
passed in. Kerberos v5 principals with two or more instances are not currently supported.
KLGetTripletFromPrincipal()
allocates the memory for the stringsoutName
,outInstance
, andoutRealm
. The strings returned should then be freed using theKLDisposeString()
function.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
KLGetStringFromPrincipal
KLStatus KLGetStringFromPrincipal( KLPrincipal inPrincipal, KLKerberosVersion inKerberosVersion, char **outFullPrincipal);
Requires:
(none)
Effects:
Returns a C string representation of the
KLPrincipal
passed in (e.g. "user/instance@realm").The
inKerberosVersion
parameter should be eitherkerberosVersion_V4
orkerberosVersion_V5
, specifying which representation (Kerberos v4 or Kerberos v5) the string should use.
KLGetStringFromPrincipal()
allocates the memory for the stringoutFullPrincipal
. The string returned should then be freed using theKLDisposeString()
function.If an error occurs
outFullPrincipal
is unchanged.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klInvalidVersionErr
Invalid Kerberos version passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
KLGetDisplayStringFromPrincipal
KLStatus KLGetDisplayStringFromPrincipal( KLPrincipal inPrincipal, KLKerberosVersion inKerberosVersion, char **outFullPrincipal);
Requires:
(none)
Effects:
Returns a C string representation of the
KLPrincipal
passed in (e.g. "user/instance@realm"), and removes any backslash characters used to quote special characters in the principal. The returned string cannot be converted back to a principal, and therefore should be used only for display purposes.The
inKerberosVersion
parameter should be eitherkerberosVersion_V4
orkerberosVersion_V5
, specifying which representation (Kerberos v4 or Kerberos v5) the string should use.
KLGetStringFromPrincipal()
allocates the memory for the stringoutFullPrincipal
. The string returned should then be freed using theKLDisposeString()
function.If an error occurs
outFullPrincipal
is unchanged.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klInvalidVersionErr
Invalid Kerberos version passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
KLComparePrincipal
KLStatus KLComparePrincipal( KLPrincipal inFirstPrincipal, KLPrincipal inSecondPrincipal, KLBoolean *outAreEquivalent);
Requires:
(none)
Effects:
If no errors occur,
inFirstPrincipal
andinSecondPrincipal
are equivalent, returnstrue
inoutAreEquivalent
. Otherwise, returnsfalse
.If an error occurs,
outAreEquivalent
is unchanged.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
KLDisposePrincipal
KLStatus KLDisposePrincipal( KLPrincipal inPrincipal);
Requires:
(none)
Effects:
Releases memory associated with the
KLPrincipal
passed in. The reference is no longer valid after the call toKLDisposePrincipal()
.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klBadPrincipalErr
Invalid KLPrincipal passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
KLLoginOptions Functions
KLCreateLoginOptions
KLStatus
KLCreateLoginOptions( KLLoginOptions *outOptions);
Requires:
(none)
Effects:
Creates a new
KLLoginOptions
to be used with other Login Library API functions. The login options are set to the KerberosLogin defaults for those values.The returned
KLLoginOptions
should be freed using theKLDisposeLoginOptions ()
function.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klBadLoginOptionsErr
Invalid KLLoginOptions passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
KLLoginOptionsSetTicketLifetime
KLStatus KLLoginOptionsSetTicketLifetime ( KLLoginOptions ioOptions, KLLifetime inTicketLifetime);
Requires:
ioOptions
is a valid KLLoginOptions created withKLCreateLoginOptions ()
Effects:
Sets the ticket lifetime in the KLLoginOptions provided.
Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klBadLoginOptionsErr
Invalid KLLoginOptions passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
KLLoginOptionsSetForwardable
KLStatus
KLLoginOptionsSetForwardable( KLLoginOptions ioOptions, KLBoolean inProxiable);
Requires:
ioOptions
is a valid KLLoginOptions created withKLCreateLoginOptions ()
Effects:
Sets the forwardable tickets flag in the KLLoginOptions provided.
Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klBadLoginOptionsErr
Invalid KLLoginOptions passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
KLLoginOptionsSetProxiable
KLStatus KLLoginOptionsSetProxiable ( KLLoginOptions ioOptions, KLBoolean inProxiable);
Requires:
ioOptions
is a valid KLLoginOptions created withKLCreateLoginOptions ()
Effects:
Sets the proxiable tickets flag in the KLLoginOptions provided.
Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klBadLoginOptionsErr
Invalid KLLoginOptions passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
KLDisposeLoginOptions
KLStatus
KLDisposeLoginOptions( KLLoginOptions inOptions);
Requires:
(none)
Effects:
Releases memory associated with the
KLLoginOptions
passed in. The reference is no longer valid after the call toKLDisposeLoginOptions()
.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klBadLoginOptionsErr
Invalid KLLoginOptions passed into function.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
Miscellaneous Functions
KLDisposeString
KLStatus KLDisposeString( char *inStringToDispose);
Requires:
inStringToDispose
is a string allocated by the Login Library API.Effects:
Zeros the memory associated with the string passed in, and then releases the memory. (Zeroing the memory first is useful for when disposing of password strings allocated by the Login Library API.) The string may have been allocated by functions including
KLLoginDialogHandleEvents(), KLChangePasswordDialogHandleEvents(), KLGetStringFromPrincipal()
orKLGetTripletFromPrincipal()
.Results:
If successful, klNoErr is returned. Otherwise, one of the following error codes is returned instead:
klParameterErr
Invalid option passed into function (check your variables).
klMemFullErr
Out of memory.
Internal Use Functions
__KLInternalAcquireTicketsForCache
KLStatus __KLInternalAcquireTicketsForCache ( KLPrincipal inPrincipal, const char *inCacheName, KLKerberosVersion inKerberosVersion, KLPrincipal *outPrincipal, char **outCacheName);
Requires:
The __KLInternalAcquireTicketsForCache
()
function requires the following:
- the function is called at a time when the AppleEvent Manager is available, i.e. system task time (as defined by Technote 1104) from an AppleEvent-aware application
- outCacheName and inCacheName are both non-nil. inCacheName may be prefixed by the Kerberos 5 "API:" (__KLInternalAcquireTicketsForCache ( ) will handle this case).
- inKerberosVersion is a valid version of Kerberos.
Effects:
The __KLInternalAcquireTicketsForCache
()
function attempts to insure that a valid ticket-granting ticket of the Kerberos version inKerberosVersion is available in the cache inCacheName and, if specified, for the principal inPrincipal, prompting the user to obtain a new one if necessary. Its main purpose is to be used interally by Kerberos5 and Kerberos4 libraries to verify the existance of the appropriate ticket granting tickets for the current session before obtaining a Kerberos service ticket.The name of the principal for which tickets are obtained (or found) is returned in
outPrincipal
.The name of the cache into which tickets are placed (or which is found if no new tickets are obtained) is returned in
outCacheName
so that the caller can change the application/context default cache if desired. This returned name can be used in Credential Cache API, Kerberos 4, or Kerberos 5 calls.If
inPrincipal
is notnil
(a principal is specified) and inKerberosVersion is a valid version for that principal (if not, klBadPrincipal is returned),
- and no valid tickets for that principal are in the the cache specified by inCacheName, __KLInternalAcquireTicketsForCache
()
presents the user interface as specified byKLLoginDialogBegin()
for obtaining user information and then attempts to acquire tickets with that information into a new cache. If successful and no tickets at all were previously in the cache collection, the newly created cache is made the system default cache;- or, valid tickets for that principal are available in the cache specified by inCacheName, no user interface is displayed.
If
inPrincipal
isnil
(no principal is specified),
- and no valid tickets for any user are in the cache specified by inCacheName,
KLAcquireTickets()
presents the user interface as specified byKLLoginDialogBegin()
for obtaining user information and then attempts to acquire tickets with that information and place them in a new cache. If successful and the cache collection is empty, the credentials cache corresponding to that principal are made the system default cache.- or, valid tickets are available in the cache specified by inCacheName, no user interface is displayed and inCacheName is returned.
__KLInternalAcquireTicketsForCache
()
does not necessarily present the user interface. If you always want to bring up the user interface, useKLAcquireNewTickets()
.__KLInternalAcquireTicketsForCache
()
will take care of presenting error dialogs to the user as necessary (for problems such as unknown principal, incorrect password, etc.). You do not need to callKLHandleError()
after this function.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, either both v4 and v5 ticket-granting tickets will be available in the cache collection (and the credentials cache containing them will possibly be set as the system default cache, as specified above) upon return, or __KLInternalAcquireTicketsForCache
()
will return an error code.If both Kerberos v4 and Kerberos v5 are available for the realm of the principal, and valid tickets for only one version but not the other are available in the cache collection, __KLInternalAcquireTicketsForCache
()
will treat this as the same as the no valid tickets case -- new tickets will be obtained for both Kerberos versions, replacing the current "orphan" ones.If only one of Kerberos v4 and Kerberos v5 is available for the realm of the principal, either a ticket-granting ticket for the appropriate version will be available in the cache collection (and the credentials cache containing them will be possibly set as the system default cache) as specified above upon return, or __KLInternalAcquireTicketsForCache
()
will return an error code.
Results:
If __KLInternalAcquireTicketsForCache
()
returnsklNoErr
, then:
- tickets are available in the cache collection specified by outCacheName;
- if
outPrincipal
is notnil
, a newKLPrincipal
is returned in*outPrincipal
. The returnedKLPrincipal
should be freed using theKLDisposePrincipal()
function. IfoutPrincipal
isnil
, nothing is returned.Otherwise,
outPrincipal
andoutCredCacheName
are unchanged and __KLInternalAcquireTicketsForCache()
returns one of the following error codes:
klParameterErr
Invalid option passed into function (check your variables).
klBadPrincipalErr
Invalid KLPrincipal passed into function or version does not match principal.
klBadVersionErr
Invalid Kerberos version passed into function.
klUserCanceledErr
The user cancelled the dialog.
klMemFullErr
Out of memory.
klPreferencesReadErr
The preferences file is inaccessible or corrupt.
klV5InitializationFailedErr
Failed to initialize a krb5 context.
klNoRealmsErr
The favorite realms list is empty.
klRealmDoesNotExistErr
The specified realm does not exist.
klNotInForegroundErr
The dialog is not in the foreground (Metrowerks debugger at fault?)
klNoAppearanceErr
Appearance Manager is unavailable.
Questions or comments? Send mail to macdev@mit.edu
Last updated on $Date: 2003/11/19 20:42:09 $
Last modified by $Author: smcguire $