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
29 .\" The following commands are required for all man pages.
31 .Dt GSS_INIT_SEC_CONTEXT 3 PRM
34 .Nm gss_init_sec_context
35 .Nd Initiate a security context with a peer application
36 .\" This next command is for sections 2 and 3 only.
41 .Fo gss_init_sec_context
42 .Fa "OM_uint32 *minor_status"
43 .Fa "const gss_cred_id_t initiator_cred_handle"
44 .Fa "gss_ctx_id_t *context_handle"
45 .Fa "const gss_name_t target_name"
46 .Fa "const gss_OID mech_type"
47 .Fa "OM_uint32 req_flags"
48 .Fa "OM_uint32 time_req"
49 .Fa "const gss_channel_bindings_t input_chan_bindings"
50 .Fa "const gss_buffer_t input_token"
51 .Fa "gss_OID *actual_mech_type"
52 .Fa "gss_buffer_t output_token"
53 .Fa "OM_uint32 *ret_flags"
54 .Fa "OM_uint32 *time_rec"
57 Initiates the establishment of a security context between the
58 application and a remote peer.
59 Initially, the input_token parameter should be specified either as
60 .Dv GSS_C_NO_BUFFER, or as a pointer to a
61 gss_buffer_desc object whose length field contains the value zero.
62 The routine may return a output_token which should be transferred to
63 the peer application, where the peer application will present it to
64 .Xr gss_accept_sec_context 3 . If no token need be sent,
65 .Fn gss_init_sec_context
66 will indicate this by setting the
68 of the output_token argument to zero. To complete the context
69 establishment, one or more reply tokens may be required from the peer
71 .Fn gss_init_sec_context
73 containing the supplementary information bit
74 .Dv GSS_S_CONTINUE_NEEDED.
76 .Fn gss_init_sec_context
77 should be called again when the reply token is received from the peer
78 application, passing the reply token to
79 .Fn gss_init_sec_context
80 via the input_token parameters.
82 Portable applications should be constructed to use the token length
83 and return status to determine whether a token needs to be sent or
84 waited for. Thus a typical portable caller should always invoke
85 .Fn gss_init_sec_context
88 int context_established = 0;
89 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
91 input_token->length = 0;
93 while (!context_established) {
94 maj_stat = gss_init_sec_context(&min_stat,
107 if (GSS_ERROR(maj_stat)) {
108 report_error(maj_stat, min_stat);
111 if (output_token->length != 0) {
112 send_token_to_peer(output_token);
113 gss_release_buffer(&min_stat, output_token)
115 if (GSS_ERROR(maj_stat)) {
117 if (context_hdl != GSS_C_NO_CONTEXT)
118 gss_delete_sec_context(&min_stat,
124 if (maj_stat & GSS_S_CONTINUE_NEEDED) {
125 receive_token_from_peer(input_token);
127 context_established = 1;
132 Whenever the routine returns a major status that includes the value
133 .Dv GSS_S_CONTINUE_NEEDED, the context is not fully established and the
134 following restrictions apply to the output parameters:
137 The value returned via the
139 parameter is undefined Unless
142 parameter contains the bit
143 .Dv GSS_C_PROT_READY_FLAG, indicating that per-message services may be
144 applied in advance of a successful completion status, the value
147 parameter is undefined until the
148 routine returns a major status value of
152 .Dv GSS_C_DELEG_FLAG ,
153 .Dv GSS_C_MUTUAL_FLAG ,
154 .Dv GSS_C_REPLAY_FLAG ,
155 .Dv GSS_C_SEQUENCE_FLAG ,
156 .Dv GSS_C_CONF_FLAG ,
157 .Dv GSS_C_INTEG_FLAG and
158 .Dv GSS_C_ANON_FLAG bits returned via the
160 parameter should contain the values that the
161 implementation expects would be valid if context establishment
162 were to succeed. In particular, if the application has requested
163 a service such as delegation or anonymous authentication via the
165 argument, and such a service is unavailable from the
166 underlying mechanism,
167 .Fn gss_init_sec_context
168 should generate a token
169 that will not provide the service, and indicate via the
171 argument that the service will not be supported. The application
172 may choose to abort the context establishment by calling
173 .Xr gss_delete_sec_context 3
174 (if it cannot continue in the absence of
175 the service), or it may choose to transmit the token and continue
176 context establishment (if the service was merely desired but not
180 .Dv GSS_C_PROT_READY_FLAG and
181 .Dv GSS_C_TRANS_FLAG bits
184 should indicate the actual state at the time
185 .Fn gss_init_sec_context
186 returns, whether or not the context is fully established.
188 GSS-API implementations that support per-message protection are
189 encouraged to set the
190 .Dv GSS_C_PROT_READY_FLAG in the final
192 returned to a caller (i.e. when accompanied by a
194 status code). However, applications should not rely on this
195 behavior as the flag was not defined in Version 1 of the GSS-API.
196 Instead, applications should determine what per-message services
197 are available after a successful context establishment according
199 .Dv GSS_C_INTEG_FLAG and
200 .Dv GSS_C_CONF_FLAG values.
202 All other bits within the
204 argument should be set to
208 If the initial call of
209 .Fn gss_init_sec_context
211 implementation should not create a context object, and should leave
215 .Dv GSS_C_NO_CONTEXT to
216 indicate this. In the event of a failure on a subsequent call, the
217 implementation is permitted to delete the "half-built" security
218 context (in which case it should set the
221 .Dv GSS_C_NO_CONTEXT ), but the preferred behavior is to leave the
222 security context untouched for the application to delete (using
223 .Xr gss_delete_sec_context 3 ).
225 During context establishment, the informational status bits
226 .Dv GSS_S_OLD_TOKEN and
227 .Dv GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
228 GSS-API mechanisms should always return them in association with a
231 This requirement for pairing did not
232 exist in version 1 of the GSS-API specification, so applications that
233 wish to run over version 1 implementations must special-case these
238 Mechanism specific status code.
239 .It initiator_cred_handle
240 handle for credentials claimed. Supply
241 .Dv GSS_C_NO_CREDENTIAL to act as a default
242 initiator principal. If no default
243 initiator is defined, the function will
247 context handle for new context. Supply
248 .Dv GSS_C_NO_CONTEXT for first call; use value
249 returned by first call in continuation calls.
250 Resources associated with this context-handle
251 must be released by the application after use
253 .Fn gss_delete_sec_context .
257 Object ID of desired mechanism. Supply
258 .Dv GSS_C_NO_OID to obtain an implementation
261 Contains various independent flags, each of
262 which requests that the context support a
263 specific service option. Symbolic
264 names are provided for each flag, and the
265 symbolic names corresponding to the required
266 flags should be logically-ORed
267 together to form the bit-mask value. The
271 .Bl -tag -width "False"
273 Delegate credentials to remote peer
277 .It GSS_C_MUTUAL_FLAG
278 .Bl -tag -width "False"
280 Request that remote peer authenticate itself
282 Authenticate self to remote peer only
284 .It GSS_C_REPLAY_FLAG
285 .Bl -tag -width "False"
287 Enable replay detection for messages protected with
292 Don't attempt to detect replayed messages
294 .It GSS_C_SEQUENCE_FLAG
295 .Bl -tag -width "False"
297 Enable detection of out-of-sequence protected messages
299 Don't attempt to detect out-of-sequence messages
302 .Bl -tag -width "False"
304 Request that confidentiality service be made available (via
307 No per-message confidentiality service is required.
310 .Bl -tag -width "False"
312 Request that integrity service be made available (via
317 No per-message integrity service is required.
320 .Bl -tag -width "False"
322 Do not reveal the initiator's identity to the acceptor.
324 Authenticate normally.
328 Desired number of seconds for which context
329 should remain valid. Supply 0 to request a
330 default validity period.
331 .It input_chan_bindings
332 Application-specified bindings. Allows
333 application to securely bind channel
334 identification information to the security
336 .Dv GSS_C_NO_CHANNEL_BINDINGS
337 if channel bindings are not used.
339 Token received from peer application.
341 .Dv GSS_C_NO_BUFFER, or a pointer to
342 a buffer containing the value
343 .Dv GSS_C_EMPTY_BUFFER
346 Actual mechanism used. The OID returned via
347 this parameter will be a pointer to static
348 storage that should be treated as read-only;
349 In particular the application should not attempt
351 .Dv NULL if not required.
353 token to be sent to peer application. If
354 the length field of the returned buffer is
355 zero, no token need be sent to the peer
356 application. Storage associated with this
357 buffer must be freed by the application
358 after use with a call to
359 .Xr gss_release_buffer 3 .
361 Contains various independent flags, each of which
362 indicates that the context supports a specific
363 service option. Specify
365 required. Symbolic names are provided
366 for each flag, and the symbolic names
367 corresponding to the required flags should be
368 logically-ANDed with the
371 whether a given option is supported by the
372 context. The flags are:
375 .Bl -tag -width "False"
377 Credentials were delegated to the remote peer
379 No credentials were delegated
381 .It GSS_C_MUTUAL_FLAG
382 .Bl -tag -width "False"
384 The remote peer has authenticated itself.
386 Remote peer has not authenticated itself.
388 .It GSS_C_REPLAY_FLAG
389 .Bl -tag -width "False"
391 Replay of protected messages will be detected
393 Replayed messages will not be detected
395 .It GSS_C_SEQUENCE_FLAG
396 .Bl -tag -width "False"
398 Out-of-sequence protected messages will be detected
400 Out-of-sequence messages will not be detected
403 .Bl -tag -width "False"
405 Confidentiality service may be invoked by calling
409 No confidentiality service (via
410 .Xr gss_wrap 3 ) available.
412 provide message encapsulation,
413 data-origin authentication and
414 integrity services only.
417 .Bl -tag -width "False"
419 Integrity service may be invoked by calling either
425 Per-message integrity service unavailable.
428 .Bl -tag -width "False"
430 The initiator's identity has not been
431 revealed, and will not be revealed if
432 any emitted token is passed to the
435 The initiator's identity has been or will be authenticated normally.
437 .It GSS_C_PROT_READY_FLAG
438 .Bl -tag -width "False"
440 Protection services (as specified by the states of the
443 .Dv GSS_C_INTEG_FLAG ) are available for
444 use if the accompanying major status
445 return value is either
448 .Dv GSS_S_CONTINUE_NEEDED.
450 Protection services (as specified by the states of the
453 .Dv GSS_C_INTEG_FLAG ) are available
454 only if the accompanying major status
459 .Bl -tag -width "False"
461 The resultant security context may be transferred to other processes via
463 .Fn gss_export_sec_context .
465 The security context is not transferable.
469 All other bits should be set to zero.
471 Number of seconds for which the context
472 will remain valid. If the implementation does
473 not support context expiration, the value
474 .Dv GSS_C_INDEFINITE will be returned. Specify
475 .Dv NULL if not required.
480 Successful completion
481 .It GSS_S_CONTINUE_NEEDED
482 Indicates that a token from the peer
483 application is required to complete the
484 context, and that gss_init_sec_context
485 must be called again with that token.
486 .It GSS_S_DEFECTIVE_TOKEN
487 Indicates that consistency checks performed
488 on the input_token failed
489 .It GSS_S_DEFECTIVE_CREDENTIAL
490 Indicates that consistency checks
491 performed on the credential failed.
493 The supplied credentials were not valid for
494 context initiation, or the credential handle
495 did not reference any credentials.
496 .It GSS_S_CREDENTIALS_EXPIRED
497 The referenced credentials have expired
498 .It GSS_S_BAD_BINDINGS
499 The input_token contains different channel
500 bindings to those specified via the
501 input_chan_bindings parameter
503 The input_token contains an invalid MIC, or a MIC
504 that could not be verified
506 The input_token was too old. This is a fatal
507 error during context establishment
508 .It GSS_S_DUPLICATE_TOKEN
509 The input_token is valid, but is a duplicate
510 of a token already processed. This is a
511 fatal error during context establishment.
513 Indicates that the supplied context handle did
514 not refer to a valid context
515 .It GSS_S_BAD_NAMETYPE
516 The provided target_name parameter contained an
517 invalid or unsupported type of name
519 The provided target_name parameter was ill-formed.
521 The specified mechanism is not supported by the
522 provided credential, or is unrecognized by the
526 .Xr gss_accept_sec_context 3 ,
527 .Xr gss_delete_sec_context 3 ,
529 .Xr gss_release_buffer 3 ,
534 Generic Security Service Application Program Interface Version 2, Update 1
536 Generic Security Service API Version 2 : C-bindings
541 function first appeared in
544 John Wray, Iris Associates
546 Copyright (C) The Internet Society (2000). All Rights Reserved.
548 This document and translations of it may be copied and furnished to
549 others, and derivative works that comment on or otherwise explain it
550 or assist in its implementation may be prepared, copied, published
551 and distributed, in whole or in part, without restriction of any
552 kind, provided that the above copyright notice and this paragraph are
553 included on all such copies and derivative works. However, this
554 document itself may not be modified in any way, such as by removing
555 the copyright notice or references to the Internet Society or other
556 Internet organizations, except as needed for the purpose of
557 developing Internet standards in which case the procedures for
558 copyrights defined in the Internet Standards process must be
559 followed, or as required to translate it into languages other than
562 The limited permissions granted above are perpetual and will not be
563 revoked by the Internet Society or its successors or assigns.
565 This document and the information contained herein is provided on an
566 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
567 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
568 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
569 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
570 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.