gss_accept_sec_context(3sec)

Establishes a security context between the application and a context acceptor

Synopsis

#include <dce/gssapi.h>

OM_uint32 gss_accept_sec_context (
OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
gss_cred_id_t verifier_cred_handle,
gss_buffer_t input_token_buffer,
gss_channel_bindings_t input_chan_bindings,
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)

Parameters

Input

verifier_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. If you do not specify a credential handle and specify instead GSS_C_NO_CREDENTIAL, the application can accept a context under any registered identity. Use the gssdce_register_acceptor_identity( ) routine to register an identity before specifying GSS_C_NO_CREDENTIAL.

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.

Input/Output

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

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
Returns the security mechanism with which the context was established. The security mechanism will be one of the following:

· GSSDCE_C_OID_DCE_KRBV5_DES, for DCE Security

· GSSDCE_C_OID_KRBV5_DES, for Kerberos Version 5

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 for GSS_C_DELEG_FLAG 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 for GSS_C_MUTUAL_FLAG 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 for GSS_C_REPLAY_FLAG 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 for GSS_C_SEQUENCE_FLAG 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 for GSS_C_CONF_FLAG 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 for GSS_C_INTEG_FLAG 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.

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 is set, indicating that delegated credentials are available.

minor_status
Returns a status code from the security mechanism.

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 gss_accept_sec_context( ) routine must find a key to decrypt the token. The token contains the unencrypted principal name of the context acceptor. The acceptor's principal name identifies the key that the context initiator used to encrypt the rest of the token. The gss_accept_sec_context( ) routine matches the principal name with the key in the following way:

· If you specify a credential, the credential and the name in the token must match. The acceptor's principal name (contained in the token) has been registered by a call to the gssdec_register_acceptor_identity( ) routine. The gss_accept_sec_context( ) routine looks in the registered key table.

· If you specify GSS_C_NO_CRED and the principal name in the token is registered, the gss_accept_sec_context( ) routine, using either the rpc_server_register_auth_info( ) routine or the gssdce_register_acceptor_identity( ) routine, looks in the table specified when you registered the token name.

· If you specify GSS_C_NO_CRED and the principal name in the token is not registered, the gss_accept_sec_context( ) routine fails and returns the status GSS_S_FAILURE because the Generic Security Service Application Programming Interface (GSSAPI) does not know where to find the key.

The following table summarizes how the gss_accept_sec_context( ) routine determines the key for the credential:

You specify... Is the principal's name registered?
Then the routine... _

A credential Yes Looks in the key table specified in gssdce_register_acceptor_identity( ) or the default key table.

GSS_C_NO_CRED Yes Looks in the key table specified in gssdce_register_acceptor_identity( ).

No Fails because the principal is not registered. It returns the status code GSS_S_FAILURE.

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.

Status Codes
The following describes a partial list of codes (messages) that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all messages. 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.

Related Information
Functions:

gss_acquire_cred(3sec)

gss_delete_sec_context(3sec)

gss_init_sec_context(3sec)

gssdce_register_acceptor_identity(3sec)