'\" te

.\" Copyright (c) 2009, 2015, Oracle and/or its affiliates. All rights reserved.

.TH gss_init_sec_context 3GSS "6 Nov 2009" "SunOS 5.12" "Generic Security Services API Library Functions"

.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

.mk

.na

\fB\fIminor_status\fR\fR

.ad

.sp .6

.RS 4n

A mechanism specific status code.

.RE

.sp

.ne 2

.mk

.na

\fB\fIinitiator_cred_handle\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fIcontext_handle\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fItarget_name\fR\fR

.ad

.sp .6

.RS 4n

The name of the context acceptor.

.RE

.sp

.ne 2

.mk

.na

\fB\fImech_type\fR\fR

.ad

.sp .6

.RS 4n

The object \fBID\fR of the desired mechanism. To obtain a specific default, supply the value \fBGSS_C_NO_OID\fR.

.RE

.sp

.ne 2

.mk

.na

\fB\fIreq_flags\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_DELEG_FLAG\fR\fR

.ad

.sp .6

.RS 4n

If true, delegate credentials to a remote peer. Do not delegate the credentials if the value is false.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_C_MUTUAL_FLAG\fR\fR

.ad

.sp .6

.RS 4n

If true, request that the peer authenticate itself. If false, authenticate to the remote peer only.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_C_REPLAY_FLAG\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_SEQUENCE_FLAG\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_CONF_FLAG\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_INTEG_FLAG\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_ANON_FLAG\fR\fR

.ad

.sp .6

.RS 4n

If true, do not reveal the initiator's identify to the acceptor. If false, authenticate normally.

.RE

.RE

.sp

.ne 2

.mk

.na

\fB\fItime_req\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fIinput_chan_bindings\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fIinput_token\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fIactual_mech_type\fR\fR

.ad

.sp .6

.RS 4n

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_OID\fR. Specify \fBNULL\fR if the parameter is not required.

.RE

.sp

.ne 2

.mk

.na

\fB\fIoutput_token\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fIret_flags\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_DELEG_FLAG\fR\fR

.ad

.sp .6

.RS 4n

If true, credentials were delegated to the remote peer. If false, no credentials were delegated.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_C_MUTUAL_FLAG\fR\fR

.ad

.sp .6

.RS 4n

If true, the remote peer authenticated itself. If false, the remote peer did not authenticate itself.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_C_REPLAY_FLAG\fR\fR

.ad

.sp .6

.RS 4n

If true, replay of protected messages will be detected. If false, replayed messages will not be detected.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_C_SEQUENCE_FLAG\fR\fR

.ad

.sp .6

.RS 4n

If true, out of sequence protected messages will be detected. If false, they will not be detected.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_C_CONF_FLAG\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_INTEG_FLAG\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_ANON_FLAG\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_PROT_READY_FLAG\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_C_TRANS_FLAG\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fItime_rec\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_S_COMPLETE\fR\fR

.ad

.sp .6

.RS 4n

Successful completion.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_CONTINUE_NEEDED\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_S_DEFECTIVE_TOKEN\fR\fR

.ad

.sp .6

.RS 4n

Consistency checks performed on the \fIinput_token\fR failed.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_DEFECTIVE_CREDENTIAL\fR\fR

.ad

.sp .6

.RS 4n

Consistency checks performed on the credential failed.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_NO_CRED\fR\fR

.ad

.sp .6

.RS 4n

The supplied credentials are not valid for context acceptance, or the credential handle does not reference any credentials.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR

.ad

.sp .6

.RS 4n

The referenced credentials have expired.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_BAD_BINDINGS\fR\fR

.ad

.sp .6

.RS 4n

The \fIinput_token\fR contains different channel bindings than those specified by means of the \fIinput_chan_bindings\fR parameter.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_BAD_SIG\fR\fR

.ad

.sp .6

.RS 4n

The \fIinput_token\fR contains an invalid \fBMIC\fR or a \fBMIC\fR that cannot be verified.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_OLD_TOKEN\fR\fR

.ad

.sp .6

.RS 4n

The \fIinput_token\fR is too old. This is a fatal error while establishing context.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_DUPLICATE_TOKEN\fR\fR

.ad

.sp .6

.RS 4n

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

.mk

.na

\fB\fBGSS_S_NO_CONTEXT\fR\fR

.ad

.sp .6

.RS 4n

The supplied context handle does not refer to a valid context.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_BAD_NAMETYPE\fR\fR

.ad

.sp .6

.RS 4n

The provided \fItarget_name\fR parameter contains an invalid or unsupported \fIname\fR type.

.RE

.sp

.ne 2