Tribblix: manual page: gss_init_sec

GSS_INIT_SEC_CONTEXT(3GSS) Generic Security Services API Library Functions

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_handle 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_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
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
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-message
integrity service is
required.

GSS_C_ANON_FLAG
If true, do not
reveal the
initiator's identify
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
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-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
acceptor. 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_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_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
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_BUFFER, 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 establishment, one or more reply tokens may be required from
the peer application; if so, gss_init_sec_context() will return a
status code that contains 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
status 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
contains the bit GSS_C_PROT_READY_FLAG, which indicates
that per-message services 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.

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
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.

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
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.

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_context(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
status 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 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
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 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
contains 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
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