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 .\" Copyright (C) The Internet Society (2000).  All Rights Reserved.
  30 .\"
  31 .\" This document and translations of it may be copied and furnished to
  32 .\" others, and derivative works that comment on or otherwise explain it
  33 .\" or assist in its implementation may be prepared, copied, published
  34 .\" and distributed, in whole or in part, without restriction of any
  35 .\" kind, provided that the above copyright notice and this paragraph are
  36 .\" included on all such copies and derivative works.  However, this
  37 .\" document itself may not be modified in any way, such as by removing
  38 .\" the copyright notice or references to the Internet Society or other
  39 .\" Internet organizations, except as needed for the purpose of
  40 .\" developing Internet standards in which case the procedures for
  41 .\" copyrights defined in the Internet Standards process must be
  42 .\" followed, or as required to translate it into languages other than
  43 .\" English.
  44 .\"
  45 .\" The limited permissions granted above are perpetual and will not be
  46 .\" revoked by the Internet Society or its successors or assigns.
  47 .\"
  48 .\" This document and the information contained herein is provided on an
  49 .\" "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
  50 .\" TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
  51 .\" BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
  52 .\" HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
  53 .\" MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  54 .\"
  55 .\" The following commands are required for all man pages.
  56 .Dd November 12, 2005
  57 .Os
  58 .Dt GSS_INIT_SEC_CONTEXT 3 PRM
  59 .Sh NAME
  60 .Nm gss_init_sec_context
  61 .Nd Initiate a security context with a peer application
  62 .\" This next command is for sections 2 and 3 only.
  63 .\" .Sh LIBRARY
  64 .Sh SYNOPSIS
  65 .In "gssapi/gssapi.h"
  66 .Ft OM_uint32
  67 .Fo gss_init_sec_context
  68 .Fa "OM_uint32 *minor_status"
  69 .Fa "const gss_cred_id_t initiator_cred_handle"
  70 .Fa "gss_ctx_id_t *context_handle"
  71 .Fa "const gss_name_t target_name"
  72 .Fa "const gss_OID mech_type"
  73 .Fa "OM_uint32 req_flags"
  74 .Fa "OM_uint32 time_req"
  75 .Fa "const gss_channel_bindings_t input_chan_bindings"
  76 .Fa "const gss_buffer_t input_token"
  77 .Fa "gss_OID *actual_mech_type"
  78 .Fa "gss_buffer_t output_token"
  79 .Fa "OM_uint32 *ret_flags"
  80 .Fa "OM_uint32 *time_rec"
  81 .Fc
  82 .Sh DESCRIPTION
  83 Initiates the establishment of a security context between the
  84 application and a remote peer.
  85 Initially, the input_token parameter should be specified either as
  86 .Dv GSS_C_NO_BUFFER, or as a pointer to a
  87 gss_buffer_desc object whose length field contains the value zero.
  88 The routine may return a output_token which should be transferred to
  89 the peer application, where the peer application will present it to
  90 .Xr gss_accept_sec_context 3 . If no token need be sent,
  91 .Fn gss_init_sec_context
  92 will indicate this by setting the
  93 .Dv length field
  94 of the output_token argument to zero. To complete the context
  95 establishment, one or more reply tokens may be required from the peer
  96 application; if so,
  97 .Fn gss_init_sec_context
  98 will return a status
  99 containing the supplementary information bit
 100 .Dv GSS_S_CONTINUE_NEEDED.
 101 In this case,
 102 .Fn gss_init_sec_context
 103 should be called again when the reply token is received from the peer
 104 application, passing the reply token to
 105 .Fn gss_init_sec_context
 106 via the input_token parameters.
 107 .Pp
 108 Portable applications should be constructed to use the token length
 109 and return status to determine whether a token needs to be sent or
 110 waited for.  Thus a typical portable caller should always invoke
 111 .Fn gss_init_sec_context
 112 within a loop:
 113 .Bd -literal
 114 int context_established = 0;
 115 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
 116        ...
 117 input_token->length = 0;
 118
 119 while (!context_established) {
 120   maj_stat = gss_init_sec_context(&min_stat,
 121                                   cred_hdl,
 122                                   &context_hdl,
 123                                   target_name,
 124                                   desired_mech,
 125                                   desired_services,
 126                                   desired_time,
 127                                   input_bindings,
 128                                   input_token,
 129                                   &actual_mech,
 130                                   output_token,
 131                                   &actual_services,
 132                                   &actual_time);
 133   if (GSS_ERROR(maj_stat)) {
 134     report_error(maj_stat, min_stat);
 135   };
 136
 137   if (output_token->length != 0) {
 138     send_token_to_peer(output_token);
 139     gss_release_buffer(&min_stat, output_token)
 140   };
 141   if (GSS_ERROR(maj_stat)) {
 142
 143     if (context_hdl != GSS_C_NO_CONTEXT)
 144       gss_delete_sec_context(&min_stat,
 145                              &context_hdl,
 146                              GSS_C_NO_BUFFER);
 147     break;
 148   };
 149
 150   if (maj_stat & GSS_S_CONTINUE_NEEDED) {
 151     receive_token_from_peer(input_token);
 152   } else {
 153     context_established = 1;
 154   };
 155 };
 156 .Ed
 157 .Pp
 158 Whenever the routine returns a major status that includes the value
 159 .Dv GSS_S_CONTINUE_NEEDED, the context is not fully established and the
 160 following restrictions apply to the output parameters:
 161 .Bl -bullet
 162 .It
 163 The value returned via the
 164 .Fa time_rec
 165 parameter is undefined Unless
 166 the accompanying
 167 .Fa ret_flags
 168 parameter contains the bit
 169 .Dv GSS_C_PROT_READY_FLAG, indicating that per-message services may be
 170 applied in advance of a successful completion status, the value
 171 returned via the
 172 .Fa actual_mech_type
 173 parameter is undefined until the
 174 routine returns a major status value of
 175 .Dv GSS_S_COMPLETE.
 176 .It
 177 The values of the
 178 .Dv GSS_C_DELEG_FLAG ,
 179 .Dv GSS_C_MUTUAL_FLAG ,
 180 .Dv GSS_C_REPLAY_FLAG ,
 181 .Dv GSS_C_SEQUENCE_FLAG ,
 182 .Fv GSS_C_CONF_FLAG ,
 183 .Dv GSS_C_INTEG_FLAG and
 184 .Dv GSS_C_ANON_FLAG bits returned via the
 185 .Fa ret_flags
 186 parameter should contain the values that the
 187 implementation expects would be valid if context establishment
 188 were to succeed.  In particular, if the application has requested
 189 a service such as delegation or anonymous authentication via the
 190 .Fa req_flags
 191 argument, and such a service is unavailable from the
 192 underlying mechanism,
 193 .Fn gss_init_sec_context
 194 should generate a token
 195 that will not provide the service, and indicate via the
 196 .Fa ret_flags
 197 argument that the service will not be supported.  The application
 198 may choose to abort the context establishment by calling
 199 .Xr gss_delete_sec_context 3
 200 (if it cannot continue in the absence of
 201 the service), or it may choose to transmit the token and continue
 202 context establishment (if the service was merely desired but not
 203 mandatory).
 204 .It
 205 The values of the
 206 .Dv GSS_C_PROT_READY_FLAG and
 207 .Dv GSS_C_TRANS_FLAG bits
 208 within
 209 .Fa ret_flags
 210 should indicate the actual state at the time
 211 .Fn gss_init_sec_context
 212 returns, whether or not the context is fully established.
 213 .It
 214 GSS-API implementations that support per-message protection are
 215 encouraged to set the
 216 .Dv GSS_C_PROT_READY_FLAG in the final
 217 .Fa ret_flags
 218 returned to a caller (i.e. when accompanied by a
 219 .Dv GSS_S_COMPLETE
 220 status code).  However, applications should not rely on this
 221 behavior as the flag was not defined in Version 1 of the GSS-API.
 222 Instead, applications should determine what per-message services
 223 are available after a successful context establishment according
 224 to the
 225 .Dv GSS_C_INTEG_FLAG and
 226 .Dv GSS_C_CONF_FLAG values.
 227 .It
 228 All other bits within the
 229 .Fa ret_flags
 230 argument should be set to
 231 zero.
 232 .El
 233 .Pp
 234 If the initial call of
 235 .Fn gss_init_sec_context
 236 fails, the
 237 implementation should not create a context object, and should leave
 238 the value of the
 239 .Fa context_handle
 240 parameter set to
 241 .Dv GSS_C_NO_CONTEXT to
 242 indicate this.  In the event of a failure on a subsequent call, the
 243 implementation is permitted to delete the "half-built" security
 244 context (in which case it should set the
 245 .Fa context_handle
 246 parameter to
 247 .Dv GSS_C_NO_CONTEXT ), but the preferred behavior is to leave the
 248 security context untouched for the application to delete (using
 249 .Xr gss_delete_sec_context 3 ).
 250 .Pp
 251 During context establishment, the informational status bits
 252 .Dv GSS_S_OLD_TOKEN and
 253 .Dv GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
 254 GSS-API mechanisms should always return them in association with a
 255 routine error of
 256 .Dv GSS_S_FAILURE .
 257 This requirement for pairing did not
 258 exist in version 1 of the GSS-API specification, so applications that
 259 wish to run over version 1 implementations must special-case these
 260 codes.
 261 .Sh PARAMETERS
 262 .Bl -tag
 263 .It minor_status
 264 Mechanism specific status code.
 265 .It initiator_cred_handle
 266 handle for credentials claimed. Supply
 267 .Dv GSS_C_NO_CREDENTIAL to act as a default
 268 initiator principal.  If no default
 269 initiator is defined, the function will
 270 return
 271 .Dv GSS_S_NO_CRED.
 272 .It context_handle
 273 context handle for new context.  Supply
 274 .Dv GSS_C_NO_CONTEXT for first call; use value
 275 returned by first call in continuation calls.
 276 Resources associated with this context-handle
 277 must be released by the application after use
 278 with a call to
 279 .Fn gss_delete_sec_context .
 280 .It target_name
 281 Name of target
 282 .It mech_type
 283 Object ID of desired mechanism. Supply
 284 .Dv GSS_C_NO_OID to obtain an implementation
 285 specific default
 286 .It req_flags
 287 Contains various independent flags, each of
 288 which requests that the context support a
 289 specific service option.  Symbolic
 290 names are provided for each flag, and the
 291 symbolic names corresponding to the required
 292 flags should be logically-ORed
 293 together to form the bit-mask value.  The
 294 flags are:
 295 .Bl -tag -width "WW"
 296 .It GSS_C_DELEG_FLAG
 297 .Bl -tag -width "False"
 298 .It True
 299 Delegate credentials to remote peer
 300 .It False
 301 Don't delegate
 302 .El
 303 .It GSS_C_MUTUAL_FLAG
 304 .Bl -tag -width "False"
 305 .It True
 306 Request that remote peer authenticate itself
 307 .It False
 308 Authenticate self to remote peer only
 309 .El
 310 .It GSS_C_REPLAY_FLAG
 311 .Bl -tag -width "False"
 312 .It True
 313 Enable replay detection for messages protected with
 314 .Xr gss_wrap 3
 315 or
 316 .Xr gss_get_mic 3
 317 .It False
 318 Don't attempt to detect replayed messages
 319 .El
 320 .It GSS_C_SEQUENCE_FLAG
 321 .Bl -tag -width "False"
 322 .It True
 323 Enable detection of out-of-sequence protected messages
 324 .It False
 325 Don't attempt to detect out-of-sequence messages
 326 .El
 327 .It GSS_C_CONF_FLAG
 328 .Bl -tag -width "False"
 329 .It True
 330 Request that confidentiality service be made available (via
 331 .Xr gss_wrap 3 )
 332 .It False
 333 No per-message confidentiality service is required.
 334 .El
 335 .It GSS_C_INTEG_FLAG
 336 .Bl -tag -width "False"
 337 .It True
 338 Request that integrity service be made available (via
 339 .Xr gss_wrap 3
 340 or
 341 .Xr gss_get_mic 3 )
 342 .It False
 343 No per-message integrity service is required.
 344 .El
 345 .It GSS_C_ANON_FLAG
 346 .Bl -tag -width "False"
 347 .It True
 348 Do not reveal the initiator's identity to the acceptor.
 349 .It False
 350 Authenticate normally.
 351 .El
 352 .El
 353 .It time_req
 354 Desired number of seconds for which context
 355 should remain valid.  Supply 0 to request a
 356 default validity period.
 357 .It input_chan_bindings
 358 Application-specified bindings.  Allows
 359 application to securely bind channel
 360 identification information to the security
 361 context.  Specify
 362 .Dv GSS_C_NO_CHANNEL_BINDINGS
 363 if channel bindings are not used.
 364 .It input_token
 365 Token received from peer application.
 366 Supply
 367 .Dv GSS_C_NO_BUFFER, or a pointer to
 368 a buffer containing the value
 369 .Dv GSS_C_EMPTY_BUFFER
 370 on initial call.
 371 .It actual_mech_type
 372 Actual mechanism used.  The OID returned via
 373 this parameter will be a pointer to static
 374 storage that should be treated as read-only;
 375 In particular the application should not attempt
 376 to free it.  Specify
 377 .Dv NULL if not required.
 378 .It output_token
 379 token to be sent to peer application.  If
 380 the length field of the returned buffer is
 381 zero, no token need be sent to the peer
 382 application.  Storage associated with this
 383 buffer must be freed by the application
 384 after use with a call to
 385 .Xr gss_release_buffer 3 .
 386 .It ret_flags
 387 Contains various independent flags, each of which
 388 indicates that the context supports a specific
 389 service option.  Specify
 390 .Dv NULL if not
 391 required.  Symbolic names are provided
 392 for each flag, and the symbolic names
 393 corresponding to the required flags should be
 394 logically-ANDed with the
 395 .Fa ret_flags
 396 value to test
 397 whether a given option is supported by the
 398 context.  The flags are:
 399 .Bl -tag -width "WW"
 400 .It GSS_C_DELEG_FLAG
 401 .Bl -tag -width "False"
 402 .It True
 403 Credentials were delegated to the remote peer
 404 .It False
 405 No credentials were delegated
 406 .El
 407 .It GSS_C_MUTUAL_FLAG
 408 .Bl -tag -width "False"
 409 .It True
 410 The remote peer has authenticated itself.
 411 .It False
 412 Remote peer has not authenticated itself.
 413 .El
 414 .It GSS_C_REPLAY_FLAG
 415 .Bl -tag -width "False"
 416 .It True
 417 Replay of protected messages will be detected
 418 .It False
 419 Replayed messages will not be detected
 420 .El
 421 .It GSS_C_SEQUENCE_FLAG
 422 .Bl -tag -width "False"
 423 .It True
 424 Out-of-sequence protected messages will be detected
 425 .It False
 426 Out-of-sequence messages will not be detected
 427 .El
 428 .It GSS_C_CONF_FLAG
 429 .Bl -tag -width "False"
 430 .It True
 431 Confidentiality service may be invoked by calling
 432 .Xr gss_wrap 3
 433 routine
 434 .It False
 435 No confidentiality service (via
 436 .Xr gss_wrap 3 ) available.
 437 .Xr gss_wrap 3 will
 438 provide message encapsulation,
 439 data-origin authentication and
 440 integrity services only.
 441 .El
 442 .It GSS_C_INTEG_FLAG
 443 .Bl -tag -width "False"
 444 .It True
 445 Integrity service may be invoked by calling either
 446 .Xr gss_get_mic 3
 447 or
 448 .Xr gss_wrap 3
 449 routines.
 450 .It False
 451 Per-message integrity service unavailable.
 452 .El
 453 .It GSS_C_ANON_FLAG
 454 .Bl -tag -width "False"
 455 .It True
 456 The initiator's identity has not been
 457 revealed, and will not be revealed if
 458 any emitted token is passed to the
 459 acceptor.
 460 .It False
 461 The initiator's identity has been or will be authenticated normally.
 462 .El
 463 .It GSS_C_PROT_READY_FLAG
 464 .Bl -tag -width "False"
 465 .It True
 466 Protection services (as specified by the states of the
 467 .Dv GSS_C_CONF_FLAG
 468 and
 469 .Dv GSS_C_INTEG_FLAG ) are available for
 470 use if the accompanying major status
 471 return value is either
 472 .Dv GSS_S_COMPLETE
 473 or
 474 .Dv GSS_S_CONTINUE_NEEDED.
 475 .It False
 476 Protection services (as specified by the states of the
 477 .Dv GSS_C_CONF_FLAG
 478 and
 479 .Dv GSS_C_INTEG_FLAG ) are available
 480 only if the accompanying major status
 481 return value is
 482 .Dv GSS_S_COMPLETE.
 483 .El
 484 .It GSS_C_TRANS_FLAG
 485 .Bl -tag -width "False"
 486 .It True
 487 The resultant security context may be transferred to other processes via
 488 a call to
 489 .Fn gss_export_sec_context .
 490 .It False
 491 The security context is not transferable.
 492 .El
 493 .El
 494 .Pp
 495 All other bits should be set to zero.
 496 .It time_rec
 497 Number of seconds for which the context
 498 will remain valid. If the implementation does
 499 not support context expiration, the value
 500 .Dv GSS_C_INDEFINITE will be returned.  Specify
 501 .Dv NULL if not required.
 502 .El
 503 .Sh RETURN VALUES
 504 .Bl -tag
 505 .It GSS_S_COMPLETE
 506 Successful completion
 507 .It GSS_S_CONTINUE_NEEDED
 508 Indicates that a token from the peer
 509 application is required to complete the
 510 context, and that gss_init_sec_context
 511 must be called again with that token.
 512 .It GSS_S_DEFECTIVE_TOKEN
 513 Indicates that consistency checks performed
 514 on the input_token failed
 515 .It GSS_S_DEFECTIVE_CREDENTIAL
 516 Indicates that consistency checks
 517 performed on the credential failed.
 518 .It GSS_S_NO_CRED
 519 The supplied credentials were not valid for
 520 context initiation, or the credential handle
 521 did not reference any credentials.
 522 .It GSS_S_CREDENTIALS_EXPIRED
 523 The referenced credentials have expired
 524 .It GSS_S_BAD_BINDINGS
 525 The input_token contains different channel
 526 bindings to those specified via the
 527 input_chan_bindings parameter
 528 .It GSS_S_BAD_SIG
 529 The input_token contains an invalid MIC, or a MIC
 530 that could not be verified
 531 .It GSS_S_OLD_TOKEN
 532 The input_token was too old.  This is a fatal
 533 error during context establishment
 534 .It GSS_S_DUPLICATE_TOKEN
 535 The input_token is valid, but is a duplicate
 536 of a token already processed.  This is a
 537 fatal error during context establishment.
 538 .It GSS_S_NO_CONTEXT
 539 Indicates that the supplied context handle did
 540 not refer to a valid context
 541 .It GSS_S_BAD_NAMETYPE
 542 The provided target_name parameter contained an
 543 invalid or unsupported type of name
 544 .It GSS_S_BAD_NAME
 545 The provided target_name parameter was ill-formed.
 546 .It GSS_S_BAD_MECH
 547 The specified mechanism is not supported by the
 548 provided credential, or is unrecognized by the
 549 implementation.
 550 .El
 551 .Sh SEE ALSO
 552 .Xr gss_accept_sec_context 3 ,
 553 .Xr gss_delete_sec_context 3 ,
 554 .Xr gss_get_mic 3 ,
 555 .Xr gss_release_buffer 3 ,
 556 .Xr gss_wrap 3
 557 .Sh STANDARDS
 558 .Bl -tag
 559 .It RFC 2743
 560 Generic Security Service Application Program Interface Version 2, Update 1
 561 .It RFC 2744
 562 Generic Security Service API Version 2 : C-bindings
 563 .El
 564 .\" .Sh HISTORY
 565 .Sh HISTORY
 566 The
 567 .Nm
 568 manual page example first appeared in
 569 .Fx 7.0 .
 570 .Sh AUTHORS
 571 John Wray, Iris Associates