|
|
gss_init_sec_context(3)
Contents
|
gss_init_sec_context - Initiate a security context between
an application and its peer.
#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 );
Kerberos 5 error code. Credentials for the initiating
application. Specify GSS_C_NO_CREDENTIAL to use default
credentials. If default credentials 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 security mechanism. Specify
GSS_C_NO_OID to obtain the Kerberos 5 default.
Flags requesting that specific service options be
supported 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 tickets. 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 application 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 application.
Specify GSS_C_NO_BUFFER, or a pointer to a
buffer containing 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 mechanism
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 application.
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 Security 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 context expiration,
the value GSS_C_INDEFINITE is always
returned. Specify NULL if this information is not
required.
The gss_init_sec_context() function initiates the establishment
of a security context between an application and
its peer. A security context 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 accepting 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_context() 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_buffer 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 applications.
Credential delegation (specified with
GSS_C_DELEG_FLAG parameter) should be used judiciously,
and only when necessary. When credentials
are delegated, the initial credential (the ticketgranting
ticket, or TGT) from the initiator of the
security context is forwarded to the acceptor. This
results in an extra ticket in the acceptor's credentials
cache that occupies additional storage.
Therefore, HP recommends, for both security and
resource reasons, using credential delegation only
when necessary. 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_HOSTBASED_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 parameters 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
established. 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.
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 [Toc] [Back] 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.
Functions: csf_gss_get_context_options(3),
gss_accept_sec_context(3), gss_acquire_cred(3),
gss_delete_sec_context(3), gss_export_sec_context(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)
[ Back ] |
