GSS_INIT_SEC_CONTEXT(3GSS)GSS_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 ini‐
tiator 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 applica‐
tion 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_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 cre‐
dentials 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 detec‐
tion of out-of-sequence
protected messages. Do
not attempt to detect
out-of-sequence mes‐
sages 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 iden‐
tify to the acceptor.
If false, authenticate
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
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, 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, spec‐
ify NULL. Test the returned bit-mask ret_flags
value against its symbolic name to determine
if the given option is supported by the con‐
text. ret_flags may contain one of the follow‐
ing 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 mes‐
sages 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() rou‐
tine. If false, no
confidentiality ser‐
vice is available by
means of
gss_wrap(3GSS).
gss_wrap() will pro‐
vide message encapsu‐
lation, 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 avail‐
able.
GSS_C_ANON_FLAG
If true, the initia‐
tor'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
authenticated nor‐
mally.
GSS_C_PROT_READY_FLAG
If true, the protec‐
tion services speci‐
fied 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_COM‐
PLETE or GSS_S_CON‐
TINUE_NEEDED. If
false, the protection
services are avail‐
able only if the
accompanying major
status return value
is GSS_S_COMPLETE.
GSS_C_TRANS_FLAG
If true, the resul‐
tant 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 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:
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.
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 cre‐
dential failed.
GSS_S_NO_CRED
The supplied credentials are not valid
for context acceptance, or the credential
handle does not reference any creden‐
tials.
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_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 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 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 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_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
May 22, 2006 GSS_INIT_SEC_CONTEXT(3GSS)
