cacheapi.h

/* windows/lib/cacheapi.h */
/*
 * 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 <[email protected]>
 * 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.
**
**
*/

#ifndef Krb_CCacheAPI_h_
#define Krb_CCacheAPI_h_

#include <windows.h>

//typedef int cc_int32;
#define cc_int32  long
#define cc_uint32 unsigned long

typedef cc_int32  cc_time_t;

#define CC_API_VER_1	1
#define CC_API_VER_2	2

//enum {
//	CC_API_VER_1 = 1,
//	CC_API_VER_2 = 2
//};

#define CCACHE_API __declspec(dllexport) cc_int32

/*
** 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
*/
// Flag bits promised by Ted "RSN"
#define CC_FLAGS_RESERVED 0xFFFFFFFF

typedef cc_uint32 cc_nc_flags;       // set via constants above

typedef struct opaque_dll_control_block_type* apiCB;
typedef struct opaque_ccache_pointer_type* ccache_p;
typedef struct opaque_credential_iterator_type* ccache_cit;

typedef struct _cc_data
{
    cc_uint32       type;		// should be one of _cc_data_type
    cc_uint32       length;
    unsigned char*  data;		// the proverbial bag-o-bits
} cc_data;

// 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_uint32       is_skey;
    cc_uint32       ticket_flags;
    cc_data **  addresses;
    cc_data         ticket;
    cc_data         second_ticket;
    cc_data **  authdata;
} cc_creds;


typedef union cred_ptr_union_type {
    cc_creds*    pV5Cred;
} cred_ptr_union;

typedef struct cred_union_type {
    cc_int32        cred_type;
    cred_ptr_union  cred;
} cred_union;

typedef struct _infoNC {
    char*     name;
    char*     principal;
    cc_int32  vers;
} infoNC;

/*
** 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
    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 # (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,
    cc_int32 vers,          // >  ticket version (CC_CRED_V5)
    cc_uint32 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
    cc_int32 vers,          // >  ticket version (CC_CRED_V5)
    cc_uint32 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_begin(
    apiCB* cc_ctx,
    ccache_cit** itNCs
    );

CCACHE_API
cc_seq_fetch_NCs_end(
    apiCB* cc_ctx,
    ccache_cit** itNCs
    );

CCACHE_API
cc_seq_fetch_NCs_next(
    apiCB* cc_ctx,
    ccache_p** ccache_ptr,
    ccache_cit* itNCs
    );

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
    );

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, // > NC control structure
    const cc_int32 vers,
    const char* principal           // > name of principal associated with NC
                                    //   Free via cc_free_principal()
    );

CCACHE_API
cc_get_principal(
    apiCB* cc_ctx,                  // > DLL's primary control structure
    const ccache_p* ccache_pointer, // > NC control structure
    char** principal                // < name of principal associated with NC
                                    //   Free via cc_free_principal()
    );

CCACHE_API
cc_get_cred_version(
    apiCB* cc_ctx,              // > DLL's primary control structure
    const ccache_p* ccache_ptr, // > NC control structure
    cc_int32* 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
    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
    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
    );

CCACHE_API
cc_seq_fetch_creds_begin(
    apiCB* cc_ctx,
    const ccache_p* ccache_ptr,
    ccache_cit** itCreds
    );

CCACHE_API
cc_seq_fetch_creds_end(
    apiCB* cc_ctx,
    ccache_cit** itCreds
    );

CCACHE_API
cc_seq_fetch_creds_next(
    apiCB* cc_ctx,
    cred_union** cred,
    ccache_cit* itCreds
    );

/*
** 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())
    );

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_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_ */