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