| minor_status | The status code returned by the underlying mechanism. | |
| initiator_cred_handle | The credential handle for the application. This should be initialized to GSS_C_NO_CREDENTIAL to indicate the default credential to use. | |
| context_handle | The context handle to be returned. This should be set to GSS_C_NO_CONTEXT before the loop begins. | |
| target_name | The name of the principal to connect to; for example, "nfs@machinename." | |
| mech_type | The security mechanism to use. Set this to GSS_C_NO_OID to get the default provided by the GSS-API. | |
| req_flags | Flags indicating additional services or parameters requested for this context. req_flags flags should be logically OR'd to make the desired bit-mask value, as in:
Requests that delegation of the initiator's credentials be permitted. See "Delegation". Requests mutual authentication. See "Mutual Authentication". Requests detection of repeated messages. See "Out-of-Sequence Detection and Replay Detection". Requests detection of out-of-sequence messages. See "Out-of-Sequence Detection and Replay Detection". Requests that the confidentiality service be allowed for transferred messages; that is, that messages be encrypted. If confidentiality is not allowed, then only data-origin authentication and integrity services can be applied (this last only if GSS_C_INTEG_FLAG is not false). Requests that the integrity service be applicable to messages; that is, that messages may be stamped with a MIC to ensure their validity. Requests that the initiator remain anonymous. See "Anonymous Authentication". | |
| time_req | The number of seconds for which the context should remain valid. Set this to zero (0) to request the default. | |
| input_chan_bindings | Specific peer-to-peer channel identification information connected with the security context. See "Channel Bindings" for more information about channel bindings. Set to GSS_C_NO_CHANNEL_BINDINGS if you don't want to use channel bindings. | |
| input_token | Token received from the context acceptor, if any. Should be initialized to GSS_C_NO_BUFFER before the function is called (or its length field set to zero). | |
| actual_mech_type | The mechanism actually used in the context. Specify NULL if you don't need to know. | |
| output_token | The token to send to the acceptor. | |
| ret_flags | Flags indicating additional services or parameters requested for this context. ret_flags flags should be logically AND'd to test the returned bit-mask value, as in:
If true, indicates that the initiator's credentials can be delegated. See "Delegation". If true, indicates that mutual authentication is allowed. See "Mutual Authentication". If true, indicates that detection of repeated messages is in effect. See "Out-of-Sequence Detection and Replay Detection". If true, indicates that detection of out-of-sequence messages is in effect. See "Out-of-Sequence Detection and Replay Detection". If true, confidentiality service is allowed for transferred messages; that is, that messages can be encrypted. If confidentiality is not allowed, then only data-origin authentication, and integrity services can be applied (this last only if GSS_C_INTEG_FLAG is not returned as false). If true, the integrity service can be applied to messages; that is, that messages can be stamped with a MIC to ensure their validity. If true, indicates that the context initiator will remain anonymous. See "Anonymous Authentication". Sometimes context establishment can take several passes, and sometimes the client might have to wait before it's complete. Even though a context is not fully established, gss_init_sec_context() can indicate what protection services, if any, will be available after the context is complete. An application can therefore buffer its data, sending it when the context is eventually fully established. If ret_flags indicates GSS_C_PROT_READY_FLAG, the protection services indicated by the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG flags are available even if the context has not been fully established (that is, if gss_init_sec_context() returns GSS_S_CONTINUE_NEEDED). An application can then call the appropriate wrapping functions, gss_wrap() or gss_get_mic(), with the preferred protection services, and buffer the output for transfer when the context is complete. If GSS_C_PROT_READY_FLAG is false, then the application cannot make any assumptions about data protection, and must wait until the context is complete (that is, when gss_init_sec_context() returns GSS_S_COMPLETE). Note - Earlier versions of the GSS-API did not support the GSS_C_PROT_READY_FLAG argument, so developers wanting to maximize portability should determine which per-message services are available by looking at the GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG flags after a context has been successfully established. This flag indicates whether this context can be exported. For more information on importing and exporting contexts, see "Context Export and Import". | |
| time_rec | Number of seconds for which the context will remain valid. Specify NULL if you're not interested in this value. |
In general, the parameter values returned when a context is not fully established are those that would be returned when the context is complete. See the gss_init_sec_context() man page for more information.
gss_init_sec_context() returns GSS_S_COMPLETE if it completes successfully. If a context-establishment token is required from the peer application, it returns GSS_S_CONTINUE_NEEDED. If there are errors, it returns error codes, which can be found on the gss_init_sec_context(3GSS) man page.
If context initiation fails, the client should disconnect from the server.