gss_init_sec_context(3sec)

Synopsis

#include <dce/gssapi.h>

OM_uint32 gss_init_sec_context (
OM_uint32 *minor_status,
gss_cred_id_t claimant_cred_handle,
gss_ctx_id_t *context_handle
gss_name_t target_name,
gss_OID mech_type,
int req_flags,
int time_req,
gss_channel_bindings_t input_channel_bindings,

gss_buffeR_t input_token,
gss_OID *actual_mech_types,
gss_buffer_t output_token,
int *ret_flags,
OM_int32 *time_rec)

Parameters

Input

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. The credential must be either an INITIATE or BOTH type credential.

target_name
Specifies the name of the context acceptor.

mech_type
Specifies the security mechanism. To use DCE Security, specify either of the following:

· GSSDCE_C_OID_DCE_KRBV5_DES

· GSS_C_NULL_OID

To use Kerberos, specify GSS_C_OID_KRBV5_DES.

req_flags
Specifies four 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 for GSS_C_DELEG_FLAG are:

TRUE	Credentials were delegated to the context acceptor.
FALSE	No credentials were delegated.

GSS_C_MUTUAL_FLAG
The TRUE/FALSE values for GSS_C_MUTUAL_FLAG 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 for GSS_C_REPLAY_FLAG 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 for GSS_C_SEQUENCE_FLAG are:

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

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.

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

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

actual_mech_type
Returns one of the following values indicating the security mechanism:

· GSSDCE_C_OID_DCE_KRBV5_DES for DCE Security

· GSS_C_OID_KRBV5_DES for Kerberos

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. The following symbolic names are provided to correspond to each flag:

GSS_C_DELEG_FLAG
The TRUE/FALSE values for GSS_C_DELEG_FLAG are:

TRUE	Credentials were delegated to the context acceptor.
FALSE	No credentials were delegated.

GSS_C_MUTUAL_FLAG
The TRUE/FALSE values for GSS_C_MUTUAL_FLAG 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 for GSS_C_REPLAY_FLAG 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 for GSS_C_SEQUENCE_FLAG 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 for GSS_C_CONF_FLAG 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 for GSS_C_INTEG_FLAG are:

TRUE	Integrity service can be invoked by calling either the gss_sign( ) or gss_seal( ) routine.
FALSE	Integrity service for individual messages is unavailable.

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.

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.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

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.

Related Information
Functions:

gss_accept_sec_context(3sec)

gss_delete_sec_context(3sec)