Generic Security Services API Library Functions
gssaddcred(3GS)
NAME
gssaddcred - add a credential-element to a credential
SYNOPSIS
cc [ flag... ] file... -lgss [ library... ]
#include
OMuint32 gssaddcred(OMuint32 *minorstatus,
const gsscredidt inputcredhandle,
const gssnamet desiredname,
const gssOID desiredmech,
gsscredusaget credusage,
OMuint32 initiatortimereq,
OMuint32 acceptortimereq,
gsscredidt *outputcredhandle,
gssOIDset *actualmechs,
OMuint32 *initiatortimerec,
OMuint32 *acceptortimerec);
PARAMETERS
The parameter descriptions for gssaddcred() follow:
minorstatus Mechanism specific status code.
inputcredhandle Credential to which the credential-
element is added. If
GSCNOCREDENTIAL is specified, the
function composes the new credential
based on default behavior. While the
credential-handle is not modified by
gssaddcred(), the underlying creden-
tial is modified if
outputcredentialhandle is NUL.
desiredname Name of the principal for which a
credential should be acquired.
desiredmech Underlying security mechanism with
which the credential can be used.
GSCNULOID can be used to obtain a
default.
credusage Flag that indicates how a credential
is used to initiate or accept security
credentials. If the flag is
GSCACEPT, the credentials are used
SunOS 5.11 Last change: 30 Jun 2005 1
Generic Security Services API Library Functions
gssaddcred(3GS)
only to accept security credentials.
If the flag is GSCINITIATE, the
credentials are used only to initiate
security credentials. If the flag is
GSCBOTH, the credentials can be
used to either initiate or accept
security contexts.
initiatortimereq Number of seconds that the credential
may remain valid for initiating secu-
rity contexts. This argument is
ignored if the composed credentials
are of the GSCACEPT type. Specify
GSCINDEFINITE to request that the
credentials have the maximum permitted
initiator lifetime.
acceptortimereq Number of seconds that the credential
may remain valid for accepting secu-
rity contexts. This argument is
ignored if the composed credentials
are of the GSCINITIATE type.
Specify GSCINDEFINITE to request
that the credentials have the maximum
permitted initiator lifetime.
outputcredhandle Returned credential handle that con-
tains the new credential-element and
all the credential-elements from
inputcredhandle. If a valid pointer
to a gsscredidt is supplied for
this parameter, gssaddcred() creates
a new credential handle that contains
all credential-elements from
inputcredhandle and the newly
acquired credential-element. If NUL
is specified for this parameter, the
newly acquired credential-element is
added to the credential identified by
inputcredhandle.
The resources associated with any
credential handle returned by means of
this parameter must be released by the
application after use by a call to
gssreleasecred(3GS).
SunOS 5.11 Last change: 30 Jun 2005 2
Generic Security Services API Library Functions
gssaddcred(3GS)
actualmechs Complete set of mechanisms for which
the new credential is valid. Storage
for the returned OID-set must be freed
by the application after use by a call
to gssreleaseoidset(3GS). Specify
NUL if this parameter is not
required.
initiatortimerec Actual number of seconds for which the
returned credentials remain valid for
initiating contexts using the speci-
fied mechanism. If a mechanism does
not support expiration of credentials,
the value GSCINDEFINITE is
returned. Specify NUL if this parame-
ter is not required.
acceptortimerec Actual number of seconds for which the
returned credentials remain valid for
accepting security contexts using the
specified mechanism. If a mechanism
does not support expiration of creden-
tials, the value GSCINDEFINITE is
returned. Specify NUL if this parame-
ter is not required.
DESCRIPTION
The gssaddcred() function adds a credential-element to a
credential. The credential-element is identified by the name
of the principal to which it refers. This function is not
intended as a function to login to the network. A function
for login to the network would involve creating new
mechanism-specific authentication data, rather than acquir-
ing a handle to existing data.
If the value of desiredname is GSCNONAME, the call is
interpreted as a request to add a credential-element to
invoke default behavior when passed to
gssinitseccontext(3GS) if the value of credusage is
GSCINITIATE or GSCBOTH. The call is also interpreted
as a request to add a credential-element to the invoke
default behavior when passed to gssacceptseccontext(3GS)
if the value of credusage is GSCACEPT or GSCBOTH.
The gssaddcred() function is expected to be used primarily
by context acceptors. The GS-API provides mechanism-
SunOS 5.11 Last change: 30 Jun 2005 3
Generic Security Services API Library Functions
gssaddcred(3GS)
specific ways to obtain GS-API initiator credentials
through the system login process. Consequently, the GS-API
does not support acquiring GSCINITIATE or GSCBOTH
credentials by means of gssacquirecred(3GS) for any name
other than the following:
o GSCNONAME
o Name produced by gssinquirecred(3GS) applied to
a valid credential
o Name produced by gssinquirecontext(3GS) applied
to an active context
If credential acquisition is time consuming for a mechanism,
the mechanism can choose to delay the actual acquisition
until the credential is required by
gssinitseccontext(3GS), for example, or by
gssacceptseccontext(3GS). Such mechanism-specific imple-
mentation decisions are invisible to the calling applica-
tion. A call to gssinquirecred(3GS) immediately following
the call gssaddcred() returns valid credential data as
well as incurring the overhead of deferred credential
acquisition.
The gssaddcred() function can be used either to compose a
new credential that contains all credential-elements of the
original in addition to the newly-acquired credential-
element. The function can also be used to add the new
credential-element to an existing credential. If the value
of the outputcredhandle parameter is NUL, the new
credential-element is added to the credential identified by
inputcredhandle. If a valid pointer is specified for the
outputcredhandle parameter, a new credential handle is
created.
If the value of inputcredhandle is GSCNOCREDENTIAL,
the gssaddcred() function composes a credential and sets
the outputcredhandle parameter based on the default
behavior. The call has the same effect as a call first made
by the application to gssacquirecred(3GS) to specify the
same usage and to pass GSCNONAME as the desiredname
parameter. Such an application call obtains an explicit
credential handle that incorporates the default behaviors,
then passes the credential handle to gssaddcred(), and
finally calls gssreleasecred(3GS) on the first credential
handle.
SunOS 5.11 Last change: 30 Jun 2005 4
Generic Security Services API Library Functions
gssaddcred(3GS)
If the value of the inputcredhandle parameter is
GSCNOCREDENTIAL, a non-NUL value must be supplied for
the outputcredhandle parameter.
RETURN VALUES
The gssaddcred() function can return the following status
codes:
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.
GSDUPLICATELEMENT The credential already contains
an element for the requested
mechanism that has overlapping
usage and validity period.
GSCREDENTIALSEXPIRED The credentials could not be
added 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 condition.
ATRIBUTES
SunOS 5.11 Last change: 30 Jun 2005 5
Generic Security Services API Library Functions
gssaddcred(3GS)
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level Safe
SEE ALSO
gssacceptseccontext(3GS), gssacquirecred(3GS),
gssinitseccontext(3GS), gssinquirecontext(3GS),
gssinquirecred(3GS), gssreleasecred(3GS),
gssreleaseoidset(3GS), libgss(3LIB), attributes(5)
Solaris Security for Developers Guide
SunOS 5.11 Last change: 30 Jun 2005 6
Generic Security Services API Library Functions
gssaddcred(3GS)
SunOS 5.11 Last change: 30 Jun 2005 7
|
