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