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