Generic Security Services API Library Functions
gssacquirecred(3GS)
NAME
gssacquirecred - acquire a handle for a pre-existing
credential by name
SYNOPSIS
cc [ flag... ] file... -lgss [ library... ]
#include
OMuint32 gssacquirecred(OMuint32 *minorstatus,
const gssnamet *desiredname, OMuint32 timereq,
const gssOIDset desiredmech, gsscredusaget credusage,
gsscredidt * outputcredhandle, gssOIDset *actualmechs,
OMuint32 *timerec);
DESCRIPTION
The gssacquirecred() function allows an application to
acquire a handle for a pre-existing credential by name. This
routine is not intended as a function to login to the net-
work; a function for login to the network would involve
creating new credentials rather than merely acquiring a han-
dle to existing credentials.
If desiredname is GSCNONAME, the call is interpreted as
a request for a credential handle that will invoke default
behavior when passed to gssinitseccontext(3GS) (if
credusage is GSCINITIATE or GSCBOTH) or
gssacceptseccontext(3GS) (if credusage is GSCACEPT
or GSCBOTH).
Normally gssacquirecred() returns a credential that is
valid only for the mechanisms requested by the desiredmechs
argument. However, if multiple mechanisms can share a single
credential element, the function returns all the mechanisms
for which the credential is valid in the actualmechs argu-
ment.
gssacquirecred() is intended to be used primarily by con-
text acceptors, since the GS-API routines obtain initiator
credentials through the system login process. Accordingly,
you may not acquire GSCINITIATE or GSCBOTH credentials
by means of gssacquirecred() for any name other than
GSCNONAME. Alternatively, you may acquire GSCINITIATE
or GSCBOTH credentials for a name produced when
gssinquirecred(3GS) is applied to a valid credential, or
when gssinquirecontext(3GS) is applied to an active con-
text.
SunOS 5.11 Last change: 14 Jan 2003 1
Generic Security Services API Library Functions
gssacquirecred(3GS)
If credential acquisition is time-consuming for a mechanism,
the mechanism may choose to delay the actual acquisition
until the credential is required, for example, by
gssinitseccontext(3GS) or by
gssacceptseccontext(3GS). Such mechanism-specific
implementations are, however, invisible to the calling
application; thus a call of gssinquirecred(3GS) immedi-
ately following the call of gssacquirecred() will return
valid credential data and incur the overhead of a deferred
credential acquisition.
PARAMETERS
The parameter descriptions for gssacquirecred() follow:
desiredname The name of the principal for which a
credential should be acquired.
timereq The number of seconds that credentials
remain valid. Specify GSCINDEFINITE
to request that the credentials have
the maximum permitted lifetime
desiredmechs The set of underlying security mechan-
isms that may be used.
GSCNOIDSET may be used to obtain
a default.
credusage A flag that indicates how this creden-
tial should be used. If the flag is
GSCACEPT, then credentials will be
used only to accept security creden-
tials. GSCINITIATE indicates that
credentials will be used only to ini-
tiate security credentials. If the
flag is GSCBOTH, then credentials
may be used either to initiate or
accept security contexts.
outputcredhandle The returned credential handle.
Resources associated with this creden-
tial handle must be released by the
application after use with a call to
gssreleasecred(3GS)
actualmechs The set of mechanisms for which the
credential is valid. Storage
SunOS 5.11 Last change: 14 Jan 2003 2
Generic Security Services API Library Functions
gssacquirecred(3GS)
associated with the returned OID-set
must be released by the application
after use with a call to
gssreleaseoidset(3GS). Specify
NUL if not required.
timerec Actual number of seconds for which the
returned credentials will remain
valid. Specify NUL if not required.
minorstatus Mechanism specific status code.
ERORS
gssacquirecred() may return the following status code:
GSCOMPLETE Successful completion.
GSBADMECH An unavailable mechanism has
been requested.
GSBADNAMETYPE The type contained within the
desiredname parameter is not
supported.
GSBADNAME The value supplied for
desiredname parameter is ill
formed.
GSCREDENTIALSEXPIRED The credentials could not be
acquired because they have
expired.
GSNOCRED No credentials were found for
the specified name.
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
SunOS 5.11 Last change: 14 Jan 2003 3
Generic Security Services API Library Functions
gssacquirecred(3GS)
condition.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWgss (32-bit)
SUNWgssx (64-bit)
MT-Level Safe
SEE ALSO
gssacceptseccontext(3GS), gssinitseccontext(3GS),
gssinquirecontext(3GS), gssinquirecred(3GS),
gssreleasecred(3GS), gssreleaseoidset(3GS), attri-
butes(5)
Solaris Security for Developers Guide
SunOS 5.11 Last change: 14 Jan 2003 4
Generic Security Services API Library Functions
gssacquirecred(3GS)
SunOS 5.11 Last change: 14 Jan 2003 5
|
