 |
Index for
Section 3 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
gss_accept_sec_context(3)
NAME
gss_accept_sec_context - Establish a remotely-initiated security context.
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
minor_status
Kerberos 5 error code.
context_handle
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().
acceptor_cred_handle
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.
input_token_buffer
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.
input_chan_bindings
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.
src_name
Authenticated internal form name of security context initiator.
After use, the application should deallocate this name by passing
it to gss_release_name().
mech_type
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.
output_token
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().
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 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.
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 initiating
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 initiating
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 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.
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.
delegated_cred_handle
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 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.
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 authentication
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_context(3),
gss_release_buffer(3), gss_release_cred(3), gss_release_name(3),
gss_wrap(3)
|
Index for
Section 3 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|