src/WINNT/kfw/inc/krbcc/cacheapi.h

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