Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > G

gss_init_sec_context(3)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

gss_init_sec_context() — establish a security context between the context initiator and a context acceptor

SYNOPSIS

#include <gssapi.h>

OM_uint32 gss_init_sec_context (

OM_uint32 *minor_status, const gss_cred_id_t claimant_cred_handle, gss_ctx_id_t *context_handle, gss_name_t target_name, const gss_OID mech_type, int req_flags, int time_req, const gss_channel_bindings_t input_channel_bindings, const gss_buffer_t input_token, gss_OID *actual_mech_types, gss_buffer_t output_token, int *ret_flags, OM_int32 *time_rec)

DESCRIPTION

The gss_init_sec_context() routine is the first step in the establishment of a security context between the context initiator and the context acceptor. To ensure the portability of the application, use its default credential by supplying GSS_C_NO_CREDENTIAL to the claimant_cred_handle parameter. Specify an explicit credential when the application needs an additional credential; for example, to use delegation.

The first time the application calls the gss_init_sec_context() routine, specify the input_token parameter as GSS_NO_BUFFER. Calls to the routine can return an output_token for transfer to the context acceptor. The context acceptor presents the token to the gss_accept_sec_context() routine.

If the context initiator does not require a token, gss_init_sec_context() sets the length field of the output_token argument to 0 (zero).

To complete establishing the context, the calling application can require one or more reply tokens from the context acceptor. If the application requires reply tokens, the gss_init_sec_context() routine returns a status value of GSS_S_CONTINUE_NEEDED. The application calls the routine again when the reply token is received from the context acceptor and passes the token to the gss_init_sec_context() routine via the input_token parameter.

The values returned by the ret_flags and time_rec parameters are not defined unless the routine returns the status GSS_S_COMPLETE.

If the initial call of gss_init_sec_context() fails, the call should not create a context object, and should leave the value of the context_handle parameter set to GSS_C_NO_CONTEXT to indicate this.

Input Parameters

claimant_cred_handle

Specifies an optional handle for the credential. To use the default credential, supply GSS_C_NO_CREDENTIAL. The credential handle created refers to the DCE default login context. If no default initiator is defined, the function will return GSS_S_NO_CRED.

target_name

Specifies the name of the context acceptor.

mech_type

Specifies the security mechanism. Supply GSS_C_NO_OID to obtain an implementation specific default.

req_flags

Specifies independent flags, each of which requests that the context support a service option. The following symbolic names are provided to correspond to each flag. The symbolic names should be logically ORed to form a bit-mask value.

GSS_C_DELEG_FLAG. The True/False values are:

True

Credentials were delegated to the context acceptor.

False

No credentials were delegated.

GSS_C_MUTUAL_FLAG. The True/False values are:

True

The context acceptor has been asked to authenticate itself.

False

The context initiator has not been asked to authenticates itself.

GSS_C_REPLAY_FLAG. The True/False values are:

True

Replayed signed or sealed messages will be detected.

False

Replayed messages will not be detected.

GSS_C_SEQUENCE_FLAG. The True/False values are:

True

Out-of-sequence signed or sealed messages will be detected.

False

Out-of-sequence signed or sealed messages will not be detected.

GSS_C_CONF_FLAG. The True/False values are:

True

Request that confidentiality service be made available

False

No per-message confidentiality service is required.

GSS_C_INTEG_FLAG. The True/False values are:

True

Request that integrity service be be made available

False

No per-message integrity service is required.

GSS_C_ANON_FLAG. The True/False values are:

True

Do not reveal the initiator's identity to the acceptor.

False

Authenticate normally.

time_req

Specifies the desired number of seconds for which the context should remain valid. To specify the default validity period, use 0 (zero).

input_chan_bindings

Specifies the bindings set by the context initiator. Allows the context initiator to bind the channel identification information securely to the security context. If channel bindings are not used specify GSS_C_NO_CHANNEL_BINDINGS.

input_token

Specifies the token received from the context acceptor.

The first time the application calls the routine, you specify GSS_NO_BUFFER. Subsequent calls require a token from the context acceptor.

Input/Output Parameters

context_handle

Specifies the context handle for the new context.

The first time the application calls the routine, you specify GSS_C_NO_CONTEXT. Subsequent calls use the value returned by the first call.

Output Parameters

actual_mech_type

Returns the OID of the actual mechanism used. Specify NULL if not required.

output_token

Returns the token to send to the context acceptor. If the length field of the returned buffer is 0 (zero), no token is sent.

ret_flags

Returns six independent flags, each of which indicates that the context supports a service option. Specify NULL if not required. The following symbolic names are provided to correspond to each flag:

GSS_C_DELEG_FLAG. The True/False values are:

True

Credentials were delegated to the context acceptor.

False

No credentials were delegated.

GSS_C_MUTUAL_FLAG. The True/False values are:

True

The context acceptor has been asked to authenticate itself.

False

The context acceptor has not been asked to authenticate itself.

GSS_C_REPLAY_FLAG. The True/False values are:

True

Replayed signed or sealed messages will be detected.

False

Replayed messages will not be detected.

GSS_C_SEQUENCE_FLAG. The True/False values are:

True

Out-of-sequence signed or sealed messages will be detected.

False

Out-of-sequence signed or sealed messages will not be detected.

GSS_C_CONF_FLAG. The True/False values are:

True

Confidentiality service can be invoked by calling the gss_seal() routine.

False

No confidentiality service is available. (Confidentiality can be provided using the gss_seal() routine, which provides only message encapsulation, data-origin authentication, and integrity services.)

GSS_C_INTEG_FLAG. The True/False values are:

True

Integrity service can be invoked by calling either the gss_get_mic() or gss_wrap() routine.

False

Integrity service for individual messages is unavailable.

GSS_C_ANON_FLAG. The True/False values are:

True

Do not reveal the initiator's identity to the acceptor.

False

Authenticate normally.

GSS_C_PROT_READY_FLAG. The True/False values are:

True

Protection services (as specified by the states of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available for use if the accompanying major status is either GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED.

False

Protection services(as specified by the states of the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available for use if the accompanying major status is either GSS_S_COMPLETE.

GSS_C_TRANS_FLAG. The True/False values are:

True

The resultant security context may be transferred to other processes

False

The security context is not is not transferable

time_rec

Returns the number of seconds for which the context will be valid. If the mechanism does not support credential expiration, the routine returns the value GSS_C_INDEFINITE. If the credential expiration time is not required, specify NULL.

minor_status

Returns a status code from the security mechanism.

STATUS CODES

The following status codes can be returned:

GSS_S_COMPLETE

The routine was completed successfully.

GSS_S_BAD_BINDINGS

The input_token parameter contains different channel bindings from those specified with the input_chan_bindings parameter.

GSS_S_BAD_NAMETYPE

The target_name parameter contains an invalid or unsupported name type.

GSS_S_BAD_NAME

The target_name parameter was incorrectly formed.

GSS_S_BAD_SIG

Indicates either that the input_token parameter contains an invalid signature or that the input_token parameter contains a signature that could not be verified.

GSS_S_CONTINUE_NEEDED

To complete the context, the gss_init_sec_context() routine must be called again with a token required from the context acceptor.

GSS_S_CREDENTIALS_EXPIRED

The referenced credentials have expired.

GSS_S_DEFECTIVE_CREDENTIAL

Consistency checks performed on the credential failed.

GSS_S_DEFECTIVE_TOKEN

Consistency checks performed on the input_token parameter failed.

GSS_S_DUPLICATE_TOKEN

The input_token parameter was already processed. This is a fatal error that occurs during context establishment.

GSS_S_FAILURE

The routine failed. See the minor_status parameter return value for more information.

GSS_S_NO_CONTEXT

The supplied context handle did not refer to a valid context.

GSS_S_OLD_TOKEN

The input_token parameter was too old. This is a fatal error that occurs during context establishment.

GSS_S_NO_CRED

The supplied credentials were not valid for context initiation, or the credential handle did not reference any credentials.

GSS_S_BAD_MECH

The specified mechanism is not supported by the provided credential

AUTHOR

gss_init_sec_context() was developed by Sun Microsystems, Inc.

SEE ALSO

gss_accept_sec_context(3), gss_delete_sec_context(3).

The manpages for DCE-GSSAPI are included with the DCE-CoreTools product. To see those manpages add /opt/dce/share/man to MANPATH.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.