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