Make krb5_tkt_creds_init() take KRB5_GC_* options like

krb5_get_credentials() does.  Add doxygen documentation for some of the
krb5_tkt_creds APIs.

git-svn-id: svn://anonsvn.mit.edu/krb5/branches/iakerb@23892 dc483132-0cff-0310-8789-dd5450dbe970

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index ba4f0c9717f8d920292ce7cf1554bd1fa0c9a2ed..9c32aef5847a5cd3cba7eb38dc5f99cd0c8958e4 100644 (file)
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -2419,13 +2419,47 @@ krb5_init_creds_get_times(krb5_context context, krb5_init_creds_context ctx,
 struct _krb5_tkt_creds_context;
 typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
 
+/**
+ * Create a context to get credentials from a KDC's Ticket Granting Service.
+ *
+ * The resulting TGS acquisition context can be used asynchronously with
+ * krb5_tkt_creds_step() or synchronously with krb5_tkt_creds_get().  See also
+ * krb5_get_credentials() for synchrous use.
+ *
+ * @param[in]  context  A krb5 library context (see krb5_init_context())
+ * @param[in]  ccache   A credentials cache containing a Ticket Granting Ticket
+ *                      (TGT) for the client realm.  Cross-realm TGTs may be
+ *                      stored into this cache.
+ * @param[in]  options  KRB5_GC_* options for this request.
+ * @param[out] ctx      The TGS acquisition context.
+ */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
-                    krb5_creds *creds, int kdcopt, krb5_tkt_creds_context *ctx);
+                    krb5_creds *creds, krb5_flags options,
+                    krb5_tkt_creds_context *ctx);
 
+/**
+ * Synchronously obtain credentials within an acquisition context.
+ *
+ * This function repeatedly generates requests, sends them to the appropriate
+ * realms' KDCs, and processes the replies until credentials are available for
+ * retrieval with krb5_tkt_creds_get_creds().
+ *
+ * @param[in]  context  A krb5 library context (see krb5_init_context())
+ * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
+ */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx);
 
+/**
+ * Retrieve credentials from an acquisition context, filling in @a creds.  The
+ * acquisition context must have completed obtaining credentials via either
+ * krb5_tkt_creds_get() or krb5_tkt_creds_step().
+ *
+ * @param[in]  context  A krb5 library context (see krb5_init_context())
+ * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
+ * @param[out] creds    The acquired credentials
+ */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_get_creds(krb5_context context, krb5_tkt_creds_context ctx,
                          krb5_creds *creds);

diff --git a/src/lib/krb5/krb/gc_frm_kdc.c b/src/lib/krb5/krb/gc_frm_kdc.c
index 02ee12ff54ab1ddce0124af3afdcaadb26b2b63b..f23a2fb08ffe431ea25d0459eb2b7e339671d966 100644 (file)
--- a/src/lib/krb5/krb/gc_frm_kdc.c
+++ b/src/lib/krb5/krb/gc_frm_kdc.c
@@ -83,7 +83,8 @@ struct _krb5_tkt_creds_context {
     krb5_principal server;      /* Server principal (alias) */
     krb5_principal req_server;  /* Caller-requested server principal */
     krb5_ccache ccache;         /* Caller-provided ccache (alias) */
-    int req_kdcopt;             /* Caller-requested KDC options */
+    krb5_flags req_options;     /* Caller-requested KRB5_GC_* options */
+    krb5_flags req_kdcopt;      /* Caller-requested options as KDC options */
     krb5_authdata **authdata;   /* Caller-requested authdata */
 
     /* The following fields are used in multiple steps. */
@@ -892,7 +893,7 @@ begin(krb5_context context, krb5_tkt_creds_context ctx)
 
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
-                    krb5_creds *in_creds, int kdcopt,
+                    krb5_creds *in_creds, krb5_flags options,
                     krb5_tkt_creds_context *pctx)
 {
     krb5_error_code code;
@@ -902,6 +903,22 @@ krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
     if (ctx == NULL)
         goto cleanup;
 
+    ctx->req_options = options;
+    ctx->req_kdcopt = 0;
+    if (options & KRB5_GC_CANONICALIZE)
+        ctx->req_kdcopt |= KDC_OPT_CANONICALIZE;
+    if (options & KRB5_GC_FORWARDABLE)
+        ctx->req_kdcopt |= KDC_OPT_FORWARDABLE;
+    if (options & KRB5_GC_NO_TRANSIT_CHECK)
+        ctx->req_kdcopt |= KDC_OPT_DISABLE_TRANSITED_CHECK;
+    if (options & KRB5_GC_CONSTRAINED_DELEGATION) {
+        if (options & KRB5_GC_USER_USER) {
+            code = EINVAL;
+            goto cleanup;
+        }
+        ctx->req_kdcopt |= KDC_OPT_FORWARDABLE | KDC_OPT_CNAME_IN_ADDL_TKT;
+    }
+
     ctx->state = STATE_BEGIN;
     ctx->cache_code = KRB5_CC_NOTFOUND;
 
@@ -916,7 +933,6 @@ krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
     code = krb5_cc_dup(context, ccache, &ctx->ccache);
     if (code != 0)
         goto cleanup;
-    ctx->req_kdcopt = kdcopt;
     code = krb5_copy_authdata(context, in_creds->authdata, &ctx->authdata);
     if (code != 0)
         goto cleanup;

diff --git a/src/lib/krb5/krb/get_creds.c b/src/lib/krb5/krb/get_creds.c
index 0149e68d65edc47782fcf946aa85ea4ae875967d..7f6e97cd46fb0f884fb359325825d7a25bac3f8c 100644 (file)
--- a/src/lib/krb5/krb/get_creds.c
+++ b/src/lib/krb5/krb/get_creds.c
@@ -141,7 +141,6 @@ krb5_get_credentials(krb5_context context, krb5_flags options,
     krb5_creds mcreds, *ncreds = NULL;
     krb5_flags fields;
     krb5_boolean not_ktype = FALSE;
-    int kdcopt = 0;
 
     *out_creds = NULL;
 
@@ -176,23 +175,8 @@ krb5_get_credentials(krb5_context context, krb5_flags options,
         goto cleanup;
     }
 
-    if (options & KRB5_GC_CANONICALIZE)
-        kdcopt |= KDC_OPT_CANONICALIZE;
-    if (options & KRB5_GC_FORWARDABLE)
-        kdcopt |= KDC_OPT_FORWARDABLE;
-    if (options & KRB5_GC_NO_TRANSIT_CHECK)
-        kdcopt |= KDC_OPT_DISABLE_TRANSITED_CHECK;
-    if (options & KRB5_GC_CONSTRAINED_DELEGATION) {
-        if (options & KRB5_GC_USER_USER) {
-            retval = EINVAL;
-            goto cleanup;
-
-        }
-        kdcopt |= KDC_OPT_FORWARDABLE | KDC_OPT_CNAME_IN_ADDL_TKT;
-    }
-
     /* Get the credential from the KDC. */
-    retval = get_tkt_creds(context, ccache, in_creds, kdcopt, ncreds);
+    retval = get_tkt_creds(context, ccache, in_creds, options, ncreds);
     if (retval != 0)
         goto cleanup;