lib/libgssapi/gss_init_sec_context.3

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2005 Doug Rabson
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   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.
  14 .\"
  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
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" The following commands are required for all man pages.
  28 .Dd January 26, 2010
  29 .Dt GSS_INIT_SEC_CONTEXT 3 PRM
  30 .Os
  31 .Sh NAME
  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.
  35 .\" .Sh LIBRARY
  36 .Sh SYNOPSIS
  37 .In "gssapi/gssapi.h"
  38 .Ft OM_uint32
  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"
  53 .Fc
  54 .Sh DESCRIPTION
  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
  65 .Dv length field
  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
  68 application; if so,
  69 .Fn gss_init_sec_context
  70 will return a status
  71 containing the supplementary information bit
  72 .Dv GSS_S_CONTINUE_NEEDED.
  73 In this case,
  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.
  79 .Pp
  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
  84 within a loop:
  85 .Bd -literal
  86 int context_established = 0;
  87 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
  88        ...
  89 input_token->length = 0;
  90
  91 while (!context_established) {
  92   maj_stat = gss_init_sec_context(&min_stat,
  93                                   cred_hdl,
  94                                   &context_hdl,
  95                                   target_name,
  96                                   desired_mech,
  97                                   desired_services,
  98                                   desired_time,
  99                                   input_bindings,
 100                                   input_token,
 101                                   &actual_mech,
 102                                   output_token,
 103                                   &actual_services,
 104                                   &actual_time);
 105   if (GSS_ERROR(maj_stat)) {
 106     report_error(maj_stat, min_stat);
 107   };
 108
 109   if (output_token->length != 0) {
 110     send_token_to_peer(output_token);
 111     gss_release_buffer(&min_stat, output_token)
 112   };
 113   if (GSS_ERROR(maj_stat)) {
 114
 115     if (context_hdl != GSS_C_NO_CONTEXT)
 116       gss_delete_sec_context(&min_stat,
 117                              &context_hdl,
 118                              GSS_C_NO_BUFFER);
 119     break;
 120   };
 121
 122   if (maj_stat & GSS_S_CONTINUE_NEEDED) {
 123     receive_token_from_peer(input_token);
 124   } else {
 125     context_established = 1;
 126   };
 127 };
 128 .Ed
 129 .Pp
 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:
 133 .Bl -bullet
 134 .It
 135 The value returned via the
 136 .Fa time_rec
 137 parameter is undefined Unless
 138 the accompanying
 139 .Fa ret_flags
 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
 143 returned via the
 144 .Fa actual_mech_type
 145 parameter is undefined until the
 146 routine returns a major status value of
 147 .Dv GSS_S_COMPLETE.
 148 .It
 149 The values of the
 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
 157 .Fa ret_flags
 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
 162 .Fa req_flags
 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
 168 .Fa ret_flags
 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
 175 mandatory).
 176 .It
 177 The values of the
 178 .Dv GSS_C_PROT_READY_FLAG and
 179 .Dv GSS_C_TRANS_FLAG bits
 180 within
 181 .Fa ret_flags
 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.
 185 .It
 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
 189 .Fa ret_flags
 190 returned to a caller (i.e. when accompanied by a
 191 .Dv GSS_S_COMPLETE
 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
 196 to the
 197 .Dv GSS_C_INTEG_FLAG and
 198 .Dv GSS_C_CONF_FLAG values.
 199 .It
 200 All other bits within the
 201 .Fa ret_flags
 202 argument should be set to
 203 zero.
 204 .El
 205 .Pp
 206 If the initial call of
 207 .Fn gss_init_sec_context
 208 fails, the
 209 implementation should not create a context object, and should leave
 210 the value of the
 211 .Fa context_handle
 212 parameter set to
 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
 217 .Fa context_handle
 218 parameter to
 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 ).
 222 .Pp
 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
 227 routine error of
 228 .Dv GSS_S_FAILURE .
 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
 232 codes.
 233 .Sh PARAMETERS
 234 .Bl -tag -width ".It initiator_cred_handle"
 235 .It minor_status
 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
 242 return
 243 .Dv GSS_S_NO_CRED.
 244 .It context_handle
 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
 250 with a call to
 251 .Fn gss_delete_sec_context .
 252 .It target_name
 253 Name of target
 254 .It mech_type
 255 Object ID of desired mechanism. Supply
 256 .Dv GSS_C_NO_OID to obtain an implementation
 257 specific default
 258 .It req_flags
 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
 266 flags are:
 267 .Bl -tag -width "WW"
 268 .It GSS_C_DELEG_FLAG
 269 .Bl -tag -width "False"
 270 .It True
 271 Delegate credentials to remote peer
 272 .It False
 273 Don't delegate
 274 .El
 275 .It GSS_C_MUTUAL_FLAG
 276 .Bl -tag -width "False"
 277 .It True
 278 Request that remote peer authenticate itself
 279 .It False
 280 Authenticate self to remote peer only
 281 .El
 282 .It GSS_C_REPLAY_FLAG
 283 .Bl -tag -width "False"
 284 .It True
 285 Enable replay detection for messages protected with
 286 .Xr gss_wrap 3
 287 or
 288 .Xr gss_get_mic 3
 289 .It False
 290 Don't attempt to detect replayed messages
 291 .El
 292 .It GSS_C_SEQUENCE_FLAG
 293 .Bl -tag -width "False"
 294 .It True
 295 Enable detection of out-of-sequence protected messages
 296 .It False
 297 Don't attempt to detect out-of-sequence messages
 298 .El
 299 .It GSS_C_CONF_FLAG
 300 .Bl -tag -width "False"
 301 .It True
 302 Request that confidentiality service be made available (via
 303 .Xr gss_wrap 3 )
 304 .It False
 305 No per-message confidentiality service is required.
 306 .El
 307 .It GSS_C_INTEG_FLAG
 308 .Bl -tag -width "False"
 309 .It True
 310 Request that integrity service be made available (via
 311 .Xr gss_wrap 3
 312 or
 313 .Xr gss_get_mic 3 )
 314 .It False
 315 No per-message integrity service is required.
 316 .El
 317 .It GSS_C_ANON_FLAG
 318 .Bl -tag -width "False"
 319 .It True
 320 Do not reveal the initiator's identity to the acceptor.
 321 .It False
 322 Authenticate normally.
 323 .El
 324 .El
 325 .It time_req
 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
 333 context.  Specify
 334 .Dv GSS_C_NO_CHANNEL_BINDINGS
 335 if channel bindings are not used.
 336 .It input_token
 337 Token received from peer application.
 338 Supply
 339 .Dv GSS_C_NO_BUFFER, or a pointer to
 340 a buffer containing the value
 341 .Dv GSS_C_EMPTY_BUFFER
 342 on initial call.
 343 .It actual_mech_type
 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
 348 to free it.  Specify
 349 .Dv NULL if not required.
 350 .It output_token
 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 .
 358 .It ret_flags
 359 Contains various independent flags, each of which
 360 indicates that the context supports a specific
 361 service option.  Specify
 362 .Dv NULL if not
 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
 367 .Fa ret_flags
 368 value to test
 369 whether a given option is supported by the
 370 context.  The flags are:
 371 .Bl -tag -width "WW"
 372 .It GSS_C_DELEG_FLAG
 373 .Bl -tag -width "False"
 374 .It True
 375 Credentials were delegated to the remote peer
 376 .It False
 377 No credentials were delegated
 378 .El
 379 .It GSS_C_MUTUAL_FLAG
 380 .Bl -tag -width "False"
 381 .It True
 382 The remote peer has authenticated itself.
 383 .It False
 384 Remote peer has not authenticated itself.
 385 .El
 386 .It GSS_C_REPLAY_FLAG
 387 .Bl -tag -width "False"
 388 .It True
 389 Replay of protected messages will be detected
 390 .It False
 391 Replayed messages will not be detected
 392 .El
 393 .It GSS_C_SEQUENCE_FLAG
 394 .Bl -tag -width "False"
 395 .It True
 396 Out-of-sequence protected messages will be detected
 397 .It False
 398 Out-of-sequence messages will not be detected
 399 .El
 400 .It GSS_C_CONF_FLAG
 401 .Bl -tag -width "False"
 402 .It True
 403 Confidentiality service may be invoked by calling
 404 .Xr gss_wrap 3
 405 routine
 406 .It False
 407 No confidentiality service (via
 408 .Xr gss_wrap 3 ) available.
 409 .Xr gss_wrap 3 will
 410 provide message encapsulation,
 411 data-origin authentication and
 412 integrity services only.
 413 .El
 414 .It GSS_C_INTEG_FLAG
 415 .Bl -tag -width "False"
 416 .It True
 417 Integrity service may be invoked by calling either
 418 .Xr gss_get_mic 3
 419 or
 420 .Xr gss_wrap 3
 421 routines.
 422 .It False
 423 Per-message integrity service unavailable.
 424 .El
 425 .It GSS_C_ANON_FLAG
 426 .Bl -tag -width "False"
 427 .It True
 428 The initiator's identity has not been
 429 revealed, and will not be revealed if
 430 any emitted token is passed to the
 431 acceptor.
 432 .It False
 433 The initiator's identity has been or will be authenticated normally.
 434 .El
 435 .It GSS_C_PROT_READY_FLAG
 436 .Bl -tag -width "False"
 437 .It True
 438 Protection services (as specified by the states of the
 439 .Dv GSS_C_CONF_FLAG
 440 and
 441 .Dv GSS_C_INTEG_FLAG ) are available for
 442 use if the accompanying major status
 443 return value is either
 444 .Dv GSS_S_COMPLETE
 445 or
 446 .Dv GSS_S_CONTINUE_NEEDED.
 447 .It False
 448 Protection services (as specified by the states of the
 449 .Dv GSS_C_CONF_FLAG
 450 and
 451 .Dv GSS_C_INTEG_FLAG ) are available
 452 only if the accompanying major status
 453 return value is
 454 .Dv GSS_S_COMPLETE.
 455 .El
 456 .It GSS_C_TRANS_FLAG
 457 .Bl -tag -width "False"
 458 .It True
 459 The resultant security context may be transferred to other processes via
 460 a call to
 461 .Fn gss_export_sec_context .
 462 .It False
 463 The security context is not transferable.
 464 .El
 465 .El
 466 .Pp
 467 All other bits should be set to zero.
 468 .It time_rec
 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.
 474 .El
 475 .Sh RETURN VALUES
 476 .Bl -tag -width ".It GSS_S_CREDENTIALS_EXPIRED"
 477 .It GSS_S_COMPLETE
 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.
 490 .It GSS_S_NO_CRED
 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
 500 .It GSS_S_BAD_SIG
 501 The input_token contains an invalid MIC, or a MIC
 502 that could not be verified
 503 .It GSS_S_OLD_TOKEN
 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.
 510 .It GSS_S_NO_CONTEXT
 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
 516 .It GSS_S_BAD_NAME
 517 The provided target_name parameter was ill-formed.
 518 .It GSS_S_BAD_MECH
 519 The specified mechanism is not supported by the
 520 provided credential, or is unrecognized by the
 521 implementation.
 522 .El
 523 .Sh SEE ALSO
 524 .Xr gss_accept_sec_context 3 ,
 525 .Xr gss_delete_sec_context 3 ,
 526 .Xr gss_get_mic 3 ,
 527 .Xr gss_release_buffer 3 ,
 528 .Xr gss_wrap 3
 529 .Sh STANDARDS
 530 .Bl -tag -width ".It RFC 2743"
 531 .It RFC 2743
 532 Generic Security Service Application Program Interface Version 2, Update 1
 533 .It RFC 2744
 534 Generic Security Service API Version 2 : C-bindings
 535 .El
 536 .Sh HISTORY
 537 The
 538 .Nm
 539 function first appeared in
 540 .Fx 7.0 .
 541 .Sh AUTHORS
 542 John Wray, Iris Associates
 543 .Sh COPYRIGHT
 544 Copyright (C) The Internet Society (2000).  All Rights Reserved.
 545 .Pp
 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
 558 English.
 559 .Pp
 560 The limited permissions granted above are perpetual and will not be
 561 revoked by the Internet Society or its successors or assigns.
 562 .Pp
 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.