Documentation pass over preauth_plugin.h

No functional changes.

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

1 files changed, 37 insertions, 38 deletions

diff --git a/src/include/krb5/preauth_plugin.h b/src/include/krb5/preauth_plugin.h
index e4f9de2e7..e618edd97 100644
--- a/src/include/krb5/preauth_plugin.h
+++ b/src/include/krb5/preauth_plugin.h
@@ -145,10 +145,9 @@ typedef struct krb5_clpreauth_modreq_st *krb5_clpreauth_modreq;
 
 /*
  * Provided by krb5: a callback which will obtain the user's long-term AS key
- * by prompting the user for the password, then salting it properly, and so on.
- * For the moment, it's identical to the get_as_key callback used inside of
- * libkrb5, but we define a new typedef here instead of making the existing one
- * public to isolate ourselves from potential future changes.
+ * by prompting the user for the password and converting it to a key using the
+ * provided salt and s2kparams.  The resulting key will be placed in
+ * as_key_out, which should be initialized to empty prior to the call.
  */
 typedef krb5_error_code
 (*krb5_clpreauth_get_as_key_fn)(krb5_context context,
@@ -158,7 +157,7 @@ typedef krb5_error_code
                                 void *prompter_data,
                                 krb5_data *salt,
                                 krb5_data *s2kparams,
-                                krb5_keyblock *as_key,
+                                krb5_keyblock *as_key_out,
                                 void *gak_data);
 
 /* Before using a callback after version 1, modules must check the vers
@@ -221,12 +220,15 @@ typedef void
                                   krb5_clpreauth_modreq modreq);
 
 /*
- * Mandatory: process server-supplied data in pa_data and returns created data
- * in out_pa_data.  It is also called after the AS-REP is received if the
- * AS-REP includes preauthentication data of the associated type.  NOTE: the
- * encoded_previous_request will be NULL the first time this function is
- * called, because it is expected to only ever contain the data obtained from a
- * previous call to this function.
+ * 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.
+ *
+ * as_key contains the client-supplied key if known, or an empty keyblock if
+ * not.  If it is empty, the module may use gak_fct to fill it in.
+ *
+ * encoded_previous_request may be NULL if there has been no previous request
+ * in the AS exchange.
  */
 typedef krb5_error_code
 (*krb5_clpreauth_process_fn)(krb5_context context,
@@ -244,12 +246,12 @@ typedef krb5_error_code
                              void *gak_data,
                              krb5_data *salt, krb5_data *s2kparams,
                              krb5_keyblock *as_key,
-                             krb5_pa_data ***out_pa_data);
+                             krb5_pa_data ***pa_data_out);
 
 /*
  * Optional: Attempt to use e-data in the error response to try to recover from
  * the given error.  If this function is provided, and it stores data in
- * out_pa_data which is different data from the contents of in_pa_data, then
+ * pa_data_out which is different data from the contents of pa_data_in, then
  * the client library will retransmit the request.
  */
 typedef krb5_error_code
@@ -262,14 +264,14 @@ typedef krb5_error_code
                               krb5_kdc_req *request,
                               krb5_data *encoded_request_body,
                               krb5_data *encoded_previous_request,
-                              krb5_pa_data *in_pa_data,
+                              krb5_pa_data *pa_data_in,
                               krb5_error *error,
                               krb5_prompter_fct prompter, void *prompter_data,
                               krb5_clpreauth_get_as_key_fn gak_fct,
                               void *gak_data,
                               krb5_data *salt, krb5_data *s2kparams,
                               krb5_keyblock *as_key,
-                              krb5_pa_data ***out_pa_data);
+                              krb5_pa_data ***pa_data_out);
 
 /*
  * Optional: receive krb5_get_init_creds_opt information.  The attr and value
@@ -305,6 +307,26 @@ typedef struct krb5_clpreauth_vtable_st {
     /* Minor version 1 ends here. */
 } *krb5_clpreauth_vtable;
 
+/*
+ * This function allows a clpreauth plugin to obtain preauth options.  The
+ * preauth_data returned from this function should be freed by calling
+ * krb5_get_init_creds_opt_free_pa().
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_get_pa(krb5_context context,
+                               krb5_get_init_creds_opt *opt,
+                               int *num_preauth_data,
+                               krb5_gic_opt_pa_data **preauth_data);
+
+/*
+ * This function frees the preauth_data that was returned by
+ * krb5_get_init_creds_opt_get_pa().
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_free_pa(krb5_context context,
+                                int num_preauth_data,
+                                krb5_gic_opt_pa_data *preauth_data);
+
 
 /*
  * kdcpreauth plugin interface definition.
@@ -486,27 +508,4 @@ typedef struct krb5_kdcpreauth_vtable_st {
     krb5_kdcpreauth_free_modreq_fn free_modreq;
 } *krb5_kdcpreauth_vtable;
 
-/*
- * This function allows a preauth plugin to obtain preauth
- * options.  The preauth_data returned from this function
- * should be freed by calling krb5_get_init_creds_opt_free_pa().
- *
- * The 'opt' pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc().
- */
-krb5_error_code KRB5_CALLCONV
-krb5_get_init_creds_opt_get_pa(krb5_context context,
-                               krb5_get_init_creds_opt *opt,
-                               int *num_preauth_data,
-                               krb5_gic_opt_pa_data **preauth_data);
-
-/*
- * This function frees the preauth_data that was returned by
- * krb5_get_init_creds_opt_get_pa().
- */
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_free_pa(krb5_context context,
-                                int num_preauth_data,
-                                krb5_gic_opt_pa_data *preauth_data);
-
 #endif /* KRB5_PREAUTH_PLUGIN_H_INCLUDED */