[65] in pc-kerberos
authlib.txt
daemon@ATHENA.MIT.EDU (Paul B. Hill )
Wed Nov 16 14:00:18 1994
To: pc-kerberos-mtg@menelaus.local
Date: Wed, 16 Nov 94 14:00:03
From: pbh@MIT.EDU (Paul B. Hill )
Subject: authlib.txt
Date: Thu, 10 Nov 94 14:30:45 -0500
From: mortong@fish-license.ifs.umich.edu
Paul, here is the text of the authlib.dll specification we talk about on
the phone and which I believe is ready for pc-kerberos world to see.
-- Regards, Morton
---------------------------------------------------------------------------
AUTHLIB.TXT -- Documentation for a Kerberos Authentication Services API
Last Modified Date: November 7, 1994 (mortong@ifs.umich.edu)
---------------------------------------------------------------------------
Copyright (c) 1992-1994 Regents of The University of Michigan. All Rights
Reserved.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appears in all copies and that both that
copyright notice and this permission notice appear in supporting documenta-
tion, and that the name of The University of Michigan not be used in adver-
tising or publicity pertaining to distribution of the software without
specific, written prior permission. This software is supplied as is without
expressed or implied warranties of any kind.
---------------------------------------------------------------------------
AUTHLIB.DLL is a Windows DLL exporting a higher-level API for authentica-
tion services than KRBV4WIN.DLL does. It is a based on an existing Apple
Macintosh implementation by R. J. Churchill (rjc@ifs.umich.edu).
This file documents the AUTHLIB API for use by programmers who want to
incorporate authentication services in their applications.
The AUTHLIB API uses the calling convention that a pointer passed to an API
function represents the address of storage already allocated by the caller
and the called API function has the right to modify the contents of said
storage.
All the functions exported from AUTHLIB.DLL return an integer type defined
by the AUTH_ERR macro. AUTH_ROUTINE is not return type -- it combines a
return type declaration with a function type declaration because these
declarations must be made in a different order in the two implementations,
Macintosh and Windows.
---------------------------------------------------------------------------
AUTHLIB.H -- a copy of the header file -- included here for reference
/*
* authlib.h
* - A Kerberos Authentication Services API available via Authentication
* Manager (Mac) and Authentication DLL (Windows)
*
* - See the additional documentation file authlib.txt for notes on
* programming with the authlib API.
*
* - Last Modified Date: November 7, 1994 (mortong@ifs.umich.edu)
*
* Copyright (c) 1992-1994 Regents of The University of Michigan.
* All Rights Reserved.
*
* Permission to use, copy, modify, and distribute this software and
* its documentation for any purpose and without fee is hereby granted,
* provided that the above copyright notice appears in all copies and
* that both that copyright notice and this permission notice appear
* in supporting documentation, and that the name of The University
* of Michigan not be used in advertising or publicity pertaining to
* distribution of the software without specific, written prior
* permission. This software is supplied as is without expressed or
* implied warranties of any kind.
*
* Campus Computing Sites, Sales, and Service
* The University of Michigan
* c/o Robert John Churchill
* 535 W. William Street
* Ann Arbor, Michigan
* +1-313-936-2528
* rjc@ccs.itd.umich.edu
*/
#if defined(THINK_C) || defined(__MWERKS__)
#define MACOS 1
#elif _WINDOWS
#else
#error Question: What do we do for MPW? Answer: Cause a compile time error.
#endif
#ifndef __AUTHLIB__
#define __AUTHLIB__
#ifdef MACOS /* Macintosh - Authentication Manager */
#pragma once
#include <Types.h>
#include <Errors.h>
#define AUTH_ERR OSErr
#define AUTH_ROUTINE_TYPE pascal
#define AUTH_ROUTINE AUTH_ROUTINE_TYPE AUTH_ERR
#define AUTH_VERSION_CODE 4 /* Current Mac API version */
#define AUTHMAN_VERSION_CODE AUTH_VERSION_CODE
#define gestaltAuthManVersion 'UMAM' /* Register with Gestalt */
#define AUTH_BYTE unsigned char /* Define data types */
#define AUTH_SHORT short
#define AUTH_SHORT_PTR short *
#define AUTH_LONG long
#define AUTH_SHORT_STR Str63
#define AUTH_STR_PTR Str255 *
#define AUTH_PTR void *
#define AUTH_DATE long
#define AUTH_NO_ERROR 0 /* Define Errors */
#define AUTH_ERROR (-1)
#define AUTH_END_OF_LIST paramErr
#define AUTH_CALLBACKS_SUPPORTED 1
#define AUTH_DES_SUPPORTED 1
#define MAX_KTXT_LEN 1250 /* max Kerberos packet size */
#elif _WINDOWS /* Windows Authentication DLL */
#include <windows.h>
#ifndef KRB_DEFS
#define MAX_KTXT_LEN 1250 /* max Kerberos packet size */
#define ANAME_SZ 40 /* maximum len - principal name */
#define INST_SZ 40 /* instance name */
#define REALM_SZ 40 /* realm name */
#define SNAME_SZ 40 /* service name */
#define MAX_HSTNM 100 /* host name */
#define MAX_K_NAME_SZ (ANAME_SZ + INST_SZ + REALM_SZ + 2)
#endif /* KRB_DEFS */
#define AUTH_ERR short
#define AUTH_ROUTINE_TYPE WINAPI __export
#define AUTH_ROUTINE AUTH_ERR AUTH_ROUTINE_TYPE
#define AUTH_VERSION_CODE 4 /* Current Windows API version */
#define AUTH_BYTE BYTE
#define AUTH_SHORT short
#define AUTH_SHORT_PTR short __far *
#define AUTH_LONG LONG
typedef char AUTH_SHORT_STR[ANAME_SZ];
#define AUTH_STR_PTR LPSTR
#define AUTH_PTR LPVOID
#define AUTH_DATE DWORD
#define AUTH_NO_ERROR 0 /* Define Errors */
#define AUTH_ERROR (-1)
#define AUTH_END_OF_LIST (-2)
#define AUTH_NO_MEMORY (-3)
#define AUTH_EXCEPTION (-4)
#endif
#ifndef DES_DEFS
#define DES_DECRYPT 0 /* DES operations */
#define DES_ENCRYPT 1 /* "or" with DES modifiers below */
#endif /* DES_DEFS */
#define DES_PCBC 0 /* DES modifiers */
#define DES_SCHED 2
#define DES_ECB 4
#define DES_QUAD_CKSUM 6
#ifdef MACOS
#define AUTHMAN_DRVR_NAME "p.AuthMan 1" /* driver name */
/* AuthMan driver v1 csCodes */
#define AUTHENTICATE_NOW 128
#define GET_AUTH_STATUS 129
#define SHOW_MESSAGE 130
#define GET_UNIQNAME 131
#define FLUSH_TICKETS 132
#define GET_AUTH_VERSION 133
#define RELOAD_INFO 134
#define SET_UNIQNAME 135
#define GET_LOCAL_REALM 256
/* AuthMan driver v2 additional csCodes */
#define GET_V4_TICKET 1024
#define EXPIRE_V4_TICKET 1025
#define GET_V4_TICKET_N_INFO 1026
#define GET_REALM_N_INFO 1027
#define GET_REALM_HOST_N_INFO 1028
#define DES_FUNCTIONS 1029
/* AuthMan driver v3 additional csCodes */
#define SET_V4_PASSWORD 1050
#define AUTH_MSG_CALLBACK 1051
/* AuthMan driver v4 additional csCodes */
#define GET_TICKET_CACHE_N_INFO 1052
#define SET_TICKET_CACHE 1053
#define AUTH_CLOSE 1054
#endif /* MACOS */
#if defined(powerc) || defined (__powerc)
#pragma options align=mac68k
#endif /* PowerPC struct alignment */
#ifdef __cplusplus
struct _V4ticketInfo {
#else
typedef struct _V4ticketInfo {
#endif
AUTH_SHORT_STR sName, sInstance, sRealm; /* service ticket info */
AUTH_SHORT_STR pName, pInstance, pRealm; /* ticket holder info */
AUTH_DATE issueDate, expireDate;
AUTH_BYTE sessionKey[8];
#ifdef __cplusplus
};
#else
} _V4ticketInfo;
#endif
typedef _V4ticketInfo * _V4ticketInfoPtr;
#if defined(powerc) || defined(__powerc)
#pragma options align=reset
#endif /* PowerPC struct alignment */
#define INFINITE_LIFETIME 0xFFFFFFFF /* infinite lifetime */
#define UNKNONW_REALM_TYPE 0 /* Realm codes */
#define UNKNOWN_REALM_TYPE 0 /* typo: oops */
#define MIT_KERBEROS_REALM_TYPE 1
#define AFS_KERBEROS_REALM_TYPE 2
#define DONT_PROMPT_FLAG 0x0000 /* getV4Ticket flags */
#define PROMPT_FLAG 0x0001 /* bit 0 set */
#define MSG_REGISTER 0x0000 /* doMsgCallback flags */
#define MSG_DEREGISTER 0x0001
#define MSG_REGISTER_MENU 0x0002
/* prototype for callback function */
/* note: callback functions always return noErr */
#ifdef __cplusplus
extern "C" {
#endif
#ifdef _WINDOWS
typedef AUTH_ERR (CALLBACK * AuthManCallbackUPP)(AUTH_SHORT messageID,
AUTH_LONG msgData,AUTH_LONG userData);
#else
typedef pascal OSErr (*doAuthMsgCallbackProc)(AUTH_SHORT messageID,
AUTH_LONG msgData,AUTH_LONG userData);
enum {
uppAuthManCallbackProcInfo = kPascalStackBased
| RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
| STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(AUTH_SHORT)))
| STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(AUTH_LONG)))
| STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(AUTH_LONG)))
};
#if USESROUTINEDESCRIPTORS
typedef UniversalProcPtr AuthManCallbackUPP;
#define NewAuthManCallbackProc(userRoutine)
(AuthManCallbackUPP) NewRoutineDescriptor((ProcPtr)(userRoutine),
uppAuthManCallbackProcInfo, GetCurrentISA())
#else
typedef ProcPtr AuthManCallbackUPP;
#define NewAuthManCallbackProc(userRoutine)
(AuthManCallbackUPP)(userRoutine)
#endif
#endif /* _WINDOWS */
#ifdef __cplusplus
}
#endif
#define AUTH_MSG_V4TICKETADDED 0x0001 /* callback messageIDs */
#define AUTH_MSG_V4TICKETEXPIRED 0x0002
#define AUTH_MSG_MENUITEM_SELECTED 0x0003
#define AUTH_RELOAD_CONFIG_INFO 0x0004
#define AUTH_MSG_AUTO_EXPIRE_MODE 0x0005
#define AUTH_MSG_NEW_USER_ACTIVE 0x0006
#ifdef __cplusplus
extern "C" {
#endif
/* AuthMan API v1 prototypes */
AUTH_ROUTINE openAuthMan(AUTH_SHORT_PTR authRefNum,
AUTH_SHORT_PTR authAPIversion);
AUTH_ROUTINE getDefaultRealm(AUTH_SHORT authRefNum,
AUTH_STR_PTR realmName,
AUTH_SHORT_PTR realmType);
AUTH_ROUTINE getAuthenticationStatus(AUTH_SHORT authRefNum,
AUTH_SHORT_PTR status);
AUTH_ROUTINE getUniqname(AUTH_SHORT authRefNum,
AUTH_STR_PTR uniqName);
AUTH_ROUTINE setUniqname(AUTH_SHORT authRefNum,
AUTH_STR_PTR uniqName);
/* AuthMan API v2 additional prototypes */
AUTH_ROUTINE reloadAuthInfo(AUTH_SHORT authRefNum);
AUTH_ROUTINE getV4Ticket(AUTH_SHORT authRefNum,
AUTH_PTR ticketStorage,
AUTH_SHORT_PTR ticketLen,
AUTH_STR_PTR sName,
AUTH_STR_PTR sInstance,
AUTH_STR_PTR sRealm,
AUTH_LONG lifetimeInSecs,
AUTH_SHORT flag);
AUTH_ROUTINE expireV4Ticket(AUTH_SHORT authRefNum,
AUTH_STR_PTR sName,
AUTH_STR_PTR sInstance,
AUTH_STR_PTR sRealm);
AUTH_ROUTINE getV4TicketNinfo(AUTH_SHORT authRefNum,
AUTH_SHORT ticketNum,
_V4ticketInfoPtr ticketInfo);
AUTH_ROUTINE getRealmNinfo(AUTH_SHORT authRefNum,
AUTH_SHORT realmNum,
AUTH_STR_PTR realmName,
AUTH_SHORT_PTR AFSflag,
AUTH_SHORT_PTR numHosts);
AUTH_ROUTINE getRealmHostNinfo(AUTH_SHORT authRefNum,
AUTH_SHORT realmNum,
AUTH_SHORT hostNum,
AUTH_STR_PTR hostName,
AUTH_SHORT_PTR portNum);
/* AuthMan API v3 additional prototypes */
AUTH_ROUTINE doDES(AUTH_SHORT authRefNum,
AUTH_SHORT operation,
AUTH_PTR sessionKey,
AUTH_PTR buffer,
AUTH_LONG bufferLen);
AUTH_ROUTINE setV4Password(AUTH_SHORT authRefNum,
AUTH_STR_PTR pName,
AUTH_STR_PTR pInstance,
AUTH_STR_PTR pRealm);
AUTH_ROUTINE doMsgCallback(AUTH_SHORT authRefNum,
AUTH_SHORT callbackOperation,
AuthManCallbackUPP callbackRtn,
AUTH_LONG callbackMiscData,
AUTH_LONG userData);
/* AuthMan API v4 additional prototypes */
AUTH_ROUTINE getTicketCacheNinfo(AUTH_SHORT authRefNum,
AUTH_SHORT userNum,
AUTH_STR_PTR pName,
AUTH_STR_PTR pInstance,
AUTH_STR_PTR pRealm,
AUTH_SHORT_PTR status);
AUTH_ROUTINE setTicketCache(AUTH_SHORT authRefNum,
AUTH_STR_PTR pName,
AUTH_STR_PTR pInstance,
AUTH_STR_PTR pRealm);
AUTH_ROUTINE closeAuthMan(AUTH_SHORT authRefNum);
#ifdef __cplusplus
}
#endif
#endif /* __AUTHLIB__ */
---------------------------------------------------------------------------
AUTHLIBX.H -- a copy of the header file -- included here for reference
/*
AUTHLIBX.H -- Windows-only Extensions to the Kerberos Authentication
Services API
All functions declared here are exported by the AUTHLIB.DLL.
Last Modified Date: October 12, 1994 (mortong@ifs.umich.edu)
*/
#ifndef __AUTHLIBX__
#define __AUTHLIBX__
#ifdef __cplusplus
extern "C"
{
#endif
AUTH_ROUTINE expireAllV4Tickets(AUTH_SHORT refNum);
AUTH_ROUTINE doAuthentication(AUTH_SHORT refNum);
#ifdef __cplusplus
}
#endif
#endif /* __AUTHLIBX__ */
---------------------------------------------------------------------------
openAuthMan
Open a session with the Authentication DLL. Get a reference number and a
version number. AUTH_ERROR will be return if the DLL can not comply with
the request to open a session.
refNum
pointer to a short integer. On return the location pointed to will
contain a magic number which you must supply when requesting further
services from the Authentication DLL.
version
pointer to a short integer. On return the location pointed to will
contain the version level of the Authentication DLL.
AUTH_ROUTINE openAuthMan(AUTH_SHORT_PTR refNum,
AUTH_SHORT_PTR authAPIversion);
API note: This function must be called before any other calls are made to
the Authentication Services API.
API note: if an error is returned, the values *refNum and *version will be
meaningless.
---------------------------------------------------------------------------
getDefaultRealm
Ask the Authentication DLL for the name of the local Kerberos realm.
refNum
reference number returned by OpenAuthMan
realmName
pointer to an AUTH_SHORT_STR which will receive the name of the realm
realmType
pointer to a short integer -- on return, *realmType will be the constant
UNKNOWN_REALM_TYPE. (The Macintosh version behaves differently -- it can
distinguish realm types.)
AUTH_ROUTINE getDefaultRealm(AUTH_SHORT refNum,
AUTH_STR_PTR realmName,
AUTH_SHORT_PTR realmType);
API note: if an error is returned, realmName will be empty.
---------------------------------------------------------------------------
getAuthenticationStatus
Ask the Authentication DLL for the user's authentication status (authenti-
cated or not authenticated).
refNum
reference number returned by OpenAuthMan
status
pointer to a short
AUTH_ROUTINE getAuthenticationStatus(AUTH_SHORT refNum,
AUTH_SHORT_PTR status);
API note: if *status is non-zero, the user has been authenticated; if
*status is 0, the user hasn't. If an error is returned, *status will be
meaningless.
API note: you may prefer to use the getTicketCacheNinfo call -- see below.
---------------------------------------------------------------------------
getUniqname
Ask the Authentication DLL for the name under which the user has authenti-
cated.
refNum
reference number returned by OpenAuthMan
uniqName
pointer to a buffer which will receive the name -- this can be a fully
qualified name (uniqname.instance@realm) so the caller should allocate
MAX_K_NAME_SZ characters for this buffer -- if an error is returned,
uniqName will be the empty string
AUTH_ROUTINE getUniqname(AUTH_SHORT refNum,
AUTH_STR_PTR uniqName);
API note: you may prefer to use the getTicketCacheNinfo call -- see below.
---------------------------------------------------------------------------
setUniqname
Tell the Authentication DLL to fill the name field of the next authenti-
cation dialog or change-password dialog with the string passed as the
second argument (uniqName).
refNum
reference number returned by OpenAuthMan
uniqName
pointer to a string holding the name -- this can be a fully qualified
name (uniqname.instance@realm) -- the length of the string should not
exceed MAX_K_NAME_SZ
AUTH_ROUTINE setUniqname(AUTH_SHORT refNum,
AUTH_STR_PTR uniqName);
API note: you may prefer to use the setTicketCache call -- see below.
---------------------------------------------------------------------------
reloadAuthInfo
Tell the Authentication DLL to reload its internal ticket cache and its
internal realm and host tables from external sources.
refNum
reference number returned by OpenAuthMan
AUTH_ROUTINE reloadAuthInfo(AUTH_SHORT refNum);
API note: the Authentication DLL reloads its internal data structures
whenever it has reason to believe they might be invalid, so you probably
don't need to make this call except in very special circumstances.
---------------------------------------------------------------------------
getV4Ticket
Ask the Authentication DLL for a Kerberos v4 ticket.
refNum
reference number returned by OpenAuthMan
ticketStorage
pointer to a buffer where the ticket, if granted, will be placed -- the
caller should allocate at least MAX_KTXT_LEN characters for this buffer
ticketLength
pointer to a short integer -- on return *ticketLength will be the actual
length of ticket in the ticketStorage buffer
serviceName
pointer to a string designating the type of service for which a ticket is
desired -- the length of the string should not exceed SNAME_SZ
serviceInstance
pointer to a string holding the ID of a host which can grant a ticket of
type desired -- the length of the string should not exceed INST_SZ
serviceRealm
pointer to a string holding the name of the realm in which the host
identified by serviceInstance can be found -- the length of the string
should not exceed REALM_SZ
lifetimeInSecs
the duration (in seconds) over which the ticket obtained will be valid --
the constant INFINITE_LIFETIME may be used
flag
Currently only bit 0 is used -- the macros
DONT_PROMPT_FLAG 0x0000
PROMPT_FLAG 0x0001
are defined for this flag in AUTHLIB.H. If bit 0 is set, the user will be
prompted with an authentication dialog if not already authenticated -- if
bit 0 is not set, getV4Ticket will return an error if the the user is not
already authenticated.
AUTH_ROUTINE getV4Ticket(AUTH_SHORT refNum,
AUTH_PTR ticketStorage,
AUTH_SHORT_PTR ticketLen,
AUTH_STR_PTR sName,
AUTH_STR_PTR sInstance,
AUTH_STR_PTR sRealm,
AUTH_LONG lifetimeInSecs,
AUTH_SHORT flag);
API note: if an error is returned, ticketStorage and ticketLen will be
meaningless.
---------------------------------------------------------------------------
expireV4Ticket
Ask the Authentication DLL to destroy one or more Kerberos V4 tickets.
refNum
reference number returned by OpenAuthMan
serviceName
pointer to a string designating the service for which the ticket(s)
should be destroyed -- the length of the string should not exceed
SNAME_SZ
serviceInstance
pointer to a string holding the ID of a host that granted the tickets to
be destroyed -- the length of the string should not exceed INST_SZ
serviceRealm
pointer to a string holding the name of the realm in which the host
identified by serviceInstance can be found -- the length of the string
should not exceed REALM_SZ
AUTH_ROUTINE expireV4Ticket(AUTH_SHORT refNum,
AUTH_STR_PTR sName,
AUTH_STR_PTR sInstance,
AUTH_STR_PTR sRealm);
API note: this API call is not currently functional in AUTHLIB.DLL and will
always return AUTH_ERROR. Use the call expireAllV4Tickets described below.
The following notes will apply only when the call is fully supported.
API note: passing a NULL pointer for one of the pointer arguments acts as a
wild card. For example, passing serviceName = NULL, serviceInstance = NULL,
serviceRealm = "UMICH.EDU" deletes all UMICH.EDU realm tickets
API note: an error will be returned if tickets exist in the ticket cache
and parameters passed to ExpireV4Ticket match none of them.
---------------------------------------------------------------------------
getV4TicketNinfo
Ask the Authentication DLL to get Kerberos v4 ticket information from the
ticket cache.
refNum
reference number returned by OpenAuthMan
ticketNum
0 to n-1 (given n tickets in the cache)
ticketInfo
pointer to a _V4ticketInfo structure (see above) to where the ticket
information will be placed
AUTH_ROUTINE getV4TicketNinfo(AUTH_SHORT refNum,
AUTH_SHORT ticketNum,
_V4ticketInfoPtr ticketInfo);
API note: an error is returned if ticketNum is out of range. In this case
the contents of the ticketInfo will be meaningless.
API note: to build a ticket table, an application may choose to iterate on
this call, starting with ticketNum = 0, until it gets an error return.
API note: although not functional in the current version, someday ticketNum
= -1 will be taken to mean that getV4TicketNinfo should search the active
ticket cache for a match to the filled-in fields of the struct pointed to
by ticketInfo and, if successful, fill in the empty fields.
---------------------------------------------------------------------------
getRealmNinfo
Ask the Authentication DLL for Kerberos realm information.
refNum
reference number returned by OpenAuthMan
realmNum
0 to n-1 (given n realms in the realm/host cache)
realmName
pointer to an AUTH_SHORT_STR which will receive the name of the realm
AFSFlag
pointer to a short integer -- on return, *realmType will be the constant
UNKNOWN_REALM_TYPE
numHosts
pointer to a short integer -- on return, *numHosts will be the host
count.
AUTH_ROUTINE getRealmNinfo(AUTH_SHORT refNum,
AUTH_SHORT realmNum,
AUTH_STR_PTR realmName,
AUTH_SHORT_PTR AFSFlag,
AUTH_SHORT_PTR numHosts);
API note: the Macintosh implementation retrieves the information from
internal resources; the Windows implementation retrieves it from
C:NETKERBKRB.CON.
API note: an error is returned if realmNum is out of range. In this
case the dereferenced values of realmName, AFSFlag, and numHosts will
be meaningless.
API note: the Macintosh implementation discriminates realm types, the
Windows implementation does not.
API note: to build a realm table, an application may choose to iterate
on this call, starting with realmNum = 0, until it gets an error
return.
API note: although not functional in the current version, someday realmNum
= -1 will be taken to mean that getRealmNinfo should search for a match on
realmName in the realm table and, if successful, pass back realm number,
realm type, and number of hosts.
---------------------------------------------------------------------------
getRealmHostNinfo
Ask the Authentication DLL for the hosts servicing a specified Kerberos
realm.
refNum
reference number returned by OpenAuthMan
realmNum
0 to n-1 (given n realms known to Authentication DLL)
hostNum
0 to n-1 (given n hosts in the specified realm)
hostName
pointer to an AUTH_SHORT_STR which will receive the name of the host
portNum
pointer to a short integer -- on return, *portNum will be the port
number.
AUTH_ROUTINE getRealmHostNinfo(AUTH_SHORT refNum,
AUTH_SHORT realmNum,
AUTH_SHORT hostNum,
AUTH_STR_PTR hostName,
AUTH_SHORT_PTR portNum);
API note: an error is returned if realmNum or hostNum is out of range. In
this case the dereferenced values of hostName and portNum will be
meaningless.
API note: to build a host table, an application may choose to iterate on
this call, starting with hostNum = 0, until it gets an error return.
API note: although not functional in the current version, someday hostNum =
-1 will be taken to mean that getRealmHostNinfo should search for a match
on hostName in the host table of the realm designated by realmNum and, if
successful, and pass back host number and port number.
---------------------------------------------------------------------------
doDES
Ask the Authentication DLL to encrypt or decrypt blocks of memory using
DES.
refNum
reference number returned by OpenAuthMan
operation
an operation code with a modifier (see above)
sessionKey
pointer to a memory block -- see API note below
buffer
pointer to the string to be encrypted or decrypted
bufferLen
number of characters to be encrypted or decrypted
AUTH_ROUTINE doDES(AUTH_SHORT refNum,
AUTH_SHORT operation,
AUTH_PTR sessionKey,
AUTH_PTR buffer,
AUTH_LONG bufferLen);
API note: Use GetV4TicketNinfo to get the session key.
API note: when operation is DES_PCBC-based, buffer data and bufferLen must
be a 8-byte multiple -- when operation is DES_ECB-based, buffer data and
bufferLen must be exactly 8 bytes
API note: this call is not functional in the Windows implementation which
will always return AUTH_ERROR.
---------------------------------------------------------------------------
setV4Password
Ask the Authentication DLL to set a new Kerberos password for user. This
function calls the Lsh_Change_Password_Dialog function provided in
KRBV4WIN.DLL which handles the whole password changing process, including
presenting the user with a non-modal dialog to get the user's uniqname,
old password, and new password.
refNum
reference number returned by OpenAuthMan
pName
pointer to an AUTH_SHORT_STR holding the user's uniqname
pInstance
pointer to an AUTH_SHORT_STR holding a user's instance (for example:
root) -- can be an empty string
pRealm
pointer to an AUTH_SHORT_STR holding the name of the realm of the
Kerberos server on which the password will be changed
AUTH_ROUTINE setV4Password(AUTH_SHORT refNum,
AUTH_STR_PTR pName,
AUTH_STR_PTR pInstance,
AUTH_STR_PTR pRealm);
API note: the principalName, principalInstance, and principalRealm
parameters will appear as suggested values when the change-password dialog
comes up.
---------------------------------------------------------------------------
doMsgCallback
This API call is a place-holder to accomodate the Macintosh Authentication
Manager API. It will always return AUTH_ERROR.
AUTH_ROUTINE doMsgCallback(AUTH_SHORT refNum,
AUTH_SHORT callbackOperation,
AuthManCallbackUPP callbackRtn,
AUTH_LONG callbackMiscData,
AUTH_LONG userData);
---------------------------------------------------------------------------
getTicketCacheNinfo
Ask the Authentication DLL for information concerning a ticket cache.
refNum
reference number returned by OpenAuthMan
userNum
0 to n-1 (given n user ticket caches in use)
pName
pointer to an AUTH_SHORT_STR to receive the user's uniqname
pInstance
pointer to an AUTH_SHORT_STR to receive the user's instance (for example:
root) -- may be an empty string
pRealm
pointer to an AUTH_SHORT_STR to receive the name of the realm in which
the user is authenticated
status
pointer to a short integer -- on return from getTicketCacheNinfo, *status
will be non-zero when the user indexed by userNum is the currently
authenticated user and 0 otherwise
AUTH_ROUTINE getTicketCacheNinfo(AUTH_SHORT refNum,
AUTH_SHORT userNum,
AUTH_STR_PTR pName,
AUTH_STR_PTR pInstance,
AUTH_STR_PTR pRealm,
AUTH_SHORT_PTR status);
API note: currently userNum must be either -1 or zero since there is only
one ticket cache. Someday this API call will support of multi-user
authentication. When that happens, it may be called with userNum set to
values greater than zero.
API note: getTicketCacheNinfo returns AUTH_END_OF_LIST if no user is
authenticated. This means it can be used to replace calls to both
getUniqname and getAuthenticationStatus with a single call.
API note: although not functional in the current version, someday userNum =
-1 will be taken to mean that getTicketCacheNinfo should search for a match
on the non-empty pName, pInstance, pRealm arguments and, if successful,
fill in the empty arguments and assign values to userNum and status.
---------------------------------------------------------------------------
setTicketCache
Tell the Authentication DLL to designate the ticket cache for the user
authenticated as <pName>@<pRealm>, when pInstance is an empty string, or
<pName>.<pInstance>@<pRealm> as the active ticket cache, i.e., the cache to
which tickets operations will apply until the next call to setTicketCache.
If no such ticket cache exists an error is returned.
refNum
reference number returned by OpenAuthMan
pName
pointer to an AUTH_SHORT_STR holding the user's uniqname
pInstance
pointer to an AUTH_SHORT_STR holding the user's instance (for example:
root)
pRealm
pointer to an AUTH_SHORT_STR holding the name of the realm of the
realm where the user wishes to be authenicated
AUTH_ROUTINE setTicketCache(AUTH_SHORT refNum,
AUTH_STR_PTR pName,
AUTH_STR_PTR pInstance,
AUTH_STR_PTR pRealm);
API note: since only a single ticket cache is supported in the current
AUTHLIB.DLL, this function will return AUTH_ERROR unless pName, pInstance,
and pRealm can be matched in that single ticket cache.
API note: in a future version of AUTHLIB.DLL with support for multiple
ticket caches, this function will search all the ticket caches and return
and error only if it finds a match in none of the caches.
---------------------------------------------------------------------------
closeAuthMan
Tell the Authentication DLL that it can invalidate your session because you
won't be making more requests. Windows applications using the Authentica-
tion DLL _must_ call this function before they exit.
refNum
reference number returned by OpenAuthMan
AUTH_ERR AUTH_ROUTINE closeAuthMan(AUTH_SHORT refNum);
---------------------------------------------------------------------------
expireAllV4Tickets
Ask the Authentication DLL to destroy all the Kerberos V4 tickets in the
external ticket cache. This also invalidates the internal ticket cache.
refNum
reference number returned by OpenAuthMan
AUTH_ROUTINE expireAllV4Tickets(AUTH_SHORT refNum);
---------------------------------------------------------------------------
doAuthentication
Ask the Authentication DLL to require the user to authenticate with
Kerberos. This function calls the Lsh_Enter_Password_Dialog function
provided in KRBV4WIN.DLL which handles the whole authentication process,
including presenting the user with a non-modal dialog to get the user's
uniqname, password, and the lifetime (in minutes) of the ticket-granting
ticket.
refNum
reference number returned by OpenAuthMan
AUTH_ROUTINE doAuthentication(AUTH_SHORT refNum);
API note: this function is intended only for the use of AUTH.EXE or similar
authentication utilities. Applications which only need service tickets
should not call doAuthentication; they should call getV4Ticket with the
flag argument set to PROMPT_FLAG.
---------------------------------------------------------------------------
