gss_init_sec_context(3) gss_init_sec_context(3)
NAME [Toc] [Back]
gss_init_sec_context() - establish a security context between the
context initiator and a context acceptor
SYNOPSIS [Toc] [Back]
#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 [Toc] [Back]
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.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
gss_init_sec_context(3) gss_init_sec_context(3)
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 [Toc] [Back]
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:
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
gss_init_sec_context(3) gss_init_sec_context(3)
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.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
gss_init_sec_context(3) gss_init_sec_context(3)
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 [Toc] [Back]
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.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
gss_init_sec_context(3) gss_init_sec_context(3)
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
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
gss_init_sec_context(3) gss_init_sec_context(3)
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 [Toc] [Back]
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 [Toc] [Back]
The referenced credentials have expired.
GSS_S_DEFECTIVE_CREDENTIAL [Toc] [Back]
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.
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
gss_init_sec_context(3) gss_init_sec_context(3)
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 [Toc] [Back]
gss_init_sec_context() was developed by Sun Microsystems, Inc.
SEE ALSO [Toc] [Back]
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.
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003 [ Back ] |
