1gss_add_cred(3GSSG)eneric Security Services API Library Functiognsss_add_cred(3GSS)
2
3
4
6 gss_add_cred - add a credential-element to a credential
7
9 cc [ flag... ] file... -lgss [ library... ]
10 #include <gssapi/gssapi.h>
11
12 OM_uint32 gss_add_cred(OM_uint32 *minor_status,
13 const gss_cred_id_t input_cred_handle,
14 const gss_name_t desired_name,
15 const gss_OID desired_mech,
16 gss_cred_usage_t cred_usage,
17 OM_uint32 initiator_time_req,
18 OM_uint32 acceptor_time_req,
19 gss_cred_id_t *output_cred_handle,
20 gss_OID_set *actual_mechs,
21 OM_uint32 *initiator_time_rec,
22 OM_uint32 *acceptor_time_rec);
23
24
26 The parameter descriptions for gss_add_cred() follow:
27
28 minor_status Mechanism specific status code.
29
30
31 input_cred_handle Credential to which the credential-element is
32 added. If GSS_C_NO_CREDENTIAL is specified, the
33 function composes the new credential based on
34 default behavior. While the credential-handle is
35 not modified by gss_add_cred(), the underlying
36 credential is modified if output_credential_han‐
37 dle is NULL.
38
39
40 desired_name Name of the principal for which a credential
41 should be acquired.
42
43
44 desired_mech Underlying security mechanism with which the cre‐
45 dential can be used. GSS_C_NULL_OID can be used
46 to obtain a default.
47
48
49 cred_usage Flag that indicates how a credential is used to
50 initiate or accept security credentials. If the
51 flag is GSS_C_ACCEPT, the credentials are used
52 only to accept security credentials. If the flag
53 is GSS_C_INITIATE, the credentials are used only
54 to initiate security credentials. If the flag is
55 GSS_C_BOTH, the credentials can be used to either
56 initiate or accept security contexts.
57
58
59 initiator_time_req Number of seconds that the credential may remain
60 valid for initiating security contexts. This
61 argument is ignored if the composed credentials
62 are of the GSS_C_ACCEPT type. Specify
63 GSS_C_INDEFINITE to request that the credentials
64 have the maximum permitted initiator lifetime.
65
66
67 acceptor_time_req Number of seconds that the credential may remain
68 valid for accepting security contexts. This argu‐
69 ment is ignored if the composed credentials are
70 of the GSS_C_INITIATE type. Specify GSS_C_INDEFI‐
71 NITE to request that the credentials have the
72 maximum permitted initiator lifetime.
73
74
75 output_cred_handle Returned credential handle that contains the new
76 credential-element and all the credential-ele‐
77 ments from input_cred_handle. If a valid pointer
78 to a gss_cred_id_t is supplied for this parame‐
79 ter, gss_add_cred() creates a new credential han‐
80 dle that contains all credential-elements from
81 input_cred_handle and the newly acquired creden‐
82 tial-element. If NULL is specified for this
83 parameter, the newly acquired credential-element
84 is added to the credential identified by
85 input_cred_handle.
86
87 The resources associated with any credential han‐
88 dle returned by means of this parameter must be
89 released by the application after use by a call
90 to gss_release_cred(3GSS).
91
92
93 actual_mechs Complete set of mechanisms for which the new cre‐
94 dential is valid. Storage for the returned OID-
95 set must be freed by the application after use by
96 a call to gss_release_oid_set(3GSS). Specify NULL
97 if this parameter is not required.
98
99
100 initiator_time_rec Actual number of seconds for which the returned
101 credentials remain valid for initiating contexts
102 using the specified mechanism. If a mechanism
103 does not support expiration of credentials, the
104 value GSS_C_INDEFINITE is returned. Specify NULL
105 if this parameter is not required.
106
107
108 acceptor_time_rec Actual number of seconds for which the returned
109 credentials remain valid for accepting security
110 contexts using the specified mechanism. If a
111 mechanism does not support expiration of creden‐
112 tials, the value GSS_C_INDEFINITE is returned.
113 Specify NULL if this parameter is not required.
114
115
117 The gss_add_cred() function adds a credential-element to a credential.
118 The credential-element is identified by the name of the principal to
119 which it refers. This function is not intended as a function to login
120 to the network. A function for login to the network would involve cre‐
121 ating new mechanism-specific authentication data, rather than acquiring
122 a handle to existing data.
123
124
125 If the value of desired_name is GSS_C_NO_NAME, the call is interpreted
126 as a request to add a credential-element to invoke default behavior
127 when passed to gss_init_sec_context(3GSS) if the value of cred_usage is
128 GSS_C_INITIATE or GSS_C_BOTH. The call is also interpreted as a request
129 to add a credential-element to the invoke default behavior when passed
130 to gss_accept_sec_context(3GSS) if the value of cred_usage is
131 GSS_C_ACCEPT or GSS_C_BOTH.
132
133
134 The gss_add_cred() function is expected to be used primarily by context
135 acceptors. The GSS-API provides mechanism-specific ways to obtain GSS-
136 API initiator credentials through the system login process. Conse‐
137 quently, the GSS-API does not support acquiring GSS_C_INITIATE or
138 GSS_C_BOTH credentials by means of gss_acquire_cred(3GSS) for any name
139 other than the following:
140
141 o GSS_C_NO_NAME
142
143 o Name produced by gss_inquire_cred(3GSS) applied to a valid
144 credential
145
146 o Name produced by gss_inquire_context(3GSS) applied to an
147 active context
148
149
150 If credential acquisition is time consuming for a mechanism, the mecha‐
151 nism can choose to delay the actual acquisition until the credential is
152 required by gss_init_sec_context(3GSS), for example, or by
153 gss_accept_sec_context(3GSS). Such mechanism-specific implementation
154 decisions are invisible to the calling application. A call to
155 gss_inquire_cred(3GSS) immediately following the call gss_add_cred()
156 returns valid credential data as well as incurring the overhead of
157 deferred credential acquisition.
158
159
160 The gss_add_cred() function can be used either to compose a new creden‐
161 tial that contains all credential-elements of the original in addition
162 to the newly-acquired credential-element. The function can also be used
163 to add the new credential-element to an existing credential. If the
164 value of the output_cred_handle parameter is NULL, the new credential-
165 element is added to the credential identified by input_cred_handle. If
166 a valid pointer is specified for the output_cred_handle parameter, a
167 new credential handle is created.
168
169
170 If the value of input_cred_handle is GSS_C_NO_CREDENTIAL, the
171 gss_add_cred() function composes a credential and sets the out‐
172 put_cred_handle parameter based on the default behavior. The call has
173 the same effect as a call first made by the application to
174 gss_acquire_cred(3GSS) to specify the same usage and to pass
175 GSS_C_NO_NAME as the desired_name parameter. Such an application call
176 obtains an explicit credential handle that incorporates the default
177 behaviors, then passes the credential handle to gss_add_cred(), and
178 finally calls gss_release_cred(3GSS) on the first credential handle.
179
180
181 If the value of the input_cred_handle parameter is GSS_C_NO_CREDENTIAL,
182 a non-NULL value must be supplied for the output_cred_handle parameter.
183
185 The gss_add_cred() function can return the following status codes:
186
187 GSS_S_COMPLETE Successful completion.
188
189
190 GSS_S_BAD_MECH An unavailable mechanism has been
191 requested.
192
193
194 GSS_S_BAD_NAMETYPE The type contained within the desired_name
195 parameter is not supported.
196
197
198 GSS_S_BAD_NAME The value supplied for desired_name param‐
199 eter is ill formed.
200
201
202 GSS_S_DUPLICATE_ELEMENT The credential already contains an element
203 for the requested mechanism that has over‐
204 lapping usage and validity period.
205
206
207 GSS_S_CREDENTIALS_EXPIRED The credentials could not be added because
208 they have expired.
209
210
211 GSS_S_NO_CRED No credentials were found for the speci‐
212 fied name.
213
214
215 GSS_S_FAILURE The underlying mechanism detected an error
216 for which no specific GSS status code is
217 defined. The mechanism-specific status
218 code reported by means of the minor_status
219 parameter details the error condition.
220
221
223 See attributes(5) for descriptions of the following attributes:
224
225
226
227
228 ┌─────────────────────────────┬─────────────────────────────┐
229 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
230 ├─────────────────────────────┼─────────────────────────────┤
231 │MT-Level │Safe │
232 └─────────────────────────────┴─────────────────────────────┘
233
235 gss_accept_sec_context(3GSS), gss_acquire_cred(3GSS), gss_init_sec_con‐
236 text(3GSS), gss_inquire_context(3GSS), gss_inquire_cred(3GSS),
237 gss_release_cred(3GSS), gss_release_oid_set(3GSS), libgss(3LIB),
238 attributes(5)
239
240
241 Solaris Security for Developers Guide
242
243
244
245SunOS 5.11 30 Jun 2005 gss_add_cred(3GSS)