gss_init_sec_context - API security context with a peer application
cc [ flag... ] file... -lgss [ library... ] #include <gssapi/gssapi.h> OM_uint32 gss_init_sec_context(OM_uint32 *minor_status, const gss_cred_id_t initiator_cred_handle, gss_ctx_id_t *context_handle, const gss_name_t *target_name, const gss_OID mech_type, OM_uint32 req_flags, OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings, const gss_buffer_t input_token, gss_OID *actual_mech_type, gss_buffer_t output_token, OM_uint32 *ret_flags, OM_uint32 *time_rec);
Generic Security Services API Library Functions
gss_init_sec_context(3gss)
NAME
gss_init_sec_context - initiate a GSS-API security context with a peer
application
SYNOPSIS
cc [ flag... ] file... -lgss [ library... ]
#include <gssapi/gssapi.h>
OM_uint32 gss_init_sec_context(OM_uint32 *minor_status,
const gss_cred_id_t initiator_cred_handle,
gss_ctx_id_t *context_handle, const gss_name_t *target_name,
const gss_OID mech_type, OM_uint32 req_flags,
OM_uint32 time_req, const gss_channel_bindings_t input_chan_bindings,
const gss_buffer_t input_token, gss_OID *actual_mech_type,
gss_buffer_t output_token, OM_uint32 *ret_flags,
OM_uint32 *time_rec);
PARAMETERS
The parameter descriptions for gss_init_sec_context() follow:
minor_status
A mechanism specific status code.
initiator_cred_handle
The handle for the credentials claimed. Supply GSS_C_NO_CREDENTIAL
to act as a default initiator principal. If no default initiator is
defined, the function returns GSS_S_NO_CRED.
context_handle
The context handle for a new context. Supply the value
GSS_C_NO_CONTEXT for the first call, and use the value returned in
any continuation calls. The resources associated with context_han-
dle must be released by the application after use by a call to
gss_delete_sec_context(3GSS).
target_name
The name of the context acceptor.
mech_type
The object ID of the desired mechanism. To obtain a specific
default, supply the value GSS_C_NO_OID.
req_flags
Contains independent flags, each of which will request that the
context support a specific service option. A symbolic name is pro-
vided for each flag. Logically-OR the symbolic name to the corre-
sponding required flag to form the bit-mask value. req_flags may
contain one of the following values:
GSS_C_DELEG_FLAG
If true, delegate credentials to a remote peer. Do not delegate
the credentials if the value is false.
GSS_C_MUTUAL_FLAG
If true, request that the peer authenticate itself. If false,
authenticate to the remote peer only.
GSS_C_REPLAY_FLAG
If true, enable replay detection for messages protected with
gss_wrap(3GSS) or gss_get_mic(3GSS). Do not attempt to detect
replayed messages if false.
GSS_C_SEQUENCE_FLAG
If true, enable detection of out-of-sequence protected mes-
sages. Do not attempt to detect out-of-sequence messages if
false.
GSS_C_CONF_FLAG
If true, request that confidential service be made available by
means of gss_wrap(3GSS). If false, no per-message confidential
service is required.
GSS_C_INTEG_FLAG
If true, request that integrity service be made available by
means of gss_wrap(3GSS) or gss_get_mic(3GSS). If false, no per-
message integrity service is required.
GSS_C_ANON_FLAG
If true, do not reveal the initiator's identify to the accep-
tor. If false, authenticate normally.
time_req
The number of seconds for which the context will remain valid. Sup-
ply a zero value to time_req to request a default validity period.
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.
input_token
Token received from the peer application. On the initial call, sup-
ply GSS_C_NO_BUFFER or a pointer to a buffer containing the value
GSS_C_EMPTY_BUFFER.
actual_mech_type
The actual mechanism used. The OID returned by means of this param-
eter will be pointer to static storage that should be treated as
read-only. The application should not attempt to free it. To obtain
a specific default, supply the value GSS_C_NO_OID. Specify NULL if
the parameter is not required.
output_token
The token to send to the peer application. If the length field of
the returned buffer is zero, no token need be sent to the peer
application. After use storage associated with this buffer must be
freed by the application by a call to gss_release_buffer(3GSS).
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, credentials were delegated to the remote peer. If
false, no credentials were delegated.
GSS_C_MUTUAL_FLAG
If true, the remote peer authenticated itself. If false, the
remote peer did not authenticate itself.
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, confidential service may be invoked by calling the
gss_wrap() routine. If false, no confidentiality service is
available by means of gss_wrap(3GSS). gss_wrap() will provide
message encapsulation, data-origin authentication and integrity
services only.
GSS_C_INTEG_FLAG
If true, integrity service may be invoked by calling either the
gss_wrap(3GSS) or gss_get_mic(3GSS) routine. If false, per-mes-
sage integrity service is not available.
GSS_C_ANON_FLAG
If true, the initiator's identity has not been revealed; it
will not be revealed if any emitted token is passed to the
acceptor. If false, the initiator has been or will be authenti-
cated normally.
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 seconds for which the context will remain valid.
Specify NULL if the parameter is not required.
DESCRIPTION
The gss_init_sec_context() function initiates the establishment of a
security context between the application and a remote peer. Initially,
the input_token parameter should be specified either as GSS_C_NO_BUF-
FER, or as a pointer to a gss_buffer_desc object with a length field
that contains a zero value. The routine may return a output_token,
which should be transferred to the peer application, which will present
it to gss_accept_sec_context(3GSS). If no token need be sent,
gss_init_sec_context() will indicate this by setting the length field
of the output_token argument to zero. To complete context establish-
ment, one or more reply tokens may be required from the peer applica-
tion; if so, gss_init_sec_context() will return a status code that con-
tains the supplementary information bit GSS_S_CONTINUE_NEEDED. In this
case, make another call to gss_init_sec_context() when the reply token
is received from the peer application and pass the reply token to
gss_init_sec_context() by means of the input_token parameter.
Construct portable applications to use the token length and return sta-
tus to determine whether to send or wait for a token.
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:
o The value returned by means of the time_rec parameter is
undefined. Unless the accompanying ret_flags parameter con-
tains the bit GSS_C_PROT_READY_FLAG, which indicates that
per-message services may be applied in advance of a success-
ful completion status, the value returned by means of the
actual_mech_type parameter is undefined until the routine
returns a major status value of GSS_S_COMPLETE.
o 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 values that will be valid if
context establishment succeeds. For example, if the applica-
tion requests a service such as delegation or anonymous
authentication by means of the req_flags argument, and the
service is unavailable from the underlying mechanism,
gss_init_sec_context() generates a token that will not pro-
vide the service, and it indicate by means of the ret_flags
argument that the service will not be supported. The appli-
cation may choose to abort context establishment by calling
gss_delete_sec_context(3GSS) if it cannot continue without
the service, or if the service was merely desired but not
mandatory, it may transmit the token and continue context
establishment.
o 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_init_sec_context() returns, whether or not the context
is fully established.
o The GSS-API sets the GSS_C_PROT_READY_FLAG in the final
ret_flags returned to a caller, for example, when accompa-
nied by a GSS_S_COMPLETE status code. However, applications
should not rely on this behavior, as the flag was not
defined in Version 1 of the GSS-API. Instead, applications
should determine what per-message services are available
after a successful context establishment according to the
GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.
o All other bits within the ret_flags argument are set to
zero.
If the initial call of gss_init_sec_context() fails, the GSS-API does
not create a context object; it leaves the value of the context_handle
parameter set to GSS_C_NO_CONTEXT to indicate this. In the event of
failure on a subsequent call, the GSS-API leaves the security context
untouched for the application to delete using gss_delete_sec_con-
text(3GSS).
During context establishment, the informational status bits
GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
GSS-API mechanisms should always return them in association with a sta-
tus code of GSS_S_FAILURE. This pairing requirement was not part of
Version 1 of the GSS-API specification, so applications that wish to
run on Version 1 implementations must special-case these codes.
ERRORS
gss_init_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 con-
text, and gss_init_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 credential failed.
GSS_S_NO_CRED
The supplied credentials are not valid for context acceptance, or
the credential handle does not reference any credentials.
GSS_S_CREDENTIALS_EXPIRED
The referenced credentials have expired.
GSS_S_BAD_BINDINGS
The input_token contains different channel bindings than those
specified by means of the input_chan_bindings parameter.
GSS_S_BAD_SIG
The input_token contains an invalid MIC or a MIC that cannot be
verified.
GSS_S_OLD_TOKEN
The input_token is too old. This is a fatal error while establish-
ing context.
GSS_S_DUPLICATE_TOKEN
The input_token is valid, but it is a duplicate of a token already
processed. This is a fatal error while establishing context.
GSS_S_NO_CONTEXT
The supplied context handle does not refer to a valid context.
GSS_S_BAD_NAMETYPE
The provided target_name parameter contains an invalid or unsup-
ported name type.
GSS_S_BAD_NAME
The supplied target_name parameter is ill-formed.
GSS_S_BAD_MECH
The token received specifies a mechanism that is not supported by
the implementation 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_init_sec_context() Within a Loop
A typical portable caller should always invoke gss_init_sec_context()
within a loop:
int context_established = 0;
gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
...
input_token->length = 0;
while (!context_established) {
maj_stat = gss_init_sec_context(&min_stat,
cred_hdl,
&context_hdl,
target_name,
desired_mech,
desired_services,
desired_time,
input_bindings,
input_token,
&actual_mech,
output_token,
&actual_services,
&actual_time);
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;
};
if (maj_stat & GSS_S_CONTINUE_NEEDED) {
receive_token_from_peer(input_token);
} else {
context_established = 1;
};
};
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_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 6 Nov 2009
gss_init_sec_context(3gss)