idnits 2.17.1 draft-kaduk-kitten-gss-loop-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 21, 2013) is 3834 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Kaduk 3 Internet-Draft MIT 4 Intended status: Standards Track October 21, 2013 5 Expires: April 24, 2014 7 Structure of the GSS Negotiation Loop 8 draft-kaduk-kitten-gss-loop-00 10 Abstract 12 This document specifies the generic structure of the negotiation loop 13 to establish a GSS security context between initiator and acceptor. 14 The control flow of the loop is indicated for both parties, including 15 error conditions, and indications are given for where application- 16 specific behavior must be specified. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on April 24, 2014. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 1. Introduction 52 The Generic Security Service Application Program Intervace version 2 53 [RFC2743] provides a generic interface for security services, in the 54 form of an abstraction layer over the underlying security mechanisms 55 that an application may use. A GSS initiator and acceptor exchange 56 messages, called tokens, until a security context is established. 57 Such a security context allows for mutual authentication of the two 58 parties, the passing of confidential or integrity-protected messages 59 between the initiator and acceptor, the generation of identical 60 pseudo-random bit strings by both participants [RFC4401], and more. 61 The number of tokens which must be exchanged between initiator and 62 acceptor in order to establish the security context is dependent on 63 the underlying mechanism as well as the desired properties of the 64 security context, and is in general not known to the application. 65 Accordingly, the application's control flow must include a loop 66 within which GSS security context tokens are exchanged, which 67 terminates upon successful establishment of a security context (or an 68 error condition). 70 The GSS-API C bindings [RFC2744] provide some example code for such a 71 negotiation loop, but this code does not specify the application's 72 behavior on unexpected or error conditions. As such, individual 73 application protocol specifications have had to specify the structure 74 of their GSS negotiation loops, including error handling, on a per- 75 protocol basis. [RFC4462], [RFC3645], [RFC5801], [RFC4752], 76 [RFC2203] This represents a substantial duplication of effort, and 77 the various specifications go into different levels of detail and 78 describe different possible error conditions. It is therefore 79 preferable to have the structure of the GSS negotiation loop, 80 including error conditions and token passing, described in a single 81 specification, which can then be referred to from other documents in 82 lieu of repeating the structure of the loop each time. This document 83 will perform that role. 85 1.1. Requirements Language 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 89 document are to be interpreted as described in [RFC2119]. 91 2. Loop Structure 93 The loop is begun by the appropriately named initiator, which calls 94 GSS_Init_sec_context() with an empty (zero-length) input_token and a 95 fixed set of input flags containing the desired attributes for the 96 security context. The initiator MUST NOT change any of the input 97 parameters to GSS_Init_sec_context() between calls to it during the 98 loop, with the exception of the input_token parameter, which will 99 contain a message from the acceptor after the initial call, and the 100 input_context_handle, which MUST be the result returned in the 101 output_context_handle of the previous call to GSS_Init_sec_context() 102 (or GSS_C_NO_CONTEXT for the first call). 104 The following subsections will describe the various steps of the 105 loop, without special consideration to whether a call to 106 GSS_Init_sec_context() or GSS_Accept_sec_context() is the first such 107 call in the loop. For the first call to each routine in the loop, 108 the major status code from the previous call to 109 GSS_Init_sec_context() or GSS_Accept_sec_context() should be taken as 110 GSS_S_CONTINUE_NEEDED. 112 2.1. Anonymous Initiators 114 If the initiator is requesting anonymity by setting the anon_req_flag 115 input to GSS_Init_sec_context(), then on non-error returns from 116 GSS_Init_sec_context() (that is, the major status is GSS_S_COMPLETE 117 or GSS_S_CONTINUE_NEEDED), the initiator MUST verify that the output 118 value of anon_state from GSS_Init_sec_context() is true before 119 sending the security context token to the acceptor. Failing to 120 perform this check could cause the initiator to lose anonymity. 122 2.2. GSS_Init_sec_context 124 The initiator calls GSS_Init_sec_context(), using the 125 input_context_handle for the current proto-security-context and its 126 fixed set of input parameters, and the input_token received from the 127 acceptor (if not the first iteration of the loop). The presence of a 128 nonempty output_token and the value of the major status code are the 129 indicators for how to proceed: 131 If the major status code is GSS_S_COMPLETE and the output_token is 132 empty, then the context negotiation is fully complete and ready 133 for use by the initiator with no further actions. 135 If the major status code is GSS_S_COMPLETE and the output_token is 136 nonempty, then the initiator's portion of the security context 137 negotiation is complete but the acceptor's is not. The initiator 138 MUST send the output_token to the acceptor so that the acceptor 139 can establish its half of the security context. 141 If the major status code is GSS_S_CONTINUE_NEEDED and the 142 output_token is nonempty, the context negotiation is incomplete. 143 The initiator MUST send the output_token to the acceptor and await 144 another input_token from the acceptor. 146 If the major status code is GSS_S_CONTINUE_NEEDED and the 147 output_token is empty, the mechanism has produced an inconsistent 148 output and the security context negotiation has failed. The 149 initiator SHOULD indicate the failure to the acceptor if an 150 appropriate channel to do so is available. 152 If the major status code is any other value, the context 153 negotiation has failed. If the output_token is nonempty, it is an 154 error token, and the initiator SHOULD send it to the acceptor. If 155 the output_token is empty, then the initiator SHOULD indicate the 156 failure to the acceptor if an appropriate channel to do so is 157 available. 159 2.3. Sending from Initiator to Acceptor 161 The establishment of a GSS security context between initiator and 162 acceptor requires some communication channel by which to exchange the 163 context negotiation tokens. The nature of this channel is not 164 specified by the GSS specification -- it could be a synchronous TCP 165 channel, a UDP-based RPC protocol, or any other sort of channel. In 166 many cases, the channel will be multiplexed with non-GSS application 167 data; the application protocol must provide some means by which the 168 GSS context tokens can be identified and passed through to the 169 mechanism accordingly. It is in such cases where the application 170 protocol has a means to indicate error conditions that the initiator 171 could indicate a failure to the acceptor, as mentioned in some of the 172 above cases conditional on "an appropriate channel to do so". 174 However, even the presence of a communication channel does not 175 necessarily indicate that it is appropriate for the initiator to 176 indicate such errors. For example, if the acceptor is a stateless or 177 near-stateless UDP server, there is probably no need for the 178 initiator to explicitly indicate its failure to the acceptor. 179 Conditions such as this can be treated in individual application 180 protocol specifications. 182 If a regular security context output_token is produced by the call to 183 GSS_Init_sec_context(), the initiator MUST transmit this token to the 184 acceptor over the application's communication channel. If the call 185 to GSS_Init_sec_context() returns an error token as output_token, it 186 is RECOMMENDED that the intiator transmit this token to the acceptor 187 over the application's communication channel. 189 2.4. Acceptor Sanity Checking 191 The acceptor's half of the negotiation loop is triggered by the 192 receipt of a context token from the initiator. Before calling 193 GSS_Accept_sec_context(), the acceptor may find it useful to perform 194 some sanity checks on the state of the negotiation loop. 196 If the acceptor receives a context token but was not expecting such a 197 token (for example, if the acceptor's previous call to 198 GSS_Accept_sec_context() returned GSS_S_COMPLETE), this is an error 199 condition indicating that the initiator's state is invalid. It is 200 likely appropriate for the acceptor to report this error condition to 201 the acceptor via the application's communication channel. 203 If the acceptor is expecting a context token (e.g., if the previous 204 call to GSS_Accept_sec_context() returned GSS_S_CONTINUE_NEEDED), but 205 does not receive such a token within a reasonable amount of time 206 after transmitting the previous output_token to the initiator, the 207 acceptor should assume that the initiator's state is invalid and fail 208 the GSS negotiation. Again, it is likely appropriate for the 209 acceptor to report this error condition to the initiator via the 210 application's communication channel. 212 [Are there other checks to perform here?] 214 2.5. GSS_Accept_sec_context 216 The GSS acceptor responds to the actions of an initiator; as such, 217 there should always be a nonempty input_token to calls to 218 GSS_Accept_sec_context(). The input_context_handle parameter will 219 always be given as the output_context_handle from the previous call 220 to GSS_Accept_sec_context() in a given negotiation loop (or 221 GSS_C_NO_CONTEXT on the first call), but the acceptor_cred_handle and 222 chan_bindings arguments MUST remain fixed over the course of a given 223 GSS negotiation loop. 225 The GSS acceptor calls GSS_Accept_sec_context(), using the 226 input_context_handle for the current proto-security-context and the 227 input_token received from the initiator. The presence of a nonempty 228 output_token and the value of the major status code are the 229 indicators for how to proceed: 231 If the major status code is GSS_S_COMPLETE and the output_token is 232 empty, then the context negotiation is fully complete and ready 233 for use by the acceptor with no further actions. 235 If the major status code is GSS_S_COMPLETE and the output_token is 236 nonempty, then the acceptor's portion of the security context 237 negotiation is complete but the initiator's is not. The acceptor 238 MUST send the output_token to the initiator so that the initiator 239 can establish its half of the security context. 241 If the major status code is GSS_S_CONTINUE_NEEDED and the 242 output_token is nonempty, the context negotiation is incomplete. 243 The acceptor MUST send the output_token to the initiator and await 244 another input_token from the initiator. 246 If the major status code is GSS_S_CONTINUE_NEEDED and the 247 output_token is empty, the mechanism has produced an inconsistent 248 output and the security context negotiation has failed. The 249 acceptor SHOULD indicate the failure to the initiator if an 250 appropriate channel to do so is available. 252 If the major status code is any other value, the context 253 negotiation has failed. If the output_token is nonempty, it is an 254 error token, and the acceptor SHOULD send it to the initiator. If 255 the output_token is empty, then the acceptor SHOULD indicate the 256 failure to the initiator if an appropriate channel to do so is 257 available. 259 2.6. Sending from Acceptor to Initiator 261 The mechanism for sending the context token from acceptor to 262 initiator will depend on the nature of the communication channel 263 between the two parties. For a synchronous bidirectional channel, it 264 can be just another piece of data sent over the link, but for a 265 stateless UDP RPC acceptor, the token will probably end up being sent 266 as an RPC output parameter. Application protocol specifications will 267 need to specify the nature of this behavior. 269 If the application protocol has the initiator driving the 270 application's control flow (with the acceptor just responding to 271 actions from the initiator), it is particularly helpful for the 272 acceptor to indicate a failure to the initiator, as mentioned in some 273 of the above cases conditional on "an appropriate channel to do so". 275 If a regular security context output_token is produced by the call to 276 GSS_Accept_sec_context(), the acceptor MUST transmit this token to 277 the initiator over the application's communication channel. If the 278 call to GSS_Accept_sec_context() returns an error token as 279 output_token, it is RECOMMENDED that the acceptor transmit this token 280 to the initiator over the application's communication channel. 282 2.7. Initiator input validation 283 The initiator's half of the negotiation loop is triggered (after the 284 first call) by receipt of a context token from the acceptor. Before 285 calling GSS_Init_sec_context(), the initiator may find it useful to 286 perform some sanity checks on the state of the negotiation loop. 288 If the initiator receives a context token but was not expecting such 289 a token (for example, if the initiator's previous call to 290 GSS_Init_sec_context() returned GSS_S_COMPLETE), this is an error 291 condition indicating that the acceptor's state is invalid. It may be 292 appropriate for the initiator to report this error condition to the 293 acceptor via the application's communication channel. 295 If the initiator is expecting a context token (that is, the previous 296 call to GSS_Init_sec_context() returned GSS_S_CONTINUE_NEEDED), but 297 does not receive such a token within a reasonable amount of time 298 after transmitting the previous output_token to the acceptor, the 299 initiator should assume that the acceptor's state is invalid and fail 300 the GSS negotiation. Again, it may be appropriate for the initiator 301 to report this error condition to the acceptor via the application's 302 communication channel. 304 [Are there other checks to perform here?] 306 2.8. Continue the Loop 308 If the loop is in neither a success or failure condition, then the 309 loop must continue. Control flow returns to Section 2.2. 311 3. After Security Context Negotiation 313 Once a party has completed its half of the security context and 314 fulfilled its obligations to the other party, the context is 315 complete, but it is not necessarily ready and appropriate for use. 316 (In some cases the context may be ready for use earlier than this, 317 see Section 3.1.) In particular, the security context flags may not 318 be appropriate for the given application's use. 320 The initiator specifies as part of its fixed set of inputs to 321 GSS_Init_sec_context() values for the following booleans: 322 deleg_req_flag, mutual_req_flag, replay_det_req_flag, 323 sequence_req_flag, conf_req_flag, and integ_req_flag. Upon 324 completion of security context negotiation, the initiator MUST verify 325 the values of the deleg_state, mutual_state, replay_det_state, 326 sequence_state, conf_avail, and integ_avail flags from the last call 327 to GSS_Init_sec_context() corresponding to the requested flags. If a 328 flag was requested but is not available, and that feature is 329 necessary for the appplication protocol, the initiator MUST destroy 330 the security context and not use the security context for application 331 traffic. 333 Application protocol specifications citing this document MUST 334 indicate which context flags are required for the application 335 protocol. 337 The acceptor receives as output the following booleans: deleg_state, 338 mutual_state, replay_det_state, sequence_state, anon_state, 339 trans_state, conf_avail, and integ_avail. The acceptor MUST verify 340 that any flags necessary for the application protocol are set. If a 341 necessary flag is not set, the acceptor MUST destroy the security 342 context and not use the security context for application traffic. 344 3.1. Using Partially Complete Security Contexts 346 For mechanism/flag combinations that require multiple token 347 exchanges, an application protocol may find it desirable to begin 348 sending application data protected with GSS per-message operations 349 while continuing to exchange security context tokens to complete the 350 security context negotiation. The prot_ready_state output value from 351 GSS_Init_sec_context() and GSS_Accept_sec_context() indicates when 352 per-message operations are avaialble. 354 Applications requiring confidentiality and/or integrity protection 355 from such messages MUST check the value of the conf_avail and/or 356 integ_avail output flags from GSS_Init_sec_context()/ 357 GSS_Accept_sec_context() as well as the conf_state output of 358 GSS_Wrap() (if GSS_Wrap() is used). 360 4. References 362 4.1. Normative References 364 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 365 Requirement Levels", BCP 14, RFC 2119, March 1997. 367 [RFC2743] Linn, J., "Generic Security Service Application Program 368 Interface Version 2, Update 1", RFC 2743, January 2000. 370 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 371 C-bindings", RFC 2744, January 2000. 373 [RFC4401] Williams, N., "A Pseudo-Random Function (PRF) API 374 Extension for the Generic Security Service Application 375 Program Interface (GSS-API)", RFC 4401, February 2006. 377 4.2. Informational References 379 [RFC4462] Hutzelman, J., Salowey, J., Galbraith, J., and V. Welch, 380 "Generic Security Service Application Program Interface 381 (GSS-API) Authentication and Key Exchange for the Secure 382 Shell (SSH) Protocol", RFC 4462, May 2006. 384 [RFC3645] Kwan, S., Garg, P., Gilroy, J., Esibov, L., Westhead, J., 385 and R. Hall, "Generic Security Service Algorithm for 386 Secret Key Transaction Authentication for DNS (GSS-TSIG)", 387 RFC 3645, October 2003. 389 [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security 390 Service Application Program Interface (GSS-API) Mechanisms 391 in Simple Authentication and Security Layer (SASL): The 392 GS2 Mechanism Family", RFC 5801, July 2010. 394 [RFC4752] Melnikov, A., "The Kerberos V5 ("GSSAPI") Simple 395 Authentication and Security Layer (SASL) Mechanism", RFC 396 4752, November 2006. 398 [RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol 399 Specification", RFC 2203, September 1997. 401 Appendix A. Acknowledgements 403 Acknowledgements. 405 Author's Address 407 Benjamin Kaduk 408 MIT Kerberos Consortium 410 Email: kaduk@mit.edu