|
1 '\" te |
|
2 .\" Copyright (c) 2009, 2015, Oracle and/or its affiliates. All rights reserved. |
|
3 .TH gss_init_sec_context 3GSS "6 Nov 2009" "SunOS 5.12" "Generic Security Services API Library Functions" |
|
4 .SH NAME |
|
5 gss_init_sec_context \- initiate a GSS-API security context with a peer application |
|
6 .SH SYNOPSIS |
|
7 .LP |
|
8 .nf |
|
9 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lgss\fR [ \fIlibrary\fR\&.\|.\|. ] |
|
10 #include <gssapi/gssapi.h> |
|
11 |
|
12 \fBOM_uint32\fR \fBgss_init_sec_context\fR(\fBOM_uint32 *\fR\fIminor_status\fR, |
|
13 \fBconst gss_cred_id_t\fR \fIinitiator_cred_handle\fR, |
|
14 \fBgss_ctx_id_t *\fR\fIcontext_handle\fR, \fBconst gss_name_t *\fR\fItarget_name\fR, |
|
15 \fBconst gss_OID\fR \fImech_type\fR, \fBOM_uint32\fR \fIreq_flags\fR, |
|
16 \fBOM_uint32\fR \fItime_req\fR, \fBconst gss_channel_bindings_t\fR \fIinput_chan_bindings\fR, |
|
17 \fBconst gss_buffer_t\fR \fIinput_token\fR, \fBgss_OID *\fR\fIactual_mech_type\fR, |
|
18 \fBgss_buffer_t\fR \fIoutput_token\fR, \fBOM_uint32 *\fR\fIret_flags\fR, |
|
19 \fBOM_uint32 *\fR\fItime_rec\fR); |
|
20 .fi |
|
21 |
|
22 .SH PARAMETERS |
|
23 .sp |
|
24 .LP |
|
25 The parameter descriptions for \fBgss_init_sec_context()\fR follow: |
|
26 .sp |
|
27 .ne 2 |
|
28 .mk |
|
29 .na |
|
30 \fB\fIminor_status\fR\fR |
|
31 .ad |
|
32 .sp .6 |
|
33 .RS 4n |
|
34 A mechanism specific status code. |
|
35 .RE |
|
36 |
|
37 .sp |
|
38 .ne 2 |
|
39 .mk |
|
40 .na |
|
41 \fB\fIinitiator_cred_handle\fR\fR |
|
42 .ad |
|
43 .sp .6 |
|
44 .RS 4n |
|
45 The handle for the credentials claimed. Supply \fBGSS_C_NO_CREDENTIAL\fR to act as a default initiator principal. If no default initiator is defined, the function returns \fBGSS_S_NO_CRED\fR. |
|
46 .RE |
|
47 |
|
48 .sp |
|
49 .ne 2 |
|
50 .mk |
|
51 .na |
|
52 \fB\fIcontext_handle\fR\fR |
|
53 .ad |
|
54 .sp .6 |
|
55 .RS 4n |
|
56 The context handle for a new context. Supply the value \fBGSS_C_NO_CONTEXT\fR for the first call, and use the value returned in any continuation calls. The resources associated with \fIcontext_handle\fR must be released by the application after use by a call to \fBgss_delete_sec_context\fR(3GSS). |
|
57 .RE |
|
58 |
|
59 .sp |
|
60 .ne 2 |
|
61 .mk |
|
62 .na |
|
63 \fB\fItarget_name\fR\fR |
|
64 .ad |
|
65 .sp .6 |
|
66 .RS 4n |
|
67 The name of the context acceptor. |
|
68 .RE |
|
69 |
|
70 .sp |
|
71 .ne 2 |
|
72 .mk |
|
73 .na |
|
74 \fB\fImech_type\fR\fR |
|
75 .ad |
|
76 .sp .6 |
|
77 .RS 4n |
|
78 The object \fBID\fR of the desired mechanism. To obtain a specific default, supply the value \fBGSS_C_NO_OID\fR. |
|
79 .RE |
|
80 |
|
81 .sp |
|
82 .ne 2 |
|
83 .mk |
|
84 .na |
|
85 \fB\fIreq_flags\fR\fR |
|
86 .ad |
|
87 .sp .6 |
|
88 .RS 4n |
|
89 Contains independent flags, each of which will request that the context support a specific service option. A symbolic name is provided for each flag. Logically-\fBOR\fR the symbolic name to the corresponding required flag to form the bit-mask value. \fIreq_flags\fR may contain one of the following values: |
|
90 .sp |
|
91 .ne 2 |
|
92 .mk |
|
93 .na |
|
94 \fB\fBGSS_C_DELEG_FLAG\fR\fR |
|
95 .ad |
|
96 .sp .6 |
|
97 .RS 4n |
|
98 If true, delegate credentials to a remote peer. Do not delegate the credentials if the value is false. |
|
99 .RE |
|
100 |
|
101 .sp |
|
102 .ne 2 |
|
103 .mk |
|
104 .na |
|
105 \fB\fBGSS_C_MUTUAL_FLAG\fR\fR |
|
106 .ad |
|
107 .sp .6 |
|
108 .RS 4n |
|
109 If true, request that the peer authenticate itself. If false, authenticate to the remote peer only. |
|
110 .RE |
|
111 |
|
112 .sp |
|
113 .ne 2 |
|
114 .mk |
|
115 .na |
|
116 \fB\fBGSS_C_REPLAY_FLAG\fR\fR |
|
117 .ad |
|
118 .sp .6 |
|
119 .RS 4n |
|
120 If true, enable replay detection for messages protected with \fBgss_wrap\fR(3GSS) or \fBgss_get_mic\fR(3GSS). Do not attempt to detect replayed messages if false. |
|
121 .RE |
|
122 |
|
123 .sp |
|
124 .ne 2 |
|
125 .mk |
|
126 .na |
|
127 \fB\fBGSS_C_SEQUENCE_FLAG\fR\fR |
|
128 .ad |
|
129 .sp .6 |
|
130 .RS 4n |
|
131 If true, enable detection of out-of-sequence protected messages. Do not attempt to detect out-of-sequence messages if false. |
|
132 .RE |
|
133 |
|
134 .sp |
|
135 .ne 2 |
|
136 .mk |
|
137 .na |
|
138 \fB\fBGSS_C_CONF_FLAG\fR\fR |
|
139 .ad |
|
140 .sp .6 |
|
141 .RS 4n |
|
142 If true, request that confidential service be made available by means of \fBgss_wrap\fR(3GSS). If false, no per-message confidential service is required. |
|
143 .RE |
|
144 |
|
145 .sp |
|
146 .ne 2 |
|
147 .mk |
|
148 .na |
|
149 \fB\fBGSS_C_INTEG_FLAG\fR\fR |
|
150 .ad |
|
151 .sp .6 |
|
152 .RS 4n |
|
153 If true, request that integrity service be made available by means of \fBgss_wrap\fR(3GSS) or \fBgss_get_mic\fR(3GSS). If false, no per-message integrity service is required. |
|
154 .RE |
|
155 |
|
156 .sp |
|
157 .ne 2 |
|
158 .mk |
|
159 .na |
|
160 \fB\fBGSS_C_ANON_FLAG\fR\fR |
|
161 .ad |
|
162 .sp .6 |
|
163 .RS 4n |
|
164 If true, do not reveal the initiator's identify to the acceptor. If false, authenticate normally. |
|
165 .RE |
|
166 |
|
167 .RE |
|
168 |
|
169 .sp |
|
170 .ne 2 |
|
171 .mk |
|
172 .na |
|
173 \fB\fItime_req\fR\fR |
|
174 .ad |
|
175 .sp .6 |
|
176 .RS 4n |
|
177 The number of seconds for which the context will remain valid. Supply a zero value to \fItime_req\fR to request a default validity period. |
|
178 .RE |
|
179 |
|
180 .sp |
|
181 .ne 2 |
|
182 .mk |
|
183 .na |
|
184 \fB\fIinput_chan_bindings\fR\fR |
|
185 .ad |
|
186 .sp .6 |
|
187 .RS 4n |
|
188 Optional application-specified bindings. Allows application to securely bind channel identification information to the security context. Set to \fBGSS_C_NO_CHANNEL_BINDINGS\fR if you do not want to use channel bindings. |
|
189 .RE |
|
190 |
|
191 .sp |
|
192 .ne 2 |
|
193 .mk |
|
194 .na |
|
195 \fB\fIinput_token\fR\fR |
|
196 .ad |
|
197 .sp .6 |
|
198 .RS 4n |
|
199 Token received from the peer application. On the initial call, supply \fBGSS_C_NO_BUFFER\fR or a pointer to a buffer containing the value \fBGSS_C_EMPTY_BUFFER\fR. |
|
200 .RE |
|
201 |
|
202 .sp |
|
203 .ne 2 |
|
204 .mk |
|
205 .na |
|
206 \fB\fIactual_mech_type\fR\fR |
|
207 .ad |
|
208 .sp .6 |
|
209 .RS 4n |
|
210 The actual mechanism used. The \fBOID\fR returned by means of this parameter will be pointer to static storage that should be treated as read-only. The application should not attempt to free it. To obtain a specific default, supply the value \fBGSS_C_NO_OID\fR. Specify \fBNULL\fR if the parameter is not required. |
|
211 .RE |
|
212 |
|
213 .sp |
|
214 .ne 2 |
|
215 .mk |
|
216 .na |
|
217 \fB\fIoutput_token\fR\fR |
|
218 .ad |
|
219 .sp .6 |
|
220 .RS 4n |
|
221 The token to send to the peer application. If the length field of the returned buffer is zero, no token need be sent to the peer application. After use storage associated with this buffer must be freed by the application by a call to \fBgss_release_buffer\fR(3GSS). |
|
222 .RE |
|
223 |
|
224 .sp |
|
225 .ne 2 |
|
226 .mk |
|
227 .na |
|
228 \fB\fIret_flags\fR\fR |
|
229 .ad |
|
230 .sp .6 |
|
231 .RS 4n |
|
232 Contains various independent flags, each of which indicates that the context supports a specific service option. If not needed, specify \fBNULL\fR. Test the returned bit-mask \fIret_flags\fR value against its symbolic name to determine if the given option is supported by the context. \fIret_flags\fR may contain one of the following values: |
|
233 .sp |
|
234 .ne 2 |
|
235 .mk |
|
236 .na |
|
237 \fB\fBGSS_C_DELEG_FLAG\fR\fR |
|
238 .ad |
|
239 .sp .6 |
|
240 .RS 4n |
|
241 If true, credentials were delegated to the remote peer. If false, no credentials were delegated. |
|
242 .RE |
|
243 |
|
244 .sp |
|
245 .ne 2 |
|
246 .mk |
|
247 .na |
|
248 \fB\fBGSS_C_MUTUAL_FLAG\fR\fR |
|
249 .ad |
|
250 .sp .6 |
|
251 .RS 4n |
|
252 If true, the remote peer authenticated itself. If false, the remote peer did not authenticate itself. |
|
253 .RE |
|
254 |
|
255 .sp |
|
256 .ne 2 |
|
257 .mk |
|
258 .na |
|
259 \fB\fBGSS_C_REPLAY_FLAG\fR\fR |
|
260 .ad |
|
261 .sp .6 |
|
262 .RS 4n |
|
263 If true, replay of protected messages will be detected. If false, replayed messages will not be detected. |
|
264 .RE |
|
265 |
|
266 .sp |
|
267 .ne 2 |
|
268 .mk |
|
269 .na |
|
270 \fB\fBGSS_C_SEQUENCE_FLAG\fR\fR |
|
271 .ad |
|
272 .sp .6 |
|
273 .RS 4n |
|
274 If true, out of sequence protected messages will be detected. If false, they will not be detected. |
|
275 .RE |
|
276 |
|
277 .sp |
|
278 .ne 2 |
|
279 .mk |
|
280 .na |
|
281 \fB\fBGSS_C_CONF_FLAG\fR\fR |
|
282 .ad |
|
283 .sp .6 |
|
284 .RS 4n |
|
285 If true, confidential service may be invoked by calling the \fBgss_wrap()\fR routine. If false, no confidentiality service is available by means of \fBgss_wrap\fR(3GSS). \fBgss_wrap()\fR will provide message encapsulation, data-origin authentication and integrity services only. |
|
286 .RE |
|
287 |
|
288 .sp |
|
289 .ne 2 |
|
290 .mk |
|
291 .na |
|
292 \fB\fBGSS_C_INTEG_FLAG\fR\fR |
|
293 .ad |
|
294 .sp .6 |
|
295 .RS 4n |
|
296 If true, integrity service may be invoked by calling either the \fBgss_wrap\fR(3GSS) or \fBgss_get_mic\fR(3GSS) routine. If false, per-message integrity service is not available. |
|
297 .RE |
|
298 |
|
299 .sp |
|
300 .ne 2 |
|
301 .mk |
|
302 .na |
|
303 \fB\fBGSS_C_ANON_FLAG\fR\fR |
|
304 .ad |
|
305 .sp .6 |
|
306 .RS 4n |
|
307 If true, the initiator's identity has not been revealed; it will not be revealed if any emitted token is passed to the acceptor. If false, the initiator has been or will be authenticated normally. |
|
308 .RE |
|
309 |
|
310 .sp |
|
311 .ne 2 |
|
312 .mk |
|
313 .na |
|
314 \fB\fBGSS_C_PROT_READY_FLAG\fR\fR |
|
315 .ad |
|
316 .sp .6 |
|
317 .RS 4n |
|
318 If true, the protection services specified by the states of \fBGSS_C_CONF_FLAG\fR and \fBGSS_C_INTEG_FLAG\fR are available if the accompanying major status return value is either \fBGSS_S_COMPLETE\fR or \fBGSS_S_CONTINUE_NEEDED\fR. If false, the protection services are available only if the accompanying major status return value is \fBGSS_S_COMPLETE\fR. |
|
319 .RE |
|
320 |
|
321 .sp |
|
322 .ne 2 |
|
323 .mk |
|
324 .na |
|
325 \fB\fBGSS_C_TRANS_FLAG\fR\fR |
|
326 .ad |
|
327 .sp .6 |
|
328 .RS 4n |
|
329 If true, the resultant security context may be transferred to other processes by means of a call to \fBgss_export_sec_context\fR(3GSS). If false, the security context cannot be transferred. |
|
330 .RE |
|
331 |
|
332 .RE |
|
333 |
|
334 .sp |
|
335 .ne 2 |
|
336 .mk |
|
337 .na |
|
338 \fB\fItime_rec\fR\fR |
|
339 .ad |
|
340 .sp .6 |
|
341 .RS 4n |
|
342 The number of seconds for which the context will remain valid. Specify \fBNULL\fR if the parameter is not required. |
|
343 .RE |
|
344 |
|
345 .SH DESCRIPTION |
|
346 .sp |
|
347 .LP |
|
348 The \fBgss_init_sec_context()\fR function initiates the establishment of a security context between the application and a remote peer. Initially, the \fIinput_token\fR parameter should be specified either as \fBGSS_C_NO_BUFFER\fR, or as a pointer to a \fBgss_buffer_desc\fR object with a \fBlength\fR field that contains a zero value. The routine may return a \fIoutput_token\fR, which should be transferred to the peer application, which will present it to \fBgss_accept_sec_context\fR(3GSS). If no token need be sent, \fBgss_init_sec_context()\fR will indicate this by setting the \fBlength\fR field of the \fIoutput_token\fR argument to zero. To complete context establishment, one or more reply tokens may be required from the peer application; if so, \fBgss_init_sec_context()\fR will return a status code that contains the supplementary information bit \fBGSS_S_CONTINUE_NEEDED\fR. In this case, make another call to \fBgss_init_sec_context()\fR when the reply token is received from the peer application and pass the reply token to \fBgss_init_sec_context()\fR by means of the \fIinput_token\fR parameter. |
|
349 .sp |
|
350 .LP |
|
351 Construct portable applications to use the token length and return status to determine whether to send or wait for a token. |
|
352 .sp |
|
353 .LP |
|
354 Whenever the routine returns a major status that includes the value \fBGSS_S_CONTINUE_NEEDED\fR, the context is not fully established, and the following restrictions apply to the output parameters: |
|
355 .RS +4 |
|
356 .TP |
|
357 .ie t \(bu |
|
358 .el o |
|
359 The value returned by means of the \fItime_rec\fR parameter is undefined. Unless the accompanying \fIret_flags\fR parameter contains the bit \fBGSS_C_PROT_READY_FLAG\fR, which indicates that per-message services may be applied in advance of a successful completion status, the value returned by means of the \fIactual_mech_type\fR parameter is undefined until the routine returns a major status value of \fBGSS_S_COMPLETE\fR. |
|
360 .RE |
|
361 .RS +4 |
|
362 .TP |
|
363 .ie t \(bu |
|
364 .el o |
|
365 The values of the \fBGSS_C_DELEG_FLAG\fR, \fBGSS_C_MUTUAL_FLAG\fR, \fBGSS_C_REPLAY_FLAG\fR, \fBGSS_C_SEQUENCE_FLAG\fR, \fBGSS_C_CONF_FLAG\fR, \fBGSS_C_INTEG_FLAG\fR and \fBGSS_C_ANON_FLAG\fR bits returned by the \fIret_flags\fR parameter contain values that will be valid if context establishment succeeds. For example, if the application requests a service such as delegation or anonymous authentication by means of the \fIreq_flags\fR argument, and the service is unavailable from the underlying mechanism, \fBgss_init_sec_context()\fR generates a token that will not provide the service, and it indicate by means of the \fIret_flags\fR argument that the service will not be supported. The application may choose to abort context establishment by calling \fBgss_delete_sec_context\fR(3GSS) if it cannot continue without the service, or if the service was merely desired but not mandatory, it may transmit the token and continue context establishment. |
|
366 .RE |
|
367 .RS +4 |
|
368 .TP |
|
369 .ie t \(bu |
|
370 .el o |
|
371 The values of the \fBGSS_C_PROT_READY_FLAG\fR and \fBGSS_C_TRANS_FLAG\fR bits within \fIret_flags\fR indicate the actual state at the time \fBgss_init_sec_context()\fR returns, whether or not the context is fully established. |
|
372 .RE |
|
373 .RS +4 |
|
374 .TP |
|
375 .ie t \(bu |
|
376 .el o |
|
377 The \fBGSS-API\fR sets the \fBGSS_C_PROT_READY_FLAG\fR in the final \fIret_flags\fR returned to a caller, for example, when accompanied by a \fBGSS_S_COMPLETE\fR status code. However, applications should not rely on this behavior, as the flag was not defined in Version 1 of the \fBGSS-API\fR. Instead, applications should determine what per-message services are available after a successful context establishment according to the \fBGSS_C_INTEG_FLAG\fR and \fBGSS_C_CONF_FLAG\fR values. |
|
378 .RE |
|
379 .RS +4 |
|
380 .TP |
|
381 .ie t \(bu |
|
382 .el o |
|
383 All other bits within the \fIret_flags\fR argument are set to zero. |
|
384 .RE |
|
385 .sp |
|
386 .LP |
|
387 If the initial call of \fBgss_init_sec_context()\fR fails, the \fBGSS-API\fR does not create a context object; it leaves the value of the \fIcontext_handle\fR parameter set to \fBGSS_C_NO_CONTEXT\fR to indicate this. In the event of failure on a subsequent call, the \fBGSS-API\fR leaves the security context untouched for the application to delete using \fBgss_delete_sec_context\fR(3GSS). |
|
388 .sp |
|
389 .LP |
|
390 During context establishment, the informational status bits \fBGSS_S_OLD_TOKEN\fR and \fBGSS_S_DUPLICATE_TOKEN\fR indicate fatal errors, and \fBGSS-API\fR mechanisms should always return them in association with a status code of \fBGSS_S_FAILURE\fR. This pairing requirement was not part of Version 1 of the GSS-API specification, so applications that wish to run on Version 1 implementations must special-case these codes. |
|
391 .SH ERRORS |
|
392 .sp |
|
393 .LP |
|
394 \fBgss_init_sec_context()\fR may return the following status codes: |
|
395 .sp |
|
396 .ne 2 |
|
397 .mk |
|
398 .na |
|
399 \fB\fBGSS_S_COMPLETE\fR\fR |
|
400 .ad |
|
401 .sp .6 |
|
402 .RS 4n |
|
403 Successful completion. |
|
404 .RE |
|
405 |
|
406 .sp |
|
407 .ne 2 |
|
408 .mk |
|
409 .na |
|
410 \fB\fBGSS_S_CONTINUE_NEEDED\fR\fR |
|
411 .ad |
|
412 .sp .6 |
|
413 .RS 4n |
|
414 A token from the peer application is required to complete the context, and \fBgss_init_sec_context()\fR must be called again with that token. |
|
415 .RE |
|
416 |
|
417 .sp |
|
418 .ne 2 |
|
419 .mk |
|
420 .na |
|
421 \fB\fBGSS_S_DEFECTIVE_TOKEN\fR\fR |
|
422 .ad |
|
423 .sp .6 |
|
424 .RS 4n |
|
425 Consistency checks performed on the \fIinput_token\fR failed. |
|
426 .RE |
|
427 |
|
428 .sp |
|
429 .ne 2 |
|
430 .mk |
|
431 .na |
|
432 \fB\fBGSS_S_DEFECTIVE_CREDENTIAL\fR\fR |
|
433 .ad |
|
434 .sp .6 |
|
435 .RS 4n |
|
436 Consistency checks performed on the credential failed. |
|
437 .RE |
|
438 |
|
439 .sp |
|
440 .ne 2 |
|
441 .mk |
|
442 .na |
|
443 \fB\fBGSS_S_NO_CRED\fR\fR |
|
444 .ad |
|
445 .sp .6 |
|
446 .RS 4n |
|
447 The supplied credentials are not valid for context acceptance, or the credential handle does not reference any credentials. |
|
448 .RE |
|
449 |
|
450 .sp |
|
451 .ne 2 |
|
452 .mk |
|
453 .na |
|
454 \fB\fBGSS_S_CREDENTIALS_EXPIRED\fR\fR |
|
455 .ad |
|
456 .sp .6 |
|
457 .RS 4n |
|
458 The referenced credentials have expired. |
|
459 .RE |
|
460 |
|
461 .sp |
|
462 .ne 2 |
|
463 .mk |
|
464 .na |
|
465 \fB\fBGSS_S_BAD_BINDINGS\fR\fR |
|
466 .ad |
|
467 .sp .6 |
|
468 .RS 4n |
|
469 The \fIinput_token\fR contains different channel bindings than those specified by means of the \fIinput_chan_bindings\fR parameter. |
|
470 .RE |
|
471 |
|
472 .sp |
|
473 .ne 2 |
|
474 .mk |
|
475 .na |
|
476 \fB\fBGSS_S_BAD_SIG\fR\fR |
|
477 .ad |
|
478 .sp .6 |
|
479 .RS 4n |
|
480 The \fIinput_token\fR contains an invalid \fBMIC\fR or a \fBMIC\fR that cannot be verified. |
|
481 .RE |
|
482 |
|
483 .sp |
|
484 .ne 2 |
|
485 .mk |
|
486 .na |
|
487 \fB\fBGSS_S_OLD_TOKEN\fR\fR |
|
488 .ad |
|
489 .sp .6 |
|
490 .RS 4n |
|
491 The \fIinput_token\fR is too old. This is a fatal error while establishing context. |
|
492 .RE |
|
493 |
|
494 .sp |
|
495 .ne 2 |
|
496 .mk |
|
497 .na |
|
498 \fB\fBGSS_S_DUPLICATE_TOKEN\fR\fR |
|
499 .ad |
|
500 .sp .6 |
|
501 .RS 4n |
|
502 The \fIinput_token\fR is valid, but it is a duplicate of a token already processed. This is a fatal error while establishing context. |
|
503 .RE |
|
504 |
|
505 .sp |
|
506 .ne 2 |
|
507 .mk |
|
508 .na |
|
509 \fB\fBGSS_S_NO_CONTEXT\fR\fR |
|
510 .ad |
|
511 .sp .6 |
|
512 .RS 4n |
|
513 The supplied context handle does not refer to a valid context. |
|
514 .RE |
|
515 |
|
516 .sp |
|
517 .ne 2 |
|
518 .mk |
|
519 .na |
|
520 \fB\fBGSS_S_BAD_NAMETYPE\fR\fR |
|
521 .ad |
|
522 .sp .6 |
|
523 .RS 4n |
|
524 The provided \fItarget_name\fR parameter contains an invalid or unsupported \fIname\fR type. |
|
525 .RE |
|
526 |
|
527 .sp |
|
528 .ne 2 |
|
529 .mk |
|
530 .na |
|
531 \fB\fBGSS_S_BAD_NAME\fR\fR |
|
532 .ad |
|
533 .sp .6 |
|
534 .RS 4n |
|
535 The supplied \fItarget_name\fR parameter is ill-formed. |
|
536 .RE |
|
537 |
|
538 .sp |
|
539 .ne 2 |
|
540 .mk |
|
541 .na |
|
542 \fB\fBGSS_S_BAD_MECH\fR\fR |
|
543 .ad |
|
544 .sp .6 |
|
545 .RS 4n |
|
546 The token received specifies a mechanism that is not supported by the implementation or the provided credential. |
|
547 .RE |
|
548 |
|
549 .sp |
|
550 .ne 2 |
|
551 .mk |
|
552 .na |
|
553 \fB\fBGSS_S_FAILURE\fR\fR |
|
554 .ad |
|
555 .sp .6 |
|
556 .RS 4n |
|
557 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. |
|
558 .RE |
|
559 |
|
560 .SH EXAMPLES |
|
561 .LP |
|
562 \fBExample 1 \fRInvoking \fBgss_init_sec_context()\fR Within a Loop |
|
563 .sp |
|
564 .LP |
|
565 A typical portable caller should always invoke \fBgss_init_sec_context()\fR within a loop: |
|
566 |
|
567 .sp |
|
568 .in +2 |
|
569 .nf |
|
570 int context_established = 0; |
|
571 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; |
|
572 ... |
|
573 input_token->length = 0; |
|
574 |
|
575 while (!context_established) { |
|
576 maj_stat = gss_init_sec_context(&min_stat, |
|
577 cred_hdl, |
|
578 &context_hdl, |
|
579 target_name, |
|
580 desired_mech, |
|
581 desired_services, |
|
582 desired_time, |
|
583 input_bindings, |
|
584 input_token, |
|
585 &actual_mech, |
|
586 output_token, |
|
587 &actual_services, |
|
588 &actual_time); |
|
589 if (GSS_ERROR(maj_stat)) { |
|
590 report_error(maj_stat, min_stat); |
|
591 }; |
|
592 |
|
593 if (output_token->length != 0) { |
|
594 send_token_to_peer(output_token); |
|
595 gss_release_buffer(&min_stat, output_token) |
|
596 }; |
|
597 if (GSS_ERROR(maj_stat)) { |
|
598 |
|
599 if (context_hdl != GSS_C_NO_CONTEXT) |
|
600 gss_delete_sec_context(&min_stat, |
|
601 &context_hdl, |
|
602 GSS_C_NO_BUFFER); |
|
603 break; |
|
604 }; |
|
605 if (maj_stat & GSS_S_CONTINUE_NEEDED) { |
|
606 receive_token_from_peer(input_token); |
|
607 } else { |
|
608 context_established = 1; |
|
609 }; |
|
610 }; |
|
611 .fi |
|
612 .in -2 |
|
613 |
|
614 .SH ATTRIBUTES |
|
615 .sp |
|
616 .LP |
|
617 See \fBattributes\fR(5) for descriptions of the following attributes: |
|
618 .sp |
|
619 |
|
620 .sp |
|
621 .TS |
|
622 tab() box; |
|
623 cw(2.75i) |cw(2.75i) |
|
624 lw(2.75i) |lw(2.75i) |
|
625 . |
|
626 ATTRIBUTE TYPEATTRIBUTE VALUE |
|
627 _ |
|
628 MT-LevelSafe |
|
629 .TE |
|
630 |
|
631 .SH SEE ALSO |
|
632 .sp |
|
633 .LP |
|
634 \fBgss_delete_sec_context\fR(3GSS), \fBgss_export_sec_context\fR(3GSS), \fBgss_get_mic\fR(3GSS), \fBgss_wrap\fR(3GSS), \fBattributes\fR(5) |
|
635 .sp |
|
636 .LP |
|
637 |