path: root/usr/src/man/man3gss/gss_init_sec_context.3gss

'\" te
.\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH GSS_INIT_SEC_CONTEXT 3GSS "May 22, 2006"
.SH NAME
gss_init_sec_context \- initiate a GSS-API security context with a peer
application
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lgss\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <gssapi/gssapi.h>

\fBOM_uint32\fR \fBgss_init_sec_context\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
     \fBconst gss_cred_id_t\fR \fIinitiator_cred_handle\fR,
     \fBgss_ctx_id_t *\fR\fIcontext_handle\fR, \fBconst gss_name_t *\fR\fItarget_name\fR,
     \fBconst gss_OID\fR \fImech_type\fR, \fBOM_uint32\fR \fIreq_flags\fR,
     \fBOM_uint32\fR \fItime_req\fR, \fBconst gss_channel_bindings_t\fR \fIinput_chan_bindings\fR,
     \fBconst gss_buffer_t\fR \fIinput_token\fR, \fBgss_OID *\fR\fIactual_mech_type\fR,
     \fBgss_buffer_t\fR \fIoutput_token\fR, \fBOM_uint32 *\fR\fIret_flags\fR,
     \fBOM_uint32 *\fR\fItime_rec\fR);
.fi

.SH PARAMETERS
.sp
.LP
The parameter descriptions for \fBgss_init_sec_context()\fR follow:
.sp
.ne 2
.na
\fB\fIminor_status\fR\fR
.ad
.RS 25n
A mechanism specific status code.
.RE

.sp
.ne 2
.na
\fB\fIinitiator_cred_handle\fR\fR
.ad
.RS 25n
The handle for the credentials claimed. Supply \fBGSS_C_NO_CREDENTIAL\fR to act
as a default initiator principal. If no default initiator is defined, the
function returns \fBGSS_S_NO_CRED\fR.
.RE

.sp
.ne 2
.na
\fB\fIcontext_handle\fR\fR
.ad
.RS 25n
The context handle for a new context. Supply the value \fBGSS_C_NO_CONTEXT\fR
for the first call, and use the value returned in any continuation calls. The
resources associated with \fIcontext_handle\fR must be released by the
application after use by a call to \fBgss_delete_sec_context\fR(3GSS).
.RE

.sp
.ne 2
.na
\fB\fItarget_name\fR\fR
.ad
.RS 25n
The name of the context acceptor.
.RE

.sp
.ne 2
.na
\fB\fImech_type\fR\fR
.ad
.RS 25n
The object \fBID\fR of the desired mechanism. To obtain a specific default,
supply the value \fBGSS_C_NO_ID\fR.
.RE

.sp
.ne 2
.na
\fB\fIreq_flags\fR\fR
.ad
.RS 25n
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-\fBOR\fR the symbolic name to the corresponding required flag to form
the bit-mask value. \fIreq_flags\fR may contain one of the following values:
.sp
.ne 2
.na
\fB\fBGSS_C_DELEG_FLAG\fR\fR
.ad
.RS 23n
If true, delegate credentials to a remote peer. Do not delegate the credentials
if the value is false.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_MUTUAL_FLAG\fR\fR
.ad
.RS 23n
If true, request that the peer authenticate itself. If false, authenticate to
the remote peer only.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_REPLAY_FLAG\fR\fR
.ad
.RS 23n
If true, enable replay detection for messages protected with
\fBgss_wrap\fR(3GSS) or \fBgss_get_mic\fR(3GSS). Do not attempt to detect
replayed messages if false.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_SEQUENCE_FLAG\fR\fR
.ad
.RS 23n
If true, enable detection of out-of-sequence protected messages. Do not attempt
to detect out-of-sequence messages if false.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_CONF_FLAG\fR\fR
.ad
.RS 23n
If true, request that confidential service be made available by means of
\fBgss_wrap\fR(3GSS). If false, no per-message confidential service is
required.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_INTEG_FLAG\fR\fR
.ad
.RS 23n
If true, request that integrity service be made available by means of
\fBgss_wrap\fR(3GSS) or \fBgss_get_mic\fR(3GSS). If false, no per-message
integrity service is required.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_ANON_FLAG\fR\fR
.ad
.RS 23n
If true, do not reveal the initiator's identify to the acceptor. If false,
authenticate normally.
.RE

.RE

.sp
.ne 2
.na
\fB\fItime_req\fR\fR
.ad
.RS 25n
The number of seconds for which the context will remain valid. Supply a zero
value to \fItime_req\fR to request a default validity period.
.RE

.sp
.ne 2
.na
\fB\fIinput_chan_bindings\fR\fR
.ad
.RS 25n
Optional application-specified bindings. Allows application to securely bind
channel identification information to the security context. Set to
\fBGSS_C_NO_CHANNEL_BINDINGS\fR if you do not want to use channel bindings.
.RE

.sp
.ne 2
.na
\fB\fIinput_token\fR\fR
.ad
.RS 25n
Token received from the peer application. On the initial call, supply
\fBGSS_C_NO_BUFFER\fR or a pointer to a buffer containing the value
\fBGSS_C_EMPTY_BUFFER\fR.
.RE

.sp
.ne 2
.na
\fB\fIactual_mech_type\fR\fR
.ad
.RS 25n
The actual mechanism used. The \fBOID\fR 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 \fBGSS_C_NO_ID\fR. Specify \fBNULL\fR if the parameter is not
required.
.RE

.sp
.ne 2
.na
\fB\fIoutput_token\fR\fR
.ad
.RS 25n
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 \fBgss_release_buffer\fR(3GSS).
.RE

.sp
.ne 2
.na
\fB\fIret_flags\fR\fR
.ad
.RS 25n
Contains various independent flags, each of which indicates that the context
supports a specific service option. If not needed, specify \fBNULL\fR. Test the
returned bit-mask \fIret_flags\fR value against its symbolic name to determine
if the given option is supported by the context. \fIret_flags\fR may contain
one of the following values:
.sp
.ne 2
.na
\fB\fBGSS_C_DELEG_FLAG\fR\fR
.ad
.RS 25n
If true, credentials were delegated to the remote peer. If false, no
credentials were delegated.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_MUTUAL_FLAG\fR\fR
.ad
.RS 25n
If true, the remote peer authenticated itself. If false, the remote peer did
not authenticate itself.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_REPLAY_FLAG\fR\fR
.ad
.RS 25n
If true, replay of protected messages will be detected. If false, replayed
messages will not be detected.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_SEQUENCE_FLAG\fR\fR
.ad
.RS 25n
If true, out of sequence protected messages will be detected. If false, they
will not be detected.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_CONF_FLAG\fR\fR
.ad
.RS 25n
If true, confidential service may be invoked by calling the \fBgss_wrap()\fR
routine. If false, no confidentiality service is available by means of
\fBgss_wrap\fR(3GSS). \fBgss_wrap()\fR will provide message encapsulation,
data-origin authentication and integrity services only.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_INTEG_FLAG\fR\fR
.ad
.RS 25n
If true, integrity service may be invoked by calling either the
\fBgss_wrap\fR(3GSS) or \fBgss_get_mic\fR(3GSS) routine. If false, per-message
integrity service is not available.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_ANON_FLAG\fR\fR
.ad
.RS 25n
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.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_PROT_READY_FLAG\fR\fR
.ad
.RS 25n
If true, the protection services specified by the states of
\fBGSS_C_CONF_FLAG\fR and \fBGSS_C_INTEG_FLAG\fR are available if the
accompanying major status return value is either \fBGSS_S_COMPLETE\fR or
\fBGSS_S_CONTINUE_NEEDED\fR. If false, the protection services are available
only if the accompanying major status return value is \fBGSS_S_COMPLETE\fR.
.RE

.sp
.ne 2
.na
\fB\fBGSS_C_TRANS_FLAG\fR\fR
.ad
.RS 25n
If true, the resultant security context may be transferred to other processes
by means of a call to \fBgss_export_sec_context\fR(3GSS). If false, the
security context cannot be transferred.
.RE

.RE

.sp
.ne 2
.na
\fB\fItime_rec\fR\fR
.ad
.RS 25n
The number of seconds for which the context will remain valid. Specify
\fBNULL\fR if the parameter is not required.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBgss_init_sec_context()\fR function initiates the establishment of a
security context between the application and a remote peer. Initially, the
\fIinput_token\fR parameter should be specified either as
\fBGSS_C_NO_BUFFER\fR, or as a pointer to a \fBgss_buffer_desc\fR object with a
\fBlength\fR field that contains a zero value. The routine may return a
\fIoutput_token\fR, which should be transferred to the peer application, which
will present it to \fBgss_accept_sec_context\fR(3GSS). If no token need be
sent, \fBgss_init_sec_context()\fR will indicate this by setting the
\fBlength\fR field of the \fIoutput_token\fR argument to zero. To complete
context establishment, one or more reply tokens may be required from the peer
application; if so, \fBgss_init_sec_context()\fR will return a status code that
contains the supplementary information bit \fBGSS_S_CONTINUE_NEEDED\fR. In this
case, make another call to \fBgss_init_sec_context()\fR when the reply token is
received from the peer application and pass the reply token to
\fBgss_init_sec_context()\fR by means of the \fIinput_token\fR parameter.
.sp
.LP
Construct portable applications to use the token length and return status to
determine whether to send or wait for a token.
.sp
.LP
Whenever the routine returns a major status that includes the value
\fBGSS_S_CONTINUE_NEEDED\fR, the context is not fully established, and the
following restrictions apply to the output parameters:
.RS +4
.TP
.ie t \(bu
.el o
The value returned by means of the \fItime_rec\fR parameter is undefined.
Unless the accompanying \fIret_flags\fR parameter contains the bit
\fBGSS_C_PROT_READY_FLAG\fR, which indicates that per-message services may be
applied in advance of a successful completion status, the value returned by
means of the \fIactual_mech_type\fR parameter is undefined until the routine
returns a major status value of \fBGSS_S_COMPLETE\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The values of the \fBGSS_C_DELEG_FLAG\fR, \fBGSS_C_MUTUAL_FLAG\fR,
\fBGSS_C_REPLAY_FLAG\fR, \fBGSS_C_SEQUENCE_FLAG\fR, \fBGSS_C_CONF_FLAG\fR,
\fBGSS_C_INTEG_FLAG\fR and \fBGSS_C_ANON_FLAG\fR bits returned by the
\fIret_flags\fR 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 \fIreq_flags\fR
argument, and the service is unavailable from the underlying mechanism,
\fBgss_init_sec_context()\fR generates a token that will not provide the
service, and it indicate by means of the \fIret_flags\fR argument that the
service will not be supported. The application may choose to abort context
establishment by calling \fBgss_delete_sec_context\fR(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.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The values of the \fBGSS_C_PROT_READY_FLAG\fR and \fBGSS_C_TRANS_FLAG\fR bits
within \fIret_flags\fR indicate the actual state at the time
\fBgss_init_sec_context()\fR returns, whether or not the context is fully
established.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBGSS-API\fR sets the \fBGSS_C_PROT_READY_FLAG\fR in the final
\fIret_flags\fR returned to a caller, for example, when accompanied by a
\fBGSS_S_COMPLETE\fR status code. However, applications should not rely on this
behavior, as the flag was not defined in Version 1 of the \fBGSS-API\fR.
Instead, applications should determine what per-message services are available
after a successful context establishment according to the
\fBGSS_C_INTEG_FLAG\fR and \fBGSS_C_CONF_FLAG\fR values.
.RE
.RS +4
.TP
.ie t \(bu
.el o
All other bits within the \fIret_flags\fR argument are set to zero.
.RE
.sp
.LP
If the initial call of \fBgss_init_sec_context()\fR fails, the \fBGSS-API\fR
does not create a context object; it leaves the value of the
\fIcontext_handle\fR parameter set to \fBGSS_C_NO_CONTEXT\fR to indicate this.
In the event of failure on a subsequent call, the \fBGSS-API\fR leaves the
security context untouched for the application to delete using
\fBgss_delete_sec_context\fR(3GSS).
.sp
.LP
During context establishment, the informational status bits
\fBGSS_S_OLD_TOKEN\fR and \fBGSS_S_DUPLICATE_TOKEN\fR indicate fatal errors,
and \fBGSS-API\fR mechanisms should always return them in association with a
status code of \fBGSS_S_FAILURE\fR. 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.
.SH ERRORS
.sp
.LP
\fBgss_init_sec_context()\fR may return the following status codes:
.sp
.ne 2
.na
\fB\fBGSS_S_COMPLETE\fR\fR
.ad
.RS 30n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_CONTINUE_NEEDED\fR\fR
.ad
.RS 30n
A token from the peer application is required to complete the context, and
\fBgss_init_sec_context()\fR must be called again with that token.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_DEFECTIVE_TOKEN\fR\fR
.ad
.RS 30n
Consistency checks performed on the \fIinput_token\fR failed.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_DEFECTIVE_CREDENTIAL\fR\fR
.ad
.RS 30n
Consistency checks performed on the credential failed.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_NO_CRED\fR\fR
.ad
.RS 30n
The supplied credentials are not valid for context acceptance, or the
credential handle does not reference any credentials.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR
.ad
.RS 30n
The referenced credentials have expired.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_BAD_BINDINGS\fR\fR
.ad
.RS 30n
The \fIinput_token\fR contains different channel bindings than those specified
by means of the \fIinput_chan_bindings\fR parameter.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_BAD_SIG\fR\fR
.ad
.RS 30n
The \fIinput_token\fR contains an invalid \fBMIC\fR or a \fBMIC\fR that cannot
be verified.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_OLD_TOKEN\fR\fR
.ad
.RS 30n
The \fIinput_token\fR is too old. This is a fatal error while establishing
context.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_DUPLICATE_TOKEN\fR\fR
.ad
.RS 30n
The \fIinput_token\fR is valid, but it is a duplicate of a token already
processed. This is a fatal error while establishing context.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_NO_CONTEXT\fR\fR
.ad
.RS 30n
The supplied context handle does not refer to a valid context.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_BAD_NAMETYPE\fR\fR
.ad
.RS 30n
The provided \fItarget_name\fR parameter contains an invalid or unsupported
\fIname\fR type.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_BAD_NAME\fR\fR
.ad
.RS 30n
The supplied \fItarget_name\fR parameter is ill-formed.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_BAD_MECH\fR\fR
.ad
.RS 30n
The token received specifies a mechanism that is not supported by the
implementation or the provided credential.
.RE

.sp
.ne 2
.na
\fB\fBGSS_S_FAILURE\fR\fR
.ad
.RS 30n
The underlying mechanism detected an error for which no specific \fBGSS\fR
status code is defined. The mechanism-specific status code reported by means of
the \fIminor_status\fR parameter details the error condition.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRInvoking \fBgss_init_sec_context()\fR Within a Loop
.sp
.LP
A typical portable caller should always invoke \fBgss_init_sec_context()\fR
within a loop:

.sp
.in +2
.nf
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;
  };
};
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
.BR gss_delete_sec_context (3GSS),
.BR gss_export_sec_context (3GSS),
.BR gss_get_mic (3GSS),
.BR gss_wrap (3GSS),
.BR attributes (7)
.sp
.LP
\fISolaris Security for Developers Guide\fR