| blob | 6c39ac034e1a24e2a30acd017974ce720d721006 |
1 '\" te
2 .\" Copyright (c) 2007, 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_ADD_CRED 3GSS "Jun 30, 2005"
7 .SH NAME
8 gss_add_cred \- add a credential-element to a credential
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR [ \fIlibrary\fR... ]
13 #include <gssapi/gssapi.h>
15 \fBOM_uint32\fR \fBgss_add_cred\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
16 \fBconst gss_cred_id_t\fR \fIinput_cred_handle\fR,
17 \fBconst gss_name_t\fR \fIdesired_name\fR,
18 \fBconst gss_OID\fR \fIdesired_mech\fR,
19 \fBgss_cred_usage_t\fR \fIcred_usage\fR,
20 \fBOM_uint32\fR \fIinitiator_time_req\fR,
21 \fBOM_uint32\fR \fIacceptor_time_req\fR,
22 \fBgss_cred_id_t *\fR\fIoutput_cred_handle\fR,
23 \fBgss_OID_set *\fR\fIactual_mechs\fR,
24 \fBOM_uint32 *\fR\fIinitiator_time_rec\fR,
25 \fBOM_uint32 *\fR\fIacceptor_time_rec\fR);
26 .fi
28 .SH PARAMETERS
29 .sp
30 .LP
31 The parameter descriptions for \fBgss_add_cred()\fR follow:
32 .sp
33 .ne 2
34 .na
35 \fB\fIminor_status\fR\fR
36 .ad
37 .RS 22n
38 Mechanism specific status code.
39 .RE
41 .sp
42 .ne 2
43 .na
44 \fB\fIinput_cred_handle\fR\fR
45 .ad
46 .RS 22n
47 Credential to which the credential-element is added. If
48 \fBGSS_C_NO_CREDENTIAL\fR is specified, the function composes the new
49 credential based on default behavior. While the credential-handle is not
50 modified by \fBgss_add_cred()\fR, the underlying credential is modified if
51 \fIoutput_credential_handle\fR is \fBNULL\fR.
52 .RE
54 .sp
55 .ne 2
56 .na
57 \fB\fIdesired_name\fR\fR
58 .ad
59 .RS 22n
60 Name of the principal for which a credential should be acquired.
61 .RE
63 .sp
64 .ne 2
65 .na
66 \fB\fIdesired_mech\fR\fR
67 .ad
68 .RS 22n
69 Underlying security mechanism with which the credential can be used.
70 GSS_C_NULL_OID can be used to obtain a default.
71 .RE
73 .sp
74 .ne 2
75 .na
76 \fB\fIcred_usage\fR\fR
77 .ad
78 .RS 22n
79 Flag that indicates how a credential is used to initiate or accept security
80 credentials. If the flag is \fBGSS_C_ACCEPT\fR, the credentials are used only
81 to accept security credentials. If the flag is \fBGSS_C_INITIATE\fR, the
82 credentials are used only to initiate security credentials. If the flag is
83 GSS_C_BOTH, the credentials can be used to either initiate or accept security
84 contexts.
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fB\fIinitiator_time_req\fR\fR
91 .ad
92 .RS 22n
93 Number of seconds that the credential may remain valid for initiating security
94 contexts. This argument is ignored if the composed credentials are of the
95 \fBGSS_C_ACCEPT\fR type. Specify \fBGSS_C_INDEFINITE\fR to request that the
96 credentials have the maximum permitted initiator lifetime.
97 .RE
99 .sp
100 .ne 2
101 .na
102 \fB\fIacceptor_time_req\fR\fR
103 .ad
104 .RS 22n
105 Number of seconds that the credential may remain valid for accepting security
106 contexts. This argument is ignored if the composed credentials are of the
107 \fBGSS_C_INITIATE\fR type. Specify \fBGSS_C_INDEFINITE\fR to request that the
108 credentials have the maximum permitted initiator lifetime.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fIoutput_cred_handle\fR\fR
115 .ad
116 .RS 22n
117 Returned credential handle that contains the new credential-element and all the
118 credential-elements from \fIinput_cred_handle\fR. If a valid pointer to a
119 \fBgss_cred_id_t\fR is supplied for this parameter, \fBgss_add_cred()\fR
120 creates a new credential handle that contains all credential-elements from
121 \fIinput_cred_handle\fR and the newly acquired credential-element. If
122 \fBNULL\fR is specified for this parameter, the newly acquired
123 credential-element is added to the credential identified by
124 \fIinput_cred_handle\fR.
125 .sp
126 The resources associated with any credential handle returned by means of this
127 parameter must be released by the application after use by a call to
128 \fBgss_release_cred\fR(3GSS).
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fIactual_mechs\fR\fR
135 .ad
136 .RS 22n
137 Complete set of mechanisms for which the new credential is valid. Storage for
138 the returned \fBOID\fR-set must be freed by the application after use by a call
139 to \fBgss_release_oid_set\fR(3GSS). Specify \fBNULL\fR if this parameter is not
140 required.
141 .RE
143 .sp
144 .ne 2
145 .na
146 \fB\fIinitiator_time_rec\fR\fR
147 .ad
148 .RS 22n
149 Actual number of seconds for which the returned credentials remain valid for
150 initiating contexts using the specified mechanism. If a mechanism does not
151 support expiration of credentials, the value \fBGSS_C_INDEFINITE\fR is
152 returned. Specify \fBNULL\fR if this parameter is not required.
153 .RE
155 .sp
156 .ne 2
157 .na
158 \fB\fIacceptor_time_rec\fR\fR
159 .ad
160 .RS 22n
161 Actual number of seconds for which the returned credentials remain valid for
162 accepting security contexts using the specified mechanism. If a mechanism does
163 not support expiration of credentials, the value \fBGSS_C_INDEFINITE\fR is
164 returned. Specify \fBNULL\fR if this parameter is not required.
165 .RE
167 .SH DESCRIPTION
168 .sp
169 .LP
170 The \fBgss_add_cred()\fR function adds a credential-element to a credential.
171 The credential-element is identified by the name of the principal to which it
172 refers. This function is not intended as a function to login to the network. A
173 function for login to the network would involve creating new mechanism-specific
174 authentication data, rather than acquiring a handle to existing data.
175 .sp
176 .LP
177 If the value of \fIdesired_name\fR is \fBGSS_C_NO_NAME\fR, the call is
178 interpreted as a request to add a credential-element to invoke default behavior
179 when passed to \fBgss_init_sec_context\fR(3GSS) if the value of
180 \fIcred_usage\fR is \fBGSS_C_INITIATE\fR or \fBGSS_C_BOTH\fR. The call is also
181 interpreted as a request to add a credential-element to the invoke default
182 behavior when passed to \fBgss_accept_sec_context\fR(3GSS) if the value of
183 \fIcred_usage\fR is \fBGSS_C_ACCEPT\fR or \fBGSS_C_BOTH\fR.
184 .sp
185 .LP
186 The \fBgss_add_cred()\fR function is expected to be used primarily by context
187 acceptors. The \fBGSS-API\fR provides mechanism-specific ways to obtain
188 \fBGSS-API\fR initiator credentials through the system login process.
189 Consequently, the \fBGSS-API\fR does not support acquiring \fBGSS_C_INITIATE\fR
190 or \fBGSS_C_BOTH\fR credentials by means of \fBgss_acquire_cred\fR(3GSS) for
191 any name other than the following:
192 .RS +4
193 .TP
194 .ie t \(bu
195 .el o
196 \fBGSS_C_NO_NAME\fR
197 .RE
198 .RS +4
199 .TP
200 .ie t \(bu
201 .el o
202 Name produced by \fBgss_inquire_cred\fR(3GSS) applied to a valid credential
203 .RE
204 .RS +4
205 .TP
206 .ie t \(bu
207 .el o
208 Name produced by \fBgss_inquire_context\fR(3GSS) applied to an active context
209 .RE
210 .sp
211 .LP
212 If credential acquisition is time consuming for a mechanism, the mechanism can
213 choose to delay the actual acquisition until the credential is required by
214 \fBgss_init_sec_context\fR(3GSS), for example, or by
215 \fBgss_accept_sec_context\fR(3GSS). Such mechanism-specific implementation
216 decisions are invisible to the calling application. A call to
217 \fBgss_inquire_cred\fR(3GSS) immediately following the call
218 \fBgss_add_cred()\fR returns valid credential data as well as incurring the
219 overhead of deferred credential acquisition.
220 .sp
221 .LP
222 The \fBgss_add_cred()\fR function can be used either to compose a new
223 credential that contains all credential-elements of the original in addition to
224 the newly-acquired credential-element. The function can also be used to add the
225 new credential-element to an existing credential. If the value of the
226 \fIoutput_cred_handle\fR parameter is \fBNULL\fR, the new credential-element is
227 added to the credential identified by \fIinput_cred_handle\fR. If a valid
228 pointer is specified for the \fIoutput_cred_handle\fR parameter, a new
229 credential handle is created.
230 .sp
231 .LP
232 If the value of \fIinput_cred_handle\fR is \fBGSS_C_NO_CREDENTIAL\fR, the
233 \fBgss_add_cred()\fR function composes a credential and sets the
234 \fIoutput_cred_handle\fR parameter based on the default behavior. The call has
235 the same effect as a call first made by the application to
236 \fBgss_acquire_cred\fR(3GSS) to specify the same usage and to pass
237 \fBGSS_C_NO_NAME\fR as the \fIdesired_name\fR parameter. Such an application
238 call obtains an explicit credential handle that incorporates the default
239 behaviors, then passes the credential handle to \fBgss_add_cred()\fR, and
240 finally calls \fBgss_release_cred\fR(3GSS) on the first credential handle.
241 .sp
242 .LP
243 If the value of the \fIinput_cred_handle\fR parameter is
244 \fBGSS_C_NO_CREDENTIAL\fR, a non-\fBNULL\fR value must be supplied for the
245 \fIoutput_cred_handle\fR parameter.
246 .SH RETURN VALUES
247 .sp
248 .LP
249 The \fBgss_add_cred()\fR function can return the following status codes:
250 .sp
251 .ne 2
252 .na
253 \fB\fBGSS_S_COMPLETE\fR\fR
254 .ad
255 .RS 29n
256 Successful completion.
257 .RE
259 .sp
260 .ne 2
261 .na
262 \fB\fBGSS_S_BAD_MECH\fR\fR
263 .ad
264 .RS 29n
265 An unavailable mechanism has been requested.
266 .RE
268 .sp
269 .ne 2
270 .na
271 \fB\fBGSS_S_BAD_NAMETYPE\fR\fR
272 .ad
273 .RS 29n
274 The type contained within the \fIdesired_name\fR parameter is not supported.
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fBGSS_S_BAD_NAME\fR\fR
281 .ad
282 .RS 29n
283 The value supplied for \fIdesired_name\fR parameter is ill formed.
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB\fBGSS_S_DUPLICATE_ELEMENT\fR\fR
290 .ad
291 .RS 29n
292 The credential already contains an element for the requested mechanism that has
293 overlapping usage and validity period.
294 .RE
296 .sp
297 .ne 2
298 .na
299 \fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR
300 .ad
301 .RS 29n
302 The credentials could not be added because they have expired.
303 .RE
305 .sp
306 .ne 2
307 .na
308 \fB\fBGSS_S_NO_CRED\fR\fR
309 .ad
310 .RS 29n
311 No credentials were found for the specified name.
312 .RE
314 .sp
315 .ne 2
316 .na
317 \fB\fBGSS_S_FAILURE\fR\fR
318 .ad
319 .RS 29n
320 The underlying mechanism detected an error for which no specific \fBGSS\fR
321 status code is defined. The mechanism-specific status code reported by means of
322 the \fIminor_status\fR parameter details the error condition.
323 .RE
325 .SH ATTRIBUTES
326 .sp
327 .LP
328 See \fBattributes\fR(5) for descriptions of the following attributes:
329 .sp
331 .sp
332 .TS
333 box;
334 c | c
335 l | l .
336 ATTRIBUTE TYPE ATTRIBUTE VALUE
337 _
338 MT-Level Safe
339 .TE
341 .SH SEE ALSO
342 .sp
343 .LP
344 \fBgss_accept_sec_context\fR(3GSS), \fBgss_acquire_cred\fR(3GSS),
345 \fBgss_init_sec_context\fR(3GSS), \fBgss_inquire_context\fR(3GSS),
346 \fBgss_inquire_cred\fR(3GSS), \fBgss_release_cred\fR(3GSS),
347 \fBgss_release_oid_set\fR(3GSS), \fBlibgss\fR(3LIB), \fBattributes\fR(5)
348 .sp
349 .LP
350 \fISolaris Security for Developers Guide\fR