gss_acquire_cred (3) - Linux Manuals

NAME

gss_accept_sec_context gss_acquire_cred gss_add_cred gss_add_oid_set_member gss_canonicalize_name gss_compare_name gss_context_time gss_create_empty_oid_set gss_delete_sec_context gss_display_name gss_display_status gss_duplicate_name gss_export_name gss_export_sec_context gss_get_mic gss_import_name gss_import_sec_context gss_indicate_mechs gss_init_sec_context gss_inquire_context gss_inquire_cred gss_inquire_cred_by_mech gss_inquire_mechs_for_name gss_inquire_names_for_mech gss_krb5_ccache_name gss_krb5_compat_des3_mic gss_krb5_copy_ccache gss_krb5_import_cred gsskrb5_extract_authz_data_from_sec_context gsskrb5_register_acceptor_identity gss_krb5_import_ccache gss_krb5_get_tkt_flags gss_process_context_token gss_release_buffer gss_release_cred gss_release_name gss_release_oid_set gss_seal gss_sign gss_test_oid_set_member gss_unseal gss_unwrap gss_verify gss_verify_mic gss_wrap gss_wrap_size_limit - Generic Security Service Application Program Interface library

LIBRARY

GSS-API library (libgssapi, -lgssapi)

SYNOPSIS

In gssapi.h

Ft OM_uint32 Fo gss_accept_sec_context Fa OM_uint32 * minor_status Fa gss_ctx_id_t * context_handle Fa gss_const_cred_id_t acceptor_cred_handle Fa const gss_buffer_t input_token_buffer Fa const gss_channel_bindings_t input_chan_bindings Fa gss_name_t * src_name Fa gss_OID * mech_type Fa gss_buffer_t output_token Fa OM_uint32 * ret_flags Fa OM_uint32 * time_rec Fa gss_cred_id_t * delegated_cred_handle Fc

Ft OM_uint32 Fo gss_acquire_cred Fa OM_uint32 * minor_status Fa gss_const_name_t desired_name Fa OM_uint32 time_req Fa const gss_OID_set desired_mechs Fa gss_cred_usage_t cred_usage Fa gss_cred_id_t * output_cred_handle Fa gss_OID_set * actual_mechs Fa OM_uint32 * time_rec Fc Ft OM_uint32 Fo gss_add_cred Fa OM_uint32 *minor_status Fa gss_const_cred_id_t input_cred_handle Fa gss_const_name_t desired_name Fa const gss_OID desired_mech Fa gss_cred_usage_t cred_usage Fa OM_uint32 initiator_time_req Fa OM_uint32 acceptor_time_req Fa gss_cred_id_t *output_cred_handle Fa gss_OID_set *actual_mechs Fa OM_uint32 *initiator_time_rec Fa OM_uint32 *acceptor_time_rec Fc Ft OM_uint32 Fo gss_add_oid_set_member Fa OM_uint32 * minor_status Fa const gss_OID member_oid Fa gss_OID_set * oid_set Fc Ft OM_uint32 Fo gss_canonicalize_name Fa OM_uint32 * minor_status Fa gss_const_name_t input_name Fa const gss_OID mech_type Fa gss_name_t * output_name Fc Ft OM_uint32 Fo gss_compare_name Fa OM_uint32 * minor_status Fa gss_const_name_t name1 Fa gss_const_name_t name2 Fa int * name_equal Fc Ft OM_uint32 Fo gss_context_time Fa OM_uint32 * minor_status Fa gss_const_ctx_id_t context_handle Fa OM_uint32 * time_rec Fc Ft OM_uint32 Fo gss_create_empty_oid_set Fa OM_uint32 * minor_status Fa gss_OID_set * oid_set Fc Ft OM_uint32 Fo gss_delete_sec_context Fa OM_uint32 * minor_status Fa gss_ctx_id_t * context_handle Fa gss_buffer_t output_token Fc Ft OM_uint32 Fo gss_display_name Fa OM_uint32 * minor_status Fa gss_const_name_t input_name Fa gss_buffer_t output_name_buffer Fa gss_OID * output_name_type Fc Ft OM_uint32 Fo gss_display_status Fa OM_uint32 *minor_status Fa OM_uint32 status_value Fa int status_type Fa const gss_OID mech_type Fa OM_uint32 *message_context Fa gss_buffer_t status_string Fc Ft OM_uint32 Fo gss_duplicate_name Fa OM_uint32 * minor_status Fa gss_const_name_t src_name Fa gss_name_t * dest_name Fc Ft OM_uint32 Fo gss_export_name Fa OM_uint32 * minor_status Fa gss_const_name_t input_name Fa gss_buffer_t exported_name Fc Ft OM_uint32 Fo gss_export_sec_context Fa OM_uint32 * minor_status Fa gss_ctx_id_t * context_handle Fa gss_buffer_t interprocess_token Fc Ft OM_uint32 Fo gss_get_mic Fa OM_uint32 * minor_status Fa gss_const_ctx_id_t context_handle Fa gss_qop_t qop_req Fa const gss_buffer_t message_buffer Fa gss_buffer_t message_token Fc Ft OM_uint32 Fo gss_import_name Fa OM_uint32 * minor_status Fa const gss_buffer_t input_name_buffer Fa const gss_OID input_name_type Fa gss_name_t * output_name Fc Ft OM_uint32 Fo gss_import_sec_context Fa OM_uint32 * minor_status Fa const gss_buffer_t interprocess_token Fa gss_ctx_id_t * context_handle Fc Ft OM_uint32 Fo gss_indicate_mechs Fa OM_uint32 * minor_status Fa gss_OID_set * mech_set Fc Ft OM_uint32 Fo gss_init_sec_context Fa OM_uint32 * minor_status Fa gss_const_cred_id_t initiator_cred_handle Fa gss_ctx_id_t * context_handle Fa gss_const_name_t target_name Fa const gss_OID mech_type Fa OM_uint32 req_flags Fa OM_uint32 time_req Fa const gss_channel_bindings_t input_chan_bindings Fa const gss_buffer_t input_token Fa gss_OID * actual_mech_type Fa gss_buffer_t output_token Fa OM_uint32 * ret_flags Fa OM_uint32 * time_rec Fc Ft OM_uint32 Fo gss_inquire_context Fa OM_uint32 * minor_status Fa gss_const_ctx_id_t context_handle Fa gss_name_t * src_name Fa gss_name_t * targ_name Fa OM_uint32 * lifetime_rec Fa gss_OID * mech_type Fa OM_uint32 * ctx_flags Fa int * locally_initiated Fa int * open_context Fc Ft OM_uint32 Fo gss_inquire_cred Fa OM_uint32 * minor_status Fa gss_const_cred_id_t cred_handle Fa gss_name_t * name Fa OM_uint32 * lifetime Fa gss_cred_usage_t * cred_usage Fa gss_OID_set * mechanisms Fc Ft OM_uint32 Fo gss_inquire_cred_by_mech Fa OM_uint32 * minor_status Fa gss_const_cred_id_t cred_handle Fa const gss_OID mech_type Fa gss_name_t * name Fa OM_uint32 * initiator_lifetime Fa OM_uint32 * acceptor_lifetime Fa gss_cred_usage_t * cred_usage Fc Ft OM_uint32 Fo gss_inquire_mechs_for_name Fa OM_uint32 * minor_status Fa gss_const_name_t input_name Fa gss_OID_set * mech_types Fc Ft OM_uint32 Fo gss_inquire_names_for_mech Fa OM_uint32 * minor_status Fa const gss_OID mechanism Fa gss_OID_set * name_types Fc Ft OM_uint32 Fo gss_krb5_ccache_name Fa OM_uint32 *minor Fa const char *name Fa const char **old_name Fc Ft OM_uint32 Fo gss_krb5_copy_ccache Fa OM_uint32 *minor Fa gss_cred_id_t cred Fa krb5_ccache out Fc Ft OM_uint32 Fo gss_krb5_import_cred Fa OM_uint32 *minor_status Fa krb5_ccache id Fa krb5_principal keytab_principal Fa krb5_keytab keytab Fa gss_cred_id_t *cred Fc Ft OM_uint32 Fo gss_krb5_compat_des3_mic Fa OM_uint32 * minor_status Fa gss_ctx_id_t context_handle Fa int onoff Fc Ft OM_uint32 Fo gsskrb5_extract_authz_data_from_sec_context Fa OM_uint32 *minor_status Fa gss_ctx_id_t context_handle Fa int ad_type Fa gss_buffer_t ad_data Fc Ft OM_uint32 Fo gsskrb5_register_acceptor_identity Fa const char *identity Fc Ft OM_uint32 Fo gss_krb5_import_cache Fa OM_uint32 *minor Fa krb5_ccache id Fa krb5_keytab keytab Fa gss_cred_id_t *cred Fc Ft OM_uint32 Fo gss_krb5_get_tkt_flags Fa OM_uint32 *minor_status Fa gss_ctx_id_t context_handle Fa OM_uint32 *tkt_flags Fc Ft OM_uint32 Fo gss_process_context_token Fa OM_uint32 * minor_status Fa gss_const_ctx_id_t context_handle Fa const gss_buffer_t token_buffer Fc Ft OM_uint32 Fo gss_release_buffer Fa OM_uint32 * minor_status Fa gss_buffer_t buffer Fc Ft OM_uint32 Fo gss_release_cred Fa OM_uint32 * minor_status Fa gss_cred_id_t * cred_handle Fc Ft OM_uint32 Fo gss_release_name Fa OM_uint32 * minor_status Fa gss_name_t * input_name Fc Ft OM_uint32 Fo gss_release_oid_set Fa OM_uint32 * minor_status Fa gss_OID_set * set Fc Ft OM_uint32 Fo gss_seal Fa OM_uint32 * minor_status Fa gss_ctx_id_t context_handle Fa int conf_req_flag Fa int qop_req Fa gss_buffer_t input_message_buffer Fa int * conf_state Fa gss_buffer_t output_message_buffer Fc Ft OM_uint32 Fo gss_sign Fa OM_uint32 * minor_status Fa gss_ctx_id_t context_handle Fa int qop_req Fa gss_buffer_t message_buffer Fa gss_buffer_t message_token Fc Ft OM_uint32 Fo gss_test_oid_set_member Fa OM_uint32 * minor_status Fa const gss_OID member Fa const gss_OID_set set Fa int * present Fc Ft OM_uint32 Fo gss_unseal Fa OM_uint32 * minor_status Fa gss_ctx_id_t context_handle Fa gss_buffer_t input_message_buffer Fa gss_buffer_t output_message_buffer Fa int * conf_state Fa int * qop_state Fc Ft OM_uint32 Fo gss_unwrap Fa OM_uint32 * minor_status Fa gss_const_ctx_id_t context_handle Fa const gss_buffer_t input_message_buffer Fa gss_buffer_t output_message_buffer Fa int * conf_state Fa gss_qop_t * qop_state Fc Ft OM_uint32 Fo gss_verify Fa OM_uint32 * minor_status Fa gss_ctx_id_t context_handle Fa gss_buffer_t message_buffer Fa gss_buffer_t token_buffer Fa int * qop_state Fc Ft OM_uint32 Fo gss_verify_mic Fa OM_uint32 * minor_status Fa gss_const_ctx_id_t context_handle Fa const gss_buffer_t message_buffer Fa const gss_buffer_t token_buffer Fa gss_qop_t * qop_state Fc Ft OM_uint32 Fo gss_wrap Fa OM_uint32 * minor_status Fa gss_const_ctx_id_t context_handle Fa int conf_req_flag Fa gss_qop_t qop_req Fa const gss_buffer_t input_message_buffer Fa int * conf_state Fa gss_buffer_t output_message_buffer Fc Ft OM_uint32 Fo gss_wrap_size_limit Fa OM_uint32 * minor_status Fa gss_const_ctx_id_t context_handle Fa int conf_req_flag Fa gss_qop_t qop_req Fa OM_uint32 req_output_size Fa OM_uint32 * max_input_size Fc

DESCRIPTION

Generic Security Service API (GSS-API) version 2, and its C binding, is described in RFC2743 and RFC2744 Version 1 (deprecated) of the C binding is described in RFC1509

Heimdals GSS-API implementation supports the following mechanisms

GSS-API have generic name types that all mechanism are supposed to implement (if possible):

GSS-API implementations that supports Kerberos 5 have some additional name types:

In GSS-API, names have two forms, internal names and contiguous string names.

ACCESS CONTROL

There are two ways of comparing GSS-API names, either comparing two internal names with each other or two contiguous string names with either other.

To compare two internal names with each other, import (if needed) the names with Fn gss_import_name into the GSS-API implementation and the compare the imported name with Fn gss_compare_name .

Importing names can be slow, so when its possible to store exported names in the access control list, comparing contiguous string name might be better.

when comparing contiguous string name, first export them into a GSS_C_NT_EXPORT_NAME name with Fn gss_export_name and then compare with memcmp(3).

Note that there are might be a difference between the two methods of comparing names. The first (using Fn gss_compare_name ) will compare to (unauthenticated) names are the same. The second will compare if a mechanism will authenticate them as the same principal.

For example, if Fn gss_import_name name was used with GSS_C_NO_OID the default syntax is used for all mechanism the GSS-API implementation supports. When compare the imported name of GSS_C_NO_OID it may match serveral mechanism names (MN).

The resulting name from Fn gss_display_name must not be used for acccess control.

FUNCTIONS

Fn gss_display_name takes the gss name in Fa input_name and puts a printable form in Fa output_name_buffer . Fa output_name_buffer should be freed when done using Fn gss_release_buffer . Fa output_name_type can either be NULL or a pointer to a gss_OID and will in the latter case contain the OID type of the name. The name must only be used for printing. If access control is needed, see section Sx ACCESS CONTROL .

Fn gss_inquire_context returns information about the context. Information is available even after the context have expired. Fa lifetime_rec argument is set to GSS_C_INDEFINITE (dont expire) or the number of seconds that the context is still valid. A value of 0 means that the context is expired. Fa mech_type argument should be considered readonly and must not be released. Fa src_name and Fn dest_name are both mechanims names and must be released with Fn gss_release_name when no longer used.

gss_context_time will return the amount of time (in seconds) of the context is still valid. If its expired Fa time_rec will be set to 0 and GSS_S_CONTEXT_EXPIRED returned.

Fn gss_sign , Fn gss_verify , Fn gss_seal , and Fn gss_unseal are part of the GSS-API V1 interface and are obsolete. The functions should not be used for new applications. They are provided so that version 1 applications can link against the library.

EXTENSIONS

Fn gss_krb5_ccache_name sets the internal kerberos 5 credential cache name to Fa name . The old name is returned in Fa old_name , and must not be freed. The data allocated for Fa old_name is free upon next call to Fn gss_krb5_ccache_name . This function is not threadsafe if Fa old_name argument is used.

Fn gss_krb5_copy_ccache will extract the krb5 credentials that are transferred from the initiator to the acceptor when using token delegation in the Kerberos mechanism. The acceptor receives the delegated token in the last argument to Fn gss_accept_sec_context .

Fn gss_krb5_import_cred will import the krb5 credentials (both keytab and/or credential cache) into gss credential so it can be used withing GSS-API. The Fa ccache is copied by reference and thus shared, so if the credential is destroyed with Fa krb5_cc_destroy , all users of thep Fa gss_cred_id_t returned by Fn gss_krb5_import_ccache will fail.

Fn gsskrb5_register_acceptor_identity sets the Kerberos 5 filebased keytab that the acceptor will use. The Fa identifier is the file name.

Fn gsskrb5_extract_authz_data_from_sec_context extracts the Kerberos authorizationdata that may be stored within the context. Tha caller must free the returned buffer Fa ad_data with Fn gss_release_buffer upon success.

Fn gss_krb5_get_tkt_flags return the ticket flags for the kerberos ticket receive when authenticating the initiator. Only valid on the acceptor context.

Fn gss_krb5_compat_des3_mic turns on or off the compatibility with older version of Heimdal using des3 get and verify mic, this is way to programmatically set the [gssapi]broken_des3_mic and [gssapi]correct_des3_mic flags (see COMPATIBILITY section in gssapi(3)). If the CPP symbol GSS_C_KRB5_COMPAT_DES3_MIC is present, Fn gss_krb5_compat_des3_mic exists. Fn gss_krb5_compat_des3_mic will be removed in a later version of the GSS-API library.

SEE ALSO

gssapi(3), krb5(3), krb5_ccache3, kerberos(8)