krb5: krb5_cc_ops backward compatibility and extensibility

The krb5_cc_ops structure is an extensible structure to which new
functionality has been added over the years.

Version zero was the original.  It included all functions up to
and including get_default_name().

Version one added set_default().

Version two added lastchange().

Version three added set_kdc_offset() and get_kdc_offset().

Version four broke compatibility by modifying the signatures
of get_name() and resolve().   This was in change
7bf4d76e75 ("krb5: Improve cccol sub
naming; add gss_store_cred_into2()").

Version five restores the original signatures of get_name()
and resolve() and introduces get_name_2() and resolve_2() that
provide the additional cccol functionality.

This change

 * introduces version five
 * documents which functions are part of each version
 * replaces KRB5_CC_OPS_VERSION with KRB5_CC_OPS_VERSION_0,
   KRB5_CC_OPS_VERSION_1, KRB5_CC_OPS_VERSION_2, KRB5_CC_OPS_VERSION_3,
   and KRB5_CC_OPS_VERSION_5.  KRB5_CC_OPS_VERSION_4 is skipped
   because of the aforementioned breakage.
 * compatibility logic is added to permit ccache plugins to implement
   any of version one, two, three, five or a future version.
 * all in-tree krb5_cc_ops implementations are updated to version 5.

Change-Id: Iadfce01d10834bc6151939e4d9d196f03001626e

lib/krb5/acache.c

@@ -444,11 +444,11 @@ get_cc_name(krb5_acc *a)
 
 
 static krb5_error_code KRB5_CALLCONV
-acc_get_name(krb5_context context,
+acc_get_name_2(krb5_context context,
-	     krb5_ccache id,
+	       krb5_ccache id,
-             const char **name,
+	       const char **name,
-             const char **colname,
+	       const char **colname,
-             const char **subsidiary)
+	       const char **subsidiary)
 {
     krb5_error_code ret = 0;
     krb5_acc *a = ACACHE(id);
@@ -523,7 +523,7 @@ acc_alloc(krb5_context context, krb5_ccache *id)
 }
 
 static krb5_error_code KRB5_CALLCONV
-acc_resolve(krb5_context context, krb5_ccache *id, const char *res, const char *sub)
+acc_resolve_2(krb5_context context, krb5_ccache *id, const char *res, const char *sub)
 {
     krb5_error_code ret;
     cc_time_t offset;
@@ -1095,10 +1095,10 @@ acc_lastchange(krb5_context context, krb5_ccache id, krb5_timestamp *mtime)
  */
 
 KRB5_LIB_VARIABLE const krb5_cc_ops krb5_acc_ops = {
-    KRB5_CC_OPS_VERSION,
+    KRB5_CC_OPS_VERSION_5,
     "API",
-    acc_get_name,
+    NULL,
-    acc_resolve,
+    NULL,
     acc_gen_new,
     acc_initialize,
     acc_destroy,
@@ -1121,6 +1121,8 @@ KRB5_LIB_VARIABLE const krb5_cc_ops krb5_acc_ops = {
     acc_lastchange,
     NULL,
     NULL,
+    acc_get_name_2,
+    acc_resolve_2
 };
 
 #endif

lib/krb5/cache.c

@@ -211,8 +211,13 @@ allocate_ccache(krb5_context context,
 	return ret;
     }
 
-    ret = (*id)->ops->resolve(context, id, residual, subsidiary);
+    if ((*id)->ops->version < KRB5_CC_OPS_VERSION_5
-    if(ret) {
+	|| (*id)->ops->resolve_2 == NULL) {
+	ret = (*id)->ops->resolve(context, id, residual);
+    } else {
+	ret = (*id)->ops->resolve_2(context, id, residual, subsidiary);
+    }
+    if (ret) {
 	free(*id);
         *id = NULL;
     }
@@ -482,10 +487,7 @@ KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL
 krb5_cc_get_name(krb5_context context,
 		 krb5_ccache id)
 {
-    const char *name;
+    return id->ops->get_name(context, id);
-
-    (void) id->ops->get_name(context, id, &name, NULL, NULL);
-    return name;
 }
 
 /**
@@ -499,8 +501,16 @@ KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL
 krb5_cc_get_collection(krb5_context context, krb5_ccache id)
 {
     const char *name;
+    int ret;
+
+    if (id->ops->version < KRB5_CC_OPS_VERSION_5
+	|| id->ops->get_name_2 == NULL)
+	return NULL;
+
+    ret = id->ops->get_name_2(context, id, NULL, &name, NULL);
+    if (ret)
+	return NULL;
 
-    (void) id->ops->get_name(context, id, NULL, &name, NULL);
     return name;
 }
 
@@ -658,7 +668,8 @@ krb5_cc_switch(krb5_context context, krb5_ccache id)
     _krb5_set_default_cc_name_to_registry(context, id);
 #endif
 
-    if (id->ops->set_default == NULL)
+    if (id->ops->version == KRB5_CC_OPS_VERSION_0
+	|| id->ops->set_default == NULL)
 	return 0;
 
     return (*id->ops->set_default)(context, id);
@@ -676,7 +687,7 @@ krb5_cc_support_switch(krb5_context context, const char *type)
     const krb5_cc_ops *ops;
 
     ops = krb5_cc_get_prefix_ops(context, type);
-    if (ops && ops->set_default)
+    if (ops && ops->version > KRB5_CC_OPS_VERSION_0 && ops->set_default)
 	return 1;
     return FALSE;
 }
@@ -1975,6 +1986,11 @@ krb5_cc_last_change_time(krb5_context context,
 			 krb5_timestamp *mtime)
 {
     *mtime = 0;
+
+    if (id->ops->version < KRB5_CC_OPS_VERSION_2
+	 || id->ops->lastchange == NULL)
+	return KRB5_CC_NOSUPP;
+
     return (*id->ops->lastchange)(context, id, mtime);
 }
 
@@ -2189,7 +2205,8 @@ krb5_cc_get_lifetime(krb5_context context, krb5_ccache id, time_t *t)
 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
 krb5_cc_set_kdc_offset(krb5_context context, krb5_ccache id, krb5_deltat offset)
 {
-    if (id->ops->set_kdc_offset == NULL) {
+    if (id->ops->version < KRB5_CC_OPS_VERSION_3
+	|| id->ops->set_kdc_offset == NULL) {
 	context->kdc_sec_offset = offset;
 	context->kdc_usec_offset = 0;
 	return 0;
@@ -2214,7 +2231,8 @@ krb5_cc_set_kdc_offset(krb5_context context, krb5_ccache id, krb5_deltat offset)
 KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
 krb5_cc_get_kdc_offset(krb5_context context, krb5_ccache id, krb5_deltat *offset)
 {
-    if (id->ops->get_kdc_offset == NULL) {
+    if (id->ops->version < KRB5_CC_OPS_VERSION_3
+	|| id->ops->get_kdc_offset == NULL) {
 	*offset = context->kdc_sec_offset;
 	return 0;
     }

lib/krb5/dcache.c

@@ -244,11 +244,11 @@ get_default_cache(krb5_context context, krb5_dcache *dc,
 
 
 static krb5_error_code KRB5_CALLCONV
-dcc_get_name(krb5_context context,
+dcc_get_name_2(krb5_context context,
-	     krb5_ccache id,
+	       krb5_ccache id,
-             const char **name,
+	       const char **name,
-             const char **dir,
+	       const char **dir,
-             const char **sub)
+	       const char **sub)
 {
     krb5_dcache *dc = DCACHE(id);
 
@@ -329,10 +329,10 @@ get_default_dir(krb5_context context, char **res)
 }
 
 static krb5_error_code KRB5_CALLCONV
-dcc_resolve(krb5_context context,
+dcc_resolve_2(krb5_context context,
-            krb5_ccache *id,
+	      krb5_ccache *id,
-            const char *res,
+	      const char *res,
-            const char *sub)
+	      const char *sub)
 {
     krb5_error_code ret;
     krb5_dcache *dc = NULL;
@@ -505,7 +505,7 @@ dcc_gen_new(krb5_context context, krb5_ccache *id)
     if (ret == 0 && (fd = mkstemp(name + sizeof("DIR::") - 1)) == -1)
 	ret = errno;
     if (ret == 0)
-        ret = dcc_resolve(context, id, name + sizeof("DIR:") - 1, NULL);
+	ret = dcc_resolve_2(context, id, name + sizeof("DIR:") - 1, NULL);
 
     free(def_dir);
     free(name);
@@ -824,10 +824,10 @@ dcc_get_kdc_offset(krb5_context context, krb5_ccache id, krb5_deltat *kdc_offset
  */
 
 KRB5_LIB_VARIABLE const krb5_cc_ops krb5_dcc_ops = {
-    KRB5_CC_OPS_VERSION,
+    KRB5_CC_OPS_VERSION_5,
     "DIR",
-    dcc_get_name,
+    NULL,
-    dcc_resolve,
+    NULL,
     dcc_gen_new,
     dcc_initialize,
     dcc_destroy,
@@ -849,5 +849,7 @@ KRB5_LIB_VARIABLE const krb5_cc_ops krb5_dcc_ops = {
     dcc_set_default,
     dcc_lastchange,
     dcc_set_kdc_offset,
-    dcc_get_kdc_offset
+    dcc_get_kdc_offset,
+    dcc_get_name_2,
+    dcc_resolve_2
 };

lib/krb5/fcache.c

@@ -67,11 +67,11 @@ struct fcc_cursor {
 #define FCC_CURSOR(C) ((struct fcc_cursor*)(C))
 
 static krb5_error_code KRB5_CALLCONV
-fcc_get_name(krb5_context context,
+fcc_get_name_2(krb5_context context,
-	     krb5_ccache id,
+	       krb5_ccache id,
-             const char **name,
+	       const char **name,
-             const char **colname,
+	       const char **colname,
-             const char **sub)
+	       const char **sub)
 {
     if (FCACHE(id) == NULL)
         return KRB5_CC_NOTFOUND;
@@ -196,7 +196,7 @@ fcc_lock(krb5_context context, krb5_ccache id,
 
     if (exclusive == FALSE)
         return 0;
-    ret = fcc_get_name(context, id, &name, NULL, NULL);
+    ret = fcc_get_name_2(context, id, &name, NULL, NULL);
     if (ret == 0)
         ret = _krb5_xlock(context, fd, exclusive, name);
     return ret;
@@ -214,10 +214,10 @@ fcc_get_default_name(krb5_context, char **);
 #define FILESUBSEPCHR ((FILESUBSEP)[0])
 
 static krb5_error_code KRB5_CALLCONV
-fcc_resolve(krb5_context context,
+fcc_resolve_2(krb5_context context,
-            krb5_ccache *id,
+	      krb5_ccache *id,
-            const char *res,
+	      const char *res,
-            const char *sub)
+	      const char *sub)
 {
     krb5_fcache *f;
     char *freeme = NULL;
@@ -1662,10 +1662,10 @@ fcc_get_kdc_offset(krb5_context context, krb5_ccache id, krb5_deltat *kdc_offset
  */
 
 KRB5_LIB_VARIABLE const krb5_cc_ops krb5_fcc_ops = {
-    KRB5_CC_OPS_VERSION,
+    KRB5_CC_OPS_VERSION_5,
     "FILE",
-    fcc_get_name,
+    NULL,
-    fcc_resolve,
+    NULL,
     fcc_gen_new,
     fcc_initialize,
     fcc_destroy,
@@ -1687,5 +1687,7 @@ KRB5_LIB_VARIABLE const krb5_cc_ops krb5_fcc_ops = {
     fcc_set_default_cache,
     fcc_lastchange,
     fcc_set_kdc_offset,
-    fcc_get_kdc_offset
+    fcc_get_kdc_offset,
+    fcc_get_name_2,
+    fcc_resolve_2
 };

lib/krb5/kcm.c

@@ -232,11 +232,11 @@ kcm_free(krb5_context context, krb5_ccache *id)
 }
 
 static krb5_error_code KRB5_CALLCONV
-kcm_get_name(krb5_context context,
+kcm_get_name_2(krb5_context context,
-	     krb5_ccache id,
+	       krb5_ccache id,
-             const char **name,
+	       const char **name,
-             const char **col,
+	       const char **col,
-             const char **sub)
+	       const char **sub)
 {
     /*
      * TODO:
@@ -255,10 +255,10 @@ kcm_get_name(krb5_context context,
 }
 
 static krb5_error_code
-kcm_resolve(krb5_context context,
+kcm_resolve_2(krb5_context context,
-            krb5_ccache *id,
+	      krb5_ccache *id,
-            const char *res,
+	      const char *res,
-            const char *sub)
+	      const char *sub)
 {
     /*
      * For now, for KCM the `res' is the `sub'.
@@ -1126,7 +1126,7 @@ kcm_get_kdc_offset(krb5_context context, krb5_ccache id, krb5_deltat *kdc_offset
  */
 
 KRB5_LIB_VARIABLE const krb5_cc_ops krb5_kcm_ops = {
-    KRB5_CC_OPS_VERSION,
+    KRB5_CC_OPS_VERSION_5,
     "KCM",
     kcm_get_name,
     kcm_resolve,
@@ -1151,14 +1151,16 @@ KRB5_LIB_VARIABLE const krb5_cc_ops krb5_kcm_ops = {
     kcm_set_default,
     kcm_lastchange,
     kcm_set_kdc_offset,
-    kcm_get_kdc_offset
+    kcm_get_kdc_offset,
+    kcm_get_name_2,
+    kcm_resolve_2
 };
 
 KRB5_LIB_VARIABLE const krb5_cc_ops krb5_akcm_ops = {
-    KRB5_CC_OPS_VERSION,
+    KRB5_CC_OPS_VERSION_5,
     "API",
-    kcm_get_name,
+    NULL,
-    kcm_resolve,
+    NULL,
     kcm_gen_new,
     kcm_initialize,
     kcm_destroy,
@@ -1180,7 +1182,9 @@ KRB5_LIB_VARIABLE const krb5_cc_ops krb5_akcm_ops = {
     kcm_set_default,
     kcm_lastchange,
     NULL,
-    NULL
+    NULL,
+    kcm_get_name_2,
+    kcm_resolve_2
 };
 
 

lib/krb5/krb5.h

@@ -491,16 +491,19 @@ typedef struct krb5_creds {
 
 typedef struct krb5_cc_cache_cursor_data *krb5_cc_cache_cursor;
 
-#define KRB5_CC_OPS_VERSION 4
+#define KRB5_CC_OPS_VERSION_0	0
+#define KRB5_CC_OPS_VERSION_1	1
+#define KRB5_CC_OPS_VERSION_2	2
+#define KRB5_CC_OPS_VERSION_3	3
+#define KRB5_CC_OPS_VERSION_5	5
 
+/* Only extend the structure. Do not change signatures. */
 typedef struct krb5_cc_ops {
+    /* Version 0 */
     int version;
     const char *prefix;
-    krb5_error_code (KRB5_CALLCONV * get_name)(krb5_context, krb5_ccache,
+    const char* (KRB5_CALLCONV * get_name)(krb5_context, krb5_ccache);
-                                               const char **, const char **,
+    krb5_error_code (KRB5_CALLCONV * resolve)(krb5_context, krb5_ccache *, const char *);
-                                               const char **);
-    krb5_error_code (KRB5_CALLCONV * resolve)(krb5_context, krb5_ccache *, const char *,
-                                              const char *);
     krb5_error_code (KRB5_CALLCONV * gen_new)(krb5_context, krb5_ccache *);
     krb5_error_code (KRB5_CALLCONV * init)(krb5_context, krb5_ccache, krb5_principal);
     krb5_error_code (KRB5_CALLCONV * destroy)(krb5_context, krb5_ccache);
@@ -523,10 +526,20 @@ typedef struct krb5_cc_ops {
     krb5_error_code (KRB5_CALLCONV * end_cache_get)(krb5_context, krb5_cc_cursor);
     krb5_error_code (KRB5_CALLCONV * move)(krb5_context, krb5_ccache, krb5_ccache);
     krb5_error_code (KRB5_CALLCONV * get_default_name)(krb5_context, char **);
+    /* Version 1 */
     krb5_error_code (KRB5_CALLCONV * set_default)(krb5_context, krb5_ccache);
+    /* Version 2 */
     krb5_error_code (KRB5_CALLCONV * lastchange)(krb5_context, krb5_ccache, krb5_timestamp *);
+    /* Version 3 */
     krb5_error_code (KRB5_CALLCONV * set_kdc_offset)(krb5_context, krb5_ccache, krb5_deltat);
     krb5_error_code (KRB5_CALLCONV * get_kdc_offset)(krb5_context, krb5_ccache, krb5_deltat *);
+    /* Version 5 */
+    krb5_error_code (KRB5_CALLCONV * get_name_2)(krb5_context, krb5_ccache,
+						 const char **id, const char **res,
+						 const char **sub);
+    krb5_error_code (KRB5_CALLCONV * resolve_2)(krb5_context, krb5_ccache *id, const char *res,
+						const char *sub);
+    /* Add new functions here for versions 6 and above */
 } krb5_cc_ops;
 
 typedef struct heim_config_binding krb5_config_binding;

lib/krb5/krcache.c

@@ -1054,10 +1054,10 @@ make_cache(krb5_context context,
 
 /* Create a keyring ccache handle for the given residual string. */
 static krb5_error_code KRB5_CALLCONV
-krcc_resolve(krb5_context context,
+krcc_resolve_2(krb5_context context,
-             krb5_ccache *id,
+	       krb5_ccache *id,
-             const char *residual,
+	       const char *residual,
-             const char *sub)
+	       const char *sub)
 {
     krb5_error_code ret;
     key_serial_t collection_id, cache_id;
@@ -1346,11 +1346,11 @@ cleanup:
 
 /* Return an alias to the residual string of the cache. */
 static krb5_error_code KRB5_CALLCONV
-krcc_get_name(krb5_context context,
+krcc_get_name_2(krb5_context context,
-              krb5_ccache id,
+		krb5_ccache id,
-              const char **name,
+		const char **name,
-              const char **collection_name,
+		const char **collection_name,
-              const char **subsidiary_name)
+		const char **subsidiary_name)
 {
     krb5_krcache *data = KRCACHE(id);
 
@@ -2040,10 +2040,10 @@ krcc_get_default_name(krb5_context context, char **str)
  * be stored at the process or thread level respectively.
  */
 KRB5_LIB_VARIABLE const krb5_cc_ops krb5_krcc_ops = {
-    KRB5_CC_OPS_VERSION,
+    KRB5_CC_OPS_VERSION_5,
     "KEYRING",
-    krcc_get_name,
+    NULL,
-    krcc_resolve,
+    NULL,
     krcc_gen_new,
     krcc_initialize,
     krcc_destroy,
@@ -2066,6 +2066,8 @@ KRB5_LIB_VARIABLE const krb5_cc_ops krb5_krcc_ops = {
     krcc_lastchange,
     krcc_set_kdc_offset,
     krcc_get_kdc_offset,
+    krcc_get_name_2,
+    krcc_resolve_2
 };
 
 #endif /* HAVE_KEYUTILS_H */

lib/krb5/mcache.c

@@ -59,11 +59,11 @@ static struct krb5_mcache *mcc_head;
 #define MISDEAD(X)	((X)->dead)
 
 static krb5_error_code KRB5_CALLCONV
-mcc_get_name(krb5_context context,
+mcc_get_name_2(krb5_context context,
-	     krb5_ccache id,
+	       krb5_ccache id,
-             const char **name,
+	       const char **name,
-             const char **col,
+	       const char **col,
-             const char **sub)
+	       const char **sub)
 {
     if (name)
         *name = MCACHE(id)->name;
@@ -157,10 +157,10 @@ again:
 }
 
 static krb5_error_code KRB5_CALLCONV
-mcc_resolve(krb5_context context,
+mcc_resolve_2(krb5_context context,
-            krb5_ccache *id,
+	      krb5_ccache *id,
-            const char *res,
+	      const char *res,
-            const char *sub)
+	      const char *sub)
 {
     krb5_error_code ret;
     krb5_mcache *m;
@@ -610,10 +610,10 @@ mcc_get_kdc_offset(krb5_context context, krb5_ccache id, krb5_deltat *kdc_offset
  */
 
 KRB5_LIB_VARIABLE const krb5_cc_ops krb5_mcc_ops = {
-    KRB5_CC_OPS_VERSION,
+    KRB5_CC_OPS_VERSION_5,
     "MEMORY",
-    mcc_get_name,
+    NULL,
-    mcc_resolve,
+    NULL,
     mcc_gen_new,
     mcc_initialize,
     mcc_destroy,
@@ -635,5 +635,7 @@ KRB5_LIB_VARIABLE const krb5_cc_ops krb5_mcc_ops = {
     NULL,
     mcc_lastchange,
     mcc_set_kdc_offset,
-    mcc_get_kdc_offset
+    mcc_get_kdc_offset,
+    mcc_get_name_2,
+    mcc_resolve_2
 };

lib/krb5/pcache.c

@@ -48,7 +48,7 @@ cc_plugin_register_to_context(krb5_context context, const void *plug, void *plug
     krb5_cc_ops *ccops = (krb5_cc_ops *)plugctx;
     krb5_error_code ret;
 
-    if (ccops == NULL || ccops->version < KRB5_CC_OPS_VERSION)
+    if (ccops == NULL)
        return KRB5_PLUGIN_NO_HANDLE;
 
     ret = krb5_cc_register(context, ccops, TRUE);

lib/krb5/scache.c

@@ -566,11 +566,11 @@ bind_principal(krb5_context context,
  */
 
 static krb5_error_code KRB5_CALLCONV
-scc_get_name(krb5_context context,
+scc_get_name_2(krb5_context context,
-	     krb5_ccache id,
+	       krb5_ccache id,
-             const char **name,
+	       const char **name,
-             const char **file,
+	       const char **file,
-             const char **sub)
+	       const char **sub)
 {
     if (name)
         *name = SCACHE(id)->name;
@@ -582,10 +582,10 @@ scc_get_name(krb5_context context,
 }
 
 static krb5_error_code KRB5_CALLCONV
-scc_resolve(krb5_context context,
+scc_resolve_2(krb5_context context,
-            krb5_ccache *id,
+	      krb5_ccache *id,
-            const char *res,
+	      const char *res,
-            const char *sub)
+	      const char *sub)
 {
     krb5_error_code ret;
     krb5_scache *s;
@@ -1351,7 +1351,7 @@ again:
 
     ret = _krb5_cc_allocate(context, &krb5_scc_ops, id);
     if (ret == 0)
-        ret = scc_resolve(context, id, ctx->file, name);
+	ret = scc_resolve_2(context, id, ctx->file, name);
     if (ret) {
         free(*id);
         *id = NULL;
@@ -1485,10 +1485,10 @@ scc_set_default(krb5_context context, krb5_ccache id)
  */
 
 KRB5_LIB_VARIABLE const krb5_cc_ops krb5_scc_ops = {
-    KRB5_CC_OPS_VERSION,
+    KRB5_CC_OPS_VERSION_5,
     "SCC",
-    scc_get_name,
+    NULL,
-    scc_resolve,
+    NULL,
     scc_gen_new,
     scc_initialize,
     scc_destroy,
@@ -1510,7 +1510,9 @@ KRB5_LIB_VARIABLE const krb5_cc_ops krb5_scc_ops = {
     scc_set_default,
     NULL,
     NULL,
-    NULL
+    NULL,
+    scc_get_name_2,
+    scc_resolve_2
 };
 
 #endif