 |
Index for
Section 3 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
gss_init_sec_context(3)
NAME
gss_init_sec_context - Initiate a security context between an application
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
minor_status
Kerberos 5 error code.
initiator_cred_handle
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.
context_handle
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().
target_name
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().
mech_type
Object identifier (OID) of the desired security mechanism. Specify
GSS_C_NO_OID to obtain the Kerberos 5 default.
req_flags
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
time_req
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.
input_chan_bindings
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.
input_token
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.
actual_mech_type
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().
output_token
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().
ret_flags
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.
time_rec
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.
DESCRIPTION
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 ticket-granting 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.
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_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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|