Add responder feature for initial cred exchanges

Add new APIs:
* krb5_get_init_creds_opt_set_responder
* krb5_responder_get_challenge
* krb5_responder_list_questions
* krb5_responder_set_answer

If a caller sets a responder, it will be invoked after preauth modules
have had a chance to review their incoming padata but before they produce
outgoing padata.  The responder will be presented a set of questions with
optional challenges.  The responder should then answer all questions it knows
how to handle.  Both the answers and the challenges are printable UTF-8 and
may contain encoded, structured data specific to the question asked.

Add two new callbacks and one optional method to the clpreauth
interface.  The new method (prep_questions) allows modules to ask questions
by setting them in the responder context using one of the new callbacks
(ask_responder_question).  The other new callback (get_responder_answer) is
used by the process method to read the answers to the questions asked.

ticket: 7355 (new)

3 files changed, 115 insertions, 1 deletions

diff --git a/src/include/k5-int.h b/src/include/k5-int.h
index 670915d741..bf36a177d9 100644
--- a/src/include/k5-int.h
+++ b/src/include/k5-int.h
@@ -792,6 +792,11 @@ error(MIT_DES_KEYSIZE does not equal KRB5_MIT_DES_KEYSIZE)
 
 #include <krb5/preauth_plugin.h>
 
+typedef struct k5_response_items_st k5_response_items;
+struct krb5_responder_context_st {
+    k5_response_items *items;
+};
+
 typedef krb5_error_code
 (*krb5_gic_get_as_key_fct)(krb5_context, krb5_principal, krb5_enctype,
                            krb5_prompter_fct, void *prompter_data,
@@ -831,6 +836,7 @@ struct krb5_clpreauth_rock_st {
     krb5_timestamp pa_offset;
     krb5_int32 pa_offset_usec;
     enum { NO_OFFSET = 0, UNAUTH_OFFSET, AUTH_OFFSET } pa_offset_state;
+    struct krb5_responder_context_st rctx;
 };
 
 typedef struct _krb5_pa_enc_ts {
@@ -1025,6 +1031,8 @@ typedef struct _krb5_gic_opt_private {
     krb5_flags fast_flags;
     krb5_expire_callback_func expire_cb;
     void *expire_data;
+    krb5_responder_fn responder;
+    void *responder_data;
 } krb5_gic_opt_private;
 
 /*
diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index 2f3974a129..7c519f05d0 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -6353,6 +6353,64 @@ krb5_prompter_posix(krb5_context context, void *data, const char *name,
                     const char *banner, int num_prompts,
                     krb5_prompt prompts[]);
 
+typedef struct krb5_responder_context_st *krb5_responder_context;
+
+/**
+ * List the question names contained in the responder context.
+ *
+ * @param [in] ctx              Library context
+ * @param [in] rctx             Responder context
+ */
+const char * const * KRB5_CALLCONV
+krb5_responder_list_questions(krb5_context ctx, krb5_responder_context rctx);
+
+/**
+ * Retrieve the challenge data for a given question in the responder context.
+ *
+ * @param [in] ctx              Library context
+ * @param [in] rctx             Responder context
+ * @param [in] question         Question name
+ */
+const char * KRB5_CALLCONV
+krb5_responder_get_challenge(krb5_context ctx, krb5_responder_context rctx,
+                             const char *question);
+
+/**
+ * Answer a named question in the responder context.
+ *
+ * @param [in] ctx              Library context
+ * @param [in] rctx             Responder context
+ * @param [in] question         Question name
+ * @param [in] answer           The string to set (MUST be printable UTF-8)
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_responder_set_answer(krb5_context ctx, krb5_responder_context rctx,
+                          const char *question, const char *answer);
+
+/**
+ * Responder function for an initial credential exchange.
+ *
+ * @param [in] ctx              Library context
+ * @param [in] rctx             Responder context
+ * @param [in] data             Callback data
+ *
+ * A responder function is like a prompter function, but is used for handling
+ * questions and answers as potentially complex data types.  Client
+ * preauthentication modules will insert a set of named "questions" into
+ * the responder context.  Each question may optionally contain a challenge.
+ * This challenge is printable UTF-8, but may be an encoded value.  The
+ * precise encoding and contents of the challenge are specific to the question
+ * asked.  When the responder is called, it should answer all the questions it
+ * understands.  Like the challenge, the answer MUST be printable UTF-8, but
+ * may contain structured/encoded data formatted to the expected answer format
+ * of the question.
+ *
+ * If a required question is unanswered, the prompter may be called.
+ */
+typedef krb5_error_code
+(*krb5_responder_fn)(krb5_context ctx, krb5_responder_context rctx,
+                     void *data);
+
 /** Store options for @c _krb5_get_init_creds */
 typedef struct _krb5_get_init_creds_opt {
     krb5_flags flags;
@@ -6712,6 +6770,19 @@ krb5_get_init_creds_opt_set_expire_callback(krb5_context context,
                                             void *data);
 
 /**
+ * Set the responder function in initial credential options.
+ *
+ * @param [in] context          Library context
+ * @param [in] opt              Options structure
+ * @param [in] responder        Responder function
+ * @param [in] data             Responder data argument
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_set_responder(krb5_context context,
+                                      krb5_get_init_creds_opt *opt,
+                                      krb5_responder_fn responder, void *data);
+
+/**
  * Get initial credentials using a password.
  *
  * @param [in]  context         Library context
diff --git a/src/include/krb5/preauth_plugin.h b/src/include/krb5/preauth_plugin.h
index 72fd92d26f..a9a2ab9d2c 100644
--- a/src/include/krb5/preauth_plugin.h
+++ b/src/include/krb5/preauth_plugin.h
@@ -38,7 +38,7 @@
  *
  *
  * The clpreauth interface has a single supported major version, which is
- * 1.  Major version 1 has a current minor version of 1.  clpreauth modules
+ * 1.  Major version 1 has a current minor version of 2.  clpreauth modules
  * should define a function named clpreauth_<modulename>_initvt, matching
  * the signature:
  *
@@ -193,6 +193,19 @@ typedef struct krb5_clpreauth_callbacks_st {
                                         krb5_timestamp *time_out,
                                         krb5_int32 *usec_out);
 
+    /* Set a question to be answered by the responder and optionally provide
+     * a challenge. */
+    krb5_error_code (*ask_responder_question)(krb5_context context,
+                                              krb5_clpreauth_rock rock,
+                                              const char *question,
+                                              const char *challenge);
+
+    /* Get an answer from the responder, or NULL if the question was
+     * unanswered. */
+    const char *(*get_responder_answer)(krb5_context context,
+                                        krb5_clpreauth_rock rock,
+                                        const char *question);
+
     /* End of version 2 clpreauth callbacks (added in 1.11). */
 } *krb5_clpreauth_callbacks;
 
@@ -235,6 +248,25 @@ typedef void
                                   krb5_clpreauth_modreq modreq);
 
 /*
+ * Optional: process server-supplied data in pa_data and set responder
+ * questions.
+ *
+ * encoded_previous_request may be NULL if there has been no previous request
+ * in the AS exchange.
+ */
+typedef krb5_error_code
+(*krb5_clpreauth_prep_questions_fn)(krb5_context context,
+                                    krb5_clpreauth_moddata moddata,
+                                    krb5_clpreauth_modreq modreq,
+                                    krb5_get_init_creds_opt *opt,
+                                    krb5_clpreauth_callbacks cb,
+                                    krb5_clpreauth_rock rock,
+                                    krb5_kdc_req *request,
+                                    krb5_data *encoded_request_body,
+                                    krb5_data *encoded_previous_request,
+                                    krb5_pa_data *pa_data);
+
+/*
  * Mandatory: process server-supplied data in pa_data and return created data
  * in pa_data_out.  Also called after the AS-REP is received if the AS-REP
  * includes preauthentication data of the associated type.
@@ -317,6 +349,9 @@ typedef struct krb5_clpreauth_vtable_st {
     krb5_clpreauth_tryagain_fn tryagain;
     krb5_clpreauth_supply_gic_opts_fn gic_opts;
     /* Minor version 1 ends here. */
+
+    krb5_clpreauth_prep_questions_fn prep_questions;
+    /* Minor version 2 ends here. */
 } *krb5_clpreauth_vtable;
 
 /*