Generic Security Services API Library Functions
gssacceptseccontext(3GS)
NAME
gssacceptseccontext - accept a security context initiated
by a peer application
SYNOPSIS
cc [ flag... ] file... -lgss [ library... ]
#include
OMuint32 gssacceptseccontext(OMuint32 *minorstatus,
gssctxidt *contexthandle,
const gsscredidt acceptorcredhandle,
const gssbuffert inputtoken,
const gsschannelbindingst inputchanbindings,
const gssnamet * srcname, gssOID * mechtype,
gssbuffert outputtoken, OMuint32 *retflags,
OMuint32 * timerec, gsscredidt *delegatedcredhandle);
PARAMETERS
The parameter descriptions for gssacceptseccontext() fol-
low:
minorstatus
The status code returned by the underlying mechanism.
contexthandle
The context handle to return to the initiator. This
should be set to GSCNOCONTEXT before the loop
begins.
acceptorcredhandle
The handle for the credentials acquired by the acceptor,
typically through gssacquirecred(). It may be initial-
ized to GSCNOCREDENTIAL to indicate a default
credential to use. If no default credential is defined,
the function returns GSCNOCRED.
inputtokenbuffer
Token received from the context initiative.
inputchanbindings
Optional application-specified bindings. Allows
SunOS 5.11 Last change: 22 May 2006 1
Generic Security Services API Library Functions
gssacceptseccontext(3GS)
application to securely bind channel identification
information to the security context. Set to
GSCNOCHANELBINDINGS if you do not want to use
channel bindings.
srcname
The authenticated name of the context initiator. After
use, this name should be deallocated by passing it to
gssreleasename(). See gssreleasename(3GS). If not
required, specify NUL.
mechtype
The security mechanism used. Set to NUL if it does not
matter which mechanism is used.
outputtoken
The token to send to the acceptor. Initialize it to
GSCNOBUFER before the function is called (or its
length field set to zero). If the length is zero, no
token need be sent.
retflags
Contains various independent flags, each of which indi-
cates that the context supports a specific service
option. If not needed, specify NUL. Test the returned
bit-mask retflags value against its symbolic name to
determine if the given option is supported by the con-
text. retflags may contain one of the following values:
GSCDELEGFLAG
If true, delegated credentials are available by
means of the delegatedcredhandle parameter. If
false, no credentials were delegated.
GSCMUTUALFLAG
If true, a remote peer asked for mutual authentica-
tion. If false, no remote peer asked for mutual
authentication.
SunOS 5.11 Last change: 22 May 2006 2
Generic Security Services API Library Functions
gssacceptseccontext(3GS)
GSCREPLAYFLAG
If true, replay of protected messages will be
detected. If false, replayed messages will not be
detected.
GSCSEQUENCEFLAG
If true, out of sequence protected messages will be
detected. If false, they will not be detected.
GSCONFLAG
If true, confidentiality service may be invoked by
calling the gsswrap() routine. If false, no confi-
dentiality service is available by means of
gsswrap(). gsswrap() will provide message encapsu-
lation, data-origin authentication and integrity
services only.
GSCINTEGFLAG
If true, integrity service may be invoked by calling
either the gssgetmic(3GS) or the gsswrap(3GS)
routine. If false, per-message integrity service is
not available.
GSCANONFLAG
If true, the initiator does not wish to be authenti-
cated. The srcname parameter, if requested, con-
tains an anonymous internal name. If false, the ini-
tiator has been authenticated normally.
GSCPROTREADYFLAG
If true, the protection services specified by the
states of GSCONFLAG and GSCINTEGFLAG are
available if the accompanying major status return
value is either GSCOMPLETE or
GSCONTINUENEDED. If false, the protection ser-
vices are available only if the accompanying major
status return value is GSCOMPLETE.
SunOS 5.11 Last change: 22 May 2006 3
Generic Security Services API Library Functions
gssacceptseccontext(3GS)
GSCTRANSFLAG
If true, the resultant security context may be
transferred to other processes by means of a call to
gssexportseccontext(3GS). If false, the security
context cannot be transferred.
timerec
The number of sections for which the context will remain
value Specify NUL if not required.
delegatedcredhandle
The credential value for credentials received from the
context's initiator. It is valid only if the initiator
has requested that the acceptor act as a proxy: that is,
if the retflag argument resolves to GSCDELEGFLAG.
DESCRIPTION
The gssacceptseccontext() function allows a remotely ini-
tiated security context between the application and a remote
peer to be established. The routine may return an
outputtoken, which should be transferred to the peer appli-
cation, where the peer application will present it to
gssinitseccontext(). See gssinitseccontext(3GS). If
no token need be sent, gssacceptseccontext() will indi-
cate this by setting the length field of the outputtoken
argument to zero. To complete the context establishment, one
or more reply tokens may be required from the peer applica-
tion; if so, gssacceptseccontext() will return a status
flag of GSCONTINUENEDED, in which case it should be
called again when the reply token is received from the peer
application, passing the token to gssacceptseccontext()
by means of the inputtoken parameters.
Portable applications should be constructed to use the token
length and return status to determine whether to send or to
wait for a token.
Whenever gssacceptseccontext() returns a major status
that includes the value GSCONTINUENEDED, the context
is not fully established, and the following restrictions
apply to the output parameters:
SunOS 5.11 Last change: 22 May 2006 4
Generic Security Services API Library Functions
gssacceptseccontext(3GS)
o The value returned by means of the timerec parame-
ter is undefined.
o Unless the accompanying retflags parameter con-
tains the bit GSCPROTREADYFLAG, which indi-
cates that per-message services may be applied in
advance of a successful completion status, the
value returned by the mechtype parameter may be
undefined until gssacceptseccontext() returns a
major status value of GSCOMPLETE.
The values of the GSCDELEGFLAG, GSCMUTUALFLAG,
GSCREPLAYFLAG, GSCSEQUENCEFLAG, GSCONFLAG,
GSCINTEGFLAG and GSCANONFLAG bits returned by means
of the retflags parameter are values that would be valid if
context establishment were to succeed.
The values of the GSCPROTREADYFLAG and GSCTRANSFLAG
bits within retflags indicate the actual state at the time
gssacceptseccontext() returns, whether or not the context
is fully established. However, applications should not rely
on this behavior, as GSCPROTREADYFLAG was not defined
in Version 1 of the GS-API. Instead, applications should be
prepared to use per-message services after a successful con-
text establishment, based upon the GSCINTEGFLAG and
GSCONFLAG values.
All other bits within the retflags argument are set to
zero.
While gssacceptseccontext() returns
GSCONTINUENEDED, the values returned by means of the
the retflags argument indicate the services available from
the established context. If the initial call of
gssacceptseccontext() fails, no context object is
created, and the value of the contexthandle parameter is
set to GSCNOCONTEXT. In the event of a failure on a sub-
sequent call, the security context and the contexthandle
parameter are left untouched for the application to delete
using gssdeleteseccontext(3GS). During context estab-
lishment, the informational status bits GSOLDTOKEN and
GSDUPLICATETOKEN indicate fatal errors; GS-API mechan-
isms always return them in association with a routine error
of GSFAILURE. This pairing requirement did not exist in
version 1 of the GS-API specification, so applications that
wish to run over version 1 implementations must special-case
these codes.
SunOS 5.11 Last change: 22 May 2006 5
Generic Security Services API Library Functions
gssacceptseccontext(3GS)
ERORS
gssacceptseccontext() may return the following status
codes:
GSCOMPLETE Successful completion.
GSCONTINUENEDED A token from the peer applica-
tion is required to complete
the context, and that
gssacceptseccontext() 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 were
not valid for context accep-
tance, or the credential han-
dle did 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.
GSNOCONTEXT The supplied context handle
did not refer to a valid con-
text.
GSBADSIG The inputtoken contains an
invalid MIC.
SunOS 5.11 Last change: 22 May 2006 6
Generic Security Services API Library Functions
gssacceptseccontext(3GS)
GSOLDTOKEN The inputtoken was too old.
This is a fatal error while
establishing context.
GSDUPLICATETOKEN The inputtoken is valid, but
it is duplicate of a token
already processed. This is a
fatal error while establishing
context.
GSBADMECH The token received specified 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 gssacceptseccontext() Within a Loop
A typical portable caller should always invoke
gssacceptseccontext() within a loop:
gssctxidt contexthdl = GSCNOCONTEXT;
do {
receivetokenfrompeer(inputtoken);
majstat = gssacceptseccontext(&minstat,
&contexthdl,
credhdl,
inputtoken,
inputbindings,
&clientname,
&mechtype,
outputtoken,
&retflags,
&timerec,
&delegcred);
SunOS 5.11 Last change: 22 May 2006 7
Generic Security Services API Library Functions
gssacceptseccontext(3GS)
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;
};
} while (majstat & GSCONTINUENEDED);
/* Check clientname authorization */
...
(void) gssreleasename(&minstat, &clientname);
/* Use and/or store delegated credential */
...
(void) gssreleasecred(&minstat, &delegcred);
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), gssinitseccontext(3GS),
gssreleasecred(3GS), gssreleasename(3GS),
gssstorecred(3GS), gsswrap(3GS), attributes(5)
Solaris Security for Developers Guide
SunOS 5.11 Last change: 22 May 2006 8
Generic Security Services API Library Functions
gssacceptseccontext(3GS)
SunOS 5.11 Last change: 22 May 2006 9
|
