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