From 8cc9326f64c2e10889ef70456338c088c5a01b3f Mon Sep 17 00:00:00 2001 From: Marco Molteni Date: Tue, 25 Sep 2012 10:05:34 +0200 Subject: [PATCH] Document some GSS-API functions and fix some spelling errors. No code changes. Signed-off-by: Love Hornquist Astrand --- lib/gssapi/mech/doxygen.c | 19 +++++++++---------- lib/gssapi/mech/gss_display_status.c | 26 ++++++++++++++++++++++---- lib/gssapi/mech/gss_export_name.c | 14 ++++++++++++++ lib/gssapi/mech/gss_import_name.c | 12 ++++++------ lib/krb5/sendauth.c | 23 +++++++++++++++++++++++ 5 files changed, 74 insertions(+), 20 deletions(-) diff --git a/lib/gssapi/mech/doxygen.c b/lib/gssapi/mech/doxygen.c index a341cba2d..e20681a80 100644 --- a/lib/gssapi/mech/doxygen.c +++ b/lib/gssapi/mech/doxygen.c @@ -39,13 +39,12 @@ * - SPNEGO * - NTLM * - * See @ref gssapi_mechs for more describtion about these mechanisms. - * - * The project web page: http://www.h5l.org/ + * @sa * * - @ref gssapi_services_intro * - @ref gssapi_mechs * - @ref gssapi_api_INvsMN + * - The project web page: http://www.h5l.org/ */ /** @@ -105,27 +104,27 @@ * @page internalVSmechname Internal names and mechanism names * @section gssapi_api_INvsMN Name forms * - * There are two forms of name in GSS-API, Internal form and - * Contiguous string ("flat") form. gss_export_name() and + * There are two name representations in GSS-API: Internal form and + * Contiguous string ("flat") form. Functions gss_export_name() and * gss_import_name() can be used to convert between the two forms. * * - The contiguous string form is described by an oid specificing the * type and an octet string. A special form of the contiguous * string form is the exported name object. The exported name * defined for each mechanism, is something that can be stored and - * complared later. The exported name is what should be used for + * compared later. The exported name is what should be used for * ACLs comparisons. * - * - The Internal form + * - The Internal form is opaque to the application programmer and + * is implementation-dependent. * - * There is also special form of the Internal Name (IN), and that is + * - There is also a special form of the Internal Name (IN), and that is * the Mechanism Name (MN). In the mechanism name all the generic * information is stripped of and only contain the information for * one mechanism. In GSS-API some function return MN and some * require MN as input. Each of these function is marked up as such. * - * - * Describe relationship between import_name, canonicalize_name, + * @TODO Describe relationship between import_name, canonicalize_name, * export_name and friends. */ diff --git a/lib/gssapi/mech/gss_display_status.c b/lib/gssapi/mech/gss_display_status.c index 1e508caa9..a79ef350d 100644 --- a/lib/gssapi/mech/gss_display_status.c +++ b/lib/gssapi/mech/gss_display_status.c @@ -134,25 +134,43 @@ supplementary_error(OM_uint32 v) return msgs[v]; } - +/** + * Convert a GSS-API status code to text + * + * @param minor_status minor status code + * @param status_value status value to convert + * @param status_type One of: + * GSS_C_GSS_CODE - status_value is a GSS status code, + * GSS_C_MECH_CODE - status_value is a mechanism status code + * @param mech_type underlying mechanism. Use GSS_C_NO_OID to obtain the + * system default. + * @param message_context state information to extract further messages from the + * status_value + * @param status_string the allocated text representation. Release with + * gss_release_buffer() + * + * @returns a gss_error code. + * + * @ingroup gssapi + */ GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_display_status(OM_uint32 *minor_status, OM_uint32 status_value, int status_type, const gss_OID mech_type, - OM_uint32 *message_content, + OM_uint32 *message_context, gss_buffer_t status_string) { OM_uint32 major_status; _mg_buffer_zero(status_string); - *message_content = 0; + *message_context = 0; major_status = _gss_mg_get_error(mech_type, status_type, status_value, status_string); if (major_status == GSS_S_COMPLETE) { - *message_content = 0; + *message_context = 0; *minor_status = 0; return GSS_S_COMPLETE; } diff --git a/lib/gssapi/mech/gss_export_name.c b/lib/gssapi/mech/gss_export_name.c index 3e6e62681..b1c0c8388 100644 --- a/lib/gssapi/mech/gss_export_name.c +++ b/lib/gssapi/mech/gss_export_name.c @@ -28,6 +28,20 @@ #include "mech_locl.h" +/** + * Convert a GGS-API name from internal form to contiguous string. + * + * @sa gss_import_name(), @ref internalVSmechname. + * + * @param minor_status minor status code + * @param input_name input name in internal name form + * @param exported_name output name in contiguos string form + * + * @returns a gss_error code, see gss_display_status() about printing + * the error code. + * + * @ingroup gssapi + */ GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_export_name(OM_uint32 *minor_status, const gss_name_t input_name, diff --git a/lib/gssapi/mech/gss_import_name.c b/lib/gssapi/mech/gss_import_name.c index d1b3dc95b..4c1d940d9 100644 --- a/lib/gssapi/mech/gss_import_name.c +++ b/lib/gssapi/mech/gss_import_name.c @@ -149,7 +149,7 @@ _gss_import_export_name(OM_uint32 *minor_status, } /** - * Import a name internal or mechanism name + * Convert a GGS-API name from contiguous string to internal form. * * Type of name and their format: * - GSS_C_NO_OID @@ -159,12 +159,12 @@ _gss_import_export_name(OM_uint32 *minor_status, * - GSS_C_NT_ANONYMOUS * - GSS_KRB5_NT_PRINCIPAL_NAME * - * For more information about @ref internalVSmechname. + * @sa gss_export_name(), @ref internalVSmechname. * - * @param minor_status minor status code - * @param input_name_buffer import name buffer - * @param input_name_type type of the import name buffer - * @param output_name the resulting type, release with + * @param minor_status minor status code + * @param input_name_buffer import name buffer + * @param input_name_type type of the import name buffer + * @param output_name the resulting type, release with * gss_release_name(), independent of input_name * * @returns a gss_error code, see gss_display_status() about printing diff --git a/lib/krb5/sendauth.c b/lib/krb5/sendauth.c index d334d3449..5011c2680 100644 --- a/lib/krb5/sendauth.c +++ b/lib/krb5/sendauth.c @@ -60,6 +60,29 @@ * } */ +/** + * Perform the client side of the sendauth protocol. + * + * @param context Kerberos 5 context. + * @param auth_context Authentication context of the peer. + * @param p_fd Socket associated to the connection. + * @param appl_version Server-specific string. + * @param client Client principal. If NULL, use the credentials in \a ccache. + * @param server Server principal. + * @param ap_req_options Options for the AP_REQ message. See the AP_OPTS_* defines in krb5.h. + * @param in_data FIXME + * @param in_creds FIXME + * @param ccache Credentials cache. If NULL, use the default credentials cache. + * @param ret_error If not NULL, will be set to the error reported by server, if any. + * Must be deallocated with krb5_free_error_contents(). + * @param rep_result If not NULL, will be set to the EncApRepPart of the AP_REP message. + * Must be deallocated with krb5_free_ap_rep_enc_part(). + * @param out_creds FIXME If not NULL, will be set to FIXME. Must be deallocated with + * krb5_free_creds(). + * + * @return 0 to indicate success. Otherwise a Kerberos error code is + * returned, see krb5_get_error_message(). + */ KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sendauth(krb5_context context, krb5_auth_context *auth_context,