Macintosh Development

[Home] [About Us] [People] [MIT Support Library] [MIT Kerberos for Macintosh]
[Applications] [Mac OS X] [Miscellaneous Documentation] [Information Systems]

KClient 3.0 API Specification

The KClient API provides a flexible interface to Kerberos v4 that is suitable for graphical user interface environments, in which it is necessary to consider the possibility that applications might need to access Kerberos tickets for several different principals at the same time, without any special actions on the users' part. The Kerberos v4 API does not provide such functionality; the KClient API builds on the Kerberos v4 API by providing additional features.

API Overview

The fundamental concept in the KClient API is a session. A session represents the authentication context in which a client authenticates to a service on behalf of a user. Once a session is created, it provides facilities for authenticating (for a client) and verifying authentication (for a server), constructing authentication response (for a server), verifying authentication response (for a client), encrypting and decrypting data, etc.

The KClient API can be used both by server and client applications. For a client application, a typical sequence of operations would be:

create a new session (KClientNewClientSession())
if using mutual authentication, set local and remote addresses (KClientSetLocalAddress() and KClientSetRemoteAddress())
get the authenticator for a service from the session (KClientGetAuthenticatorForService())
send the authenticator to the server
if using mutual authentication, receive authentication reply from the server
if using mutual authentication, verify the authentication reply from the server (KClientVerifyEncryptedServiceReply() or KClientVerifyProtectedServiceReply())
if using encryption, encrypt data and send it to the server (KClientEncrypt())
if using encryption, receive data from the server and decrypt it (KClientDecrypt())
destroy the session (KClientDisposeSession())

For a server application, a typical sequence of operations would be:

create a new session (KClientNewServerSession())
receive the authenticator from the client
if using mutual authentication, set the local and the remote address (KClientSetLocalAddress() and KClientSetRemoteAddress())
verify the authenticator (KClientVerifyAuthenticator())
if using mutual authentication, create an authentication response (KClientGetEncryptedServiceReply() or KClientGetProtectedServiceReply())
if using mutual authentication, send the authentication response to the client
if using encryption, encrypt data and send it to the client (KClientEncrypt())
if using encryption, receive data from the client and decrypt it (KClientDecrypt())
destroy the session (KClientDisposeSession())

API Specification

Types

Integer types

KClient API uses the following integer types:

UInt16: an unsigned integer type at least 16 bits wide
UInt32: an unsigned integer type at least 32 bits wide
SInt16: a signed integer type at least 16 bits wide
SInt32: a signed integer type at least 32 bits wide

Transparent types

KClientFile

KClientFile is a platform-specific unique file identifier. On Mac OS, it is the same as the file manager FSSpec type.

KClientKey

KClientKey is a type that represents a DES key. It contains a des_key_block, but using a struct rather than an array typedef makes it easier to correctly pass DES keys into functions.

KClientKeySchedule

KClientKeySchedule is a type that represents a DES key schedule. It contains a des_key_sched; as with KClientKey, using a struct makes it easier to correctly pass this type into functions.

KClientAddress

KClientAddress is a type that represents an IP v4 network address and a port number.

Opaque types

KClientSession

KClientSession is an opaque type which represents a KClient session. It is used both by server or client applications; clients need to create the session with KClientNewClientSession(), and servers with KClientNewServerSession(). After the session is created, it can be used to authenticate the client to a server and to encrypt or decrypt data. Finally, the session must be destroyed with KClientDisposeSession() when it is no longer needed.

A session must have a client principal and a server principal.

For a client session, the server principal is explicitly set using KClientSetServerPrincipal(). The client principal can either be set explicitly, by calling KClientSetClientPrincipal(), or it is set implicitly, by calling KClientLogin(), KClientPasswordLogin(), KClientGetTicketForService(), or KClientGetAuthenticatorForService(). Once the client principal is set (explicitly or implicitly), it can be changed by calling KClientSetClientPrincipal(). When the client principal is set for a session, any calls that require the user to enter a password will only allow the user to enter the password for the client principal. For example, if KClientGetTicketForService() is successfully called for a session, and then called again for the same sessioin after the tickets expire, the second call will not allow the user to enter a different principal in the login dialog. This behavior is different from the old KClient behavior; if you want the old behavior (and you probably shouldn't), you need to get a new KClient session every time you need to allow the user to change the principal.

For a server session, the server principal has to be explicitly set when the session is created. The client principal can be set explicitly, by calling KClientSetClientPrincipal(), in which case the session will only allow communication with the specified principal, or it can be set implicitly, by calling KClientVerifyAuthenticator(), in which case the session will accept any valid authenticator, but can subsequently only be used to communicate with the same principal (unless KClientSetClientPrincipal() is called). Note that this means that server session cannot be recycled for communication with multiple clients.

A session that is used for mutual authentication or encryption must have a local address and a remote address. They are set explicitly with KClientSetLocalAddress() and KClientSetRemoteAddress().

A session must have a session key. The session key is the cryptographic key used for encryption, decryption, and integrity protection. It can be retrieved by calling KClientGetSessionKey(). For a client session, it is implicitly set by calls to KClientGetTicketForService() or KClientGetAuthentictorForService(); for a server session, it's implicitly set by calls to KClientVerifyAutenticator().

KClientPrincipal

KClientPrincipal() is an opaque type which represents a Kerberos principal. It is used to manipulate client and server principals for a KClient session. A KClientPrincipal() can be created from a single string (a quoted Kerberos principal), or a triplet of strings (unquoted components of a Kerberos principal); likewise, it can be converted into a single string or a triplet of strings. When a KClientPrincipal() is no longer needed, it must be destroyed with KClientDisposePrincipal().

API behavior

Error handling

The calls in the KClient API never modify any of the arguments passed by reference when an error other than kcNoError is returned.

KClient API functions can return one of three kinds of errors: a KClient error, a Login library error, or a Kerberos v4 error.

KClient errors

KClient errors returned by the KClient 3.0 API are:

kcNoError 0 No error has occurred

kcErrBadParam 23001 A bad parameter was passed to the function (e.g. a nil pointer where nil is not allowed)

kcErrNoMemory 23000 The KClient library doesn't have enough memory to complete the request

kcErrInvalidPrincipal 23011 An invalid principal was passed to a function

kcErrInvalidSession 23010 An invalid session was passed to a function

kcErrNoClientPrincipal 23020 A client principal has not been set, but is required

kcErrNoServerPrincipal 23021 A server principal has not been set, but is required

kcErrInvalidAddress 23012 An invalid network address was passed to a function

kcErrNoLocalAddress 23022 A local address has not been set, but is required

kcErrNoRemoteAddress 23023 A remote address has not been set, but is required

kcErrNoSessionKey 23024 A session key has not been set, but is required

kcErrNoServiceKey 23025 A service key has not been set, but is required

kcErrNotLoggedIn 23030 No user is currently authenticated to Kerberos

kcErrInvalidFile 23013 An invalid file was passed to a function

kcErrKeyFileAccess 23041 The key file could not be accessed

kcErrNoChecksum 23026 A checksum has not been set, but is required

kcErrUserCancelled 23031 User cancelled the operation

kcErrIncorrectPassword 23032 Password was incorrect

kcErrBufferTooSmall 23040 The buffer passed into a function is was too small

kcErrFileNotFound 23042 The key file couldn't be found

kcErrInvalidPreferences 23043 The preferences file was invalid

kcErrChecksumMismatch 23044 The checksum did not match the expected value

Login library errors

Some KClient calls can return Login library errors; exactly which calls return Login library errors is documented for each function below. Login library errors are always returned unchanged, and you can refer to the Login library API for details on those errors.

Kerberos v4 library errors

Some KClient calls can return Kerberos v4 library errors; exactly which calls return Kerberos v4 library errors is documented for each function below. Kerberos v4 library error range is changed by adding kcFirstKerberosError to each Kerberos v4 error before returning it. For example, KClient will return RD_AP_MODIFIED + kcFirstKerberosError when trying to decrypt or verify a modified message.

Functions

General
OSStatus KClientGetVersion (
   UInt16*                   outMajorVersion, 
   UInt16*                   outMinorVersion, 
   const char**              outVersionString);
KClientGetVersion() returns the version of KClient libraries. The major version is returned in outMajorVersion, and the minor version in outMinorVersion. The version string identifying the library implementation is returned in outVersionString. If outMinorVersion or outVersionString are nil, the minor version and the version string are not returned; the major version is always returned. The API described in this document is distinguished by major version equal to KClientAPIVersion3.

If any of the arguments is not a valid pointer, or if outMajorVersion is nil, kcErrBadParam is returned.

Possible return values: kcNoError, kcErrBadParam

KClientSession functions

Creating and destroying sessions
OSStatus KClientNewClientSession (
    KClientSession*          outSession);
Used by clients.

KClientNewClientSession() creates a new client session. This is used by any client application (an application which intends to authenticate to a service on behalf of a user).

If the session will be used for mutual authentication, the client and the server address must be set using KClientSetLocalAddress() and KClientSetRemoteAddress(), as described below.

The session returned by KClientNewClientSession() must be destroyed by calling KClientDisposeSession().

Possible return values: kcNoError, kcErrBadParam, kcErrNoMemory
OSStatus KClientNewServerSession (
    KClientSession*          outSession,
    KClientPrincipal         inServicePrincipal);
Used by servers. Sets the server principal.

KClientNewServerSession() creates a new server session. This is used by any server application (an application which intends to authenticate clients to a service).

The principal of the service to which clients will be authenticated has to be specified. See the KClientPrincipal() functions for information on creating and destroying KClient principals.

Possible return values: kcNoError, kcErrBadParam, kcErrNoMemory, kcErrBadPrincipal.
OSStatus KClientDisposeSession (
    KClientSession           inSession);
Used by clients and servers.

KClientDisposeSession() must be used to destroy a session obtained from KClientNewClientSession() or KClientNewServerSession(). After a session is disposed, it is no longer valid and passing it to any KClient API function will result in an error.

Possible return values: kcNoError, kcErrInvalidSession.

Accessing session information
OSStatus KClientSetClientPrincipal (
    KClientSession           inSession,
    KClientPrincipal         inPrincipal);
Used by clients and servers. Sets the client principal.

KClientSetClientPrincipal() sets the client principal for a session.

For a client session, setting a principal will make all subsequent operations on that session operate on the specified principal. For example, calling KClientLogin() for the session will require from the user to authenticate as the specified principal; see descriptions of individual functions to see what the effects are of having an explicitly set session principal. If the principal for a session is not set, then the session operates on the principal associated with the credentials cache which is the default cache at the time the session is created.

For a server session, setting the principal determines which principal will be authenticated. This is useful when the server process wants to verify that an authenticator is valid and belongs to a specific Kerberos principal. If the client principal is not set for a server session, it will be determined the first time an authenticator is verified, and can subsequently be retrieved with KClientGetClientPrincipal().

Possible return values: kcNoError, kcErrInvalidSession, kcErrInvalidPrincipal, kcErrNoMemory
OSStatus KClientGetClientPrincipal (
    KClientSession           inSession,
    KClientPrincipal*        outPrincipal);
Used by clients and servers.

Returns the client principal for a session. Requires the client principal to be set.

For a client session, returns the client principal, which is set explicitly by KClientSetClientPrincipal() and implicitly by KClientLogin(), KClientGetTicketForService(), and KClientGetAuthenticatorForService(). If no client principal is set, returns kcErrNoClientPrincipal. Note, in particular, that this means that KClientGetClientPrincipal() will return an error for a new session. This is different from the KClient 1.x API, in which the default username displayed in the login dialog was returned.

For a server session, if the client principal is not explicitly set, then it is determined at the time an authenticator is verified. Otherwise, the principal returned is the principal set with KClientSetClientPrincipal(). If no authenticator has been verified in the session, nor has a principal been explicitly set, the kcErrNoClientPrincipal is returned.

Possible return values: kcNoError, kcErrInvalidSession, kcErrBadParam, kcErrNoClientPrincipal, kcErrNoMemory
OSStatus KClientSetServerPrincipal (
    KClientSession           inSession,
    KClientPrincipal         inPrincipal);
Used by clients and servers. Sets the server principal.

Sets the server principal for a session.

For a client session, setting the server principal determines which service the session will authenticate to. The server principal has to be set before tickets or authenticators for a service can be acquired for the session.

For a server session, setting the server principal determines which service the session with authenticate for. The server principal can be set using KClientSetServerPrincipal(), but it is better to set it directly in the call to KClientNewServerSession().

Possible return values: kcNoError, kcErrInvalidSession, kcErrNoSessionKey, kcErrNoMemory
OSStatus KClientGetServerPrincipal (
    KClientSession           inSession,
    KClientPrincipal*        outPrincipal);
Used by clients and servers. Requires the server principal to be set.

Returns the server principal for a session.

For a client session, the principal returned is the principal set by KClientSetServerPrincipal(). If no server principal has been set, kcErrNoServerPrincipal is returned.

For a server session, the principal returned is the principal set by KClientSetServerPrincipal() or the principal specified to KClientNewServerSession() when the session is created.

Possible return values: kcNoError, kcErrInvalidSession, kcErrBadParam, kcErrNoServerPrincipal, kcErrNoMemory
OSStatus KClientSetLocalAddress (
    KClientSession           inSession,
    const KClientAddress*    inLocalAddress);
Used by clients and servers. Sets the local address.

Sets the local address for the session.

For both client and server sessions, the local address has to be set before encryption, decryption, integrity protection, and integrity verification will work.

For client sessions, the local address has to be set for KClientVerifyEncryptedServiceResponse() and KClientVerifyProtectedServiceResponse() to work. The address must be set to the network address of the network interface which is used to communicate with the server. The local address doesn't need to be set for one-sided authentication to work.

For server sessions, the local address also has to be set for KClientVerifyAuthenticator(), KClientGetEncryptedServiceResponse() and KClientGetProtectedService() to work. The address is set explicitly by calling KClientSetLocalAddress() after the session is created, and should be set to the address of the interface on which communication with the client will occur.

Possible return values: kcNoError, kcErrInvalidSession, kcErrInvalidAddress, kcErrNoMemory
OSStatus KClientGetLocalAddress (
    KClientSession           inSession,
    KClientAddress*          outLocalAddress);
Used by clients and servers. Requires the local address to be set.

Returns the address set by KClientSetLocalAddress(), or kcErrNoLocalAddress if none has been set.

Possible return values: kcNoError, kcErrInvalidSession, kcErrBadParam, kcErrNoMemory, kcErrNoLocalAddress
OSStatus KClientSetRemoteAddress (
    KClientSession           inSession,
    const KClientAddress*    inRemoteAddress);
Used by clients and server. Sets the remote address.

Sets the remote address for the session.

For both client and server sessions, the remote address has to be set before encryption, decryption, integrity protection, and integrity verification will work.

For client sessions, the remote address has to be set before attempting mutual authentication by calling KClientVerifyEncryptedServiceReply() or KClientVerifyProtectedServiceReply(). The remote address does not need to be set for one-sided authentication.

For server sessions, the remote address also has to be set for KClientVerifyAuthenticator(), KClientGetEncryptedServiceResponse() and KClientGetProtectedServiceReply() to work.

Possible return values: kcNoError, kcErrInvalidSession, kcErrInvalidAddress, kcErrNoMemory
OSStatus KClientGetRemoteAddress (
    KClientSession			        inSession,
   	KClientAddress*			       outRemoteAddress);
Used by clients and servers. Requires the remote address to be set.

Returns the address set by KClientSetRemoteAddress(), or kcErrNoRemoteAddress if none has been set.

Possible return values: kcNoError, kcErrInvalidSession, kcErrBadParam, kcErrNoMemory, kcErrNoRemoteAddress
OSStatus KClientGetSessionKey (
    KClientSession     inSession,
    KClientKey*        outPrivateKey);
Used by clients and servers. Requires the session key to be set.

Retrieves the session key for the session.

For a client session, returns the session key for the of the session. The session key has to be set, for example by KClientGetTicketsForService().

Note that if the service tickets are renewed, KClientGetSessionKey() will return the new key. Therefore, you should only call KClientGetSessionKey() repeatedly if you expressly want to take advantage of this; otherwise, you should only call it once, and remember the key. This is important depending on what kind of service you are using; for services which use the service key to maintain a session indefinitely (such as telnet or CVS), the session key should obtained from KClient once and remembered by the client. For services which want the current session key frequently (so as to avoid using a session key from expired tickets -- FTP or Zephyr, for example), the client should call KClientGetSessionKey() repeatedly to always retrieve the session key for the current service tickets.

For a server session, return the session key of the session. The session key has to be set, for example by KClientVerifyAuthenticator().

Possible return values: kcNoError, kcErrInvalidSession, kcErrBadParam, kcErrNoServiceKey, or any error from KClientLogin()
OSStatus KClientGetExpirationTime (
    KClientSession     inSession,
    UInt32*            outExpirationTime);
Used by clients and servers. For client sessions, uses the client principal if set. For server sessions, requires the session key to be set.

Returns the time of expiration of the session's tickets.

For a client session, returns the time when the ticket-granting ticket for the client principal expires, in seconds since 00:00 January 1, 1970. If the credentials cache contains no valid ticket-granting ticket, (the cache does not exist, or the ticket exists, but is not valid), kcErrNotLoggedIn is returned.

For a server session, returns expiration time of the service ticket for the client principal. If no client has been authenticated yet, returns kcErrNoClientPrincipal.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcErrNotLoggedIn, kcErrNoClientPrincipal.
OSStatus KClientSetKeyFile (
    KClientSession     inSession,
    const KClientFile* inKeyFile);
Used by servers. Sets the key file.

Sets the key file used by the session, for retrieval of service keys. This function does not verify that the specified key file can be read.

Unless KClientSetKeyFile() is called, a KClient server session uses the default key file to locate the service keys.

Possible return values: kcNoError, kcErrInvalidSession, kcErrInvalidFile, kcErrNoMemory

Logging in and out (client)
OSStatus KClientLogin (
    KClientSession     inSession);
Used by clients. Requires the server principal to be set. Sets the client principal.

Acquires the ticket-granting ticket for the client principal, if necessary.

If the client principal is not set for the session, and there are no valid tickets in the default credentials cache, then KClientLogin() displays a login dialog, acquires the tickets, and puts them in the default credentials cache. If the client principal is not set, but there are valid tickets in the default credentials cache, then KClientLogin() does nothing. In either case, KClientLogin() sets the principal of the session to the principal of the tickets in the default credentials cache.

If the client principal is set for the session, and there are no valid tickets for that principal in any credentials cache, then KClientLogin() displays a login dialog, requiring the password for that principal, and then acquires the tickets and puts them in a new credentials cache. If the tickets for the specified principal exist, KClientLogin() does nothing.

After KClientLogin() returns successfully, valid tickets for the specified principal (if specified), or for a user-selected principal (if no client principal was specified), exist in a credentials cache, and can be used to acquire service tickets.

Possible return values: kcNoError, kcErrInvalidSession, kcErrNoMemory, or any Login library error
OSStatus KClientPasswordLogin (
    KClientSession     inSession,
    const char*        inPassword);
Used by clients. Requires the client and the server principal to be set.

Acquires the ticket-granting ticket for the client principal, if necessary, without displaying a login dialog.

The KClientPasswordLogin() function behaves the same as the KClientLogin() function, except that it never presents a login dialog; instead, if it needs to acquire new tickets for the principal, it uses the provided password.

Possible return values: kcNoError, kcErrInvalidSession, kcErrNoMemory, or any login library error
OSStatus KClientLogout (
    KClientSession     inSession);
Used by clients. Uses the client principal, if set.

Destroys all tickets for the client principal of the session. If no principal is specified for the session, destroys all the tickets in the default credentials cache.

Possible return values: kcNoError, kcErrInvalidSession, or any Login library error

Accessing service keys (server)
OSStatus KClientGetServiceKey (
    KClientSession     inSession,
    UInt32             inVersion,
    KClientKey*        outKey);
Used by servers. Requires the service principal to be set. Uses the key file, if set.

Retrieves a service key from the key file. The service must be set with KClientSetServerPrincipal() before calling KClientGetServiceKey(). The inVersion argument should be the key version number to be retrieved, or zero. If it is zero, the first key in the key file will be returned.

KClientGetServiceKey() uses the default key file, unless some other key file has been set with KClientSetKeyFile().

If the key file of the key cannot be read, kcErrKeyFileAccess is returned.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcErrKeyFileAccess
OSStatus KClientAddServiceKey (
    KClientSession     inSession,
    UInt32             inVersion,
    const KClientKey*  inKey);
Used by servers. Requires the server principal to be set. Uses the key file, if set.

Adds a service key to the key file. The service must be set with KClientSetServerPrincipal() before calling KClientAddServiceKey(). The key is written to the server key file; if a key for the same service with the same version number already exists, it is replaced.

KClientAddServiceKey() uses the default key file, unless some other key file has been set with KClientSetKeyFile().

If the key file cannot be written, kcErrKeyFileAccess is returned.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcErrKeyFileAccess

Authenticating to a service
OSStatus KClientGetTicketForService (
    KClientSession     inSession,
    void*              ioBuffer,
    UInt32*            ioBufferLength);
Used by clients. Requires the server principal to be set. Uses the client principal, if set, and sets the client principal otherwise. Sets the session key and the checksum.

Returns the ticket for the service of the session. The service has to be set by KClientSetServicePrincipal() before calling KClientGetTicketForService(), or else kcErrNoServerPrincipal is returned. The ticket is returned in the provided buffer, whose size should be passed in the location pointed to by ioBufferLength. The size of the ticket is returned in the same location.

If no valid ticket-granting ticket for the client principal of the session can be found, KClientGetTicketForService() will present a login dialog before acquiring and returning the ticket.

On return, ioBuffer does not contain the length of the ticket, just the ticket itself.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcErrBufferTooSmall, kcErrNoServerPrincipal, or any return value from KClientLogin(), or any KClient Kerberos error.
OSStatus KClientGetAuthenticatorForService (
    KClientSession     inSession,
    void*              ioBuffer,
    UInt32*            ioBufferLength,
    UInt32             inChecksum,
    char*              inApplicationVersion);
Used by clients. Requires the server principal to be set. Uses the client principal, if set, and sets the client principal otherwise. Sets the session key and the checksum.

Returns an authenticator for the service of the session. The service has to be set by KClientSetServicePrincipal() before calling KClientGetAuthenticatorForService(). The authenticator is returned in ioBuffer, whose size should be passed in the location pointed to by ioBufferLength. The size of the authenticator is returned in ioBufferLength.

If no valid ticket-granting ticket for the client principal of the session can be found, KClientGetAuthenticatorForService() will present a login dialog before acquiring and returning the authenticator.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcErrBufferTooSmall, or any return value from KClientLogin(), or any KClient Kerberos error.
OSStatus KClientVerifyEncryptedServiceReply (
    KClientSession     inSession,
    const void*        inBuffer,
    UInt32             inBufferLength);
Used by clients. Requires the client principal, the server principal, the local address, the remote address, and the checksum to be set.

Verifies an encrypted authenticator reply returned by a server. The authenticator should be in the buffer pointed to by inBuffer, and the length of the authenticator should be in inBufferLength. The buffer should only contain the server response, not the length of the response.

This function should only be used if the protocol uses encryption in authentication. If integrity protection is used instead, use KClientVerifyProtectedServiceReply().

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, or any KClient Kerberos error.
OSStatus KClientVerifyProtectedServiceReply (
    KClientSession     inSession,
    const void*        inBuffer,
    UInt32             inBufferLength);
Used by clients. Requires the client principal, the server principal, the local address, the remote address, and the checksum to be set.

Verifies a protected authenticator reply returned by a server. The authenticator should be in the buffer pointed to by inBuffer, and the length of the authenticator should be in inBufferLength. The buffer should only contain the server response, not the length of the response.

This function should only be used if the protocol uses integrity protection in authentication. If encryption is used instead, use KClientVerifyEncryptedServiceReply().

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, or any KClient Kerberos error.

Authenticating a client
OSStatus KClientVerifyAuthenticator (
    KClientSession     inSession,
    const void*        inBuffer,
    UInt32             inBufferLength);
Used by servers. Requires the server principal to be set. Uses the client principal and the remote address, if set. Sets the client principal, the remote address, the session key, and the checksum.

Verifies an authenticator received from the client. The authenticator should be in the buffer pointed to by inBuffer, and the length of the authenticator should be in inBufferLength. The buffer should only contain the authenticator data, not the length of the authenticator. The checksum is read from the authenticator and used on subsequent calls to KClientGetEncryptedServiceReply() and KClientGetProtectedServiceReply().

If the client principal is set for the session (either by calling KClientSetClientPrincipal(), or by calling KClientVerifyAuthenticator()), the authenticator will be rejected unless the principal in the authenticator matches the session principal.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, or any KClient Kerberos error
OSStatus KClientGetEncryptedServiceReply (
    KClientSession     inSession,
    void*              ioBuffer,
    UInt32*            ioBufferLength);
Used by servers. Requires the server principal, the client principal, the local address, the remote address, and the checksum to be set.

Create an encrypted authentication response. The response is stored in the provided buffer (pointed to by ioBuffer), and the length of the response is returned in the location pointed to by ioBufferLength. KClientVerifyAuthenticator() has to be called first, to set the session checksum used to generate the reply.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, or any KClient Kerberos error.
OSStatus KClientGetProtectedServiceReply (
    KClientSession     inSession,
    void*              ioBuffer,
    UInt32*            ioBufferLength);
Used by servers. Requires the server principal, the client principal, the local address, the remote address, and the checksum to be set.

Create an integrity-protected authentication response. The response is stored in the provided buffer (pointed to by ioBuffer), and the length of the response is returned in the location pointed to by ioBufferLength. KClientVerifyAuthenticator() has to be called first, to obtain the checksum used to generate the reply.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcErrBufferTooSmall, or any KClient Kerberos error.

Communicating with a service or a client
OSStatus KClientEncrypt (
    KClientSession     inSession,
    const void*        inPlainBuffer,
    UInt32             inPlainBufferLength,
    void*              outEncryptedBuffer,
    UInt32*            ioEncryptedBufferLength);
Used by clients and servers. Requires the local address, the remote address, and the session key to be set.

Encrypts data. The data should be in the buffer pointed to by inPlainBuffer, and its length should be in inPlainBufferLength. The data will be encrypted into the buffer pointed to by outEncryptedBuffer, whose maximum length should be passed in location pointed to by ioEncryptedBufferLength. On success, the length of the encrypted data is returned in the location pointed to by ioEncryptedBufferLength.

Before KClientEncrypt() can be called, both the client and the server principal have to be set, and both the remote and the local address have to be set for the session.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcErrBufferTooSmall, or any KClient Kerberos error.
OSStatus KClientDecrypt (
    KClientSession     inSession,
    const void*        ioBuffer,
    UInt32             inEncryptedDataLength,
    UInt32*            outPlainDataOffset,
    UInt32*            outPlainDataLength);
Used by clients and servers. Requires the local address, the remote address, and the session key to be set.

Decrypts data. The data should be in the buffer pointed to by ioBuffer, and its length should be in inEncryptedDataLength; the data is decrypted in place, and returned in the buffer pointed to by ioBuffer, at the offset outPlainDataOffset, with the length of outPlainDataLength from that offset.

Before KClientDecrypt() can be called, both the client and the server principal have to be set, and both the remote and the local address have to be set for the session.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, or any KClient Kerberos error.
OSStatus KClientProtectIntegrity (
    KClientSession     inSession,
    const void*        inPlainBuffer,
    UInt32             inPlainBufferLength,
    void*              outProtectedBuffer,
    UInt32*            ioProtectedBufferLength);
Used by clients and servers. Requires the local address, the remote address, and the session key to be set.

Integrity-protects data. The data should be in the buffer pointed to by inPlainBuffer, and its length should be in inPlainBufferLength; the data will be integrity-protected into the buffer pointed to by outProtectedBuffer, whose maximum length should be passed in the location pointed to by ioProtectedBufferLength. On success, the length of the encrypted data is returned in the location pointed to by ioProtectedBufferLength.

Before KClientProtectIntegrity() can be called, both the client and the server principal have to be set, and both the remote and the local address have to be set for the session.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcErrBufferTooSmall, or any KClient Kerberos error.
OSStatus KClientVerifyIntegrity (
    KClientSession     inSession,
    const void*        ioBuffer,
    UInt32             inProtectedDataLength,
    UInt32*            outPlainDataOffset,
    UInt32*            outPlainDataLength);
Used by clients and servers. Requires the local address, the remote address, and the session key to be set.

Verifies the integrity of data. The data should be in the buffer pointed to by ioBuffer, and its length should be in inProtectedDataLength; the data is verified in place, and returned in the buffer pointed to by ioBuffer, at the offset outPlainDataOffset, with the length of outPlainDataLength from that offset.

Before KClientVerifyIntegrity() can be called, both the client and the server principal have to be set, and both the remote and the local address have to be set for the session.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, or any KClient Kerberos error.

Getting to other APIs
OSStatus KClientGetCCacheReference (
    KClientSession     inSession,
    cc_ccache_t*       outCCacheReference);
Used by clients.

Returns a CCache API ccache reference for the credentials cache used by the session. For a session for which no client principal has been set, this is the default credentials cache; for a session for which a client principal has been set, this is the credentials cache for that principal, if such a credentials cache exists.

The returned ccache reference is owned by the caller, and should be disposed by calling cc_ccache_release() on it when it's no longer needed (which may be before or after inSession is diposed with KClientDisposeSession()).

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcNoMemory.
OSStatus KClientGetProfileHandle (
    KClientSession     inSession,
    profile_t*         outProfileHandle);
Used by clients and servers.

Returns a Kerberos Profile API handle for the Kerberos profile used by the session.

The returned handle is owned by the caller and should be disposed with profile_abandon() or profile_release() when it's no longer needed.

Possible return values: kcNoError, kcErrInvalidSession, kcBadParam, kcNoMemory.

Principal manipulation
OSStatus KClientV4StringToPrincipal (
    const char*        inPrincipalString,
    KClientPrincipal*  outPrincipal);
Converts a fully qualified Kerberos v4-style string representation of a principal to a KClientPrincipal.

outPrincipal must be freed using KClientDisposePrincipal() when you are done using it.

Possible return values: kcNoError, kcErrInvalidPreferences
OSStatus KClientPrincipalToV4String ( KClientPrincipal inPrincipal, char* outPrincipalString); Converts a KClientPrincipal to a fully qualified Kerberos v4-style string representation of the principal. The caller is responsible for allocating memory for outPrincipalString. It should be of length MAX_K_NAME_SZ as specified in the Keberos v4 krb.h header file. Possible return values: kcNoError, kcErrInvalidPreferences. OSStatus KClientPrincipalToV4Triplet ( KClientPrincipal inPrincipal, char* outName, char* outInstance, char* outRealm); Extracts the three components of a Kerberos v4 principal from the KClientPrincipal. The caller is responsible for allocating memory for the three returned char * values. They should be of length ANAME_SZ, INST_SZ, and REALM_SZ respectively, as specified in the Keberos v4 krb.h header file. Possible return values: kcNoError, kcErrInvalidPreferences. OSStatus KClientDisposePrincipal ( KClientPrincipal inPrincipal); Frees the KClientPrincipal. Possible return values: kcNoError, kcErrInvalidPreferences.




 
 
	  
		Questions or comments? Send mail to macdev@mit.edu 
	  

	Last updated on $Date: 2002/11/04 18:35:58 $ 
 
	Last modified by $Author: smcguire $

`kcNoError`	0	No error has occurred
`kcErrBadParam`	23001	A bad parameter was passed to the function (e.g. a nil pointer where nil is not allowed)
`kcErrNoMemory`	23000	The KClient library doesn't have enough memory to complete the request
`kcErrInvalidPrincipal`	23011	An invalid principal was passed to a function
`kcErrInvalidSession`	23010	An invalid session was passed to a function
`kcErrNoClientPrincipal`	23020	A client principal has not been set, but is required
`kcErrNoServerPrincipal`	23021	A server principal has not been set, but is required
`kcErrInvalidAddress`	23012	An invalid network address was passed to a function
`kcErrNoLocalAddress`	23022	A local address has not been set, but is required
`kcErrNoRemoteAddress`	23023	A remote address has not been set, but is required
`kcErrNoSessionKey`	23024	A session key has not been set, but is required
`kcErrNoServiceKey`	23025	A service key has not been set, but is required
`kcErrNotLoggedIn`	23030	No user is currently authenticated to Kerberos
`kcErrInvalidFile`	23013	An invalid file was passed to a function
`kcErrKeyFileAccess`	23041	The key file could not be accessed
`kcErrNoChecksum`	23026	A checksum has not been set, but is required
`kcErrUserCancelled`	23031	User cancelled the operation
`kcErrIncorrectPassword`	23032	Password was incorrect
`kcErrBufferTooSmall`	23040	The buffer passed into a function is was too small
`kcErrFileNotFound`	23042	The key file couldn't be found
`kcErrInvalidPreferences`	23043	The preferences file was invalid
`kcErrChecksumMismatch`	23044	The checksum did not match the expected value