gss_init_sec_conGenericSSecurity Services API Librargss_init_sec_context(3GSS)NAMEgss_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 initia‐
tor 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 con‐
text_handle must be released by the application
after use by a call to gss_delete_sec_con‐
text(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_ID.
req_flags Contains independent flags, each of which will
request that the context support a specific
service option. A symbolic name is provided for
each flag. Logically-OR the symbolic name to
the corresponding 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 mes‐
sages 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 messages. 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-mes‐
sage integrity service is required.
GSS_C_ANON_FLAG
If true, do not reveal the initiator's
identify to the acceptor. If false, authen‐
ticate normally.
time_req The number of seconds for which the context
will remain valid. Supply 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 identifi‐
cation 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, supply 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 parameter 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_ID. 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 appli‐
cation. 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 val‐
ues:
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 encapsula‐
tion, 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-
message 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 accep‐
tor. If false, the initiator has been or
will be authenticated 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_CON‐
TINUE_NEEDED. If false, the protection ser‐
vices are available only if the accompany‐
ing major status return value is GSS_S_COM‐
PLETE.
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_context(3GSS).
If false, the security context cannot be
transferred.
time_rec The number of seconds for which the context
will remain valid. Specify NULL if the parame‐
ter 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:
· The value returned by means of the time_rec parameter is unde‐
fined. 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 means of 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 values that will be valid if context
establishment succeeds. For example, if the application 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 provide the service, and it indicate by means of the
ret_flags argument that the service will not be supported. The
application 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.
· 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.
· The GSS-API sets the GSS_C_PROT_READY_FLAG in the final ret_flags
returned to a caller, for example, when accompanied 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.
· 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 implemen‐
tations must special-case these codes.
ERRORSgss_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 context, 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 creden‐
tial handle does not reference any cre‐
dentials.
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 establishing 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 establish‐
ing 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 con‐
tains an invalid or unsupported name
type.
GSS_S_BAD_NAME The supplied target_name parameter is
ill-formed.
GSS_S_BAD_MECH The token received specifies a mecha‐
nism that is not supported by the
implementation or the provided creden‐
tial.
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(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOgss_delete_sec_context(3GSS), gss_export_sec_context(3GSS),
gss_get_mic(3GSS), gss_wrap(3GSS), attributes(5)
Solaris Security for Developers Guide
SunOS 5.10 22 May 2006 gss_init_sec_context(3GSS)
