gss_accept_sec_context()--Accept Security Context

 #include <gssapi.h>

 OM_uint32 gss_accept_sec_context (
     OM_uint32 *    minor_status,
     gss_ctx_id_t *   context_handle,
     gss_cred_id_t    acceptor_cred_handle,
     gss_buffer_t   input_token,
     gss_channel_bindings_t input_chan_bindings,  
     gss_name_t *   src_name,
     gss_OID *      mech_type,
     gss_buffer_t   output_token,
     gss_flags_t *    ret_flags,
     OM_uint32 *    time_rec,
     gss_cred_id_t *    delegated_cred_handle);  

The gss_accept_sec_context() function accepts a security context created by the context initiator.

Parameters

minor_status  (Output)

A status code from the security mechanism.

context_handle  (Input/Output)

A context handle for the context. The first time the context acceptor calls the gss_accept_sec_context() routine, the context handle value must be set to GSS_C_NO_CONTEXT. For subsequent calls to continue setting up the context, the context handle must be the value returned by the previous call to the gss_accept_sec_context() routine.

acceptor_cred_handle  (Input)

The GSS credential for the identity claimed by the context acceptor. The credential must have been created using either GSS_C_ACCEPT or GSS_C_BOTH.

input_token  (Input)

The token received from the context initiator.

input_chan_bindings  (Input)

The bindings describing the communications channel used between the communicating applications. The channel bindings specified by the context acceptor must match the bindings that were specified by the context initiator when the input token was created. Specify GSS_C_NO_CHANNEL_BINDINGS if there are no channel bindings.

src_name  (Output)

The authenticated name of the context initiator. If the authenticated name is not required, specify NULL for this parameter. The returned name is an anonymous internal name if the GSS_C_ANON_FLAG is set in the returned flags.

mech_type  (Output)

The security mechanism with which the context was established. If the security mechanism type is not required, specify NULL for this parameter. The gss_OID value returned for this parameter points to a read-only structure and must not be released by the application. The returned security mechanism is one of the following:

gss_mech_krb5_old	Beta Kerberos V5 mechanism
gss_mech_krb5	Kerberos V5 mechanism

output_token  (Output)

A token to be returned to the context initiator. If no token is to be passed to the context initiator, the gss_accept_sec_context() routine sets the output_token length field to zero. Otherwise, the output_token length and value fields are set to nonzero values. The application should release the output token when it is no longer needed by calling the gss_release_buffer() routine.

ret_flags  (Output)

A bit mask containing independent flags representing services that have been requested by the initiating application. Specify NULL for this parameter if the flag values are not required. The following symbolic definitions are provided to test the individual flags and should be logically ANDed with the value of ret_flags to test whether the context supports the service option.

GSS_C_ANON_FLAG	Anonymous services are available if this flag is TRUE. The src_name parameter returns an anonymous internal name.
GSS_C_CONF_FLAG	Confidentiality services are available if this flag is TRUE.
GSS_C_DELEG_FLAG	Delegated credentials are available if this flag is TRUE.
GSS_C_INTEG_FLAG	Integrity services are available if this flag is TRUE.
GSS_C_MUTUAL_FLAG	Mutual authentication is required if this flag is TRUE.
GSS_C_PROT_READY_FLAG	Protection services, as specified by the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG, are available if the accompanying major status is GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED. Otherwise, protection services are available only if the accompanying major status is GSS_S_COMPLETE.
GSS_C_REPLAY_FLAG	Replayed signed or sealed messages are detected if this flag is TRUE.
GSS_C_SEQUENCE_FLAG	Out-of-sequence signed or sealed messages are detected if this flag is TRUE.

time_rec  (Output)

The number of seconds remaining before the context is no longer valid. If the mechanism does not support credential expiration, the return value is GSS_C_INDEFINITE. Specify NULL for this parameter if the remaining time is not required.

delegated_cred_handle  (Output)

The credential handle for delegated credentials received from the context initiator. Specify NULL for this parameter if the delegated credentials are not required. A credential handle is returned only if the GSS_C_DELEG_FLAG flag is set in the return flags. The returned credential can then be used to initiate a new security context by calling the gss_init_sec_context() routine. The returned credential should be released when it is no longer needed by calling the gss_release_cred() routine.

Return Value

The return value is one of the following status codes:

GSS_S_BAD_BINDINGS

The input_token parameter contains different channel bindings from those specified with the input_chan_bindings parameter.

GSS_S_BAD_MECH

The security mechanism used by the context initiator is not available on the acceptor system.

GSS_S_BAD_SIG

The received input token contains an incorrect signature.

GSS_S_COMPLETE

The routine completed successfully.

GSS_S_CONTINUE_NEEDED

Control information in the returned output token must be sent to the initiator and a response must be received and passed as the input_token argument to a continuation call to the gss_accept_sec_context() routine.

GSS_S_CREDENTIALS_EXPIRED

Credentials are no longer valid.

GSS_S_DEFECTIVE_CREDENTIAL

Consistency checks performed on the credential structure referenced by the verifier_cred_handle parameter failed.

GSS_S_DEFECTIVE_TOKEN

Consistency checks performed on the input token failed.

GSS_S_DUPLICATE_TOKEN

The token is a duplicate of a token that already has been processed. This is a fatal error during context establishment.

GSS_S_FAILURE

The routine failed for reasons that are not defined at the GSS level. The minor_status return parameter contains a mechanism-dependent error code describing the reason for the failure.

GSS_S_NO_CONTEXT

The context identifier provided by the caller does not refer to a valid security context.

GSS_S_NO_CRED

No credentials are available or the credentials are valid for context initiation use only.

GSS_S_OLD_TOKEN

The token is too old to be checked for duplication against previous tokens. This is a fatal error during context establishment.

Authorities

Error Messages

Usage Notes

1. The gss_accept_sec_context() routine is the second step in establishing a security context between the context initiator and the context acceptor. In the first step, the context initiator calls the gss_init_sec_context() routine, which returns a token for the security context. The context initiator then passes this security token to the context acceptor. In the second step, the context acceptor takes the token supplied by the context initiator and calls the gss_accept_sec_context() routine to accept the context.

   If the length value in the output_token is not zero, the context acceptor must pass the returned token to the context initiator. The context initiator must then call gss_init_sec_context() and specify the context identifier returned by the original call to gss_init_sec_context(), as well as the output token that was returned by the context acceptor.

   To complete the context establishment, one or more reply tokens may be required from the peer application. If so, gss_accept_sec_context() returns a status flag of GSS_S_CONTINUE_NEEDED, in which case it should be called again when the reply token is received from the peer application, passing the token to gss_accept_sec_context() through the input_token parameter.

2. The availability of confidentiality services is dependent on the underlying security mechanism and the features that have been installed on the system. The GSS_C_CONF_FLAG is returned only if confidentiality services are available on both the local and remote systems. If confidentiality services are available on the remote system but not on the local system, an error is returned by the gss_unwrap() routine if an encrypted message is received (that is, confidentiality was requested on the call to the gss_wrap() routine on the remote system).
   
   
3. Whenever the GSS_S_CONTINUE_NEEDED status flag is set, the context is not fully established and the following restrictions apply to the output parameters:
   
   
   • The value returned by the time_rec parameter is undefined.
     
     
   • Unless the accompanying ret_flags parameter contains the bit GSS_C_PROT_READY_FLAG, indicating that per-message services may be applied in advance of a successful completion status, the value returned by the mech_type parameter may be undefined until the routine returns a major status of GSS_S_COMPLETE.
     
     
   • The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, GSS_C_INTEG_FLAG, and GSS_C_ANON_FLAG bits returned by the ret_flags parameter contain the values that the implementation expects would be valid if context establishment were to succeed.
     
     
   • The value of the GSS_C_PROT_READY_FLAG bit returned by the ret_flags parameter indicates the actual state at the time gss_accept_sec_context() returns, whether or not the context is fully established.
     
     
4. Kerberos mechanism
   
   
   • The gss_accept_sec_context() routine needs a key to decrypt the token provided by the context initiator. The token contains the clear text principal name of the context acceptor. This name identifies the key that the context initiator used to encrypt the token. The default key table is used to obtain the key for the indicated principal. The KRB5_KTNAME environment variable can be set to use a different key table.
     
     
   • The context expiration time is obtained from the service ticket that was obtained by the context initiator as part of the gss_init_sec_context() processing.
     
     
   • When delegation is used, the forwarded Kerberos credentials are stored in a new Kerberos credentials cache that will be associated with the GSS credential returned for the delegated_cred_handle parameter. This GSS credential can then be used to initiate new security contexts on behalf of the original context initiator.

[ Back to top | Security APIs | UNIX-Type APIs | APIs by category ]