Generic Security Services API Library Functions
gssinitseccontext(3GS)
NAME
gssinitseccontext - initiate a GS-API security context
with a peer application
SYNOPSIS
cc [ flag... ] file... -lgss [ library... ]
#include
OMuint32 gssinitseccontext(OMuint32 *minorstatus,
const gsscredidt initiatorcredhandle,
gssctxidt *contexthandle, const gssnamet *targetname,
const gssOID mechtype, OMuint32 reqflags,
OMuint32 timereq, const gsschannelbindingst inputchanbindings,
const gssbuffert inputtoken, gssOID *actualmechtype,
gssbuffert outputtoken, OMuint32 *retflags,
OMuint32 *timerec);
PARAMETERS
The parameter descriptions for gssinitseccontext() fol-
low:
minorstatus A mechanism specific status code.
initiatorcredhandle The handle for the credentials
claimed. Supply GSCNOCREDENTIAL
to act as a default initiator prin-
cipal. If no default initiator is
defined, the function returns
GSNOCRED.
contexthandle The context handle for a new con-
text. Supply the value
GSCNOCONTEXT for the first
call, and use the value returned in
any continuation calls. The
resources associated with
contexthandle must be released by
the application after use by a call
to gssdeleteseccontext(3GS).
targetname The name of the context acceptor.
mechtype The object ID of the desired
mechanism. To obtain a specific
default, supply the value
GSCNOID.
SunOS 5.11 Last change: 22 May 2006 1
Generic Security Services API Library Functions
gssinitseccontext(3GS)
reqflags 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 sym-
bolic name to the corresponding
required flag to form the bit-mask
value. reqflags may contain one of
the following values:
GSCDELEGFLAG If true,
delegate
credentials
to a remote
peer. Do not
delegate the
credentials
if the value
is false.
GSCMUTUALFLAG If true,
request that
the peer
authenticate
itself. If
false,
authenticate
to the
remote peer
only.
GSCREPLAYFLAG If true,
enable
replay
detection
for messages
protected
with
gsswrap(3GS)
or
gssgetmic(3GS).
Do not
attempt to
detect
replayed
messages if
false.
SunOS 5.11 Last change: 22 May 2006 2
Generic Security Services API Library Functions
gssinitseccontext(3GS)
GSCSEQUENCEFLAG If true,
enable
detection of
out-of-
sequence
protected
messages. Do
not attempt
to detect
out-of-
sequence
messages if
false.
GSCONFLAG If true,
request that
confidential
service be
made avail-
able by
means of
gsswrap(3GS).
If false, no
per-message
confidential
service is
required.
GSCINTEGFLAG If true,
request that
integrity
service be
made avail-
able by
means of
gsswrap(3GS)
or
gssgetmic(3GS).
If false, no
per-message
integrity
service is
required.
GSCANONFLAG If true, do
not reveal
the
initiator's
SunOS 5.11 Last change: 22 May 2006 3
Generic Security Services API Library Functions
gssinitseccontext(3GS)
identify to
the accep-
tor. If
false,
authenticate
normally.
timereq The number of seconds for which the
context will remain valid. Supply a
zero value to timereq to request a
default validity period.
inputchanbindings Optional application-specified
bindings. Allows application to
securely bind channel identifica-
tion information to the security
context. Set to
GSCNOCHANELBINDINGS if you do
not want to use channel bindings.
inputtoken Token received from the peer appli-
cation. On the initial call, supply
GSCNOBUFER or a pointer to a
buffer containing the value
GSCEMPTYBUFER.
actualmechtype 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
GSCNOID. Specify NUL if the
parameter is not required.
outputtoken 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 gssreleasebuffer(3GS).
SunOS 5.11 Last change: 22 May 2006 4
Generic Security Services API Library Functions
gssinitseccontext(3GS)
retflags Contains various independent flags,
each of which indicates that the
context supports a specific service
option. If not needed, specify
NUL. Test the returned bit-mask
retflags value against its sym-
bolic name to determine if the
given option is supported by the
context. retflags may contain one
of the following values:
GSCDELEGFLAG If true,
creden-
tials were
delegated
to the
remote
peer. If
false, no
creden-
tials were
delegated.
GSCMUTUALFLAG If true,
the remote
peer
authenti-
cated
itself. If
false, the
remote
peer did
not
authenti-
cate
itself.
GSCREPLAYFLAG If true,
replay of
protected
messages
will be
detected.
If false,
replayed
messages
will not
be
detected.
SunOS 5.11 Last change: 22 May 2006 5
Generic Security Services API Library Functions
gssinitseccontext(3GS)
GSCSEQUENCEFLAG If true,
out of
sequence
protected
messages
will be
detected.
If false,
they will
not be
detected.
GSCONFLAG If true,
confiden-
tial ser-
vice may
be invoked
by calling
the
gsswrap()
routine.
If false,
no confi-
dentiality
service is
available
by means
of
gsswrap(3GS).
gsswrap()
will pro-
vide mes-
sage
encapsula-
tion,
data-
origin
authenti-
cation and
integrity
services
only.
GSCINTEGFLAG If true,
integrity
service
may be
invoked by
calling
SunOS 5.11 Last change: 22 May 2006 6
Generic Security Services API Library Functions
gssinitseccontext(3GS)
either the
gsswrap(3GS)
or
gssgetmic(3GS)
routine.
If false,
per-
message
integrity
service is
not avail-
able.
GSCANONFLAG 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
authenti-
cated nor-
mally.
GSCPROTREADYFLAG If true,
the pro-
tection
services
specified
by the
states of
GSCONFLAG
and
GSCINTEGFLAG
are avail-
able if
SunOS 5.11 Last change: 22 May 2006 7
Generic Security Services API Library Functions
gssinitseccontext(3GS)
the accom-
panying
major
status
return
value is
either
GSCOMPLETE
or
GSCONTINUENEDED.
If false,
the pro-
tection
services
are avail-
able only
if the
accompany-
ing major
status
return
value is
GSCOMPLETE.
GSCTRANSFLAG If true,
the resul-
tant secu-
rity con-
text may
be
transferred
to other
processes
by means
of a call
to
gssexportseccontext(3GS).
If false,
the secu-
rity con-
text can-
not be
transferred.
timerec The number of seconds for which the
context will remain valid. Specify
NUL if the parameter is not
required.
SunOS 5.11 Last change: 22 May 2006 8
Generic Security Services API Library Functions
gssinitseccontext(3GS)
DESCRIPTION
The gssinitseccontext() function initiates the establish-
ment of a security context between the application and a
remote peer. Initially, the inputtoken parameter should be
specified either as GSCNOBUFER, or as a pointer to a
gssbufferdesc object with a length field that contains a
zero value. The routine may return a outputtoken, which
should be transferred to the peer application, which will
present it to gssacceptseccontext(3GS). If no token need
be sent, gssinitseccontext() will indicate this by set-
ting the length field of the outputtoken argument to zero.
To complete context establishment, one or more reply tokens
may be required from the peer application; if so,
gssinitseccontext() will return a status code that con-
tains the supplementary information bit
GSCONTINUENEDED. In this case, make another call to
gssinitseccontext() when the reply token is received from
the peer application and pass the reply token to
gssinitseccontext() by means of the inputtoken parame-
ter.
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 GSCONTINUENEDED, the context is not fully
established, and the following restrictions apply to the
output parameters:
o The value returned by means of the timerec parame-
ter is undefined. Unless the accompanying retflags
parameter contains the bit GSCPROTREADYFLAG,
which indicates that per-message services may be
applied in advance of a successful completion
status, the value returned by means of the
actualmechtype parameter is undefined until the
routine returns a major status value of
GSCOMPLETE.
o The values of the GSCDELEGFLAG,
GSCMUTUALFLAG, GSCREPLAYFLAG,
GSCSEQUENCEFLAG, GSCONFLAG,
GSCINTEGFLAG and GSCANONFLAG bits returned
by the retflags 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 reqflags argument, and the service is
SunOS 5.11 Last change: 22 May 2006 9
Generic Security Services API Library Functions
gssinitseccontext(3GS)
unavailable from the underlying mechanism,
gssinitseccontext() generates a token that will
not provide the service, and it indicate by means
of the retflags argument that the service will not
be supported. The application may choose to abort
context establishment by calling
gssdeleteseccontext(3GS) 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 GSCPROTREADYFLAG and
GSCTRANSFLAG bits within retflags indicate the
actual state at the time gssinitseccontext()
returns, whether or not the context is fully esta-
blished.
o The GS-API sets the GSCPROTREADYFLAG in the
final retflags returned to a caller, for example,
when accompanied by a GSCOMPLETE status code.
However, applications should not rely on this
behavior, as the flag was not defined in Version 1
of the GS-API. Instead, applications should
determine what per-message services are available
after a successful context establishment according
to the GSCINTEGFLAG and GSCONFLAG values.
o All other bits within the retflags argument are
set to zero.
If the initial call of gssinitseccontext() fails, the
GS-API does not create a context object; it leaves the
value of the contexthandle parameter set to
GSCNOCONTEXT to indicate this. In the event of failure
on a subsequent call, the GS-API leaves the security con-
text untouched for the application to delete using
gssdeleteseccontext(3GS).
During context establishment, the informational status bits
GSOLDTOKEN and GSDUPLICATETOKEN indicate fatal
errors, and GS-API mechanisms should always return them in
association with a status code of GSFAILURE. This pair-
ing requirement was not part of Version 1 of the GS-API
specification, so applications that wish to run on Version 1
implementations must special-case these codes.
ERORS
gssinitseccontext() may return the following status
codes:
SunOS 5.11 Last change: 22 May 2006 10
Generic Security Services API Library Functions
gssinitseccontext(3GS)
GSCOMPLETE Successful completion.
GSCONTINUENEDED A token from the peer applica-
tion is required to complete
the context, and
gssinitseccontext() must be
called again with that token.
GSDEFECTIVETOKEN Consistency checks performed
on the inputtoken failed.
GSDEFECTIVECREDENTIAL Consistency checks performed
on the credential failed.
GSNOCRED The supplied credentials are
not valid for context accep-
tance, or the credential han-
dle does not reference any
credentials.
GSCREDENTIALSEXPIRED The referenced credentials
have expired.
GSBADBINDINGS The inputtoken contains dif-
ferent channel bindings than
those specified by means of
the inputchanbindings param-
eter.
GSBADSIG The inputtoken contains an
invalid MIC or a MIC that can-
not be verified.
GSOLDTOKEN The inputtoken is too old.
This is a fatal error while
establishing context.
GSDUPLICATETOKEN The inputtoken is valid, but
it is a duplicate of a token
already processed. This is a
fatal error while establishing
context.
SunOS 5.11 Last change: 22 May 2006 11
Generic Security Services API Library Functions
gssinitseccontext(3GS)
GSNOCONTEXT The supplied context handle
does not refer to a valid con-
text.
GSBADNAMETYPE The provided targetname
parameter contains an invalid
or unsupported name type.
GSBADNAME The supplied targetname
parameter is ill-formed.
GSBADMECH The token received specifies a
mechanism that is not sup-
ported by the implementation
or the provided credential.
GSFAILURE The underlying mechanism
detected an error for which no
specific GS status code is
defined. The mechanism-
specific status code reported
by means of the minorstatus
parameter details the error
condition.
EXAMPLES
Example 1 Invoking gssinitseccontext() Within a Loop
A typical portable caller should always invoke
gssinitseccontext() within a loop:
int contextestablished = 0;
gssctxidt contexthdl = GSCNOCONTEXT;
...
inputtoken->length = 0;
while (!contextestablished) {
majstat = gssinitseccontext(&minstat,
credhdl,
&contexthdl,
targetname,
desiredmech,
desiredservices,
desiredtime,
SunOS 5.11 Last change: 22 May 2006 12
Generic Security Services API Library Functions
gssinitseccontext(3GS)
inputbindings,
inputtoken,
&actualmech,
outputtoken,
&actualservices,
&actualtime);
if (GSEROR(majstat)) {
reporterror(majstat, minstat);
};
if (outputtoken->length != 0) {
sendtokentopeer(outputtoken);
gssreleasebuffer(&minstat, outputtoken)
};
if (GSEROR(majstat)) {
if (contexthdl != GSCNOCONTEXT)
gssdeleteseccontext(&minstat,
&contexthdl,
GSCNOBUFER);
break;
};
if (majstat & GSCONTINUENEDED) {
receivetokenfrompeer(inputtoken);
} else {
contextestablished = 1;
};
};
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level Safe
SEE ALSO
gssdeleteseccontext(3GS), gssexportseccontext(3GS),
gssgetmic(3GS), gsswrap(3GS), attributes(5)
Solaris Security for Developers Guide
SunOS 5.11 Last change: 22 May 2006 13
Generic Security Services API Library Functions
gssinitseccontext(3GS)
SunOS 5.11 Last change: 22 May 2006 14
|
