gss_accept_sec_context()--Accept Security Context
Syntax
#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);Service Program Name: QSYS/QKRBGSS
Default public authority: *USE
Threadsafe: Yes
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
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 keytab file | *X |
Keytab file | *R |
Error Messages
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
Usage Notes
- 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.
- 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).
- 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.
- The value returned by the time_rec parameter is undefined.
- 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.
- 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.
API introduced: V5R1
[ Back to top | Security APIs | UNIX-Type APIs | APIs by category ]