gss_init_sec_context()--Initiate Security Context

 #include <gssapi.h>

 OM_uint32 gss_init_sec_context (
     OM_uint32 *    minor_status,
     gss_cred_id_t    cred_handle,
     gss_ctx_id_t *   context_handle,
     gss_name_t     target_name,
     gss_OID      mech_type,
     gss_flags_t    req_flags,
     OM_uint32      time_req,
     gss_channel_bindings_t input_chan_bindings,  
     gss_buffer_t   input_token,
     gss_OID *      actual_mech_type,
     gss_buffer_t   output_token,
     gss_flags_t *    ret_flags,
     OM_uint32 *    time_rec); 

The gss_init_sec_context() function initiates a security context for use by two communicating applications.

Parameters

minor_status  (Output)

A status code from the security mechanism.

cred_handle  (Input)

The credential handle of the GSS credential to be used to initiate the security context. The specified credential must have been created using either GSS_C_INITIATE or GSS_C_BOTH. Specify GSS_C_NO_CREDENTIAL to use the default credential obtained from the current login context.

context_handle  (Input/Output)

The context handle for the context. The first time the context initiator calls the gss_init_sec_context() routine, the context handle 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_init_sec_context() routine.

target_name  (Input)

The name of the context acceptor. This must be a Kerberos service name if delegation is requested for the Kerberos security mechanism. Otherwise, it can be any principal defined in the security registry, subject to registry policy rules.

mech_type  (Input)

The desired security mechanism as follows:

gss_mech_krb5_old	Beta Kerberos V5 mechanism
gss_mech_krb5	Kerberos V5 mechanism
GSS_C_NO_OID	Default mechanism. For the IBM® i implementation of GSS, this is the Kerberos V5 mechanism.

req_flags  (Input)

A bit mask containing independent flags representing requested GSS services. GSS does not guarantee that a requested service will be available on all systems. The application should check the ret_flags parameter to determine which of the requested services are actually provided for the context. The following symbolic definitions are provided to correspond to each flag. The symbolic names should be logically ORed to form the bit mask value.

GSS_C_ANON_FLAG	Request initiator anonymity. This flag is ignored in the current GSS implementation since Kerberos mechanism does not support initiator anonymity.
GSS_C_DELEG_FLAG	Request delegated credentials for use by the context acceptor.
GSS_C_MUTUAL_FLAG	Request mutual authentication to validate the identity of the context acceptor.
GSS_C_REPLAY_FLAG	Request message replay detection for signed or sealed messages.
GSS_C_SEQUENCE_FLAG	Request message sequence checking for signed or sealed messages.

time_req  (Input)

The desired number of seconds the security context remains valid. Specify zero for the default lifetime of 2 hours. Specify GSS_C_INDEFINITE to request the maximum lifetime.

input_chan_bindings  (Input)

The bindings describing the communications channel that is used between the communicating applications. The channel bindings information is placed in the output token that is generated by the gss_init_sec_context() routine and is validated by the gss_accept_sec_context() routine. Specify GSS_C_NO_CHANNEL_BINDINGS if there are no channel bindings.

input_token  (Input)

The token received from the context acceptor. GSS_C_NO_BUFFER should be specified if this is the first call to the gss_init_sec_context() routine.

actual_mech_type  (Output)

The security mechanism that is used with the context. The gss_OID value returned for this parameter points to read-only storage and must not be released by the application.

output_token  (Output)

A token to be sent to the context acceptor. If no token is to be sent to the context acceptor, the gss_init_sec_context() routine sets the output_token length field to zero. Otherwise, the output_token length and value fields are set. 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 indicating which GSS services are available for the context. 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 options:

GSS_C_ANON_FLAG	The initiator identity will not be provided to the context acceptor.
GSS_C_CONF_FLAG	Message confidentiality services are available.
GSS_C_DELEG_FLAG	Delegated credentials will be available to the context acceptor.
GSS_C_INTEG_FLAG	Message integrity services are available.
GSS_C_MUTUAL_FLAG	Mutual authentication will be performed. The gss_accept_sec_context() routine will generate an output token which the context acceptor must return to the context initiator to complete the security context setup.
GSS_C_PROT_READY_FLAG	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 GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED. Otherwise, protection services are available for use only if the accompanying major status return value is GSS_S_COMPLETE.
GSS_C_REPLAY_FLAG	Message replay detection will be performed.
GSS_C_SEQUENCE_FLAG	Message sequence checking will be performed.

time_rec  (Output)

The number of seconds for which the context will remain valid. If the mechanism does not support context expiration, the return value will be GSS_C_INDEFINITE. Specify NULL for this parameter if the context expiration time is not required.

Return Value

The return value is one of the following status codes:

GSS_S_COMPLETE

The routine completed successfully.

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_BAD_BINDINGS

The channel bindings are not valid.

GSS_S_BAD_MECH

The request security mechanism is not supported.

GSS_S_BAD_NAME

The target_name parameter is not valid.

GSS_S_BAD_SIG

The input token contains an incorrect integrity check value.

GSS_S_CONTINUE_NEEDED

To complete the context, the gss_init_sec_context() routine must be called again with a token created by the gss_accept_sec_context() routine.

GSS_S_CREDENTIALS_EXPIRED

The supplied credentials are no longer valid.

GSS_S_DEFECTIVE_CREDENTIAL

Consistency checks performed on the credential 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 has already been processed.

GSS_S_NO_CONTEXT

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

GSS_S_NO_CRED

The supplied credential handle does not refer to a valid credential, the supplied credential is not valid for context initiation, or there are no default credentials available.

GSS_S_OLD_TOKEN

The token is too old to be checked for duplication against previous tokens which have already been processed.

Authorities

Error Messages

Usage Notes

1. The gss_init_sec_context() routine is the first step in the establishment of a security context between the context initiator and the context acceptor. To ensure the portability of the application, use the default credential by specifying GSS_C_NO_CREDENTIAL for the cred_handle parameter.

   The first time the application calls the gss_init_sec_context() routine, the input_token parameter should either be specified as GSS_C_NO_BUFFER or the buffer length field should be set to zero. If no token needs to be sent to the context acceptor, the gss_init_sec_context() routine sets the output_token length field to zero.

   To finish establishing the context, the calling application can require one or more tokens from the context acceptor. If the application requires reply tokens, the gss_init_sec_context() routine returns GSS_S_CONTINUE_NEEDED in the supplementary information portion of the major status value. The application must call the gss_init_sec_context() routine again when it receives the reply token from the context acceptor and pass the token using the input_token parameter. When calling the gss_init_sec_context() routine to continue processing a context, the same request values must be used as for the initial call.
   
   

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 the local system. This does not guarantee, however, that confidentiality services are also available on the remote system. If confidentiality services are available on the local system but not on the remote system, an error is returned by the gss_unwrap() routine on the remote system if an encrypted message is received (that is, confidentiality was requested on the call to the gss_wrap() routine on the local system).
   
   
3. Whenever the routine returns a major status that includes the value GSS_S_CONTINUE_NEEDED, 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 actual_mech_type parameter is undefined until the routine returns a major status value 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 would be returned if the context establishment were to succeed. In particular, if the application has requested a service such as delegation or anonymous authentication through the req_flags parameter and such a service is unavailable from the underlying mechanism, gss_init_sec_context() generates a token that does not provide the service and indicates through the ret_flags parameter that the service is not supported. The application may choose to abort the context establishment by calling gss_delete_sec_context() or it may choose to transmit the token and continue context establishment.
     
     
   • 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_init_context() returns, whether or not the context is fully established.
     
     
4. Kerberos mechanism
   • To use delegation, the target principal name must be a service name. A service name is created by calling the gss_import_name() routine with the name type specified as gss_nt_service_name (object identifier {1 2 840 113554 1 2 1 4}). The service name is specified as "name@host" and results in a Kerberos principal of "name/host@host-realm". The local host name is used if no host is specified. If a host name alias is specified, the primary host name returned by the domain name service is used when constructing the principal name. The target principal name is not required to be a service name if the ticket-granting ticket does not contain a client address list. You can obtain a ticket-granting ticket without a client address list by specifying the -a option on the kinit command. Otherwise, the service name must correctly identify the host on which the target service is running.
     
     
   • The requested context lifetime is used to specify the end time when obtaining a Kerberos service ticket to the target application. The actual context lifetime is then set to the lifetime of the ticket, which may be less than the requested lifetime as determined by the registry policy.
     
     
   • If delegation is requested, the ticket-granting-ticket contained in the login context must allow forwardable tickets. If the ticket-granting ticket is not forwardable, the gss_init_sec_context() request will be successful but the GSS_C_DELEG_FLAG will not be set in the returned flags. In addition, the service ticket obtained for the target principal must allow delegation. If the target system is not enabled for delegation, the gss_init_sec_context() request will be successful but the GSS_C_DELEG_FLAG will not be set in the returned flags. You can use the klist command with the -f option to display the ticket flags. The ticket-granting ticket must have the F flag set and the service ticket must have the o flag set.

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