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

\fBOM_uint32\fR \fBgss_store_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
     \fBconst gss_cred_id_t\fR \fIinput_cred\fR, \fBconst gss_cred_usage_t\fR \fIcred_usage\fR,
     \fBconst gss_OID\fR \fIdesired_mech\fR, \fBOM_uint32\fR \fIoverwrite_cred\fR,
     \fBOM_uint32\fR \fIdefault_cred\fR, \fBgss_OID_set *\fR\fIelements_stored\fR,
     \fBgss_cred_usage_t *\fR\fIcred_usage_stored\fR);
.fi

.SH PARAMETERS
.sp
.LP
The parameter descriptions for \fBgss_store_cred()\fR follow:
.sp
.ne 2
.mk
.na
\fB\fIinput_cred\fR\fR
.ad
.RS 21n
.rt  
The credential to be stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcred_usage\fR\fR
.ad
.RS 21n
.rt  
This parameter specifies whether to store an initiator, an acceptor, or both usage components of a credential.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdesired_mech\fR\fR
.ad
.RS 21n
.rt  
The mechanism-specific component of a credential to be stored. If \fBGSS_C_NULL_OID\fR is specified, the \fBgss_store_cred()\fR function attempts to store all the elements of the given \fIinput_cred_handle\fR.
.sp
The \fBgss_store_cred()\fR function is not atomic when storing multiple elements of a credential. All delegated credentials, however, contain a single element.
.RE

.sp
.ne 2
.mk
.na
\fB\fIoverwrite_cred\fR\fR
.ad
.RS 21n
.rt  
A boolean that indicates whether to overwrite existing credentials in the current store for the same principal as that of the \fIinput_cred_handle\fR. A non-zero value indicates that credentials are overwritten. A zero value indicates that credentials are not overwritten.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdefault_cred\fR\fR
.ad
.RS 21n
.rt  
A boolean that indicates whether to set the principal name of the \fIinput_cred_handle\fR parameter as the default of the current credential store. A non-zero value indicates that the principal name is set as the default. A zero value indicates that the principal name is not set as the default. The default principal of a credential store matches \fBGSS_C_NO_NAME\fR as the \fIdesired_name\fR input parameter for gss_store_cred(3GSS).
.RE

.sp
.ne 2
.mk
.na
\fB\fIelements_stored\fR\fR
.ad
.RS 21n
.rt  
The set of mechanism \fBOID\fRs for which \fIinput_cred_handle\fR elements have been stored.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcred_usage_stored\fR\fR
.ad
.RS 21n
.rt  
The stored \fIinput_cred_handle\fR usage elements: initiator, acceptor, or both.
.RE

.sp
.ne 2
.mk
.na
\fB\fIminor_status\fR\fR
.ad
.RS 21n
.rt  
Minor status code that is specific to one of the following: the mechanism identified by the \fIdesired_mech_element\fR parameter, or the element of a single mechanism in the \fIinput_cred_handle\fR. In all other cases, \fIminor_status\fR has an undefined value on return.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBgss_store_cred()\fR function stores a credential in the the current GSS-API credential store for the calling process. Input credentials can be re-acquired through \fBgss_add_cred\fR(3GSS) and \fBgss_acquire_cred\fR(3GSS).
.sp
.LP
The \fBgss_store_cred()\fR function is specifically intended to make delegated credentials available to a user's login session.
.sp
.LP
The \fBgss_accept_sec_context()\fR function can return a delegated GSS-API credential to its caller. The function does not store delegated credentials to be acquired through \fBgss_add_cred\fR(3GSS). Delegated credentials can be used only by a receiving process unless they are made available for acquisition by calling the \fBgss_store_cred()\fR function.
.sp
.LP
The Solaris Operating System supports a single GSS-API credential store per user. The current GSS-API credential store of a process is determined by its effective UID.
.sp
.LP
In general, acceptor applications should switch the current credential store by changing the effective UID before storing a delegated credential.
.SH RETURN VALUES
.sp
.LP
The \fBgss_store_cred()\fR can return the following status codes:
.sp
.ne 2
.mk
.na
\fB\fBGSS_S_COMPLETE\fR\fR
.ad
.sp .6
.RS 4n
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR
.ad
.sp .6
.RS 4n
The credentials could not be stored because they have expired.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_CALL_INACCESSIBLE_READ\fR\fR
.ad
.sp .6
.RS 4n
No input credentials were given.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_UNAVAILABLE\fR\fR
.ad
.sp .6
.RS 4n
The credential store is unavailable.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_DUPLICATE_ELEMENT\fR\fR
.ad
.sp .6
.RS 4n
The credentials could not be stored because the \fIoverwrite_cred\fR input parameter was set to false (\fB0\fR) and the \fIinput_cred\fR parameter conflicts with a credential in the current credential store.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_FAILURE\fR\fR
.ad
.sp .6
.RS 4n
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
_
Interface StabilityUncommitted
_
MT-LevelSafe
.TE

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