gss_accept_sec_context(3)

NAME

gss_accept_sec_context() — establish a security context between the application and a context acceptor

SYNOPSIS

#include <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,
const gss_name_t *src_name,
gss_OID *actual_mech_type,
gss_buffer_t output_token,
int *ret_flags,
OM_uint32 *time_rec
gss_cred_id_t *delegated_cred_handle)

DESCRIPTION

The gss_accept_sec_context() routine is the second step in establishing a security context between the context initiator and a context acceptor. In the first step, the context initiator calls the gss_init_sec_context() routine. The gss_init_sec_context() routine generates a token for the security context and passes it to the context initiator. The context initiator sends the token to the context acceptor.

In the second step, the context acceptor accepts the call from the context initiator and calls the gss_accept_sec_context() routine. The gss_accept_sec_context() routine expects a value for the input_token parameter. The value for the input_token parameter is generated by the gss_init_sec_context() routine and passed by the initiator to the acceptor.

The gss_accept_sec_context() routine can also return a value for the output_token parameter. The context acceptor presents the token to the gss_init_sec_context() routine. If the acceptor does not need to send a token to the initiator, gss_accept_sec_context() sets the length field of the output_token parameter to 0 (zero).

To complete establishing the context, the context initiator can require one or more reply tokens from the context acceptor. If the application requires reply tokens, the gss_accept_sec_context() routine returns a status value containing GSS_S_CONTINUE_NEEDED. The application calls the routine again when the reply token is received from the context acceptor. The application passes the token to the gss_accept_sec_context() routine via the output_token parameters.

The values returned using the src_name, ret_flags, time_rec, and delegated_cred_handle parameters are not defined unless the routine returns the status, GSS_S_COMPLETE.

Input Parameters

acceptor_cred_handle: Specifies the credential handle (the identity) claimed by the context acceptor. This is optional information. The credential must be either an ACCEPT type credential or a BOTH type credential. Specify GSS_C_NO_CREDENTIAL, to accept the context as default principal
input_token_buffer: Specifies the token received from the context acceptor.
input_chan_bindings: Specifies bindings supplied by the context initiator. Allows the context initiator to bind the channel identification information securely to the security context. If no channel bindings are used, specify GSS_C_NO_CHANNEL_BINDINGS.

Input/Output Parameters

context_handle: Specifies a context handle for a new context. The first time the context initiator uses the routine, specify GSS_C_NO_CONTEXT to set up a specific context. In subsequent calls, use the value returned by this parameter.

Output Parameters

src_name

Returns the authenticated name of the context initiator. This information is optional. If the authenticated name is not required, specify NULL. To deallocate the authenticated name, pass it to the gss_release_name() routine.

actual_mech_type

Actual mechanism used. Specify NULL if not required.

output_token

Returns a token to pass to the context acceptor. If no token is to be passed to the context acceptor, the routine sets the length field of the returned token buffer to 0 (zero).

ret_flags

Returns a bitmask containing six independent flags, each of which requests that the context support a service option. The following symbolic names are provided to correspond to each flag. The symbolic names should be logically ANDed with the value of ret_flags to test whether the context supports the service option.

GSS_C_DELEG_FLAG. The True/False values are:

True: Delegated credentials are available from the delegated_cred_handle parameter.
False: No credentials were delegated.

GSS_C_MUTUAL_FLAG. The True/False values are:

True: The context acceptor requested mutual authentication.
False: The context acceptor did not request mutual authentication.

GSS_C_REPLAY_FLAG. The True/False values are:

True: Replayed signed or sealed messages will be detected.
False: Replayed messages will not be detected.

GSS_C_SEQUENCE_FLAG. The True/False values are:

True: Out-of-sequence signed or sealed messages will be detected.
False: Out-of-sequence signed or sealed messages will not be detected.

GSS_C_CONF_FLAG. The True/False values are:

True: Confidentiality services are available by calling the gss_seal() routine.
False: Confidentiality services are not available. However, the application can call the gss_seal() routine to provide message encapsulation, data-origin authentication, and integrity services.

GSS_C_INTEG_FLAG. The True/False values are:

True: Integrity services can be invoked by calling either the gss_sign() or gss_seal() routine.
False: Integrity services for individual messages are not available.

GSS_C_ANON_FLAG. The True/False values are:

True: The initiator's identity has not been revealed, and will not be revealed if any emitted token is passed to the acceptor.
False: The initiator's identity has been or will be authenticated normally.

GSS_C_PROT_READY_FLAG. The True/False values are:

True: Protection services (as specified by the states of the 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 the 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_TRANS_FLAG. The True/False values are:

True: The resultant 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

Returns the number of seconds for which the context remains valid. This is optional information. If the time is not required, specify NULL.

delegated_cred_handle

Returns the credential handle for credentials received from the context initiator. The credential handle is valid only if delegated credentials are available. If the ret_flags parameter is true, the flag GSS_C_DELEG_FLAG s set, indicating that delegated credentials are available.

minor_status

Returns a status code from the security mechanism.

STATUS CODES

The following status codes can be returned:

GSS_S_COMPLETE: The routine was completed successfully.
GSS_S_BAD_BINDINGS: The input_token parameter contains different channel bindings from those specified with the input_chan_bindings parameter.
GSS_S_BAD_SIG: The input_token parameter contains an invalid signature.
GSS_S_CONTINUE_NEEDED: To complete the context, the gss_accept_sec_context() routine must be called again with a token required from the context acceptor.
GSS_S_CREDENTIALS_EXPIRED: The referenced credentials have expired.
GSS_S_DEFECTIVE_CREDENTIAL: Consistency checks performed on the credential failed.
GSS_S_DEFECTIVE_TOKEN: Consistency checks performed on the input_token parameter failed.
GSS_S_DUPLICATE_TOKEN: The input_token parameter was already processed. This is a fatal error that occurs during context establishment.
GSS_S_FAILURE: The routine failed. See the minor_status parameter return value for more information.
GSS_S_NO_CONTEXT: The supplied context handle did not refer to a valid context.
GSS_S_NO_CRED: Indicates either the supplied credentials were not valid for context acceptance or the credential handle did not reference any credentials.
GSS_S_OLD_TOKEN: The input_token parameter was too old. This is a fatal error that occurs during context establishment.
GSS_S_BAD_MECH: The received token specified a mechanism that is not supported

AUTHOR

gss_accept_sec_context() was developed by Sun Microsystems, Inc.

gss_accept_sec_context(3)

Technical documentation

» Table of Contents

» Index