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.
Printable version
