NAME

gss_init_sec_context — Establishes a security context between the context initiator and a context acceptor

Synopsis

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_typeSpecifies the security mechanism.  To use DCE security, specify either of the following:

   •GSS_C_OID_DCE_KRBV5_DES

   •GSS_C_NULL_OID

To use Kerberos, specify GSS_C_OID_KRBV5_DES. 

req_flagsSpecifies 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

TRUECredentials were delegated to the context acceptor. 

FALSENo credentials were delegated. 

GSS_C_MUTUAL_FLAG

TRUEThe context acceptor has been asked to authenticate itself. 

FALSEThe context initiator has not been asked to authenticates itself. 

GSS_C_REPLAY_FLAG

TRUEReplayed signed or sealed messages will be detected. 

FALSEReplayed messages will not be detected. 

GSS_C_SEQUENCE_FLAG

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

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

time_reqSpecifies 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:

   •GSS_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_flagsReturns 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

TRUECredentials were delegated to the context acceptor. 

FALSENo credentials were delegated. 

GSS_C_MUTUAL_FLAG

TRUEThe context acceptor has been asked to authenticate itself. 

FALSEThe context acceptor has not been asked to authenticate itself. 

GSS_C_REPLAY_FLAG

TRUEReplayed signed or sealed messages will be detected. 

FALSEReplayed messages will not be detected. 

GSS_C_SEQUENCE_FLAG

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

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

GSS_C_CONF_FLAG

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

FALSENo 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

TRUEIntegrity service can be invoked by calling either the gss_sign() or gss_seal() routine. 

FALSEIntegrity service for individual messages is unavailable. 

time_recReturns 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).