Preliminary implementation of CCAPI v2 added

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@11193 dc483132-0cff-0310-8789-dd5450dbe970

1 files changed, 177 insertions, 141 deletions

diff --git a/src/mac/libraries/CCache API/include/CCache.h b/src/mac/libraries/CCache API/include/CCache.h
index e078cdc6b..9bdfefa6b 100644
--- a/src/mac/libraries/CCache API/include/CCache.h
+++ b/src/mac/libraries/CCache API/include/CCache.h
@@ -68,22 +68,46 @@ extern "C" {
 
 #define CRED_TYPE_IN_UNION
 
-typedef int cc_int32;
-typedef cc_int32 cc_time_t;
-typedef cc_int32 cc_nc_flags;
+typedef		SInt32		cc_int32;
+typedef		UInt32		cc_uint32;
+typedef		cc_int32	cc_time_t;
+typedef		cc_int32	cc_nc_flags;
 //typedef short cc_cred_vers;
+
+/*
+ * Enumerations and constants
+ */
 	
-enum StringToKey_Type { STK_AFS = 0, STK_DES = 1};
+enum StringToKey_Type {
+	STK_AFS = 0,
+	STK_DES = 1
+};
 
-enum {  MAX_V4_CRED_LEN = 1250, 
-		KRB_PRINCIPAL_SZ = 40, 
-		KRB_INSTANCE_SZ = 40,
-		KRB_REALM_SZ = 40,
-		KRB_SERVICE_SZ = 40,
-		ADDR_SZ = 16  };
+enum {  
+	MAX_V4_CRED_LEN = 1250, 
+	KRB_PRINCIPAL_SZ = 40, 
+	KRB_INSTANCE_SZ = 40,
+	KRB_REALM_SZ = 40,
+	KRB_SERVICE_SZ = 40,
+	ADDR_SZ = 16 
+};
+
+// version indentfiers
+// extend to authentication schemes beyond Kerberos?
+enum cc_cred_vers {  
+    CC_CRED_VUNKNOWN = 0,       // For validation
+    CC_CRED_V4 = 1,
+    CC_CRED_V5 = 2,
+    CC_CRED_VMAX = 3,            // For validation
+    CC_INVALID_RECORD = 99
+};
+
+/*
+ * Credentials structures
+ */
 
 // V4 Credentials
-typedef struct _V4Credentials {
+typedef struct _V4credential {
 	unsigned char	kversion;
     char			principal[KRB_PRINCIPAL_SZ];
     char			principal_instance[KRB_INSTANCE_SZ];
@@ -101,26 +125,9 @@ typedef struct _V4Credentials {
     unsigned long	oops;
 } V4Cred_type;
 
-// version indentfiers
-// extend to authentication schemes beyond Kerberos?
-enum cc_cred_vers {  
-    CC_CRED_VUNKNOWN = 0,       // For validation
-    CC_CRED_V4 = 1,
-    CC_CRED_V5 = 2,
-    CC_CRED_VMAX = 3,            // For validation
-    CC_INVALID_RECORD = 99
-};
-
-#define NC_MAX_NAME_LENGTH 255
-typedef struct _infoNC  {
-	char name[NC_MAX_NAME_LENGTH];
-	char principal[NC_MAX_NAME_LENGTH];
-	enum cc_cred_vers vers;
-} infoNC;
-
-
+// V5 credentials
 typedef struct _cc_data {
-	cc_int32		type; // should be one of above
+	cc_int32		type; // should be one of above // FIXME: wth is this field for??
 	cc_int32		length;
 	unsigned char*	data;
 } cc_data;
@@ -155,146 +162,155 @@ typedef struct cred_union_type {
     cred_ptr_union cred;
 } cred_union;
 
-#define kInitialCredBufferSize 10
-#define kLocalCopyNCType 1
-#define kMasterRecordNCType 2
-#define kUnlocked 100
-#define kReadLock 101
-#define kWriteLock 102
-typedef struct _ccache_p {
-	char					name[NC_MAX_NAME_LENGTH + 1]; 
-	enum cc_cred_vers			vers;
-	char					principal[NC_MAX_NAME_LENGTH + 1];
-	short					numCreds;
-	short					maxCreds;
-	cred_union**	 		creds; //self-growing array of pointers
-	int						cc_flags;
-	char					typeFlag; //master or local copy
-	long					lock;
-	ProcessSerialNumber		lockOwner;
-	struct _ccache_p		*next;
-	struct _ccache_p		*prev;
-} ccache_p;
-
-
-typedef struct _ccache_it {
-	ccache_p *prevNC;
-	int		  lastCredOffset;
-} ccache_cit;
-
-typedef struct _apiCB {
-	ccache_p* listHead;
-	ccache_p* listTail;
-	int		  numNCs;
-	cc_time_t	  changeCount;
-} apiCB;
-
-
-// --- Globals -------------
-extern apiCB *gCntrlBlock;
+/*
+ * Cache info structures
+ */
+
+typedef struct _infoNC  {
+	char*			name;
+	char*			principal;
+	enum	cc_cred_vers	vers;
+} infoNC;
+
+/*
+ * Opaque structures
+ * (you never need anything but pointers)
+ */
+ 
+struct ccache_p;
+typedef struct ccache_p ccache_p;
+
+struct apiCB;
+typedef struct apiCB apiCB;
 
+struct ccache_cit;
+typedef struct ccache_cit ccache_cit;
 
 /*
 ** The official (externally visible) API
 */
 
+/*
+ * Note that some of the types in the API below are typedefs, to match the API spec.
+ * This is because I expect at least some of them to change in the future.
+ */
+ 
+typedef		int						cc_result;
+typedef		int						cc_api_version;
+typedef		enum cc_cred_vers		cc_cred_vers;
+typedef		int						cc_flags;
+
 #define CC_API_VER_1	1
+#define CC_API_VER_2	2
 
 // -- Main cache routines ------
 
 /* Initialize the Credentials Cache, return a control structure in cc_ctx,
 	This should be the entry point of the shared library, or called from
 	the entry point */
-int
-cc_initialize(apiCB ** cc_ctx,		// < SL's primary control structure. 
-									//   returned here, passed everywhere else 
-			  int	api_version,	// > ver supported by caller (use CC_API_VER_1)
-			  int*	api_supported,	// < if ~NULL, returned max ver supported by DLL
-			  char** vendor);		// < if ~NULL, returns read only C string, vendor name */
+cc_result
+cc_initialize (
+		apiCB**				cc_ctx,			// < SL's primary control structure. 
+											//   returned here, passed everywhere else 
+		cc_api_version		api_version,	// > ver supported by caller (use CC_API_VER_1)
+		cc_api_version*		api_supported,	// < if ~NULL, returned max ver supported by DLL
+		char**				vendor);		// < if ~NULL, returns read only C string, vendor name */
 
 /* Termination routine */
-int
-cc_shutdown(apiCB** cc_ctx);			// <> SL's primary control structure. NULL after call. 
+cc_result
+cc_shutdown (
+		apiCB**				cc_ctx);		// <> SL's primary control structure. NULL after call. 
 
 
 /* Open a name cache within the ccache designated by name and version? 
  	Returns a control struture pointer to the NC in *handle */
-int
-cc_open(apiCB * cc_ctx,				// > SL's primary control structure
-		char * name,				// > name of pre-created cache
-		const enum cc_cred_vers vers,	// > version of credentials held in this NC 
-		int cc_flags,				// > options
-		ccache_p ** handle);		// < named cache control structure 
+cc_result
+cc_open (
+		apiCB*				cc_ctx,				// > SL's primary control structure
+		char*				name,				// > name of pre-created cache
+		cc_cred_vers		vers,				// > version of credentials held in this NC 
+		cc_flags			flags,				// > options
+		ccache_p**			handle);			// < named cache control structure 
 
 /* Close and deallocate memory assoicated with the named cache pointed to by *handle */
-int
-cc_close(apiCB* cc_ctx,				// > DLL's primary control structure
-		 ccache_p** handle);		// <> named cache control structure. NULL after call. 
+cc_result
+cc_close (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		ccache_p**			handle);			// <> named cache control structure. NULL after call. 
 
 /* Create a new named cache in the cache cc_ctx.
 Specify the cache by: a name, a principal, a version
 return a pointer to the control structure for the cache via handle */
-int
-cc_create(apiCB* cc_ctx,			// > DLL's primary control structure
-		  char* name,				// > name of cache to be [destroyed if exists, then] created
-		  char* principal,			// > name of principal associated with named cache
-		  const enum cc_cred_vers vers,	// > version of credentials to be held in cache
-		  int cc_flags,				// > options
-		  ccache_p** handle);		// < named cache control structure 
-
-/* Seems remarkably similiar to cc_close ???? */
-int
-cc_destroy(apiCB* cc_ctx,			// > DLL's primary control structure
-		   ccache_p** handle);		// <> named cache control structure. NULL after call.
+cc_result
+cc_create (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		char*				name,				// > name of cache to be [destroyed if exists, then] created
+		char*				principal,			// > name of principal associated with named cache
+		cc_cred_vers		vers,				// > version of credentials to be held in cache
+		cc_flags			flags,				// > options
+		ccache_p**			handle);			// < named cache control structure 
+
+/* Destroy cache associated with the handle (handle becomes invalid) */
+cc_result
+cc_destroy (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		ccache_p**			handle);			// <> named cache control structure. NULL after call.
 
 /* Get the global last changed time variable for the CCache 
    Replace this with a change counter instead of an actual time?*/
-int
-cc_get_change_time(apiCB* cc_ctx,	  // > DLL's primary control structure
-				   cc_time_t* time); // < time of last change to named cache
+cc_result
+cc_get_change_time (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		cc_time_t*			time);				// < time of last change to named cache
 
 // -- Named Cache routines ---------
 
 /* store the credentials (tickets) in cred in the named cache pointed 
 to by handle.  Maybe the last argument should be more general? */
-int
-cc_store(apiCB* cc_ctx,				// > DLL's primary control structure
-		 const ccache_p* ccache_pointer,			// > named cache control structure
-		 const cred_union cred);			// > credentials to store in cache named
+cc_result
+cc_store (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		const ccache_p*		ccache_pointer,		// > named cache control structure
+		cred_union			cred);				// > credentials to store in cache named
 
 /* Remove the credentials pointed to by cred from the Named Cache pointed to
 by handle. */
-int
-cc_remove_cred(apiCB* cc_ctx,		// > DLL's primary control structure
-			   ccache_p* ccache_pointer,	// > named cache control structure
-			   const cred_union cred);		// > credentials to remove from named cache
+cc_result
+cc_remove_cred (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		const ccache_p*		ccache_pointer,		// > named cache control structure
+		cred_union			cred);				// > credentials to remove from named cache
 
 /* set the principal of the NC *ccache_pointer to principal,
 	principal should be a null terminated C string */
-int
-cc_set_principal(apiCB* cc_ctx,						// > cs 
-				const ccache_p* ccache_pointer,		// > NC
-			    const enum cc_cred_vers vers,			// > version: to check pointer?
-			    const char* principal);				// > new principal name
+cc_result
+cc_set_principal (
+		apiCB*				cc_ctx,				// > cs 
+		const ccache_p*		ccache_pointer,		// > NC
+		cc_cred_vers		vers,				// > version: to check pointer?
+		const char*			principal);			// > new principal name
 
 /* Get the name of the principal associated with the NC handle */
-int
-cc_get_principal(apiCB* cc_ctx,		// > DLL's primary control structure
-				 ccache_p * ccache_pointer,	// > named cache control structure
-				 char** principal);	// < name of principal associated with named cache
-									//   Free via cc_free_principal()
+cc_result
+cc_get_principal (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		const ccache_p*		ccache_pointer,		// > named cache control structure
+		char**				principal);			// < name of principal associated with named cache
+												//   Free via cc_free_principal()
 
 /* Get version of credentials stored in the NC pointed to by ccache_pointer */ 
-int
-cc_get_cred_version(apiCB* cc_ctx, 					// > cs
-					const ccache_p* ccache_pointer, // > the named cache
-					enum cc_cred_vers* vers);			// <> the version of credentials in the NC
+cc_result
+cc_get_cred_version (
+		apiCB*				cc_ctx,				// > cs
+		const ccache_p*		ccache_pointer,		// > the named cache
+		cc_cred_vers*		vers);				// <> the version of credentials in the NC
 
 /* Return the name of the NC specified by ccache_p */
-int
-cc_get_name(apiCB* cc_ctx,						// > control struct
-			const ccache_p* ccache_pointer, 	// > NC
-			char** name);						// <> name					
+cc_result
+cc_get_name (
+		apiCB*				cc_ctx,				// > control struct
+		const ccache_p*		ccache_pointer, 	// > NC
+		char**				name);				// <> name					
 
 
 //  - Search routines ----
@@ -305,49 +321,69 @@ To use (?): initially set handle and itCache to NULL
 after each call set itCache to handle,
 repeated calls will return all currently held NC's
 */
-int
-cc_seq_fetch_NCs(apiCB* cc_ctx,			// > DLL's primary control structure
-				   ccache_p** ccache_pointer,	// <> named cache control structure (close, then open next)
-			       ccache_cit** itCache);// <> iterator used by DLL, set to NULL before first call
+cc_result
+cc_seq_fetch_NCs_begin (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		ccache_cit**		itCache);			// <> iterator used by DLL, set to NULL before first call
+
+cc_result
+cc_seq_fetch_NCs_next (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		ccache_p**			ccache_pointer,		// <> named cache control structure (close, then open next)
+		ccache_cit*			itCache);			// <> iterator used by DLL, set to NULL before first call
+
+cc_result
+cc_seq_fetch_NCs_end (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		ccache_cit**		itCache);			// <> iterator used by DLL, set to NULL before first call
 
 /* Sequentially fetch every set of credentials in the Named Cache handle
 use similiarly to cc_seq_fetch_NCs */
-int
-cc_seq_fetch_creds(apiCB* cc_ctx,			// > DLL's primary control structure
-				   ccache_p* ccache_pointer,		// > named cache 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
+cc_result
+cc_seq_fetch_creds_begin (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		ccache_p*			ccache_pointer,		// > named cache control structure
+		ccache_cit**		itCreds);			// <> iterator used by DLL, set to NULL before first call
+
+cc_result
+cc_seq_fetch_creds_next (
+		apiCB*				cc_ctx,				// > DLL's primary 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
+
+cc_result
+cc_seq_fetch_creds_end (
+		apiCB*				cc_ctx,				// > DLL's primary control structure
+		ccache_cit**		itCreds);			// <> iterator used by DLL, set to NULL before first call
 
 /* a wrapper for cc_seq_fetch_NCs.
 	Returns: a null terminated list (array) of pointers to infoNC structs
 	if this works, maybe we should hide that seq call...
 	*/
-int
+cc_result
 cc_get_NC_info(apiCB *cc_ctx,		// > control structure
 			 infoNC*** ppNCi);		// <> info about the NC (yes.. three asterisks...)
 
 				
 // -- Memory recovery ---------
 
-/* just a wrapper for free() ??? */
-int
+cc_result
 cc_free_principal(apiCB* cc_ctx,		// > DLL's primary control structure
 				  char** principal);// <> principal to be freed, returned as NULL
 									//   (from cc_get_principal())
-/* another wrapper? */
-int
+cc_result
 cc_free_name(apiCB* cc_ctx,			// > DLL's primary control structure
 			 char** name);			// <> name to be freed, returned as NULL
 									//   (from cc_seq_fetch_cache())
 
 /* free storage associated with cred_union** */
-int
+cc_result
 cc_free_creds(apiCB* cc_ctx,			// > DLL's primary control structure
 			  cred_union** creds);		// <> creds (from cc_seq_fetch_creds()) to be freed
 										//    Returned as NULL.
 
 /* Free that nasty array we created above */
-int 
+cc_result
 cc_free_NC_info(apiCB *cc_ctx,		// > control structure
 				infoNC*** ppNCi);	// <> pointer to free