gss_accept_sec_context(3)gss_accept_sec_context(3)NAMEgss_accept_sec_context - Establish a remotely-initiated security con‐
text.
SYNOPSIS
#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 );
PARAMETERS
Kerberos 5 error code. Security context being established. A context
is successively built up using multiple iterations of this call. Con‐
text values are updated with each iteration. The partially built con‐
text 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 creden‐
tials. 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 con‐
text initiator.
After use, the application should deallocate this name by pass‐
ing 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_COM‐
PLETE.
The OID returned via this parameter is a pointer to static stor‐
age 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 ini‐
tiating 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 call‐
ing 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 ser‐
vice 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 applica‐
tion, 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_COM‐
PLETE 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 con‐
text 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.
DESCRIPTION
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 ini‐
tiating application receives the token, it calls gss_init_sec_con‐
text(), 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_CON‐
TINUE_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 con‐
texts, 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 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_accept_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_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_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 authentica‐
tion or context expiration.
SEE ALSO
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_con‐
text(3), gss_release_buffer(3), gss_release_cred(3),
gss_release_name(3), gss_wrap(3)gss_accept_sec_context(3)