gss_init_sec_context()--Initiate Security Context
Syntax
#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);Service Program Name: QSYS/QKRBGSS
Default public authority: *USE
Threadsafe: Yes
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
Object Referred to | Data Authority Required |
---|---|
Each directory in the path name preceding the configuration file | *X |
Configuration file | *R |
Each directory in the path name preceding the credential cache file | *X |
Credential cache file | *RW |
Error Messages
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
Usage Notes
- 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.
- 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).
- 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.
- The value returned by the time_rec parameter is undefined.
- 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.
- 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.
API introduced: V5R1
[ Back to top | Security APIs | UNIX-Type APIs | APIs by category ]