3 .\" Copyright (c) 2005 Doug Rabson
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" The following commands are required for all man pages.
29 .Dt GSS_INIT_SEC_CONTEXT 3 PRM
32 .Nm gss_init_sec_context
33 .Nd Initiate a security context with a peer application
34 .\" This next command is for sections 2 and 3 only.
39 .Fo gss_init_sec_context
40 .Fa "OM_uint32 *minor_status"
41 .Fa "const gss_cred_id_t initiator_cred_handle"
42 .Fa "gss_ctx_id_t *context_handle"
43 .Fa "const gss_name_t target_name"
44 .Fa "const gss_OID mech_type"
45 .Fa "OM_uint32 req_flags"
46 .Fa "OM_uint32 time_req"
47 .Fa "const gss_channel_bindings_t input_chan_bindings"
48 .Fa "const gss_buffer_t input_token"
49 .Fa "gss_OID *actual_mech_type"
50 .Fa "gss_buffer_t output_token"
51 .Fa "OM_uint32 *ret_flags"
52 .Fa "OM_uint32 *time_rec"
55 Initiates the establishment of a security context between the
56 application and a remote peer.
57 Initially, the input_token parameter should be specified either as
58 .Dv GSS_C_NO_BUFFER, or as a pointer to a
59 gss_buffer_desc object whose length field contains the value zero.
60 The routine may return a output_token which should be transferred to
61 the peer application, where the peer application will present it to
62 .Xr gss_accept_sec_context 3 . If no token need be sent,
63 .Fn gss_init_sec_context
64 will indicate this by setting the
66 of the output_token argument to zero. To complete the context
67 establishment, one or more reply tokens may be required from the peer
69 .Fn gss_init_sec_context
71 containing the supplementary information bit
72 .Dv GSS_S_CONTINUE_NEEDED.
74 .Fn gss_init_sec_context
75 should be called again when the reply token is received from the peer
76 application, passing the reply token to
77 .Fn gss_init_sec_context
78 via the input_token parameters.
80 Portable applications should be constructed to use the token length
81 and return status to determine whether a token needs to be sent or
82 waited for. Thus a typical portable caller should always invoke
83 .Fn gss_init_sec_context
86 int context_established = 0;
87 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
89 input_token->length = 0;
91 while (!context_established) {
92 maj_stat = gss_init_sec_context(&min_stat,
105 if (GSS_ERROR(maj_stat)) {
106 report_error(maj_stat, min_stat);
109 if (output_token->length != 0) {
110 send_token_to_peer(output_token);
111 gss_release_buffer(&min_stat, output_token)
113 if (GSS_ERROR(maj_stat)) {
115 if (context_hdl != GSS_C_NO_CONTEXT)
116 gss_delete_sec_context(&min_stat,
122 if (maj_stat & GSS_S_CONTINUE_NEEDED) {
123 receive_token_from_peer(input_token);
125 context_established = 1;
130 Whenever the routine returns a major status that includes the value
131 .Dv GSS_S_CONTINUE_NEEDED, the context is not fully established and the
132 following restrictions apply to the output parameters:
135 The value returned via the
137 parameter is undefined Unless
140 parameter contains the bit
141 .Dv GSS_C_PROT_READY_FLAG, indicating that per-message services may be
142 applied in advance of a successful completion status, the value
145 parameter is undefined until the
146 routine returns a major status value of
150 .Dv GSS_C_DELEG_FLAG ,
151 .Dv GSS_C_MUTUAL_FLAG ,
152 .Dv GSS_C_REPLAY_FLAG ,
153 .Dv GSS_C_SEQUENCE_FLAG ,
154 .Dv GSS_C_CONF_FLAG ,
155 .Dv GSS_C_INTEG_FLAG and
156 .Dv GSS_C_ANON_FLAG bits returned via the
158 parameter should contain the values that the
159 implementation expects would be valid if context establishment
160 were to succeed. In particular, if the application has requested
161 a service such as delegation or anonymous authentication via the
163 argument, and such a service is unavailable from the
164 underlying mechanism,
165 .Fn gss_init_sec_context
166 should generate a token
167 that will not provide the service, and indicate via the
169 argument that the service will not be supported. The application
170 may choose to abort the context establishment by calling
171 .Xr gss_delete_sec_context 3
172 (if it cannot continue in the absence of
173 the service), or it may choose to transmit the token and continue
174 context establishment (if the service was merely desired but not
178 .Dv GSS_C_PROT_READY_FLAG and
179 .Dv GSS_C_TRANS_FLAG bits
182 should indicate the actual state at the time
183 .Fn gss_init_sec_context
184 returns, whether or not the context is fully established.
186 GSS-API implementations that support per-message protection are
187 encouraged to set the
188 .Dv GSS_C_PROT_READY_FLAG in the final
190 returned to a caller (i.e. when accompanied by a
192 status code). However, applications should not rely on this
193 behavior as the flag was not defined in Version 1 of the GSS-API.
194 Instead, applications should determine what per-message services
195 are available after a successful context establishment according
197 .Dv GSS_C_INTEG_FLAG and
198 .Dv GSS_C_CONF_FLAG values.
200 All other bits within the
202 argument should be set to
206 If the initial call of
207 .Fn gss_init_sec_context
209 implementation should not create a context object, and should leave
213 .Dv GSS_C_NO_CONTEXT to
214 indicate this. In the event of a failure on a subsequent call, the
215 implementation is permitted to delete the "half-built" security
216 context (in which case it should set the
219 .Dv GSS_C_NO_CONTEXT ), but the preferred behavior is to leave the
220 security context untouched for the application to delete (using
221 .Xr gss_delete_sec_context 3 ).
223 During context establishment, the informational status bits
224 .Dv GSS_S_OLD_TOKEN and
225 .Dv GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
226 GSS-API mechanisms should always return them in association with a
229 This requirement for pairing did not
230 exist in version 1 of the GSS-API specification, so applications that
231 wish to run over version 1 implementations must special-case these
234 .Bl -tag -width ".It initiator_cred_handle"
236 Mechanism specific status code.
237 .It initiator_cred_handle
238 handle for credentials claimed. Supply
239 .Dv GSS_C_NO_CREDENTIAL to act as a default
240 initiator principal. If no default
241 initiator is defined, the function will
245 context handle for new context. Supply
246 .Dv GSS_C_NO_CONTEXT for first call; use value
247 returned by first call in continuation calls.
248 Resources associated with this context-handle
249 must be released by the application after use
251 .Fn gss_delete_sec_context .
255 Object ID of desired mechanism. Supply
256 .Dv GSS_C_NO_OID to obtain an implementation
259 Contains various independent flags, each of
260 which requests that the context support a
261 specific service option. Symbolic
262 names are provided for each flag, and the
263 symbolic names corresponding to the required
264 flags should be logically-ORed
265 together to form the bit-mask value. The
269 .Bl -tag -width "False"
271 Delegate credentials to remote peer
275 .It GSS_C_MUTUAL_FLAG
276 .Bl -tag -width "False"
278 Request that remote peer authenticate itself
280 Authenticate self to remote peer only
282 .It GSS_C_REPLAY_FLAG
283 .Bl -tag -width "False"
285 Enable replay detection for messages protected with
290 Don't attempt to detect replayed messages
292 .It GSS_C_SEQUENCE_FLAG
293 .Bl -tag -width "False"
295 Enable detection of out-of-sequence protected messages
297 Don't attempt to detect out-of-sequence messages
300 .Bl -tag -width "False"
302 Request that confidentiality service be made available (via
305 No per-message confidentiality service is required.
308 .Bl -tag -width "False"
310 Request that integrity service be made available (via
315 No per-message integrity service is required.
318 .Bl -tag -width "False"
320 Do not reveal the initiator's identity to the acceptor.
322 Authenticate normally.
326 Desired number of seconds for which context
327 should remain valid. Supply 0 to request a
328 default validity period.
329 .It input_chan_bindings
330 Application-specified bindings. Allows
331 application to securely bind channel
332 identification information to the security
334 .Dv GSS_C_NO_CHANNEL_BINDINGS
335 if channel bindings are not used.
337 Token received from peer application.
339 .Dv GSS_C_NO_BUFFER, or a pointer to
340 a buffer containing the value
341 .Dv GSS_C_EMPTY_BUFFER
344 Actual mechanism used. The OID returned via
345 this parameter will be a pointer to static
346 storage that should be treated as read-only;
347 In particular the application should not attempt
349 .Dv NULL if not required.
351 token to be sent to peer application. If
352 the length field of the returned buffer is
353 zero, no token need be sent to the peer
354 application. Storage associated with this
355 buffer must be freed by the application
356 after use with a call to
357 .Xr gss_release_buffer 3 .
359 Contains various independent flags, each of which
360 indicates that the context supports a specific
361 service option. Specify
363 required. Symbolic names are provided
364 for each flag, and the symbolic names
365 corresponding to the required flags should be
366 logically-ANDed with the
369 whether a given option is supported by the
370 context. The flags are:
373 .Bl -tag -width "False"
375 Credentials were delegated to the remote peer
377 No credentials were delegated
379 .It GSS_C_MUTUAL_FLAG
380 .Bl -tag -width "False"
382 The remote peer has authenticated itself.
384 Remote peer has not authenticated itself.
386 .It GSS_C_REPLAY_FLAG
387 .Bl -tag -width "False"
389 Replay of protected messages will be detected
391 Replayed messages will not be detected
393 .It GSS_C_SEQUENCE_FLAG
394 .Bl -tag -width "False"
396 Out-of-sequence protected messages will be detected
398 Out-of-sequence messages will not be detected
401 .Bl -tag -width "False"
403 Confidentiality service may be invoked by calling
407 No confidentiality service (via
408 .Xr gss_wrap 3 ) available.
410 provide message encapsulation,
411 data-origin authentication and
412 integrity services only.
415 .Bl -tag -width "False"
417 Integrity service may be invoked by calling either
423 Per-message integrity service unavailable.
426 .Bl -tag -width "False"
428 The initiator's identity has not been
429 revealed, and will not be revealed if
430 any emitted token is passed to the
433 The initiator's identity has been or will be authenticated normally.
435 .It GSS_C_PROT_READY_FLAG
436 .Bl -tag -width "False"
438 Protection services (as specified by the states of the
441 .Dv GSS_C_INTEG_FLAG ) are available for
442 use if the accompanying major status
443 return value is either
446 .Dv GSS_S_CONTINUE_NEEDED.
448 Protection services (as specified by the states of the
451 .Dv GSS_C_INTEG_FLAG ) are available
452 only if the accompanying major status
457 .Bl -tag -width "False"
459 The resultant security context may be transferred to other processes via
461 .Fn gss_export_sec_context .
463 The security context is not transferable.
467 All other bits should be set to zero.
469 Number of seconds for which the context
470 will remain valid. If the implementation does
471 not support context expiration, the value
472 .Dv GSS_C_INDEFINITE will be returned. Specify
473 .Dv NULL if not required.
476 .Bl -tag -width ".It GSS_S_CREDENTIALS_EXPIRED"
478 Successful completion
479 .It GSS_S_CONTINUE_NEEDED
480 Indicates that a token from the peer
481 application is required to complete the
482 context, and that gss_init_sec_context
483 must be called again with that token.
484 .It GSS_S_DEFECTIVE_TOKEN
485 Indicates that consistency checks performed
486 on the input_token failed
487 .It GSS_S_DEFECTIVE_CREDENTIAL
488 Indicates that consistency checks
489 performed on the credential failed.
491 The supplied credentials were not valid for
492 context initiation, or the credential handle
493 did not reference any credentials.
494 .It GSS_S_CREDENTIALS_EXPIRED
495 The referenced credentials have expired
496 .It GSS_S_BAD_BINDINGS
497 The input_token contains different channel
498 bindings to those specified via the
499 input_chan_bindings parameter
501 The input_token contains an invalid MIC, or a MIC
502 that could not be verified
504 The input_token was too old. This is a fatal
505 error during context establishment
506 .It GSS_S_DUPLICATE_TOKEN
507 The input_token is valid, but is a duplicate
508 of a token already processed. This is a
509 fatal error during context establishment.
511 Indicates that the supplied context handle did
512 not refer to a valid context
513 .It GSS_S_BAD_NAMETYPE
514 The provided target_name parameter contained an
515 invalid or unsupported type of name
517 The provided target_name parameter was ill-formed.
519 The specified mechanism is not supported by the
520 provided credential, or is unrecognized by the
524 .Xr gss_accept_sec_context 3 ,
525 .Xr gss_delete_sec_context 3 ,
527 .Xr gss_release_buffer 3 ,
530 .Bl -tag -width ".It RFC 2743"
532 Generic Security Service Application Program Interface Version 2, Update 1
534 Generic Security Service API Version 2 : C-bindings
539 function first appeared in
542 John Wray, Iris Associates
544 Copyright (C) The Internet Society (2000). All Rights Reserved.
546 This document and translations of it may be copied and furnished to
547 others, and derivative works that comment on or otherwise explain it
548 or assist in its implementation may be prepared, copied, published
549 and distributed, in whole or in part, without restriction of any
550 kind, provided that the above copyright notice and this paragraph are
551 included on all such copies and derivative works. However, this
552 document itself may not be modified in any way, such as by removing
553 the copyright notice or references to the Internet Society or other
554 Internet organizations, except as needed for the purpose of
555 developing Internet standards in which case the procedures for
556 copyrights defined in the Internet Standards process must be
557 followed, or as required to translate it into languages other than
560 The limited permissions granted above are perpetual and will not be
561 revoked by the Internet Society or its successors or assigns.
563 This document and the information contained herein is provided on an
564 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
565 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
566 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
567 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
568 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.