/* * $Id$ * * Copyright 1997 by the Regents of the University of Michigan * * This software is being provided to you, the LICENSEE, by the * Regents of the University of Michigan (UM) under the following * license. By obtaining, using and/or copying this software, you agree * that you have read, understood, and will comply with these terms and * conditions: * * Permission to use, copy, modify and distribute this software and its * documentation for any purpose and without fee or royalty is hereby * granted, provided that you agree to comply with the following copyright * notice and statements, including the disclaimer, and that the same * appear on ALL copies of the software and documentation, including * modifications that you make for internal use or for distribution: * * Copyright 1997 by the Regents of the University of Michigan. * All rights reserved. * * THIS SOFTWARE IS PROVIDED "AS IS", AND UM MAKES NO REPRESENTATIONS * OR WARRANTIES, EXPRESS OR IMPLIED. By way of example, but not * limitation, UM MAKES NO REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY * OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE LICENSED * SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, * COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. * * The name of the University of Michigan or UM may NOT be used in * advertising or publicity pertaining to distribution of the software. * Title to copyright in this software and any associated documentation * shall at all times remain with UM, and USER agrees to preserve same. * * The University of Michigan * c/o Steve Rothwell * 535 W. William Street * Ann Arbor, Michigan 48013-4943 * U.S.A. */ /* ** CacheAPI.h ** ** The externally visible functions and data structures ** for the Kerberos Common Cache DLL ** This should be the ONLY externally visible file. ** This is ALL anyone should need to call the API. ** ** */ #include #ifndef Krb_CCacheAPI_h_ #define Krb_CCacheAPI_h_ #include #define CC_API_VER_1 1 #define CCACHE_API __declspec(dllexport) cc_int32 //#define CCACHE_API __declspec( dllexport ) cc_int32 __stdcall /* ** Decisions I haven't nailed down yet */ // determines if cred_type precedes ptrs to creds in cred_union //#define CRED_TYPE_IN_UNION // // JENNYEXT - modifications Jenny made to cacheapi for MIT code // not blessed, but reproduced temporarily #ifndef JENNYEXT #define JENNYEXT #endif /* ** The Official Error Codes */ #define CC_NOERROR 0 #define CC_BADNAME 1 #define CC_NOTFOUND 2 #define CC_END 3 #define CC_IO 4 #define CC_WRITE 5 #define CC_NOMEM 6 #define CC_FORMAT 7 #define CC_LOCKED 8 #define CC_BAD_API_VERSION 9 #define CC_NO_EXIST 10 #define CC_NOT_SUPP 11 #define CC_BAD_PARM 12 #define CC_ERR_CACHE_ATTACH 13 #define CC_ERR_CACHE_RELEASE 14 #define CC_ERR_CACHE_FULL 15 #define CC_ERR_CRED_VERSION 16 /* ** types, structs, & constants */ typedef int cc_int32; typedef cc_int32 cc_time_t; // Flag bits promised by Ted "RSN" #define CC_FLAGS_RESERVED 0xFFFFFFFF typedef cc_int32 cc_nc_flags; // set via constants above typedef struct opaque_ccache_pointer_type* ccache_p; typedef struct opaque_dll_control_block_type* apiCB; typedef struct opaque_credential_iterator_type* ccache_cit; enum { KRB5_CLIENT_SZ = 256}; enum { KRB5_SERVER_SZ = 256}; enum { KRB5_DATA_SZ = 1024}; enum { KRB5_DATA_CNT = 20}; enum _cc_data_type { type_ticket = 0, // 0 for ticket, second_ticket /* Ted's draft spec says these are to be "as defined in the Kerberos V5 protocol" all I can find are typdefs, can't find an enumerated type or #define */ type_address, /* = <"as defined in the Kerberos V5 protocol"> */ type_authdata, /* = <"as defined in the Kerberos V5 protocol"> */ type_encryption, /* = <"as defined in the Kerberos V5 protocol"> */ cc_data_type_max }; // for validation typedef struct _cc_data { cc_int32 type; // should be one of _cc_data_type cc_int32 length; unsigned char* data; // the proverbial bag-o-bits } cc_data; typedef struct _cc_data1 { cc_int32 type; // should be one of _cc_data_type cc_int32 length; unsigned char data[KRB5_DATA_SZ]; // the proverbial bag-o-bits } cc_data1; // V5 Credentials typedef struct _cc_creds { char* client; char* server; cc_data keyblock; cc_time_t authtime; cc_time_t starttime; cc_time_t endtime; cc_time_t renew_till; cc_int32 is_skey; cc_int32 ticket_flags; cc_data FAR ** addresses; cc_data ticket; cc_data second_ticket; cc_data FAR ** authdata; } cc_creds; typedef struct _cc_cache_creds { char client[KRB5_CLIENT_SZ]; char server[KRB5_SERVER_SZ]; cc_data1 keyblock; cc_time_t authtime; cc_time_t starttime; cc_time_t endtime; cc_time_t renew_till; cc_int32 is_skey; cc_int32 ticket_flags; cc_data1 addresses[KRB5_DATA_CNT]; cc_data1 ticket; cc_data1 second_ticket; cc_data1 authdata[KRB5_DATA_CNT]; } cc_cache_creds; // begin V4 stuff enum { KRB_PRINCIPAL_SZ = 40 }; enum { KRB_SERVICE_SZ = 40}; enum { KRB_INSTANCE_SZ = 40}; enum { KRB_REALM_SZ = 40}; #ifndef ADDR_SZ enum { ADDR_SZ = 16}; #endif // use an enumerated type so all callers infer the same meaning // these values are what krbv4win uses internally. enum StringToKey_Type { STK_AFS = 0, STK_DES = 1 }; // K4 uses a MAX_KTXT_LEN of 1250 to hold a ticket // K95 uses 256 // To be safe I'll use the larger number, but a factor of 5!!! enum { MAX_V4_CRED_LEN = 1250 }; // V4 Credentials typedef struct cc_V4credential { unsigned char kversion; char principal[KRB_PRINCIPAL_SZ]; char principal_instance[KRB_INSTANCE_SZ]; char service[KRB_SERVICE_SZ]; char service_instance[KRB_INSTANCE_SZ]; char realm[KRB_REALM_SZ]; unsigned char session_key[8]; cc_int32 kvno; // k95 used BYTE skvno enum StringToKey_Type str_to_key; // k4 infers dynamically, k95 stores long issue_date; // k95 called this issue_time cc_int32 lifetime; // k95 used LONG expiration_time char address[ADDR_SZ]; // IP Address of local host cc_int32 ticket_sz; // k95 used BYTE, k4 ktext uses int to hold up to 1250 unsigned char ticket[MAX_V4_CRED_LEN]; unsigned long oops; // zero to catch runaways } V4Cred_type; #ifdef JENNYEXT typedef struct cc_V4credential CCV4CREDENTIALS; // JENNYEXT #endif enum cc_cred_vers { CC_CRED_VUNKNOWN = 0, // For validation CC_CRED_V4 = 1, CC_CRED_V5 = 2, CC_CRED_VMAX = 3 // For validation }; typedef union cred_ptr_union_type { V4Cred_type* pV4Cred; cc_creds* pV5Cred; } cred_ptr_union; typedef struct cred_union_type { //#ifdef CRED_TYPE_IN_UNION enum cc_cred_vers cred_type; //#endif cred_ptr_union cred; } cred_union; /* ** The official (externally visible) API */ #ifdef __cplusplus extern "C" /* this entire list of functions */ { #endif /* __cplusplus */ /* ** Main cache routines : initialize, shutdown, get_cache_names, & get_change_time */ CCACHE_API cc_initialize(apiCB** cc_ctx, // < DLL's primary control structure. // returned here, passed everywhere else const cc_int32 api_version,// > ver supported by caller (use CC_API_VER_1) cc_int32* api_supported, // < if ~NULL, max ver supported by DLL const char** vendor); // < if ~NULL, vendor name in read only C string CCACHE_API cc_shutdown(apiCB** cc_ctx); // <> DLL's primary control structure. NULL after call. CCACHE_API cc_get_change_time(apiCB* cc_ctx, // > DLL's primary control structure cc_time_t* time); // < time of last change to main cache /* ** Named Cache (NC) routines ** create, open, close, destroy, get_principal, get_cred_version, & lock_request ** ** Multiple NCs are allowed within the main cache. Each has a Name and kerberos ** version # (V4 or V5). Caller gets "ccache_ptr"s for NCs. */ CCACHE_API cc_create(apiCB* cc_ctx, // > DLL's primary control structure const char* name, // > name of cache to be [destroyed if exists, then] created const char* principal, // > name of principal associated with NC const enum cc_cred_vers vers, // > ticket version (CC_CRED_V4 or CC_CRED_V5) const cc_int32 cc_flags, // > options ccache_p** ccache_ptr); // < NC control structure CCACHE_API cc_open(apiCB* cc_ctx, // > DLL's primary control structure const char* name, // > name of pre-created cache const enum cc_cred_vers vers, // > ticket version (CC_CRED_V4 or CC_CRED_V5) const cc_int32 cc_flags, // > options ccache_p** ccache_ptr); // < NC control structure CCACHE_API cc_close(apiCB* cc_ctx, // > DLL's primary control structure ccache_p** ccache_ptr); // <> NC control structure. NULL after call. CCACHE_API cc_destroy(apiCB* cc_ctx, // > DLL's primary control structure ccache_p** ccache_ptr); // <> NC control structure. NULL after call. /* ** Ways to get information about the NCs */ CCACHE_API cc_seq_fetch_NCs(apiCB* cc_ctx, // > DLL's primary control structure ccache_p** ccache_ptr, // < NC control structure (free via cc_close()) ccache_cit** itNCs); // <> iterator used by DLL, // set to NULL before first call // returned NULL at CC_END typedef struct _infoNC { char* name; enum cc_cred_vers vers; } infoNC; CCACHE_API cc_get_NC_info(apiCB* cc_ctx, // > DLL's primary control structure struct _infoNC*** ppNCi); // < (NULL before call) null terminated, // list of a structs (free via cc_free_infoNC()) CCACHE_API cc_free_NC_info(apiCB* cc_ctx, struct _infoNC*** ppNCi); // < free list of structs returned by cc_get_cache_names() // set to NULL on return /* ** Functions that provide distinguishing characteristics of NCs. */ CCACHE_API cc_get_name(apiCB* cc_ctx, // > DLL's primary control structure const ccache_p* ccache_ptr, // > NC control structure char** name); // < name of NC associated with ccache_ptr (free via cc_free_name()) CCACHE_API cc_set_principal(apiCB* cc_ctx, // > DLL's primary control structure const ccache_p* ccache_pointer,// < name of principal associated with NC const enum cc_cred_vers vers, // Free via cc_free_principal() const char* principal); CCACHE_API cc_get_principal(apiCB* cc_ctx, // > DLL's primary control structure ccache_p* ccache_pointer, // < name of principal associated with NC char** principal); // Free via cc_free_principal() #ifdef JENNYEXT CCACHE_API cc_set_instance(apiCB* cc_ctx, // > DLL's primary control structure const char* instance); // < name of principal_instance associated with NC // Free via cc_free_instance() CCACHE_API cc_get_instance(apiCB* cc_ctx, // > DLL's primary control structure char** instance); // < name of principal_instance associated with NC // Free via cc_free_instance() #endif /* JENNYEXT */ CCACHE_API cc_get_cred_version(apiCB* cc_ctx, // > DLL's primary control structure const ccache_p* ccache_ptr,// > NC control structure enum cc_cred_vers* vers);// < ticket version associated with NC #define CC_LOCK_UNLOCK 1 #define CC_LOCK_READER 2 #define CC_LOCK_WRITER 3 #define CC_LOCK_NOBLOCK 16 CCACHE_API cc_lock_request(apiCB* cc_ctx, // > DLL's primary control structure const ccache_p* ccache_ptr,// > NC control structure const cc_int32 lock_type);// > one (or combination) of above defined lock types /* ** Credentials routines (work within an NC) ** store, remove_cred, seq_fetch_creds */ CCACHE_API cc_store(apiCB* cc_ctx, // > DLL's primary control structure const ccache_p* ccache_ptr, // > NC control structure const cred_union creds); // > credentials to be copied into NC CCACHE_API cc_remove_cred(apiCB* cc_ctx, // > DLL's primary control structure const ccache_p* ccache_ptr, // > NC control structure const cred_union cred); // > credentials to remove from NC CCACHE_API cc_seq_fetch_creds(apiCB* cc_ctx, // > DLL's primary control structure const ccache_p* ccache_ptr, // > NC control structure cred_union** creds, // < filled in by DLL, free via cc_free_creds() ccache_cit** itCreds); // <> iterator used by DLL, set to NULL before first call // Also NULL for final call if loop ends before CC_END /* ** methods of liberation, ** or freeing space via the free that goes with the malloc used to get it ** It's important to use the free carried in the DLL, not the one supplied ** by your compiler vendor. ** ** freeing a NULL pointer is not treated as an error */ CCACHE_API cc_free_principal(apiCB* cc_ctx, // > DLL's primary control structure char** principal); // <> ptr to principal to be freed, returned as NULL // (from cc_get_principal()) #ifdef JENNYEXT CCACHE_API cc_free_instance(apiCB* cc_ctx, // > DLL's primary control structure char** instance); // <> ptr to instance to be freed, returned as NULL // (from cc_get_instance()) #endif CCACHE_API cc_free_name(apiCB* cc_ctx, // > DLL's primary control structure char** name); // <> ptr to name to be freed, returned as NULL // (from cc_get_name()) CCACHE_API cc_free_name_list(apiCB* cc_ctx, // > DLL's primary control structure char*** name_list); // <> ptr to null terminated list of names to be freed // (from cc_get_cache_names()), returned as NULL CCACHE_API cc_free_creds(apiCB* cc_ctx, // > DLL's primary control structure cred_union** pCred); // <> cred (from cc_seq_fetch_creds()) to be freed // Returned as NULL. #ifdef __cplusplus } /* end extern "C" */ #endif /* __cplusplus */ #endif /* Krb_CCacheAPI_h_ */