| ## 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) ##