gss_init_sec_context(3)gss_init_sec_context(3)NAMEgss_init_sec_context - Initiate a security context between an applica‐
tion and its peer.
SYNOPSIS
#include <gssapi/gssapi.h>
OM_uint32 gss_init_sec_context(
OM_uint32 * minor_status,
const gss_cred_id_t initiator_cred_handle,
gss_ctx_id_t * context_handle,
const gss_name_t target_name,
const gss_OID mech_type,
OM_uint32 req_flags,
OM_uint32 time_req,
const gss_channel_bindings_t input_chan_bindings,
const gss_buffer_t input_token,
gss_OID * actual_mech_type,
gss_buffer_t output_token,
OM_uint32 * ret_flags,
OM_uint32 time_rec );
PARAMETERS
Kerberos 5 error code. Credentials for the initiating application.
Specify GSS_C_NO_CREDENTIAL to use default credentials. If default cre‐
dentials cannot be obtained, GSS_S_NO_CRED is returned.
If credentials for the initiating application are not provided
and default credentials cannot be obtained from a credentials
cache, this function attempts to use the login name of the user.
gss_acquire_cred() contains more information. Security context
to be initiated. Specify GSS_C_NO_CONTEXT for first call and use
the value returned by the first call in continuation calls.
Resources associated with this context must be released by the
application after use with a call to gss_delete_sec_context().
Name of peer application accepting the security context. This
name is an internal form name. The application must obtain the
internal form name beforehand using a call such as
gss_import_name(). Object identifier (OID) of the desired secu‐
rity mechanism. Specify GSS_C_NO_OID to obtain the Kerberos 5
default. Flags requesting that specific service options be sup‐
ported by the security context. Symbolic names are provided for
each flag. The symbolic names need to be bitwise ORed together
to form the bit mask input value.
The flags are: CSF_GSS_C_DES_FLAG
True -- Request DES encryption.
False -- Do not request DES encryption. CSF_GSS_C_DES3_FLAG
True -- Request DES3 encryption.
False -- Do not request DES3 encryption.
Note
DES3 and DES encryption are mutually exclusive and unique to the
HP implementation of the GSS-API. GSS_C_ANON_FLAG
Since the HP Application Security SDK does not support anonymous
authentication, this bit is ignored. GSS_C_DELEG_FLAG
True -- Delegate credentials to the accepting application.
Set this flag as true to allow the application to forward tick‐
ets. The user must also have a forwardable TGT.
False -- Do not delegate credentials. GSS_C_MUTUAL_FLAG
True -- Request that the accepting application authenticate
itself.
False -- Request one way authentication only. GSS_C_REPLAY_FLAG
True -- Enable replay detection for protected messages.
False -- Do not attempt to detect replayed messages.
Replay detection contains more information about the replay
cache. GSS_C_SEQUENCE_FLAG
True -- Enable detection of out-of-sequence protected messages.
False -- Do not attempt to detect out-of-sequence messages
Desired number of seconds for which the security context should
remain valid. Since the HP implementation of the GSS-API does
not support security context expiration, this parameter is
ignored. Application-specified bindings that allow the applica‐
tion to securely bind channel identification information to the
security context. Specify GSS_C_NO_CHANNEL_BINDINGS if channel
bindings are not used. Token received from the accepting appli‐
cation. Specify GSS_C_NO_BUFFER, or a pointer to a buffer con‐
taining the value GSS_C_EMPTY_BUFFER, on the initial call. If
multiple invocations of this function are used to establish a
context, the token will be different each time. Security mecha‐
nism used that, in the HP implementation of GSS-API, is Kerberos
5. Specify NULL if this information is not required.
The storage associated with this OID set should be freed by the
application after use with a call to gss_release_oid_set().
Token to be sent to the accepting application. If a token is
created, it must be sent to the accepting application even if a
return code indicates an error. The only exception is when the
length field of the returned token buffer is zero, in which
case, the token does not need to be sent to the accepting appli‐
cation.
The application must free storage associated with this buffer
after use with a call to gss_release_buffer(). Flags indicating
the service options supported by the security context. If this
information is not needed, specify NULL.
Symbolic names are provided for each flag. (See Context Flag
Constants for the definitions.) The symbolic names need to be
bitwise ANDed with the value of the ret_flags parameter to test
whether a given option is supported by the context. Unused bits
are set to zero.
Note
To check whether the requested encryption is being used (DES3 or
DES), call csf_gss_get_context_options().
The flags are: GSS_C_ANON_FLAG -- Since the HP Application Secu‐
rity SDK does not support anonymous authentication, this value
is always set to false. GSS_C_CONF_FLAG
True -- Confidentiality service may be invoked by calling the
gss_wrap() function.
False -- No confidentiality service via gss_wrap() is available.
The gss_wrap() function provides message encapsulation, data
origin authentication, and integrity services only.
GSS_C_DELEG_FLAG
True -- Credentials were delegated to the accepting application.
False -- No credentials were delegated. GSS_C_INTEG_FLAG
True -- Integrity service may be invoked by calling either
gss_get_mic() or gss_wrap().
False -- Per-message integrity service is unavailable.
GSS_C_MUTUAL_FLAG
True -- The remote peer that, in this case, is the accepting
application, requested mutual authentication.
False -- The remote peer did not request mutual authentication.
GSS_C_PROT_READY_FLAG -- The value of this bit indicates the
actual state at the time gss_accept_sec_context() returns,
whether or not the context is fully established.
True -- Protection services (as specified by the states of
GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available for use.
False -- Protection services (as specified by the states of
GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are available only if the
security context is established. GSS_C_REPLAY_FLAG
True -- Replay of protected messages will be detected.
False -- Replay of messages will not be detected.
GSS_C_SEQUENCE_FLAG
True -- Out-of-sequence protected messages will be detected.
False -- Out-of-sequence messages will not be detected.
GSS_C_TRANS_FLAG -- The value of this bit indicates the actual
state at the time gss_accept_sec_context() returns, whether or
not the context is fully established.
True -- The resulting security context may be transferred to
other processes via a call to gss_export_sec_context().
False -- The security context is not transferable. Number of
seconds for which the security context remains valid. Since the
HP implementation of the GSS-API does not support security con‐
text expiration, the value GSS_C_INDEFINITE is always returned.
Specify NULL if this information is not required.
DESCRIPTION
The gss_init_sec_context() function initiates the establishment of a
security context between an application and its peer. A security con‐
text must be established prior to exchanging secured messages.
The initiating application may require multiple invocations of this
function to establish a security context between it and the accepting
application: If the gss_init_sec_context() function returns a non-zero
length token when it is called, the token must be transferred to the
accepting application even if an error is indicated. When the accept‐
ing application receives the token, it calls gss_accept_sec_context()
and passes the token to it. If the function returns a status flag of
GSS_S_CONTINUE_NEEDED, a non-zero length output token is also returned.
The token must be returned to the initiating application even if an
error is indicated. If the function returns a major status containing
GSS_C_COMPLETE, the security context is fully established. When the
initiating application receives the token, it calls gss_init_sec_con‐
text() again, passing the token to it. If gss_init_sec_context()
returns a major status containing GSS_C_CONTINUE_NEEDED, the cycle
repeats. If gss_init_sec_context() returns a major status containing
GSS_C_COMPLETE, the security context is fully established.
When multiple iterations are needed to establish the security
context, parameter values from the current call should be used
on subsequent calls. The only exception is the input_token_buf‐
fer parameter whose value changes each time.
If the initial call of gss_init_sec_context() fails, a context
is not created and the value of the context_handle parameter is
set to GSS_C_NO_CONTEXT to indicate this.
Note
Because of the way sequence numbers are incremented in security
contexts, each initiating application needs a unique security
context with an accepting application. A single security context
must not be used with multiple initiating and accepting applica‐
tions.
Credential delegation (specified with GSS_C_DELEG_FLAG parame‐
ter) should be used judiciously, and only when necessary. When
credentials are delegated, the initial credential (the ticket-
granting ticket, or TGT) from the initiator of the security con‐
text is forwarded to the acceptor. This results in an extra
ticket in the acceptor's credentials cache that occupies addi‐
tional storage. Therefore, HP recommends, for both security and
resource reasons, using credential delegation only when neces‐
sary. Credentials delegation requires that one of the following
conditions be true: The target_name input parameter to
gss_init_sec_context() must be of type GSS_KRB5_NT_HOST‐
BASED_SERVICE_NAME. Channel bindings must be provided to
gss_init_sec_context() and gss_accept_sec_context() using
address type GSS_C_AF_INET.
Before calling this function, the application must obtain the internal
form name of the accepting application using a call such as
gss_import_name().
When the initiating application is finished using the context, it must
release the resources associated with context_handle with a call to
gss_delete_sec_context(). Storage associated with the following parame‐
ters must also be freed when the data is no longer needed: src_name
with a call to gss_release_name() after the context is fully estab‐
lished. output_token with a call to gss_release_buffer() after each
invocation of gss_init_sec_context(). delegated_cred_handle with a
call to gss_release_cred() after the context is fully established.
RETURN VALUES
GSS_S_BAD_BINDINGS xx04xxxx
GSS_S_BAD_MECH xx01xxxx
GSS_S_BAD_NAME xx02xxxx
GSS_S_BAD_NAMETYPE xx03xxxx
GSS_S_CALL_BAD_STRUCTURE 03xxxxxx
GSS_S_CALL_INACCESSIBLE_READ 01xxxxxx
GSS_S_CALL_INACCESSIBLE_WRITE 02xxxxxx
GSS_S_COMPLETE 00000000
GSS_S_CONTINUE_NEEDED xxxx0001
GSS_S_CREDENTIALS_EXPIRED xx0Bxxxx
GSS_S_DEFECTIVE_CREDENTIAL xx0Axxxx
GSS_S_DEFECTIVE_TOKEN xx09xxxx
GSS_S_DUPLICATE_TOKEN xxxx0002
GSS_S_FAILURE xx0Dxxxx
GSS_S_NO_CONTEXT xx08xxxx
GSS_S_NO_CRED xx07xxxx
GSS_S_OLD_TOKEN xxxx0004
GSS_S_UNSEQ_TOKEN xxxx0008
PORTABILITY CONSIDERATIONS
Portable applications should be constructed to use the token length to
determine whether a token needs to be sent. Tokens of zero length do
not need to be sent.
Return status should be used to determine whether waiting for a reply
is necessary. Thus, an initiating application should always invoke
gss_init_sec_context() within a loop.
Since the HP implementation of DES3 is an extension of the GSS-API, it
will not interoperate with other GSS-API vendors offering DES3.
Application Security SDK does not support anonymous authentication or
context expiration.
SEE ALSO
Functions: csf_gss_get_context_options(3), gss_accept_sec_context(3),
gss_acquire_cred(3), gss_delete_sec_context(3), gss_export_sec_con‐
text(3), gss_get_mic(3), gss_import_name(3), gss_import_sec_context(3),
gss_inquire_context(3), gss_release_buffer(3), gss_release_oid_set(3),
gss_wrap(3)gss_init_sec_context(3)