Create KRB5_TKT_CREDS_CONTINUE symbolic name for flag bit 1 in the

krb5_tkt_creds_step() output.  Finish doxygen documentation for
krb5_tkt_creds APIs.

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

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index f94df1e7ef42d3282ca5997c21333e4b70acfbe9..8138b5f893e424f3e6a498d675c5d41ca05e6a51 100644 (file)
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -2427,9 +2427,10 @@ typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
  * 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]  ccache   A credentials cache containing the desired credentials
+ *                      or a Ticket Granting Ticket (TGT) for the client realm.
+ *                      TGT and service credentials may be stored into this
+ *                      cache as they are acquired.
  * @param[in]  options  KRB5_GC_* options for this request.
  * @param[out] ctx      The TGS acquisition context.
  */
@@ -2452,8 +2453,9 @@ 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
+ * 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())
@@ -2464,14 +2466,48 @@ krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_get_creds(krb5_context context, krb5_tkt_creds_context ctx,
                          krb5_creds *creds);
 
+/**
+ * Release the resources used by an acquisition context.
+ *
+ * @param[in]  context  A krb5 library context (see krb5_init_context())
+ * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
+ */
 void KRB5_CALLCONV
 krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx);
 
+#define KRB5_TKT_CREDS_CONTINUE 1  /* Another KDC response is needed. */
+
+/**
+ * Process a response and generate the next request to acquire credentials.
+ *
+ * On the first call, @a in should be empty or NULL.  If more responses are
+ * needed, the @a flags output parameter will contain @a
+ * KRB5_TKT_CREDS_CONTINUE.  In this case, the caller must transport @a out to
+ * a KDC for @a realm and receive a response, which should be provided as @a
+ * in to the next call.
+ *
+ * @param[in]  context  A krb5 library context (see krb5_init_context())
+ * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
+ * @param[in]  in       The last response (empty or NULL for first call)
+ * @param[out] out      The next request to be sent
+ * @param[out] realm    The realm to which the next request should be sent
+ * @param[out] flags    Indicates whether more responses are needed
+ */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx,
                     krb5_data *in, krb5_data *out, krb5_data *realm,
                     unsigned int *flags);
 
+/**
+ * Retrieve ticket times for obtained credentials, filling in @a times.
+ *
+ * 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] times    Ticket times for the acquired credentials
+ */
 krb5_error_code KRB5_CALLCONV
 krb5_tkt_creds_get_times(krb5_context context, krb5_tkt_creds_context ctx,
                          krb5_ticket_times *times);

diff --git a/src/lib/krb5/krb/get_creds.c b/src/lib/krb5/krb/get_creds.c
index bf3c226d123fedca39aa364cac3da9b692750da4..e9356f18bdd0b99ea9645b1dc41ec362e234a830 100644 (file)
--- a/src/lib/krb5/krb/get_creds.c
+++ b/src/lib/krb5/krb/get_creds.c
@@ -221,7 +221,7 @@ set_caller_request(krb5_context context, krb5_tkt_creds_context ctx)
 
     *ctx->caller_out = out_copy;
     *ctx->caller_realm = realm_copy;
-    *ctx->caller_flags = 1;
+    *ctx->caller_flags = KRB5_TKT_CREDS_CONTINUE;
     return 0;
 
 cleanup:
@@ -1140,7 +1140,7 @@ krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx)
                                    &flags);
         if (code == KRB5KRB_ERR_RESPONSE_TOO_BIG && !tcp_only)
             tcp_only = 1;
-        else if (code != 0 || (flags & 1) == 0)
+        else if (code != 0 || !(flags & KRB5_TKT_CREDS_CONTINUE))
             break;
         krb5_free_data_contents(context, &reply);