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 83Initiates the establishment of a security context between the 84application and a remote peer. 85Initially, the input_token parameter should be specified either as 86.Dv GSS_C_NO_BUFFER, or as a pointer to a 87gss_buffer_desc object whose length field contains the value zero. 88The routine may return a output_token which should be transferred to 89the 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 92will indicate this by setting the 93.Dv length field 94of the output_token argument to zero. To complete the context 95establishment, one or more reply tokens may be required from the peer 96application; if so, 97.Fn gss_init_sec_context 98will return a status 99containing the supplementary information bit 100.Dv GSS_S_CONTINUE_NEEDED. 101In this case, 102.Fn gss_init_sec_context 103should be called again when the reply token is received from the peer 104application, passing the reply token to 105.Fn gss_init_sec_context 106via the input_token parameters. 107.Pp 108Portable applications should be constructed to use the token length 109and return status to determine whether a token needs to be sent or 110waited for. Thus a typical portable caller should always invoke 111.Fn gss_init_sec_context 112within a loop: 113.Bd -literal 114int context_established = 0; 115gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; 116 ... 117input_token->length = 0; 118 119while (!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 158Whenever the routine returns a major status that includes the value 159.Dv GSS_S_CONTINUE_NEEDED, the context is not fully established and the 160following restrictions apply to the output parameters: 161.Bl -bullet 162.It 163The value returned via the 164.Fa time_rec 165parameter is undefined Unless 166the accompanying 167.Fa ret_flags 168parameter contains the bit 169.Dv GSS_C_PROT_READY_FLAG, indicating that per-message services may be 170applied in advance of a successful completion status, the value 171returned via the 172.Fa actual_mech_type 173parameter is undefined until the 174routine returns a major status value of 175.Dv GSS_S_COMPLETE. 176.It 177The 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 186parameter should contain the values that the 187implementation expects would be valid if context establishment 188were to succeed. In particular, if the application has requested 189a service such as delegation or anonymous authentication via the 190.Fa req_flags 191argument, and such a service is unavailable from the 192underlying mechanism, 193.Fn gss_init_sec_context 194should generate a token 195that will not provide the service, and indicate via the 196.Fa ret_flags 197argument that the service will not be supported. The application 198may choose to abort the context establishment by calling 199.Xr gss_delete_sec_context 3 200(if it cannot continue in the absence of 201the service), or it may choose to transmit the token and continue 202context establishment (if the service was merely desired but not 203mandatory). 204.It 205The values of the 206.Dv GSS_C_PROT_READY_FLAG and 207.Dv GSS_C_TRANS_FLAG bits 208within 209.Fa ret_flags 210should indicate the actual state at the time 211.Fn gss_init_sec_context 212returns, whether or not the context is fully established. 213.It 214GSS-API implementations that support per-message protection are 215encouraged to set the 216.Dv GSS_C_PROT_READY_FLAG in the final 217.Fa ret_flags 218returned to a caller (i.e. when accompanied by a 219.Dv GSS_S_COMPLETE 220status code). However, applications should not rely on this 221behavior as the flag was not defined in Version 1 of the GSS-API. 222Instead, applications should determine what per-message services 223are available after a successful context establishment according 224to the 225.Dv GSS_C_INTEG_FLAG and 226.Dv GSS_C_CONF_FLAG values. 227.It 228All other bits within the 229.Fa ret_flags 230argument should be set to 231zero. 232.El 233.Pp 234If the initial call of 235.Fn gss_init_sec_context 236fails, the 237implementation should not create a context object, and should leave 238the value of the 239.Fa context_handle 240parameter set to 241.Dv GSS_C_NO_CONTEXT to 242indicate this. In the event of a failure on a subsequent call, the 243implementation is permitted to delete the "half-built" security 244context (in which case it should set the 245.Fa context_handle 246parameter to 247.Dv GSS_C_NO_CONTEXT ), but the preferred behavior is to leave the 248security context untouched for the application to delete (using 249.Xr gss_delete_sec_context 3 ). 250.Pp 251During context establishment, the informational status bits 252.Dv GSS_S_OLD_TOKEN and 253.Dv GSS_S_DUPLICATE_TOKEN indicate fatal errors, and 254GSS-API mechanisms should always return them in association with a 255routine error of 256.Dv GSS_S_FAILURE . 257This requirement for pairing did not 258exist in version 1 of the GSS-API specification, so applications that 259wish to run over version 1 implementations must special-case these 260codes. 261.Sh PARAMETERS 262.Bl -tag 263.It minor_status 264Mechanism specific status code. 265.It initiator_cred_handle 266handle for credentials claimed. Supply 267.Dv GSS_C_NO_CREDENTIAL to act as a default 268initiator principal. If no default 269initiator is defined, the function will 270return 271.Dv GSS_S_NO_CRED. 272.It context_handle 273context handle for new context. Supply 274.Dv GSS_C_NO_CONTEXT for first call; use value 275returned by first call in continuation calls. 276Resources associated with this context-handle 277must be released by the application after use 278with a call to 279.Fn gss_delete_sec_context . 280.It target_name 281Name of target 282.It mech_type 283Object ID of desired mechanism. Supply 284.Dv GSS_C_NO_OID to obtain an implementation 285specific default 286.It req_flags 287Contains various independent flags, each of 288which requests that the context support a 289specific service option. Symbolic 290names are provided for each flag, and the 291symbolic names corresponding to the required 292flags should be logically-ORed 293together to form the bit-mask value. The 294flags are: 295.Bl -tag -width "WW" 296.It GSS_C_DELEG_FLAG 297.Bl -tag -width "False" 298.It True 299Delegate credentials to remote peer 300.It False 301Don't delegate 302.El 303.It GSS_C_MUTUAL_FLAG 304.Bl -tag -width "False" 305.It True 306Request that remote peer authenticate itself 307.It False 308Authenticate self to remote peer only 309.El 310.It GSS_C_REPLAY_FLAG 311.Bl -tag -width "False" 312.It True 313Enable replay detection for messages protected with 314.Xr gss_wrap 3 315or 316.Xr gss_get_mic 3 317.It False 318Don't attempt to detect replayed messages 319.El 320.It GSS_C_SEQUENCE_FLAG 321.Bl -tag -width "False" 322.It True 323Enable detection of out-of-sequence protected messages 324.It False 325Don't attempt to detect out-of-sequence messages 326.El 327.It GSS_C_CONF_FLAG 328.Bl -tag -width "False" 329.It True 330Request that confidentiality service be made available (via 331.Xr gss_wrap 3 ) 332.It False 333No per-message confidentiality service is required. 334.El 335.It GSS_C_INTEG_FLAG 336.Bl -tag -width "False" 337.It True 338Request that integrity service be made available (via 339.Xr gss_wrap 3 340or 341.Xr gss_get_mic 3 ) 342.It False 343No per-message integrity service is required. 344.El 345.It GSS_C_ANON_FLAG 346.Bl -tag -width "False" 347.It True 348Do not reveal the initiator's identity to the acceptor. 349.It False 350Authenticate normally. 351.El 352.El 353.It time_req 354Desired number of seconds for which context 355should remain valid. Supply 0 to request a 356default validity period. 357.It input_chan_bindings 358Application-specified bindings. Allows 359application to securely bind channel 360identification information to the security 361context. Specify 362.Dv GSS_C_NO_CHANNEL_BINDINGS 363if channel bindings are not used. 364.It input_token 365Token received from peer application. 366Supply 367.Dv GSS_C_NO_BUFFER, or a pointer to 368a buffer containing the value 369.Dv GSS_C_EMPTY_BUFFER 370on initial call. 371.It actual_mech_type 372Actual mechanism used. The OID returned via 373this parameter will be a pointer to static 374storage that should be treated as read-only; 375In particular the application should not attempt 376to free it. Specify 377.Dv NULL if not required. 378.It output_token 379token to be sent to peer application. If 380the length field of the returned buffer is 381zero, no token need be sent to the peer 382application. Storage associated with this 383buffer must be freed by the application 384after use with a call to 385.Xr gss_release_buffer 3 . 386.It ret_flags 387Contains various independent flags, each of which 388indicates that the context supports a specific 389service option. Specify 390.Dv NULL if not 391required. Symbolic names are provided 392for each flag, and the symbolic names 393corresponding to the required flags should be 394logically-ANDed with the 395.Fa ret_flags 396value to test 397whether a given option is supported by the 398context. The flags are: 399.Bl -tag -width "WW" 400.It GSS_C_DELEG_FLAG 401.Bl -tag -width "False" 402.It True 403Credentials were delegated to the remote peer 404.It False 405No credentials were delegated 406.El 407.It GSS_C_MUTUAL_FLAG 408.Bl -tag -width "False" 409.It True 410The remote peer has authenticated itself. 411.It False 412Remote peer has not authenticated itself. 413.El 414.It GSS_C_REPLAY_FLAG 415.Bl -tag -width "False" 416.It True 417Replay of protected messages will be detected 418.It False 419Replayed messages will not be detected 420.El 421.It GSS_C_SEQUENCE_FLAG 422.Bl -tag -width "False" 423.It True 424Out-of-sequence protected messages will be detected 425.It False 426Out-of-sequence messages will not be detected 427.El 428.It GSS_C_CONF_FLAG 429.Bl -tag -width "False" 430.It True 431Confidentiality service may be invoked by calling 432.Xr gss_wrap 3 433routine 434.It False 435No confidentiality service (via 436.Xr gss_wrap 3 ) available. 437.Xr gss_wrap 3 will 438provide message encapsulation, 439data-origin authentication and 440integrity services only. 441.El 442.It GSS_C_INTEG_FLAG 443.Bl -tag -width "False" 444.It True 445Integrity service may be invoked by calling either 446.Xr gss_get_mic 3 447or 448.Xr gss_wrap 3 449routines. 450.It False 451Per-message integrity service unavailable. 452.El 453.It GSS_C_ANON_FLAG 454.Bl -tag -width "False" 455.It True 456The initiator's identity has not been 457revealed, and will not be revealed if 458any emitted token is passed to the 459acceptor. 460.It False 461The 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 466Protection services (as specified by the states of the 467.Dv GSS_C_CONF_FLAG 468and 469.Dv GSS_C_INTEG_FLAG ) are available for 470use if the accompanying major status 471return value is either 472.Dv GSS_S_COMPLETE 473or 474.Dv GSS_S_CONTINUE_NEEDED. 475.It False 476Protection services (as specified by the states of the 477.Dv GSS_C_CONF_FLAG 478and 479.Dv GSS_C_INTEG_FLAG ) are available 480only if the accompanying major status 481return value is 482.Dv GSS_S_COMPLETE. 483.El 484.It GSS_C_TRANS_FLAG 485.Bl -tag -width "False" 486.It True 487The resultant security context may be transferred to other processes via 488a call to 489.Fn gss_export_sec_context . 490.It False 491The security context is not transferable. 492.El 493.El 494.Pp 495All other bits should be set to zero. 496.It time_rec 497Number of seconds for which the context 498will remain valid. If the implementation does 499not 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 506Successful completion 507.It GSS_S_CONTINUE_NEEDED 508Indicates that a token from the peer 509application is required to complete the 510context, and that gss_init_sec_context 511must be called again with that token. 512.It GSS_S_DEFECTIVE_TOKEN 513Indicates that consistency checks performed 514on the input_token failed 515.It GSS_S_DEFECTIVE_CREDENTIAL 516Indicates that consistency checks 517performed on the credential failed. 518.It GSS_S_NO_CRED 519The supplied credentials were not valid for 520context initiation, or the credential handle 521did not reference any credentials. 522.It GSS_S_CREDENTIALS_EXPIRED 523The referenced credentials have expired 524.It GSS_S_BAD_BINDINGS 525The input_token contains different channel 526bindings to those specified via the 527input_chan_bindings parameter 528.It GSS_S_BAD_SIG 529The input_token contains an invalid MIC, or a MIC 530that could not be verified 531.It GSS_S_OLD_TOKEN 532The input_token was too old. This is a fatal 533error during context establishment 534.It GSS_S_DUPLICATE_TOKEN 535The input_token is valid, but is a duplicate 536of a token already processed. This is a 537fatal error during context establishment. 538.It GSS_S_NO_CONTEXT 539Indicates that the supplied context handle did 540not refer to a valid context 541.It GSS_S_BAD_NAMETYPE 542The provided target_name parameter contained an 543invalid or unsupported type of name 544.It GSS_S_BAD_NAME 545The provided target_name parameter was ill-formed. 546.It GSS_S_BAD_MECH 547The specified mechanism is not supported by the 548provided credential, or is unrecognized by the 549implementation. 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 560Generic Security Service Application Program Interface Version 2, Update 1 561.It RFC 2744 562Generic Security Service API Version 2 : C-bindings 563.El 564.\" .Sh HISTORY 565.Sh HISTORY 566The 567.Nm 568manual page example first appeared in 569.Fx 7.0 . 570.Sh AUTHORS 571John Wray, Iris Associates 572