|
|
gss_accept_sec_context(3)
Contents
|
gss_accept_sec_context - Establish a remotely-initiated
security context.
#include <gssapi/gssapi.h>
OM_uint32 gss_accept_sec_context(
OM_uint32 * minor_status,
gss_ctx_id_t * context_handle,
const gss_cred_id_t acceptor_cred_handle,
const gss_buffer_t input_token_buffer,
const gss_channel_bindings_t input_chan_bindings,
gss_name_t * src_name,
gss_OID * mech_type,
gss_buffer_t output_token,
OM_uint32 * ret_flags,
OM_uint32 * time_rec,
gss_cred_id_t * delegated_cred_handle );
Kerberos 5 error code. Security context being established.
A context is successively built up using multiple
iterations of this call. Context values are updated with
each iteration. The partially built context returned from
a previous invocation of the call must be input to the
next invocation. The context_handle parameter is actually
a pointer to the context and must be initialized to
GSS_C_NO_CONTEXT before the first call. Then pass the same
pointer on each subsequent iteration of the call.
Resources associated with this context must be
released by the application after use with a call
to gss_delete_sec_context(). Credentials for the
application accepting the context. Specify
GSS_C_NO_CREDENTIAL to obtain the context using
default credentials. If no default credentials are
available, GSS_S_NO_CRED is returned. Token
obtained from the initiating application. If multiple
invocations of this function are used to establish
a context, the token will be different each
time. Application-specified channel 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. Authenticated internal form
name of security context initiator.
After use, the application should deallocate this
name by passing it to gss_release_name(). Security
mechanism used that, in the HP implementation of
the GSS-API, is Kerberos 5. Specify NULL if this
information is not required.
Unless the ret_flags parameter contains the bit
GSS_C_PROT_READY_FLAG, indicating that per-message
services may be applied in advance of a successful
context completion, the value returned via the
mech_type parameter may be undefined until the
function returns a major status value of GSS_S_COMPLETE.
The OID returned via this parameter is a pointer to
static storage that should be treated as read-only.
The application should not attempt to free it.
Token to be returned to the initiating application.
If a token is created, it must be sent to the initiating
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 initiating 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 Flags 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. Since the HP Application
Security SDK does not support anonymous authentication,
this value is always set to false. 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. True -- Credentials were
delegated to the initiating application.
False -- No credentials were delegated. True --
Integrity service may be invoked by calling either
gss_get_mic() or gss_wrap().
False -- Per-message integrity service is unavailable.
True -- The remote peer that, in this case,
is the initiating application, requested mutual
authentication.
False -- The remote peer did not request mutual
authentication. 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 if the accompanying major status
return value is either GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED.
False -- Protection services (as specified by the
states of GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG) are
available only if the accompanying major status
return value is GSS_S_COMPLETE. True -- Replay of
protected messages will be detected.
False -- Replay of messages will not be detected.
True -- Out-of-sequence protected messages will be
detected.
False -- Out-of-sequence messages will not be
detected. 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. Credentials received from the context
initiator. This parameter is only valid if
GSS_C_DELEG_FLAG in ret_flags is true, in which
case, explicit credentials are returned. If
GSS_C_DELEG_FLAG is false, this parameter is set to
GSS_C_NO_CREDENTIAL.
If credentials are returned, the associated
resources must be released by the application after
use with a call to gss_release_cred().
In the HP implementation of the GSS-API, delegated
credentials are used for ticket forwarding. Credentials
delegation requires that channel bindings are
provided with the address type GSS_C_AF_INET.
The gss_accept_sec_context() function allows establishment
of a remotely-initiated security context between an application
and its peer. A security context must be established
prior to exchanging secured messages.
The accepting application may require multiple invocations
of this function to establish a security context between
it and the initiating application: If gss_accept_sec_context()
returns a status flag of GSS_S_CONTINUE_NEEDED, an
output token is also returned. If a token is created, it
must be sent to the initiating application even if the
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 initiating
application. When the initiating application
receives the token, it calls gss_init_sec_context(), passing
the token to it. If the function generates a reply
token, it must be sent back to the accepting application.
When the accepting application receives the reply token,
it must call gss_accept_sec_context() again, passing the
reply token to it. If gss_accept_sec_context() returns a
major status containing GSS_C_CONTINUE_NEEDED, the cycle
repeats. If gss_accept_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_accept_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.
When the accepting 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_accept_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_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_accept_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.
The HP Application Security SDK does not support anonymous
authentication or context expiration.
Functions: csf_gss_get_context_options(3), gss_context_time(3), gss_delete_sec_context(3),
gss_export_sec_context(3), gss_get_mic(3),
gss_import_sec_context(3), gss_init_sec_context(3),
gss_inquire_context(3), gss_release_buffer(3),
gss_release_cred(3), gss_release_name(3), gss_wrap(3)
gss_accept_sec_context(3)
[ Back ] |
