466 lines
12 KiB
Groff
466 lines
12 KiB
Groff
.\" Copyright (c) 2003 Kungliga Tekniska Högskolan
|
|
.\" (Royal Institute of Technology, Stockholm, Sweden).
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" 3. Neither the name of the Institute nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $Id: gss_acquire_cred.3,v 1.8.2.1 2003/04/28 13:41:42 lha Exp $
|
|
.\"
|
|
.Dd April 2, 2003
|
|
.Dt GSS_ACQUIRE_CRED 3
|
|
.Os HEIMDAL
|
|
.Sh NAME
|
|
.Nm gss_accept_sec_context ,
|
|
.Nm gss_acquire_cred ,
|
|
.Nm gss_add_cred ,
|
|
.Nm gss_add_oid_set_member ,
|
|
.Nm gss_canonicalize_name ,
|
|
.Nm gss_compare_name ,
|
|
.Nm gss_context_time ,
|
|
.Nm gss_create_empty_oid_set ,
|
|
.Nm gss_delete_sec_context ,
|
|
.Nm gss_display_name ,
|
|
.Nm gss_display_status ,
|
|
.Nm gss_duplicate_name ,
|
|
.Nm gss_export_name ,
|
|
.Nm gss_export_sec_context ,
|
|
.Nm gss_get_mic ,
|
|
.Nm gss_import_name ,
|
|
.Nm gss_import_sec_context ,
|
|
.Nm gss_indicate_mechs ,
|
|
.Nm gss_init_sec_context ,
|
|
.Nm gss_inquire_context ,
|
|
.Nm gss_inquire_cred ,
|
|
.Nm gss_inquire_cred_by_mech ,
|
|
.Nm gss_inquire_mechs_for_name ,
|
|
.Nm gss_inquire_names_for_mech ,
|
|
.Nm gss_krb5_copy_ccache ,
|
|
.Nm gss_krb5_compat_des3_mic ,
|
|
.Nm gss_process_context_token ,
|
|
.Nm gss_release_buffer ,
|
|
.Nm gss_release_cred ,
|
|
.Nm gss_release_name ,
|
|
.Nm gss_release_oid_set ,
|
|
.Nm gss_seal ,
|
|
.Nm gss_sign ,
|
|
.Nm gss_test_oid_set_member ,
|
|
.Nm gss_unseal ,
|
|
.Nm gss_unwrap ,
|
|
.Nm gss_verify ,
|
|
.Nm gss_verify_mic ,
|
|
.Nm gss_wrap ,
|
|
.Nm gss_wrap_size_limit
|
|
.Nd Generic Security Service Application Program Interface library
|
|
.Sh LIBRARY
|
|
GSS-API library (libgssapi, -lgssapi)
|
|
.Sh SYNOPSIS
|
|
.In gssapi.h
|
|
.Pp
|
|
.Ft OM_uint32
|
|
.Fo gss_accept_sec_context
|
|
.Fa "OM_uint32 * minor_status"
|
|
.Fa "gss_ctx_id_t * context_handle"
|
|
.Fa "const gss_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
|
|
.Pp
|
|
.Ft OM_uint32
|
|
.Fo gss_acquire_cred
|
|
.Fa "OM_uint32 * minor_status"
|
|
.Fa "const gss_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
|
|
.\" .Fn gss_add_cred
|
|
.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 "const gss_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 "const gss_name_t name1"
|
|
.Fa "const gss_name_t name2"
|
|
.Fa "int * name_equal"
|
|
.Fc
|
|
.Ft OM_uint32
|
|
.Fo gss_context_time
|
|
.Fa "OM_uint32 * minor_status"
|
|
.Fa "const gss_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 "const gss_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 "const gss_name_t src_name"
|
|
.Fa "gss_name_t * dest_name"
|
|
.Fc
|
|
.Ft OM_uint32
|
|
.Fo gss_export_name
|
|
.Fa "OM_uint32 * minor_status"
|
|
.Fa "const gss_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 "const gss_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 "const gss_cred_id_t initiator_cred_handle"
|
|
.Fa "gss_ctx_id_t * context_handle"
|
|
.Fa "const gss_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 "const gss_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 "const gss_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
|
|
.Fc
|
|
.Ft OM_uint32
|
|
.Fo gss_inquire_mechs_for_name
|
|
.Fc
|
|
.Ft OM_uint32
|
|
.Fo gss_inquire_names_for_mech
|
|
.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_compat_des3_mic
|
|
.Fa "OM_uint32 * minor_status"
|
|
.Fa "gss_ctx_id_t context_handle"
|
|
.Fa "int onoff"
|
|
.Fc
|
|
.Ft OM_uint32
|
|
.Fo gss_process_context_token
|
|
.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
|
|
.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 "const gss_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 "const gss_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
|
|
.Fo gss_wrap
|
|
.Fa "OM_uint32 * minor_status"
|
|
.Fa "const gss_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 "const gss_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
|
|
.Sh DESCRIPTION
|
|
Generic Security Service API (GSS-API) version 2, and its C binding,
|
|
is described in
|
|
.Li RFC2743
|
|
and
|
|
.Li RFC2744 .
|
|
Version 1 (deprecated) of the C binding is described in
|
|
.Li RFC1509 .
|
|
.Pp
|
|
Heimdals GSS-API implementation supports the following mechanisms
|
|
.Bl -bullet
|
|
.It
|
|
.Li GSS_KRB5_MECHANISM
|
|
.El
|
|
.Pp
|
|
GSS-API have generic name types that all mechanism are supposed to
|
|
implement (if possible)
|
|
.Bl -bullet
|
|
.It
|
|
.Li GSS_C_NT_USER_NAME
|
|
.It
|
|
.Li GSS_C_NT_MACHINE_UID_NAME
|
|
.It
|
|
.Li GSS_C_NT_STRING_UID_NAME
|
|
.It
|
|
.Li GSS_C_NT_HOSTBASED_SERVICE
|
|
.It
|
|
.Li GSS_C_NT_ANONYMOUS
|
|
.It
|
|
.Li GSS_C_NT_EXPORT_NAME
|
|
.El
|
|
.Pp
|
|
GSS-API implementations that supports Kerberos 5 have some additional
|
|
name types
|
|
.Bl -bullet
|
|
.It
|
|
.Li GSS_KRB5_NT_PRINCIPAL_NAME
|
|
.It
|
|
.Li GSS_KRB5_NT_USER_NAME
|
|
.It
|
|
.Li GSS_KRB5_NT_MACHINE_UID_NAME
|
|
.It
|
|
.Li GSS_KRB5_NT_STRING_UID_NAME
|
|
.El
|
|
.Pp
|
|
.Fn gss_display_name
|
|
takes the gss name in
|
|
.Fa input_name
|
|
and put 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
|
|
.Dv NULL
|
|
or a pointer to a
|
|
.Li gss_OID
|
|
and will in the later case contain the OID type of the name.
|
|
The name should only be used for printing.
|
|
Access control should be done with the result of
|
|
.Fn gss_export_name .
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
.Fn gss_krb5_copy_ccache
|
|
is an extension to the GSS-API API.
|
|
The function will extract the krb5 credential that are transfered 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 .
|
|
.Pp
|
|
.Nm gss_krb5_compat_des3_mic
|
|
turns on or off the compatibly 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
|
|
.Xr gssapi 3 ) .
|
|
If the CPP symbol
|
|
.Dv GSS_C_KRB5_COMPAT_DES3_MIC
|
|
is present,
|
|
.Nm gss_krb5_compat_des3_mic
|
|
exists.
|
|
.Nm gss_krb5_compat_des3_mic
|
|
will be removed in a later version of the GSS-API library.
|
|
.Sh SEE ALSO
|
|
.Xr krb5 3 ,
|
|
.Xr krb5_ccache 3 ,
|
|
.Xr gssapi 3 ,
|
|
.Xr kerberos 8
|