Introduce new krb5_tkt_creds API

Merged from branches/iakerb: add new asynchronous krb5_tkt_creds APIs,
which allow a caller to take responsibility for transporting requests
to the KDC and getting responses back.  Rewrite the existing
krb5_get_credentials API in terms of the new functions.  Get rid of
krb5_get_cred_from_kdc and friends, since they are no longer used.

ticket: 6700

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

2 files changed, 96 insertions, 9 deletions

diff --git a/src/include/k5-int.h b/src/include/k5-int.h
index 8b72b06da..fde8e6660 100644
--- a/src/include/k5-int.h
+++ b/src/include/k5-int.h
@@ -2574,15 +2574,6 @@ krb5_error_code krb5_kdc_rep_decrypt_proc(krb5_context, const krb5_keyblock *,
 krb5_error_code KRB5_CALLCONV krb5_decrypt_tkt_part(krb5_context,
                                                     const krb5_keyblock *,
                                                     krb5_ticket * );
-krb5_error_code krb5_get_cred_from_kdc(krb5_context, krb5_ccache,
-                                       krb5_creds *, krb5_creds **,
-                                       krb5_creds *** );
-krb5_error_code krb5_get_cred_from_kdc_validate(krb5_context, krb5_ccache,
-                                                krb5_creds *, krb5_creds **,
-                                                krb5_creds *** );
-krb5_error_code krb5_get_cred_from_kdc_renew(krb5_context, krb5_ccache,
-                                             krb5_creds *, krb5_creds **,
-                                             krb5_creds *** );
 
 krb5_error_code krb5_get_cred_via_tkt(krb5_context, krb5_creds *, krb5_flags,
                                       krb5_address *const *, krb5_creds *,
diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index 740390c9a..945d424d2 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -2415,6 +2415,102 @@ krb5_error_code KRB5_CALLCONV
 krb5_init_creds_get_times(krb5_context context, krb5_init_creds_context ctx,
                           krb5_ticket_times *times);
 
+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 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.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
+                    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);
+
+/**
+ * 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);
+
 krb5_error_code KRB5_CALLCONV
 krb5_get_init_creds_keytab(krb5_context context, krb5_creds *creds,
                            krb5_principal client, krb5_keytab arg_keytab,