'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.TH gss_add_cred 3GSS "30 Jun 2005" "SunOS 5.11" "Generic Security Services API Library Functions"
.SH NAME
gss_add_cred \- add a credential-element to a credential
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR [ \fIlibrary\fR... ]
#include <gssapi/gssapi.h>

\fBOM_uint32\fR \fBgss_add_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
     \fBconst gss_cred_id_t\fR \fIinput_cred_handle\fR,
     \fBconst gss_name_t\fR \fIdesired_name\fR,
     \fBconst gss_OID\fR \fIdesired_mech\fR,
     \fBgss_cred_usage_t\fR \fIcred_usage\fR,
     \fBOM_uint32\fR \fIinitiator_time_req\fR,
     \fBOM_uint32\fR \fIacceptor_time_req\fR,
     \fBgss_cred_id_t *\fR\fIoutput_cred_handle\fR,
     \fBgss_OID_set *\fR\fIactual_mechs\fR,
     \fBOM_uint32 *\fR\fIinitiator_time_rec\fR,
     \fBOM_uint32 *\fR\fIacceptor_time_rec\fR);
.fi

.SH PARAMETERS
.sp
.LP
The parameter descriptions for \fBgss_add_cred()\fR follow:
.sp
.ne 2
.mk
.na
\fB\fIminor_status\fR\fR
.ad
.RS 22n
.rt  
Mechanism specific status code.
.RE

.sp
.ne 2
.mk
.na
\fB\fIinput_cred_handle\fR\fR
.ad
.RS 22n
.rt  
Credential to which the credential-element is added. If \fBGSS_C_NO_CREDENTIAL\fR is specified, the function composes the new credential based on default behavior. While the credential-handle is not modified by \fBgss_add_cred()\fR, the underlying credential is modified if \fIoutput_credential_handle\fR is \fBNULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdesired_name\fR\fR
.ad
.RS 22n
.rt  
Name of the principal for which a credential should be acquired.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdesired_mech\fR\fR
.ad
.RS 22n
.rt  
Underlying security mechanism with which the credential can be used. GSS_C_NULL_OID can be used to obtain a default.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcred_usage\fR\fR
.ad
.RS 22n
.rt  
Flag that indicates how a credential is used to initiate or accept security credentials. If the flag is \fBGSS_C_ACCEPT\fR, the credentials are used only to accept security credentials. If the flag is \fBGSS_C_INITIATE\fR, the credentials are used only to initiate security credentials. If the flag is GSS_C_BOTH, the credentials can be used to either initiate or accept security contexts.
.RE

.sp
.ne 2
.mk
.na
\fB\fIinitiator_time_req\fR\fR
.ad
.RS 22n
.rt  
Number of seconds that the credential may remain valid for initiating security contexts. This argument is ignored if the composed credentials are of the \fBGSS_C_ACCEPT\fR type. Specify \fBGSS_C_INDEFINITE\fR to request that the credentials have the maximum permitted initiator lifetime.
.RE

.sp
.ne 2
.mk
.na
\fB\fIacceptor_time_req\fR\fR
.ad
.RS 22n
.rt  
Number of seconds that the credential may remain valid for accepting security contexts. This argument is ignored if the composed credentials are of the \fBGSS_C_INITIATE\fR type. Specify \fBGSS_C_INDEFINITE\fR to request that the credentials have the maximum permitted initiator lifetime.
.RE

.sp
.ne 2
.mk
.na
\fB\fIoutput_cred_handle\fR\fR
.ad
.RS 22n
.rt  
Returned credential handle that contains the new credential-element and all the credential-elements from \fIinput_cred_handle\fR. If a valid pointer to a \fBgss_cred_id_t\fR is supplied for this parameter, \fBgss_add_cred()\fR creates a new credential handle that contains all credential-elements from \fIinput_cred_handle\fR and the newly acquired credential-element. If \fBNULL\fR is specified for this parameter, the newly acquired credential-element is added to the credential identified by \fIinput_cred_handle\fR.
.sp
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 \fBgss_release_cred\fR(3GSS).
.RE

.sp
.ne 2
.mk
.na
\fB\fIactual_mechs\fR\fR
.ad
.RS 22n
.rt  
Complete set of mechanisms for which the new credential is valid. Storage for the returned \fBOID\fR-set must be freed by the application after use by a call to \fBgss_release_oid_set\fR(3GSS). Specify \fBNULL\fR if this parameter is not required.
.RE

.sp
.ne 2
.mk
.na
\fB\fIinitiator_time_rec\fR\fR
.ad
.RS 22n
.rt  
Actual number of seconds for which the returned credentials remain valid for initiating contexts using the specified mechanism. If a mechanism does not support expiration of credentials, the value \fBGSS_C_INDEFINITE\fR is returned. Specify \fBNULL\fR if this parameter is not required.
.RE

.sp
.ne 2
.mk
.na
\fB\fIacceptor_time_rec\fR\fR
.ad
.RS 22n
.rt  
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 credentials, the value \fBGSS_C_INDEFINITE\fR is returned. Specify \fBNULL\fR if this parameter is not required.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBgss_add_cred()\fR 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 acquiring a handle to existing data.
.sp
.LP
If the value of \fIdesired_name\fR is \fBGSS_C_NO_NAME\fR, the call is interpreted as a request to add a credential-element to invoke default behavior when passed to \fBgss_init_sec_context\fR(3GSS) if the value of \fIcred_usage\fR is \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR. The call is also interpreted as a request to add a credential-element to the invoke default behavior when passed to \fBgss_accept_sec_context\fR(3GSS) if the value of \fIcred_usage\fR is \fBGSS_C_ACCEPT\fR or \fBGSS_C_BOTH\fR.
.sp
.LP
The \fBgss_add_cred()\fR function is expected to be used primarily by context acceptors. The \fBGSS-API\fR provides mechanism-specific ways to obtain \fBGSS-API\fR initiator credentials through the system login process. Consequently, the \fBGSS-API\fR does not support acquiring \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR credentials by means of \fBgss_acquire_cred\fR(3GSS) for any name other than the following:
.RS +4
.TP
.ie t \(bu
.el o
\fBGSS_C_NO_NAME\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
Name produced by \fBgss_inquire_cred\fR(3GSS) applied to a valid credential
.RE
.RS +4
.TP
.ie t \(bu
.el o
Name produced by \fBgss_inquire_context\fR(3GSS) applied to an active context
.RE
.sp
.LP
If credential acquisition is time consuming for a mechanism, the mechanism can choose to delay the actual acquisition until the credential is required by \fBgss_init_sec_context\fR(3GSS), for example, or by \fBgss_accept_sec_context\fR(3GSS). Such mechanism-specific implementation decisions are invisible to the calling application. A call to \fBgss_inquire_cred\fR(3GSS) immediately following the call \fBgss_add_cred()\fR returns valid credential data as well as incurring the overhead of deferred credential acquisition.
.sp
.LP
The \fBgss_add_cred()\fR 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 \fIoutput_cred_handle\fR parameter is \fBNULL\fR, the new credential-element is added to the credential identified by \fIinput_cred_handle\fR. If a valid pointer is specified for the \fIoutput_cred_handle\fR parameter, a new credential handle is created.
.sp
.LP
If the value of \fIinput_cred_handle\fR is \fBGSS_C_NO_CREDENTIAL\fR, the \fBgss_add_cred()\fR function composes a credential and sets the \fIoutput_cred_handle\fR parameter based on the default behavior. The call has the same effect as a call first made by the application to \fBgss_acquire_cred\fR(3GSS) to specify the same usage and to pass \fBGSS_C_NO_NAME\fR as the \fIdesired_name\fR parameter. Such an application call obtains an explicit credential handle that incorporates the default behaviors, then passes the credential handle to \fBgss_add_cred()\fR, and finally calls \fBgss_release_cred\fR(3GSS) on the first credential handle.
.sp
.LP
If the value of the \fIinput_cred_handle\fR parameter is \fBGSS_C_NO_CREDENTIAL\fR, a non-\fBNULL\fR value must be supplied for the \fIoutput_cred_handle\fR parameter.
.SH RETURN VALUES
.sp
.LP
The \fBgss_add_cred()\fR function can return the following status codes:
.sp
.ne 2
.mk
.na
\fB\fBGSS_S_COMPLETE\fR\fR
.ad
.RS 29n
.rt  
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_BAD_MECH\fR\fR
.ad
.RS 29n
.rt  
An unavailable mechanism has been requested.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_BAD_NAMETYPE\fR\fR
.ad
.RS 29n
.rt  
The type contained within the \fIdesired_name\fR parameter is not supported.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_BAD_NAME\fR\fR
.ad
.RS 29n
.rt  
The value supplied for \fIdesired_name\fR parameter is ill formed.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_DUPLICATE_ELEMENT\fR\fR
.ad
.RS 29n
.rt  
The credential already contains an element for the requested mechanism that has overlapping usage and validity period.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR
.ad
.RS 29n
.rt  
The credentials could not be added because they have expired.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_NO_CRED\fR\fR
.ad
.RS 29n
.rt  
No credentials were found for the specified name.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_FAILURE\fR\fR
.ad
.RS 29n
.rt  
The underlying mechanism detected an error for which no specific \fBGSS\fR status code is defined. The mechanism-specific status code reported by means of the \fIminor_status\fR parameter details the error condition.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBgss_accept_sec_context\fR(3GSS), \fBgss_acquire_cred\fR(3GSS), \fBgss_init_sec_context\fR(3GSS), \fBgss_inquire_context\fR(3GSS), \fBgss_inquire_cred\fR(3GSS), \fBgss_release_cred\fR(3GSS), \fBgss_release_oid_set\fR(3GSS), \fBlibgss\fR(3LIB), \fBattributes\fR(5)
.sp
.LP
\fIDeveloper\&'s Guide to Oracle Solaris 11 Security\fR