Projects/Responder

This project was completed in release 1.11.

Description

The responder mechanism is an alternative to the prompting interface for libkrb5 client preauth plugins.

Problem

The existing prompting interface permits client preauth plugins to ask questions of the user in order to resolve conflicts or ascertain data in order to properly process padata. Most commonly this is something akin to asking the user for a password. However, as time has progressed, user interfaces have moved from text based to graphical and the complexity of questions has increased. This results in a situation where the prompter interface is not the most efficient way to answer complex questions.

Further, the prompter interface requires linear interaction. If multiple questions are required, they have to be asked in serial. However, graphical interfaces present to option to answer multiple questions simultaneously.

The responder mechanism presents the consumer of libkrb5 with a full list of questions needing answers. The responder callback can consider the list and answer whichever questions it chooses to. Each named question is a string contract between the preauth mechanism and the responder callback, allowing complex questions to be handled.

Proposal

The responder allows client preauth plugins to define questions (and optional structured/encoded challenge data) which will be collected and asked once for the entire set from a libkrb5 callback. This callback can view which questions have been asked, optionally inspect the challenge data and then provide structured/encoded answers back to libkrb5. The end result is that inside the responder callback, the application has full knowledge of every question asked, including complex questions, and can provide back a single set of potentially complex answers.

libkrb5 will add the following new functions and types to gic_opts:

typedef struct krb5_responder_context_st *krb5_responder_context;

const char * const * KRB5_CALLCONV
krb5_responder_list_questions(krb5_context ctx, krb5_responder_context rctx);

const char * KRB5_CALLCONV
krb5_responder_get_challenge(krb5_context ctx, krb5_responder_context rctx,
                             const char *question);

krb5_error_code KRB5_CALLCONV
krb5_responder_set_answer(krb5_context ctx, krb5_responder_context rctx,
                          const char *question, const char *answer);

typedef krb5_error_code
(*krb5_responder_fn)(krb5_context ctx, krb5_responder_context rctx,
                     void *data);

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);

The responder callback will be called after libkrb5 receives padata, but before the process() function of the clpreauth interface is called. The responder function will process some or all of the values contained in the response set.

In order to populate the set of questions, a new (optional) function will be added to the clpreauth interface:

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);

This function will be called after receiving padata, but before the process() function is called. Its responsibility is to identify any decisions that need to be made and to expose these decisions via the krb5_response_set data structure.

Expected Behavior

The questions, challenges and answers MUST all be printable UTF8. They can, however, contain encoded data. The preference for encoding is JSON.

Testing

In lib/krb5/krb, a new program t_response_items will exercise the internal k5_response_items manipulation functions.

Documentation

New API functions will have doxygen markup.

The new facility will be documented in init_creds.rst.

Release notes

Developer experience:

• Add an optional responder callback to the krb5_get_init_creds functions. The responder callback can consider and answer all preauth-related questions at once, and can process more complicated questions than the prompter.
• Add a method to the clpreauth interface to allow modules to supply response items for consideration by the responder callback.