'\" te

.\" Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.

.TH gss_store_cred 3GSS "30 Jun 2005" "SunOS 5.12" "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 \fBgss_store_cred\fR(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