gss_accept_sec_context - accept a security context initiated by a peer application
cc [ flag... ] file... -lgss [ library... ] #include <gssapi/gssapi.h> OM_uint32 gss_accept_sec_context(OM_uint32 *minor_status, gss_ctx_id_t *context_handle, const gss_cred_id_t acceptor_cred_handle, const gss_buffer_t input_token, const gss_channel_bindings_t input_chan_bindings, const gss_name_t * src_name, gss_OID * mech_type, gss_buffer_t output_token, OM_uint32 *ret_flags, OM_uint32 * time_rec, gss_cred_id_t *delegated_cred_handle);
Generic Security Services API Library Functions
gss_accept_sec_context(3gss)
NAME
gss_accept_sec_context - accept a security context initiated by a peer
application
SYNOPSIS
cc [ flag... ] file... -lgss [ library... ]
#include <gssapi/gssapi.h>
OM_uint32 gss_accept_sec_context(OM_uint32 *minor_status,
gss_ctx_id_t *context_handle,
const gss_cred_id_t acceptor_cred_handle,
const gss_buffer_t input_token,
const gss_channel_bindings_t input_chan_bindings,
const gss_name_t * src_name, gss_OID * mech_type,
gss_buffer_t output_token, OM_uint32 *ret_flags,
OM_uint32 * time_rec, gss_cred_id_t *delegated_cred_handle);
PARAMETERS
The parameter descriptions for gss_accept_sec_context() follow:
minor_status
The status code returned by the underlying mechanism.
context_handle
The context handle to return to the initiator. This should be set
to GSS_C_NO_CONTEXT before the loop begins.
acceptor_cred_handle
The handle for the credentials acquired by the acceptor, typically
through gss_acquire_cred(). It may be initialized to GSS_C_NO_CRE-
DENTIAL to indicate a default credential to use. If no default cre-
dential is defined, the function returns GSS_C_NO_CRED.
input_token_buffer
Token received from the context initiative.
input_chan_bindings
Optional application-specified bindings. Allows application to
securely bind channel identification information to the security
context. Set to GSS_C_NO_CHANNEL_BINDINGS if you do not want to use
channel bindings.
src_name
The authenticated name of the context initiator. After use, this
name should be deallocated by passing it to gss_release_name(). See
gss_release_name(3GSS). If not required, specify NULL.
mech_type
The security mechanism used. Set to NULL if it does not matter
which mechanism is used.
output_token
The token to send to the acceptor. Initialize it to GSS_C_NO_BUFFER
before the function is called (or its length field set to zero). If
the length is zero, no token need be sent.
ret_flags
Contains various independent flags, each of which indicates that
the context supports a specific service option. If not needed,
specify NULL. Test the returned bit-mask ret_flags value against
its symbolic name to determine if the given option is supported by
the context. ret_flags may contain one of the following values:
GSS_C_DELEG_FLAG
If true, delegated credentials are available by means of the
delegated_cred_handle parameter. If false, no credentials were
delegated.
GSS_C_MUTUAL_FLAG
If true, a remote peer asked for mutual authentication. If
false, no remote peer asked for mutual authentication.
GSS_C_REPLAY_FLAG
If true, replay of protected messages will be detected. If
false, replayed messages will not be detected.
GSS_C_SEQUENCE_FLAG
If true, out of sequence protected messages will be detected.
If false, they will not be detected.
GSS_C_CONF_FLAG
If true, confidentiality service may be invoked by calling the
gss_wrap() routine. If false, no confidentiality service is
available by means of gss_wrap(). gss_wrap() will provide mes-
sage encapsulation, data-origin authentication and integrity
services only.
GSS_C_INTEG_FLAG
If true, integrity service may be invoked by calling either the
gss_get_mic(3GSS) or the gss_wrap(3GSS) routine. If false, per-
message integrity service is not available.
GSS_C_ANON_FLAG
If true, the initiator does not wish to be authenticated. The
src_name parameter, if requested, contains an anonymous inter-
nal name. If false, the initiator has been authenticated nor-
mally.
GSS_C_PROT_READY_FLAG
If true, the protection services specified by the states of
GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG are available if the
accompanying major status return value is either GSS_S_COMPLETE
or GSS_S_CONTINUE_NEEDED. If false, the protection services are
available only if the accompanying major status return value is
GSS_S_COMPLETE.
GSS_C_TRANS_FLAG
If true, the resultant security context may be transferred to
other processes by means of a call to gss_export_sec_con-
text(3GSS). If false, the security context cannot be trans-
ferred.
time_rec
The number of sections for which the context will remain valid.
Specify NULL if not required.
delegated_cred_handle
The credential value for credentials received from the context's
initiator. It is valid only if the initiator has requested that the
acceptor act as a proxy: that is, if the ret_flag argument resolves
to GSS_C_DELEG_FLAG.
DESCRIPTION
The gss_accept_sec_context() function allows a remotely initiated secu-
rity context between the application and a remote peer to be estab-
lished. The routine may return an output_token, which should be trans-
ferred to the peer application, where the peer application will present
it to gss_init_sec_context(). See gss_init_sec_context(3GSS). If no
token need be sent, gss_accept_sec_context() will indicate this by set-
ting the length field of the output_token argument to zero. To complete
the context establishment, one or more reply tokens may be required
from the peer application; if so, gss_accept_sec_context() will return
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 applica-
tion, passing the token to gss_accept_sec_context() by means of the
input_token parameters.
Portable applications should be constructed to use the token length and
return status to determine whether to send or to wait for a token.
Whenever gss_accept_sec_context() 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:
o The value returned by means of the time_rec parameter is
undefined.
o Unless the accompanying ret_flags parameter contains the bit
GSS_C_PROT_READY_FLAG, which indicates that per-message ser-
vices may be applied in advance of a successful completion
status, the value returned by the mech_type parameter may be
undefined until gss_accept_sec_context() 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 means of the
ret_flags parameter are values that would be valid if context estab-
lishment were to succeed.
The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
within ret_flags indicate the actual state at the time
gss_accept_sec_context() returns, whether or not the context is fully
established. However, applications should not rely on this behavior, as
GSS_C_PROT_READY_FLAG was not defined in Version 1 of the GSS-API.
Instead, applications should be prepared to use per-message services
after a successful context establishment, based upon the
GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.
All other bits within the ret_flags argument are set to zero.
While gss_accept_sec_context() returns GSS_S_CONTINUE_NEEDED, the val-
ues returned by means of the the ret_flags argument indicate the ser-
vices available from the established context. If the initial call of
gss_accept_sec_context() fails, no context object is created, and the
value of the context_handle parameter is set to GSS_C_NO_CONTEXT. In
the event of a failure on a subsequent call, the security context and
the context_handle parameter are left untouched for the application to
delete using gss_delete_sec_context(3GSS). During context establish-
ment, the informational status bits GSS_S_OLD_TOKEN and GSS_S_DUPLI-
CATE_TOKEN indicate fatal errors; GSS-API mechanisms always return them
in association with a routine error of GSS_S_FAILURE. This pairing
requirement did not exist in version 1 of the GSS-API specification, so
applications that wish to run over version 1 implementations must spe-
cial-case these codes.
ERRORS
gss_accept_sec_context() may return the following status codes:
GSS_S_COMPLETE Successful completion.
GSS_S_CONTINUE_NEEDED A token from the peer application is
required to complete the context, and
that gss_accept_sec_context() must be
called again with that token.
GSS_S_DEFECTIVE_TOKEN Consistency checks performed on the
input_token failed.
GSS_S_DEFECTIVE_CREDENTIAL Consistency checks performed on the cre-
dential failed.
GSS_S_NO_CRED The supplied credentials were not valid
for context acceptance, or the credential
handle did not reference any credentials.
GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
GSS_S_BAD_BINDINGS The input_token contains different chan-
nel bindings than those specified by
means of the input_chan_bindings parame-
ter.
GSS_S_NO_CONTEXT The supplied context handle did not refer
to a valid context.
GSS_S_BAD_SIG The input_token contains an invalid MIC.
GSS_S_OLD_TOKEN The input_token was too old. This is a
fatal error while establishing context.
GSS_S_DUPLICATE_TOKEN The input_token is valid, but it is
duplicate of a token already processed.
This is a fatal error while establishing
context.
GSS_S_BAD_MECH The token received specified a mechanism
that is not supported by the implementa-
tion or the provided credential.
GSS_S_FAILURE The underlying mechanism detected an
error for which no specific GSS status
code is defined. The mechanism-specific
status code reported by means of the
minor_status parameter details the error
condition.
EXAMPLES
Example 1 Invoking gss_accept_sec_context() Within a Loop
A typical portable caller should always invoke gss_accept_sec_context()
within a loop:
gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
do {
receive_token_from_peer(input_token);
maj_stat = gss_accept_sec_context(&min_stat,
&context_hdl,
cred_hdl,
input_token,
input_bindings,
&client_name,
&mech_type,
output_token,
&ret_flags,
&time_rec,
&deleg_cred);
if (GSS_ERROR(maj_stat)) {
report_error(maj_stat, min_stat);
};
if (output_token->length != 0) {
send_token_to_peer(output_token);
gss_release_buffer(&min_stat, output_token);
};
if (GSS_ERROR(maj_stat)) {
if (context_hdl != GSS_C_NO_CONTEXT)
gss_delete_sec_context(&min_stat,
&context_hdl,
GSS_C_NO_BUFFER);
break;
};
} while (maj_stat & GSS_S_CONTINUE_NEEDED);
/* Check client_name authorization */
...
(void) gss_release_name(&min_stat, &client_name);
/* Use and/or store delegated credential */
...
(void) gss_release_cred(&min_stat, &deleg_cred);
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|MT-Level |Safe |
+-----------------------------+-----------------------------+
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------------+
|Availability | security/kerberos-5 |
+---------------+------------------------+
|Stability | Pass-through committed |
+---------------+------------------------+
SEE ALSO
gss_delete_sec_context(3GSS), gss_export_sec_context(3GSS),
gss_get_mic(3GSS), gss_init_sec_context(3GSS), gss_release_cred(3GSS),
gss_release_name(3GSS), gss_store_cred(3GSS), gss_wrap(3GSS),
attributes(7)
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://web.mit.edu/ker-
beros/dist/krb5/1.18/krb5-1.18.4.tar.gz.
Further information about this software can be found on the open source
community website at http://web.mit.edu/kerberos/.
Solaris 11.4 22 May 2006
gss_accept_sec_context(3gss)