'\" te
.\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH GSS_STORE_CRED 3GSS "Jun 30, 2005"
.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
.na
\fB\fIinput_cred\fR\fR
.ad
.RS 21n
The credential to be stored.
.RE

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

.sp
.ne 2
.na
\fB\fIdesired_mech\fR\fR
.ad
.RS 21n
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
.na
\fB\fIoverwrite_cred\fR\fR
.ad
.RS 21n
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
.na
\fB\fIdefault_cred\fR\fR
.ad
.RS 21n
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
.na
\fB\fIelements_stored\fR\fR
.ad
.RS 21n
The set of mechanism \fBOID\fRs for which \fIinput_cred_handle\fR elements have
been stored.
.RE

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

.sp
.ne 2
.na
\fB\fIminor_status\fR\fR
.ad
.RS 21n
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
.na
\fB\fBGSS_S_COMPLETE\fR\fR
.ad
.sp .6
.RS 4n
Successful completion.
.RE

.sp
.ne 2
.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
.na
\fB\fBGSS_S_CALL_INACCESSIBLE_READ\fR\fR
.ad
.sp .6
.RS 4n
No input credentials were given.
.RE

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

.sp
.ne 2
.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
.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
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Unstable
_
MT-Level	Safe
.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
\fISolaris Security for Developers Guide\fR