lib/libgssapi/gss_accept_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_ACCEPT_SEC_CONTEXT 3 PRM
  32 .Os
  33 .Sh NAME
  34 .Nm gss_accept_sec_context
  35 .Nd Accept a security context initiated by 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_accept_sec_context
  42 .Fa "OM_uint32 *minor_status"
  43 .Fa "gss_ctx_id_t *context_handle"
  44 .Fa "const gss_cred_id_t acceptor_cred_handle"
  45 .Fa "const gss_buffer_t input_token_buffer"
  46 .Fa "const gss_channel_bindings_t input_chan_bindings"
  47 .Fa "const gss_name_t *src_name"
  48 .Fa "gss_OID *mech_type"
  49 .Fa "gss_buffer_t output_token"
  50 .Fa "OM_uint32 *ret_flags"
  51 .Fa "OM_uint32 *time_rec"
  52 .Fa "gss_cred_id_t *delegated_cred_handle"
  53 .Fc
  54 .Sh DESCRIPTION
  55 Allows a remotely initiated security context between the application and a remote
  56 peer to be established.
  57 The routine may return a
  58 .Fa output_token
  59 which should be transferred to the peer application,
  60 where the peer application will present it to
  61 .Xr gss_init_sec_context 3 .
  62 If no token need be sent,
  63 .Fn gss_accept_sec_context
  64 will indicate this
  65 by setting the length field of the
  66 .Fa output_token
  67 argument to zero.
  68 To complete the context establishment, one or more reply tokens may be
  69 required from the peer application; if so,
  70 .Fn gss_accept_sec_context
  71 will return a status flag of
  72 .Dv GSS_S_CONTINUE_NEEDED , in which case it
  73 should be called again when the reply token is received from the peer
  74 application, passing the token to
  75 .Fn gss_accept_sec_context
  76 via the
  77 .Fa input_token
  78 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.
  83 Thus a typical portable caller should always invoke
  84 .Fn gss_accept_sec_context
  85 within a loop:
  86 .Bd -literal
  87 gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
  88
  89 do {
  90   receive_token_from_peer(input_token);
  91   maj_stat = gss_accept_sec_context(&min_stat,
  92                                     &context_hdl,
  93                                     cred_hdl,
  94                                     input_token,
  95                                     input_bindings,
  96                                     &client_name,
  97                                     &mech_type,
  98                                     output_token,
  99                                     &ret_flags,
 100                                     &time_rec,
 101                                     &deleg_cred);
 102   if (GSS_ERROR(maj_stat)) {
 103     report_error(maj_stat, min_stat);
 104   };
 105   if (output_token->length != 0) {
 106     send_token_to_peer(output_token);
 107
 108     gss_release_buffer(&min_stat, output_token);
 109   };
 110   if (GSS_ERROR(maj_stat)) {
 111     if (context_hdl != GSS_C_NO_CONTEXT)
 112       gss_delete_sec_context(&min_stat,
 113                              &context_hdl,
 114                              GSS_C_NO_BUFFER);
 115     break;
 116   };
 117 } while (maj_stat & GSS_S_CONTINUE_NEEDED);
 118 .Ed
 119 .Pp
 120 Whenever the routine returns a major status that includes the value
 121 .Dv GSS_S_CONTINUE_NEEDED , the context is not fully established and the
 122 following restrictions apply to the output parameters:
 123 .Pp
 124 The value returned via the
 125 .Fa time_rec
 126 parameter is undefined unless the
 127 accompanying
 128 .Fa ret_flags
 129 parameter contains the bit
 130 .Dv GSS_C_PROT_READY_FLAG , indicating that per-message services may be
 131 applied in advance of a successful completion status, the value
 132 returned via the
 133 .Fa mech_type
 134 parameter may be undefined until the
 135 routine returns a major status value of
 136 .Dv GSS_S_COMPLETE .
 137 .Pp
 138 The values of the
 139 .Dv GSS_C_DELEG_FLAG ,
 140 .Dv GSS_C_MUTUAL_FLAG ,
 141 .Dv GSS_C_REPLAY_FLAG ,
 142 .Dv GSS_C_SEQUENCE_FLAG ,
 143 .Dv GSS_C_CONF_FLAG ,
 144 .Dv GSS_C_INTEG_FLAG
 145 and
 146 .Dv GSS_C_ANON_FLAG bits returned
 147 via the
 148 .Fa ret_flags
 149 parameter should contain the values that the
 150 implementation expects would be valid if context establishment were
 151 to succeed.
 152 .Pp
 153 The values of the
 154 .Dv GSS_C_PROT_READY_FLAG
 155 and
 156 .Dv GSS_C_TRANS_FLAG bits
 157 within
 158 .Fa ret_flags
 159 should indicate the actual state at the time
 160 .Fn gss_accept_sec_context
 161 returns, whether or not the context is fully established.
 162 .Pp
 163 Although this requires that GSS-API implementations set the
 164 .Dv GSS_C_PROT_READY_FLAG
 165 in the final
 166 .Fa ret_flags
 167 returned to a caller
 168 (i.e. when accompanied by a
 169 .Dv GSS_S_COMPLETE
 170 status code), applications
 171 should not rely on this behavior as the flag was not defined in Version 1 of the GSS-API.
 172 Instead, applications should be prepared to use per-message services after a
 173 successful context establishment, according to the
 174 .Dv GSS_C_INTEG_FLAG
 175 and
 176 .Dv GSS_C_CONF_FLAG values.
 177 .Pp
 178 All other bits within the
 179 .Fa ret_flags
 180 argument should be set to zero.
 181 While the routine returns
 182 .Dv GSS_S_CONTINUE_NEEDED , the values returned
 183 via the
 184 .Fa ret_flags
 185 argument indicate the services that the
 186 implementation expects to be available from the established context.
 187 .Pp
 188 If the initial call of
 189 .Fn gss_accept_sec_context
 190 fails, the
 191 implementation should not create a context object, and should leave
 192 the value of the context_handle parameter set to
 193 .Dv GSS_C_NO_CONTEXT to
 194 indicate this.
 195 In the event of a failure on a subsequent call, the implementation is
 196 permitted to delete the "half-built" security context (in which case it
 197 should set the
 198 .Fa context_handle
 199 parameter to
 200 .Dv GSS_C_NO_CONTEXT ), but the preferred behavior is to leave the
 201 security context (and the context_handle parameter) untouched for the
 202 application to delete (using
 203 .Xr gss_delete_sec_context 3 ).
 204 .Pp
 205 During context establishment, the informational status bits
 206 .Dv GSS_S_OLD_TOKEN
 207 and
 208 .Dv GSS_S_DUPLICATE_TOKEN
 209 indicate fatal errors, and
 210 GSS-API mechanisms should always return them in association with a
 211 routine error of
 212 .Dv GSS_S_FAILURE .  This requirement for pairing did not
 213 exist in version 1 of the GSS-API specification, so applications that
 214 wish to run over version 1 implementations must special-case these
 215 codes.
 216 .Sh PARAMETERS
 217 .Bl -tag -width ".It input_chan_bindings"
 218 .It context_handle
 219 Context handle for new context.
 220 Supply
 221 .Dv GSS_C_NO_CONTEXT for first
 222 call; use value returned in subsequent calls.
 223 Once
 224 .Fn gss_accept_sec_context
 225 has returned a
 226 value via this parameter, resources have been
 227 assigned to the corresponding context, and must
 228 be freed by the application after use with a
 229 call to
 230 .Xr gss_delete_sec_context 3 .
 231 .It acceptor_cred_handle
 232 Credential handle claimed by context acceptor.
 233 Specify
 234 .Dv GSS_C_NO_CREDENTIAL to accept the context as a
 235 default principal.
 236 If
 237 .Dv GSS_C_NO_CREDENTIAL is
 238 specified, but no default acceptor principal is
 239 defined,
 240 .Dv GSS_S_NO_CRED will be returned.
 241 .It input_token_buffer
 242 Token obtained from remote application.
 243 .It input_chan_bindings
 244 Application-specified bindings.
 245 Allows application to securely bind channel identification information
 246 to the security context.
 247 If channel bindings are not used, specify
 248 .Dv GSS_C_NO_CHANNEL_BINDINGS .
 249 .It src_name
 250 Authenticated name of context initiator.
 251 After use, this name should be deallocated by passing it to
 252 .Xr gss_release_name 3 .
 253 If not required, specify
 254 .Dv NULL .
 255 .It mech_type
 256 Security mechanism used.
 257 The returned OID value will be a pointer into static storage,
 258 and should be treated as read-only by the caller
 259 (in particular, it does not need to be freed).
 260 If not required, specify
 261 .Dv NULL .
 262 .It output_token
 263 Token to be passed to peer application.
 264 If the length field of the returned token buffer is 0,
 265 then no token need be passed to the peer application.
 266 If a non-zero length field is returned,
 267 the associated storage must be freed after use by the
 268 application with a call to
 269 .Xr gss_release_buffer 3 .
 270 .It ret_flags
 271 Contains various independent flags,
 272 each of which indicates that the context supports a specific service option.
 273 If not needed, specify
 274 .Dv NULL .
 275 Symbolic names are provided for each flag,
 276 and the symbolic names corresponding to the required flags should be
 277 logically-ANDed with the
 278 .Fa ret_flags
 279 value to test whether a given option is supported by the context.
 280 The flags are:
 281 .Bl -tag -width "WW"
 282 .It GSS_C_DELEG_FLAG
 283 .Bl -tag -width "False"
 284 .It True
 285 Delegated credentials are available via the delegated_cred_handle parameter
 286 .It False
 287 No credentials were delegated
 288 .El
 289 .It GSS_C_MUTUAL_FLAG
 290 .Bl -tag -width "False"
 291 .It True
 292 Remote peer asked for mutual authentication
 293 .It False
 294 Remote peer did not ask for mutual authentication
 295 .El
 296 .It GSS_C_REPLAY_FLAG
 297 .Bl -tag -width "False"
 298 .It True
 299 Replay of protected messages will be detected
 300 .It False
 301 Replayed messages will not be detected
 302 .El
 303 .It GSS_C_SEQUENCE_FLAG
 304 .Bl -tag -width "False"
 305 .It True
 306 Out-of-sequence protected messages will be detected
 307 .It False
 308 Out-of-sequence messages will not be detected
 309 .El
 310 .It GSS_C_CONF_FLAG
 311 .Bl -tag -width "False"
 312 .It True
 313 Confidentiality service may be invoked by calling the
 314 .Xr gss_wrap 3
 315 routine
 316 .It False
 317 No confidentiality service (via
 318 .Xr gss_wrap 3 )
 319 available.
 320 .Xr gss_wrap 3
 321 will provide message encapsulation,
 322 data-origin authentication and integrity services only.
 323 .El
 324 .It GSS_C_INTEG_FLAG
 325 .Bl -tag -width "False"
 326 .It True
 327 Integrity service may be invoked by calling either
 328 .Xr gss_get_mic 3
 329 or
 330 .Xr gss_wrap 3
 331 routines.
 332 .It False
 333 Per-message integrity service unavailable.
 334 .El
 335 .It GSS_C_ANON_FLAG
 336 .Bl -tag -width "False"
 337 .It True
 338 The initiator does not wish to be authenticated; the
 339 .Fa src_name
 340 parameter (if requested) contains an anonymous internal name.
 341 .It False
 342 The initiator has been authenticated normally.
 343 .El
 344 .It GSS_C_PROT_READY_FLAG
 345 .Bl -tag -width "False"
 346 .It True
 347 Protection services (as specified by the states of the
 348 .Dv GSS_C_CONF_FLAG
 349 and
 350 .Dv GSS_C_INTEG_FLAG )
 351 are available if the accompanying major status return value is either
 352 .Dv GSS_S_COMPLETE
 353 or
 354 .Dv GSS_S_CONTINUE_NEEDED.
 355 .It False
 356 Protection services (as specified by the states of the
 357 .Dv GSS_C_CONF_FLAG
 358 and
 359 .Dv GSS_C_INTEG_FLAG )
 360 are available only if the accompanying major status return value is
 361 .Dv GSS_S_COMPLETE .
 362 .El
 363 .It GSS_C_TRANS_FLAG
 364 .Bl -tag -width "False"
 365 .It True
 366 The resultant security context may be transferred to other processes
 367 via a call to
 368 .Xr gss_export_sec_context 3 .
 369 .It False
 370 The security context is not transferable.
 371 .El
 372 .El
 373 .Pp
 374 All other bits should be set to zero.
 375 .It time_rec
 376 Number of seconds for which the context will remain valid.
 377 Specify
 378 .Dv NULL
 379 if not required.
 380 .It delegated_cred_handle
 381 Credential
 382 handle for credentials received from context initiator.
 383 Only valid if
 384 .Dv GSS_C_DELEG_FLAG
 385 in
 386 .Fa ret_flags
 387 is true,
 388 in which case an explicit credential handle
 389 (i.e. not
 390 .Dv GSS_C_NO_CREDENTIAL )
 391 will be returned; if false,
 392 .Fn gss_accept_context
 393 will set this parameter to
 394 .Dv GSS_C_NO_CREDENTIAL .
 395 If a credential handle is returned,
 396 the associated resources must be released by the application after use
 397 with a call to
 398 .Xr gss_release_cred 3 .
 399 Specify
 400 .Dv NULL if not required.
 401 .It minor_status
 402 Mechanism specific status code.
 403 .El
 404 .Sh RETURN VALUES
 405 .Bl -tag -width ".It GSS_S_DEFECTIVE_CREDENTIAL"
 406 .It GSS_S_CONTINUE_NEEDED
 407 Indicates that a token from the peer application is required to
 408 complete the context,
 409 and that gss_accept_sec_context must be called again with that token.
 410 .It GSS_S_DEFECTIVE_TOKEN
 411 Indicates that consistency checks performed on the input_token failed.
 412 .It GSS_S_DEFECTIVE_CREDENTIAL
 413 Indicates that consistency checks performed on the credential failed.
 414 .It GSS_S_NO_CRED
 415 The supplied credentials were not valid for context acceptance,
 416 or the credential handle did not reference any credentials.
 417 .It GSS_S_CREDENTIALS_EXPIRED
 418 The referenced credentials have expired.
 419 .It GSS_S_BAD_BINDINGS
 420 The input_token contains different channel bindings to those specified via the
 421 input_chan_bindings parameter.
 422 .It GSS_S_NO_CONTEXT
 423 Indicates that the supplied context handle did not refer to a valid context.
 424 .It GSS_S_BAD_SIG
 425 The input_token contains an invalid MIC.
 426 .It GSS_S_OLD_TOKEN
 427 The input_token was too old.
 428 This is a fatal error during context establishment.
 429 .It GSS_S_DUPLICATE_TOKEN
 430 The input_token is valid,
 431 but is a duplicate of a token already processed.
 432 This is a fatal error during context establishment.
 433 .It GSS_S_BAD_MECH
 434 The received token specified a mechanism that is not supported by
 435 the implementation or the provided credential.
 436 .El
 437 .Sh SEE ALSO
 438 .Xr gss_delete_sec_context 3 ,
 439 .Xr gss_export_sec_context 3 ,
 440 .Xr gss_get_mic 3 ,
 441 .Xr gss_init_sec_context 3 ,
 442 .Xr gss_release_buffer 3 ,
 443 .Xr gss_release_cred 3 ,
 444 .Xr gss_release_name 3 ,
 445 .Xr gss_wrap 3
 446 .Sh STANDARDS
 447 .Bl -tag -width ".It RFC 2743"
 448 .It RFC 2743
 449 Generic Security Service Application Program Interface Version 2, Update 1
 450 .It RFC 2744
 451 Generic Security Service API Version 2 : C-bindings
 452 .El
 453 .Sh HISTORY
 454 The
 455 .Nm
 456 function first appeared in
 457 .Fx 7.0 .
 458 .Sh AUTHORS
 459 John Wray, Iris Associates
 460 .Sh COPYRIGHT
 461 Copyright (C) The Internet Society (2000).  All Rights Reserved.
 462 .Pp
 463 This document and translations of it may be copied and furnished to
 464 others, and derivative works that comment on or otherwise explain it
 465 or assist in its implementation may be prepared, copied, published
 466 and distributed, in whole or in part, without restriction of any
 467 kind, provided that the above copyright notice and this paragraph are
 468 included on all such copies and derivative works.  However, this
 469 document itself may not be modified in any way, such as by removing
 470 the copyright notice or references to the Internet Society or other
 471 Internet organizations, except as needed for the purpose of
 472 developing Internet standards in which case the procedures for
 473 copyrights defined in the Internet Standards process must be
 474 followed, or as required to translate it into languages other than
 475 English.
 476 .Pp
 477 The limited permissions granted above are perpetual and will not be
 478 revoked by the Internet Society or its successors or assigns.
 479 .Pp
 480 This document and the information contained herein is provided on an
 481 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 482 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 483 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 484 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 485 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.