1 /* windows/lib/cacheapi.h */ 2 /* 3 * Copyright 1997 by the Regents of the University of Michigan 4 * 5 * This software is being provided to you, the LICENSEE, by the 6 * Regents of the University of Michigan (UM) under the following 7 * license. By obtaining, using and/or copying this software, you agree 8 * that you have read, understood, and will comply with these terms and 9 * conditions: 10 * 11 * Permission to use, copy, modify and distribute this software and its 12 * documentation for any purpose and without fee or royalty is hereby 13 * granted, provided that you agree to comply with the following copyright 14 * notice and statements, including the disclaimer, and that the same 15 * appear on ALL copies of the software and documentation, including 16 * modifications that you make for internal use or for distribution: 17 * 18 * Copyright 1997 by the Regents of the University of Michigan. 19 * All rights reserved. 20 * 21 * THIS SOFTWARE IS PROVIDED "AS IS", AND UM MAKES NO REPRESENTATIONS 22 * OR WARRANTIES, EXPRESS OR IMPLIED. By way of example, but not 23 * limitation, UM MAKES NO REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY 24 * OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE LICENSED 25 * SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, 26 * COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. 27 * 28 * The name of the University of Michigan or UM may NOT be used in 29 * advertising or publicity pertaining to distribution of the software. 30 * Title to copyright in this software and any associated documentation 31 * shall at all times remain with UM, and USER agrees to preserve same. 32 * 33 * The University of Michigan 34 * c/o Steve Rothwell <sgr@umich.edu> 35 * 535 W. William Street 36 * Ann Arbor, Michigan 48013-4943 37 * U.S.A. 38 */ 39 40 /* 41 ** CacheAPI.h 42 ** 43 ** The externally visible functions and data structures 44 ** for the Kerberos Common Cache DLL 45 ** This should be the ONLY externally visible file. 46 ** This is ALL anyone should need to call the API. 47 ** 48 ** 49 */ 50 51 #ifndef Krb_CCacheAPI_h_ 52 #define Krb_CCacheAPI_h_ 53 54 #include <windows.h> 55 56 //typedef int cc_int32; 57 #define cc_int32 long 58 #define cc_uint32 unsigned long 59 60 typedef cc_int32 cc_time_t; 61 62 #define CC_API_VER_1 1 63 #define CC_API_VER_2 2 64 65 //enum { 66 // CC_API_VER_1 = 1, 67 // CC_API_VER_2 = 2 68 //}; 69 70 #define CCACHE_API __declspec(dllexport) cc_int32 71 72 /* 73 ** The Official Error Codes 74 */ 75 #define CC_NOERROR 0 76 #define CC_BADNAME 1 77 #define CC_NOTFOUND 2 78 #define CC_END 3 79 #define CC_IO 4 80 #define CC_WRITE 5 81 #define CC_NOMEM 6 82 #define CC_FORMAT 7 83 #define CC_LOCKED 8 84 #define CC_BAD_API_VERSION 9 85 #define CC_NO_EXIST 10 86 #define CC_NOT_SUPP 11 87 #define CC_BAD_PARM 12 88 #define CC_ERR_CACHE_ATTACH 13 89 #define CC_ERR_CACHE_RELEASE 14 90 #define CC_ERR_CACHE_FULL 15 91 #define CC_ERR_CRED_VERSION 16 92 93 /* 94 ** types, structs, & constants 95 */ 96 // Flag bits promised by Ted "RSN" 97 #define CC_FLAGS_RESERVED 0xFFFFFFFF 98 99 typedef cc_uint32 cc_nc_flags; // set via constants above 100 101 typedef struct opaque_dll_control_block_type* apiCB; 102 typedef struct opaque_ccache_pointer_type* ccache_p; 103 typedef struct opaque_credential_iterator_type* ccache_cit; 104 105 typedef struct _cc_data 106 { 107 cc_uint32 type; // should be one of _cc_data_type 108 cc_uint32 length; 109 unsigned char* data; // the proverbial bag-o-bits 110 } cc_data; 111 112 // V5 Credentials 113 typedef struct _cc_creds { 114 char* client; 115 char* server; 116 cc_data keyblock; 117 cc_time_t authtime; 118 cc_time_t starttime; 119 cc_time_t endtime; 120 cc_time_t renew_till; 121 cc_uint32 is_skey; 122 cc_uint32 ticket_flags; 123 cc_data ** addresses; 124 cc_data ticket; 125 cc_data second_ticket; 126 cc_data ** authdata; 127 } cc_creds; 128 129 130 typedef union cred_ptr_union_type { 131 cc_creds* pV5Cred; 132 } cred_ptr_union; 133 134 typedef struct cred_union_type { 135 cc_int32 cred_type; 136 cred_ptr_union cred; 137 } cred_union; 138 139 typedef struct _infoNC { 140 char* name; 141 char* principal; 142 cc_int32 vers; 143 } infoNC; 144 145 /* 146 ** The official (externally visible) API 147 */ 148 149 #ifdef __cplusplus 150 extern "C" /* this entire list of functions */ 151 { 152 #endif /* __cplusplus */ 153 154 /* 155 ** Main cache routines : initialize, shutdown, get_cache_names, & get_change_time 156 */ 157 CCACHE_API 158 cc_initialize( 159 apiCB** cc_ctx, // < DLL's primary control structure. 160 // returned here, passed everywhere else 161 cc_int32 api_version, // > ver supported by caller (use CC_API_VER_1) 162 cc_int32* api_supported, // < if ~NULL, max ver supported by DLL 163 const char** vendor // < if ~NULL, vendor name in read only C string 164 ); 165 166 CCACHE_API 167 cc_shutdown( 168 apiCB** cc_ctx // <> DLL's primary control structure. NULL after call. 169 ); 170 171 CCACHE_API 172 cc_get_change_time( 173 apiCB* cc_ctx, // > DLL's primary control structure 174 cc_time_t* time // < time of last change to main cache 175 ); 176 177 /* 178 ** Named Cache (NC) routines 179 ** create, open, close, destroy, get_principal, get_cred_version, & 180 ** lock_request 181 ** 182 ** Multiple NCs are allowed within the main cache. Each has a Name and 183 ** kerberos version # (V5). Caller gets "ccache_ptr"s for NCs. 184 */ 185 CCACHE_API 186 cc_create( 187 apiCB* cc_ctx, // > DLL's primary control structure 188 const char* name, // > name of cache to be [destroyed if exists, then] created 189 const char* principal, 190 cc_int32 vers, // > ticket version (CC_CRED_V5) 191 cc_uint32 cc_flags, // > options 192 ccache_p** ccache_ptr // < NC control structure 193 ); 194 195 CCACHE_API 196 cc_open( 197 apiCB* cc_ctx, // > DLL's primary control structure 198 const char* name, // > name of pre-created cache 199 cc_int32 vers, // > ticket version (CC_CRED_V5) 200 cc_uint32 cc_flags, // > options 201 ccache_p** ccache_ptr // < NC control structure 202 ); 203 204 CCACHE_API 205 cc_close( 206 apiCB* cc_ctx, // > DLL's primary control structure 207 ccache_p** ccache_ptr // <> NC control structure. NULL after call. 208 ); 209 210 CCACHE_API 211 cc_destroy( 212 apiCB* cc_ctx, // > DLL's primary control structure 213 ccache_p** ccache_ptr // <> NC control structure. NULL after call. 214 ); 215 216 /* 217 ** Ways to get information about the NCs 218 */ 219 220 CCACHE_API 221 cc_seq_fetch_NCs_begin( 222 apiCB* cc_ctx, 223 ccache_cit** itNCs 224 ); 225 226 CCACHE_API 227 cc_seq_fetch_NCs_end( 228 apiCB* cc_ctx, 229 ccache_cit** itNCs 230 ); 231 232 CCACHE_API 233 cc_seq_fetch_NCs_next( 234 apiCB* cc_ctx, 235 ccache_p** ccache_ptr, 236 ccache_cit* itNCs 237 ); 238 239 CCACHE_API 240 cc_seq_fetch_NCs( 241 apiCB* cc_ctx, // > DLL's primary control structure 242 ccache_p** ccache_ptr, // < NC control structure (free via cc_close()) 243 ccache_cit** itNCs // <> iterator used by DLL, 244 // set to NULL before first call 245 // returned NULL at CC_END 246 ); 247 248 CCACHE_API 249 cc_get_NC_info( 250 apiCB* cc_ctx, // > DLL's primary control structure 251 struct _infoNC*** ppNCi // < (NULL before call) null terminated, 252 // list of a structs (free via cc_free_infoNC()) 253 ); 254 255 CCACHE_API 256 cc_free_NC_info( 257 apiCB* cc_ctx, 258 struct _infoNC*** ppNCi // < free list of structs returned by 259 // cc_get_cache_names(). set to NULL on return 260 ); 261 262 /* 263 ** Functions that provide distinguishing characteristics of NCs. 264 */ 265 266 CCACHE_API 267 cc_get_name( 268 apiCB* cc_ctx, // > DLL's primary control structure 269 const ccache_p* ccache_ptr, // > NC control structure 270 char** name // < name of NC associated with ccache_ptr 271 // (free via cc_free_name()) 272 ); 273 274 CCACHE_API 275 cc_set_principal( 276 apiCB* cc_ctx, // > DLL's primary control structure 277 const ccache_p* ccache_pointer, // > NC control structure 278 const cc_int32 vers, 279 const char* principal // > name of principal associated with NC 280 // Free via cc_free_principal() 281 ); 282 283 CCACHE_API 284 cc_get_principal( 285 apiCB* cc_ctx, // > DLL's primary control structure 286 const ccache_p* ccache_pointer, // > NC control structure 287 char** principal // < name of principal associated with NC 288 // Free via cc_free_principal() 289 ); 290 291 CCACHE_API 292 cc_get_cred_version( 293 apiCB* cc_ctx, // > DLL's primary control structure 294 const ccache_p* ccache_ptr, // > NC control structure 295 cc_int32* vers // < ticket version associated with NC 296 ); 297 298 #define CC_LOCK_UNLOCK 1 299 #define CC_LOCK_READER 2 300 #define CC_LOCK_WRITER 3 301 #define CC_LOCK_NOBLOCK 16 302 303 CCACHE_API 304 cc_lock_request( 305 apiCB* cc_ctx, // > DLL's primary control structure 306 const ccache_p* ccache_ptr, // > NC control structure 307 const cc_int32 lock_type // > one (or combination) of above defined 308 // lock types 309 ); 310 311 /* 312 ** Credentials routines (work within an NC) 313 ** store, remove_cred, seq_fetch_creds 314 */ 315 CCACHE_API 316 cc_store( 317 apiCB* cc_ctx, // > DLL's primary control structure 318 ccache_p* ccache_ptr, // > NC control structure 319 const cred_union creds // > credentials to be copied into NC 320 ); 321 322 CCACHE_API 323 cc_remove_cred( 324 apiCB* cc_ctx, // > DLL's primary control structure 325 ccache_p* ccache_ptr, // > NC control structure 326 const cred_union cred // > credentials to remove from NC 327 ); 328 329 CCACHE_API 330 cc_seq_fetch_creds( 331 apiCB* cc_ctx, // > DLL's primary control structure 332 const ccache_p* ccache_ptr, // > NC control structure 333 cred_union** creds, // < filled in by DLL, free via cc_free_creds() 334 ccache_cit** itCreds // <> iterator used by DLL, set to NULL 335 // before first call -- Also NULL for final 336 // call if loop ends before CC_END 337 ); 338 339 CCACHE_API 340 cc_seq_fetch_creds_begin( 341 apiCB* cc_ctx, 342 const ccache_p* ccache_ptr, 343 ccache_cit** itCreds 344 ); 345 346 CCACHE_API 347 cc_seq_fetch_creds_end( 348 apiCB* cc_ctx, 349 ccache_cit** itCreds 350 ); 351 352 CCACHE_API 353 cc_seq_fetch_creds_next( 354 apiCB* cc_ctx, 355 cred_union** cred, 356 ccache_cit* itCreds 357 ); 358 359 /* 360 ** methods of liberation, 361 ** or freeing space via the free that goes with the malloc used to get it 362 ** It's important to use the free carried in the DLL, not the one supplied 363 ** by your compiler vendor. 364 ** 365 ** freeing a NULL pointer is not treated as an error 366 */ 367 CCACHE_API 368 cc_free_principal( 369 apiCB* cc_ctx, // > DLL's primary control structure 370 char** principal // <> ptr to principal to be freed, returned as NULL 371 // (from cc_get_principal()) 372 ); 373 374 CCACHE_API 375 cc_free_name( 376 apiCB* cc_ctx, // > DLL's primary control structure 377 char** name // <> ptr to name to be freed, returned as NULL 378 // (from cc_get_name()) 379 ); 380 381 CCACHE_API 382 cc_free_creds( 383 apiCB* cc_ctx, // > DLL's primary control structure 384 cred_union** pCred // <> cred (from cc_seq_fetch_creds()) to be freed 385 // Returned as NULL. 386 ); 387 388 #ifdef __cplusplus 389 } /* end extern "C" */ 390 #endif /* __cplusplus */ 391 392 #endif /* Krb_CCacheAPI_h_ */ 393