HeimdalGSS-APIlibrary: Heimdal GSS-API functions

Heimdal GSS-API functions


Functions
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_add_oid_set_member (OM_uint32 minor_status, const gss_OID member_oid, gss_OID_set oid_set)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_wrap_iov (OM_uint32 minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int conf_state, gss_iov_buffer_desc *iov, int iov_count)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_unwrap_iov (OM_uint32 minor_status, gss_ctx_id_t context_handle, int conf_state, gss_qop_t qop_state, gss_iov_buffer_desc iov, int iov_count)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_wrap_iov_length (OM_uint32 minor_status, gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, int conf_state, gss_iov_buffer_desc *iov, int iov_count)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_release_iov_buffer (OM_uint32 minor_status, gss_iov_buffer_desc iov, int iov_count)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_canonicalize_name (OM_uint32 minor_status, const gss_name_t input_name, const gss_OID mech_type, gss_name_t output_name)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_import_name (OM_uint32 minor_status, const gss_buffer_t input_name_buffer, const gss_OID input_name_type, gss_name_t output_name)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_init_sec_context (OM_uint32 minor_status, const gss_cred_id_t initiator_cred_handle, gss_ctx_id_t context_handle, const gss_name_t target_name, const gss_OID input_mech_type, OM_uint32 req_flags, OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings, const gss_buffer_t input_token, gss_OID actual_mech_type, gss_buffer_t output_token, OM_uint32 ret_flags, OM_uint32 *time_rec)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_inquire_saslname_for_mech (OM_uint32 *minor_status, const gss_OID desired_mech, gss_buffer_t sasl_mech_name, gss_buffer_t mech_name, gss_buffer_t mech_description)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_inquire_attrs_for_mech (OM_uint32 minor_status, gss_const_OID mech, gss_OID_set mech_attr, gss_OID_set *known_mech_attrs)
GSSAPI_LIB_FUNCTION int GSSAPI_LIB_CALL	gss_oid_equal (gss_const_OID a, gss_const_OID b)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_release_cred (OM_uint32 minor_status, gss_cred_id_t cred_handle)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_release_name (OM_uint32 minor_status, gss_name_t input_name)
GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL	gss_wrap (OM_uint32 minor_status, const gss_ctx_id_t context_handle, int conf_req_flag, gss_qop_t qop_req, const gss_buffer_t input_message_buffer, int conf_state, gss_buffer_t output_message_buffer)
Variables
gss_OID_desc GSSAPI_LIB_FUNCTION	__gss_c_attr_stream_sizes_oid_desc

Detailed Description

Function Documentation

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_add_oid_set_member	(	OM_uint32 *	minor_status,
		const gss_OID	member_oid,
		gss_OID_set *	oid_set
	)

Add a oid to the oid set, function does not make a copy of the oid, so the pointer to member_oid needs to be stable for the whole time oid_set is used.

If there is a duplicate member of the oid, the new member is not added to to the set.

Parameters:

	minor_status	minor status code.
	member_oid	member to add to the oid set
	oid_set	oid set to add the member too

Returns:: a gss_error code, see gss_display_status() about printing the error code.

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_canonicalize_name	(	OM_uint32 *	minor_status,
		const gss_name_t	input_name,
		const gss_OID	mech_type,
		gss_name_t *	output_name
	)

gss_canonicalize_name takes a Internal Name (IN) and converts in into a mechanism specific Mechanism Name (MN).

The input name may multiple name, or generic name types.

If the input_name if of the GSS_C_NT_USER_NAME, and the Kerberos mechanism is specified, the resulting MN type is a GSS_KRB5_NT_PRINCIPAL_NAME.

For more information about internalVSmechname.

Parameters:

	minor_status	minor status code.
	input_name	name to covert, unchanged by gss_canonicalize_name().
	mech_type	the type to convert Name too.
	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 the error code.

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_import_name	(	OM_uint32 *	minor_status,
		const gss_buffer_t	input_name_buffer,
		const gss_OID	input_name_type,
		gss_name_t *	output_name
	)

Import a name internal or mechanism name

Type of name and their format:

GSS_C_NO_OID
GSS_C_NT_USER_NAME
GSS_C_NT_HOSTBASED_SERVICE
GSS_C_NT_EXPORT_NAME
GSS_C_NT_ANONYMOUS
GSS_KRB5_NT_PRINCIPAL_NAME

For more information about internalVSmechname.

Parameters:

	minor_status	minor status code
	input_name_buffer	import name buffer
	input_name_type	type of the import name buffer
	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 the error code.

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_init_sec_context	(	OM_uint32 *	minor_status,
		const gss_cred_id_t	initiator_cred_handle,
		gss_ctx_id_t *	context_handle,
		const gss_name_t	target_name,
		const gss_OID	input_mech_type,
		OM_uint32	req_flags,
		OM_uint32	time_req,
		const gss_channel_bindings_t	input_chan_bindings,
		const gss_buffer_t	input_token,
		gss_OID *	actual_mech_type,
		gss_buffer_t	output_token,
		OM_uint32 *	ret_flags,
		OM_uint32 *	time_rec
	)

As the initiator build a context with an acceptor.

Returns in the major

GSS_S_COMPLETE - if the context if build
GSS_S_CONTINUE_NEEDED - if the caller needs to continue another round of gss_i nit_sec_context
error code - any other error code

Parameters:

	minor_status	minor status code.
	initiator_cred_handle	the credential to use when building the context, if GSS_C_NO_CREDENTIAL is passed, the default credential for the mechanism will be used.
	context_handle	a pointer to a context handle, will be returned as long as there is not an error.
	target_name	the target name of acceptor, created using gss_import_name(). The name is can be of any name types the mechanism supports, check supported name types with gss_inquire_names_for_mech().
	input_mech_type	mechanism type to use, if GSS_C_NO_OID is used, Kerberos (GSS_KRB5_MECHANISM) will be tried. Other available mechanism are listed in the GSS-API mechanisms section.
	req_flags	flags using when building the context, see Context creation flags
	time_req	time requested this context should be valid in seconds, common used value is GSS_C_INDEFINITE
	input_chan_bindings	Channel bindings used, if not exepected otherwise, used GSS_C_NO_CHANNEL_BINDINGS
	input_token	input token sent from the acceptor, for the initial packet the buffer of { NULL, 0 } should be used.
	actual_mech_type	the actual mech used, MUST NOT be freed since it pointing to static memory.
	output_token	if there is an output token, regardless of complete, continue_needed, or error it should be sent to the acceptor
	ret_flags	return what flags was negotitated, caller should check if they are accetable. For example, if GSS_C_MUTUAL_FLAG was negotiated with the acceptor or not.
	time_rec	amount of time this context is valid for

Returns:: a gss_error code, see gss_display_status() about printing the error code.

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_inquire_attrs_for_mech	(	OM_uint32 *	minor_status,
		gss_const_OID	mech,
		gss_OID_set *	mech_attr,
		gss_OID_set *	known_mech_attrs
	)

List support attributes for a mech and/or all mechanisms.

Parameters:

	minor_status	minor status code
	mech	given together with mech_attr will return the list of attributes for mechanism, can optionally be GSS_C_NO_OID.
	mech_attr	see mech parameter, can optionally be NULL, release with gss_release_oid_set().
	known_mech_attrs	all attributes for mechanisms supported, release with gss_release_oid_set().

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_inquire_saslname_for_mech	(	OM_uint32 *	minor_status,
		const gss_OID	desired_mech,
		gss_buffer_t	sasl_mech_name,
		gss_buffer_t	mech_name,
		gss_buffer_t	mech_description
	)

Returns different protocol names and description of the mechanism.

Parameters:

	minor_status	minor status code
	desired_mech	mech list query
	sasl_mech_name	SASL GS2 protocol name
	mech_name	gssapi protocol name
	mech_description	description of gssapi mech

Returns:: returns GSS_S_COMPLETE or a error code.

GSSAPI_LIB_FUNCTION int GSSAPI_LIB_CALL gss_oid_equal	(	gss_const_OID	a,
		gss_const_OID	b
	)

Compare two GSS-API OIDs with each other.

GSS_C_NO_OID matches nothing, not even it-self.

Parameters:

	a	first oid to compare
	b	second oid to compare

Returns:: non-zero when both oid are the same OID, zero when they are not the same.

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_cred	(	OM_uint32 *	minor_status,
		gss_cred_id_t *	cred_handle
	)

Release a credentials

Its ok to release the GSS_C_NO_CREDENTIAL/NULL credential, it will return a GSS_S_COMPLETE error code. On return cred_handle is set ot GSS_C_NO_CREDENTIAL.

Example:

 gss_cred_id_t cred = GSS_C_NO_CREDENTIAL;
 major = gss_release_cred(&minor, &cred);

Parameters:

	minor_status	minor status return code, mech specific
	cred_handle	a pointer to the credential too release

Returns:: an gssapi error code

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_iov_buffer	(	OM_uint32 *	minor_status,
		gss_iov_buffer_desc *	iov,
		int	iov_count
	)

Free all buffer allocated by gss_wrap_iov() or gss_unwrap_iov() by looking at the GSS_IOV_BUFFER_FLAG_ALLOCATED flag.

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_release_name	(	OM_uint32 *	minor_status,
		gss_name_t *	input_name
	)

Free a name

import_name can point to NULL or be NULL, or a pointer to a gss_name_t structure. If it was a pointer to gss_name_t, the pointer will be set to NULL on success and failure.

Parameters:

	minor_status	minor status code
	input_name	name to free

Returns:: a gss_error code, see gss_display_status() about printing the error code.

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_unwrap_iov	(	OM_uint32 *	minor_status,
		gss_ctx_id_t	context_handle,
		int *	conf_state,
		gss_qop_t *	qop_state,
		gss_iov_buffer_desc *	iov,
		int	iov_count
	)

Decrypt or verifies the signature on the data.

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap	(	OM_uint32 *	minor_status,
		const gss_ctx_id_t	context_handle,
		int	conf_req_flag,
		gss_qop_t	qop_req,
		const gss_buffer_t	input_message_buffer,
		int *	conf_state,
		gss_buffer_t	output_message_buffer
	)

Wrap a message using either confidentiality (encryption + signature) or sealing (signature).

Parameters:

	minor_status	minor status code.
	context_handle	context handle.
	conf_req_flag	if non zero, confidentiality is requestd.
	qop_req	type of protection needed, in most cases it GSS_C_QOP_DEFAULT should be passed in.
	input_message_buffer	messages to wrap
	conf_state	returns non zero if confidentiality was honoured.
	output_message_buffer	the resulting buffer, release with gss_release_buffer().

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap_iov	(	OM_uint32 *	minor_status,
		gss_ctx_id_t	context_handle,
		int	conf_req_flag,
		gss_qop_t	qop_req,
		int *	conf_state,
		gss_iov_buffer_desc *	iov,
		int	iov_count
	)

Encrypts or sign the data.

This is a more complicated version of gss_wrap(), it allows the caller to use AEAD data (signed header/trailer) and allow greater controll over where the encrypted data is placed.

The maximum packet size is gss_context_stream_sizes.max_msg_size.

The caller needs provide the folloing buffers when using in conf_req_flag=1 mode:

HEADER (of size gss_context_stream_sizes.header) { DATA or SIGN_ONLY } (optional, zero or more) PADDING (of size gss_context_stream_sizes.blocksize, if zero padding is zero, can be omitted) TRAILER (of size gss_context_stream_sizes.trailer)

on DCE-RPC mode, the caller can skip PADDING and TRAILER if the DATA elements is padded to a block bountry and header is of at least size gss_context_stream_sizes.header + gss_context_stream_sizes.trailer.

HEADER, PADDING, TRAILER will be shrunken to the size required to transmit any of them too large.

To generate gss_wrap() compatible packets, use: HEADER | DATA | PADDING | TRAILER

When used in conf_req_flag=0,

HEADER (of size gss_context_stream_sizes.header) { DATA or SIGN_ONLY } (optional, zero or more) PADDING (of size gss_context_stream_sizes.blocksize, if zero padding is zero, can be omitted) TRAILER (of size gss_context_stream_sizes.trailer)

The input sizes of HEADER, PADDING and TRAILER can be fetched using gss_wrap_iov_length() or gss_context_query_attributes().

GSSAPI_LIB_FUNCTION OM_uint32 GSSAPI_LIB_CALL gss_wrap_iov_length	(	OM_uint32 *	minor_status,
		gss_ctx_id_t	context_handle,
		int	conf_req_flag,
		gss_qop_t	qop_req,
		int *	conf_state,
		gss_iov_buffer_desc *	iov,
		int	iov_count
	)

Update the length fields in iov buffer for the types:

GSS_IOV_BUFFER_TYPE_HEADER
GSS_IOV_BUFFER_TYPE_PADDING
GSS_IOV_BUFFER_TYPE_TRAILER

Consider using gss_context_query_attributes() to fetch the data instead.

Variable Documentation

gss_OID_desc GSSAPI_LIB_FUNCTION __gss_c_attr_stream_sizes_oid_desc

Initial value:

    {10, rk_UNCONST("\x2a\x86\x48\x86\xf7\x12\x01\x02\x01\x03")}

Query the context for parameters.

SSPI equivalent if this function is QueryContextAttributes.

GSS_C_ATTR_STREAM_SIZES data is a gss_context_stream_sizes.

Generated on Wed Jan 11 14:07:44 2012 for HeimdalGSS-APIlibrary by

1.5.6