share/man/man3gss/gss_store_cred.3gss

   1 '\" te
   2 .\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH GSS_STORE_CRED 3GSS "April 9, 2016"
   7 .SH NAME
   8 gss_store_cred \- store a credential in the current credential store
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR [ \fIlibrary\fR... ]
  13 #include <gssapi/gssapi.h>
  14
  15 \fBOM_uint32\fR \fBgss_store_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  16      \fBconst gss_cred_id_t\fR \fIinput_cred\fR, \fBconst gss_cred_usage_t\fR \fIcred_usage\fR,
  17      \fBconst gss_OID\fR \fIdesired_mech\fR, \fBOM_uint32\fR \fIoverwrite_cred\fR,
  18      \fBOM_uint32\fR \fIdefault_cred\fR, \fBgss_OID_set *\fR\fIelements_stored\fR,
  19      \fBgss_cred_usage_t *\fR\fIcred_usage_stored\fR);
  20 .fi
  21
  22 .SH PARAMETERS
  23 .LP
  24 The parameter descriptions for \fBgss_store_cred()\fR follow:
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIinput_cred\fR\fR
  29 .ad
  30 .RS 21n
  31 The credential to be stored.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIcred_usage\fR\fR
  38 .ad
  39 .RS 21n
  40 This parameter specifies whether to store an initiator, an acceptor, or both
  41 usage components of a credential.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIdesired_mech\fR\fR
  48 .ad
  49 .RS 21n
  50 The mechanism-specific component of a credential to be stored. If
  51 \fBGSS_C_NULL_OID\fR is specified, the \fBgss_store_cred()\fR function attempts
  52 to store all the elements of the given \fIinput_cred_handle\fR.
  53 .sp
  54 The \fBgss_store_cred()\fR function is not atomic when storing multiple
  55 elements of a credential. All delegated credentials, however, contain a single
  56 element.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fIoverwrite_cred\fR\fR
  63 .ad
  64 .RS 21n
  65 A boolean that indicates whether to overwrite existing credentials in the
  66 current store for the same principal as that of the \fIinput_cred_handle\fR. A
  67 non-zero value indicates that credentials are overwritten. A zero value
  68 indicates that credentials are not overwritten.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fIdefault_cred\fR\fR
  75 .ad
  76 .RS 21n
  77 A boolean that indicates whether to set the principal name of the
  78 \fIinput_cred_handle\fR parameter as the default of the current credential
  79 store. A non-zero value indicates that the principal name is set as the
  80 default. A zero value indicates that the principal name is not set as the
  81 default. The default principal of a credential store matches
  82 \fBGSS_C_NO_NAME\fR as the \fIdesired_name\fR input parameter for
  83 gss_store_cred(3GSS).
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fIelements_stored\fR\fR
  90 .ad
  91 .RS 21n
  92 The set of mechanism \fBOID\fRs for which \fIinput_cred_handle\fR elements have
  93 been stored.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fIcred_usage_stored\fR\fR
 100 .ad
 101 .RS 21n
 102 The stored \fIinput_cred_handle\fR usage elements: initiator, acceptor, or
 103 both.
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fIminor_status\fR\fR
 110 .ad
 111 .RS 21n
 112 Minor status code that is specific to one of the following: the mechanism
 113 identified by the \fIdesired_mech_element\fR parameter, or the element of a
 114 single mechanism in the \fIinput_cred_handle\fR. In all other cases,
 115 \fIminor_status\fR has an undefined value on return.
 116 .RE
 117
 118 .SH DESCRIPTION
 119 .LP
 120 The \fBgss_store_cred()\fR function stores a credential in the current
 121 GSS-API credential store for the calling process. Input credentials can be
 122 re-acquired through \fBgss_add_cred\fR(3GSS) and \fBgss_acquire_cred\fR(3GSS).
 123 .sp
 124 .LP
 125 The \fBgss_store_cred()\fR function is specifically intended to make delegated
 126 credentials available to a user's login session.
 127 .sp
 128 .LP
 129 The \fBgss_accept_sec_context()\fR function can return a delegated GSS-API
 130 credential to its caller. The function does not store delegated credentials to
 131 be acquired through \fBgss_add_cred\fR(3GSS). Delegated credentials can be used
 132 only by a receiving process unless they are made available for acquisition by
 133 calling the \fBgss_store_cred()\fR function.
 134 .sp
 135 .LP
 136 The Solaris Operating System supports a single GSS-API credential store per
 137 user. The current GSS-API credential store of a process is determined by its
 138 effective UID.
 139 .sp
 140 .LP
 141 In general, acceptor applications should switch the current credential store by
 142 changing the effective UID before storing a delegated credential.
 143 .SH RETURN VALUES
 144 .LP
 145 The \fBgss_store_cred()\fR can return the following status codes:
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBGSS_S_COMPLETE\fR\fR
 150 .ad
 151 .sp .6
 152 .RS 4n
 153 Successful completion.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR
 160 .ad
 161 .sp .6
 162 .RS 4n
 163 The credentials could not be stored because they have expired.
 164 .RE
 165
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBGSS_S_CALL_INACCESSIBLE_READ\fR\fR
 170 .ad
 171 .sp .6
 172 .RS 4n
 173 No input credentials were given.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBGSS_S_UNAVAILABLE\fR\fR
 180 .ad
 181 .sp .6
 182 .RS 4n
 183 The credential store is unavailable.
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBGSS_S_DUPLICATE_ELEMENT\fR\fR
 190 .ad
 191 .sp .6
 192 .RS 4n
 193 The credentials could not be stored because the \fIoverwrite_cred\fR input
 194 parameter was set to false (\fB0\fR) and the \fIinput_cred\fR parameter
 195 conflicts with a credential in the current credential store.
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fBGSS_S_FAILURE\fR\fR
 202 .ad
 203 .sp .6
 204 .RS 4n
 205 The underlying mechanism detected an error for which no specific \fBGSS\fR
 206 status code is defined. The mechanism-specific status code reported by means of
 207 the \fIminor_status\fR parameter details the error condition.
 208 .RE
 209
 210 .SH ATTRIBUTES
 211 .LP
 212 See \fBattributes\fR(5) for descriptions of the following attributes:
 213 .sp
 214
 215 .sp
 216 .TS
 217 box;
 218 c | c
 219 l | l .
 220 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 221 _
 222 Interface Stability     Unstable
 223 _
 224 MT-Level        Safe
 225 .TE
 226
 227 .SH SEE ALSO
 228 .LP
 229 \fBgss_accept_sec_context\fR(3GSS), \fBgss_acquire_cred\fR(3GSS),
 230 \fBgss_add_cred\fR(3GSS), \fBgss_init_sec_context\fR(3GSS),
 231 \fBgss_inquire_cred\fR(3GSS), \fBgss_release_cred\fR(3GSS),
 232 \fBgss_release_oid_set\fR(3GSS), \fBattributes\fR(5)
 233 .sp
 234 .LP
 235 \fISolaris Security for Developers Guide\fR