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