| ## gss_init_sec_context(3sec) Establishes a security context between the context initiator and a context acceptor 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) ##