From: Greg Hudson Date: Wed, 12 Oct 2011 15:05:39 +0000 (+0000) Subject: Documentation pass over preauth_plugin.h X-Git-Tag: krb5-1.10-alpha1~51 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=36f0bb19f13e132d449c8a3826154f263ae59ba7;p=krb5.git Documentation pass over preauth_plugin.h No functional changes. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25324 dc483132-0cff-0310-8789-dd5450dbe970 --- 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 */