1 2 3 4 5 6 7Network Working Group A. Melnikov, Ed. 8Request for Comments: 4752 Isode 9Obsoletes: 2222 November 2006 10Category: Standards Track 11 12 13 The Kerberos V5 ("GSSAPI") 14 Simple Authentication and Security Layer (SASL) Mechanism 15 16Status of This Memo 17 18 This document specifies an Internet standards track protocol for the 19 Internet community, and requests discussion and suggestions for 20 improvements. Please refer to the current edition of the "Internet 21 Official Protocol Standards" (STD 1) for the standardization state 22 and status of this protocol. Distribution of this memo is unlimited. 23 24Copyright Notice 25 26 Copyright (C) The IETF Trust (2006). 27 28Abstract 29 30 The Simple Authentication and Security Layer (SASL) is a framework 31 for adding authentication support to connection-based protocols. 32 This document describes the method for using the Generic Security 33 Service Application Program Interface (GSS-API) Kerberos V5 in the 34 SASL. 35 36 This document replaces Section 7.2 of RFC 2222, the definition of the 37 "GSSAPI" SASL mechanism. This document, together with RFC 4422, 38 obsoletes RFC 2222. 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58Melnikov Standards Track [Page 1] 59 60RFC 4752 SASL GSSAPI Mechanism November 2006 61 62 63Table of Contents 64 65 1. Introduction ....................................................2 66 1.1. Relationship to Other Documents ............................2 67 2. Conventions Used in This Document ...............................2 68 3. Kerberos V5 GSS-API Mechanism ...................................2 69 3.1. Client Side of Authentication Protocol Exchange ............3 70 3.2. Server Side of Authentication Protocol Exchange ............4 71 3.3. Security Layer .............................................6 72 4. IANA Considerations .............................................7 73 5. Security Considerations .........................................7 74 6. Acknowledgements ................................................8 75 7. Changes since RFC 2222 ..........................................8 76 8. References ......................................................8 77 8.1. Normative References .......................................8 78 8.2. Informative References .....................................9 79 801. Introduction 81 82 This specification documents currently deployed Simple Authentication 83 and Security Layer (SASL [SASL]) mechanism supporting the Kerberos V5 84 [KERBEROS] Generic Security Service Application Program Interface 85 ([GSS-API]) mechanism [RFC4121]. The authentication sequence is 86 described in Section 3. Note that the described authentication 87 sequence has known limitations, in particular, it lacks channel 88 bindings and the number of round-trips required to complete 89 authentication exchange is not minimal. SASL WG is working on a 90 separate document that should address these limitations. 91 921.1. Relationship to Other Documents 93 94 This document, together with RFC 4422, obsoletes RFC 2222 in its 95 entirety. This document replaces Section 7.2 of RFC 2222. The 96 remainder is obsoleted as detailed in Section 1.2 of RFC 4422. 97 982. Conventions Used in This Document 99 100 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" 101 in this document are to be interpreted as defined in "Key words for 102 use in RFCs to Indicate Requirement Levels" [KEYWORDS]. 103 1043. Kerberos V5 GSS-API Mechanism 105 106 The SASL mechanism name for the Kerberos V5 GSS-API mechanism 107 [RFC4121] is "GSSAPI". Though known as the SASL GSSAPI mechanism, 108 the mechanism is specifically tied to Kerberos V5 and GSS-API's 109 Kerberos V5 mechanism. 110 111 112 113 114Melnikov Standards Track [Page 2] 115 116RFC 4752 SASL GSSAPI Mechanism November 2006 117 118 119 The GSSAPI SASL mechanism is a "client goes first" SASL mechanism; 120 i.e., it starts with the client sending a "response" created as 121 described in the following section. 122 123 The implementation MAY set any GSS-API flags or arguments not 124 mentioned in this specification as is necessary for the 125 implementation to enforce its security policy. 126 127 Note that major status codes returned by GSS_Init_sec_context() or 128 GSS_Accept_sec_context() other than GSS_S_COMPLETE or 129 GSS_S_CONTINUE_NEEDED cause authentication failure. Major status 130 codes returned by GSS_Unwrap() other than GSS_S_COMPLETE (without any 131 additional supplementary status codes) cause authentication and/or 132 security layer failure. 133 1343.1. Client Side of Authentication Protocol Exchange 135 136 The client calls GSS_Init_sec_context, passing in 137 input_context_handle of 0 (initially), mech_type of the Kerberos V5 138 GSS-API mechanism [KRB5GSS], chan_binding of NULL, and targ_name 139 equal to output_name from GSS_Import_Name called with input_name_type 140 of GSS_C_NT_HOSTBASED_SERVICE (*) and input_name_string of 141 "service@hostname" where "service" is the service name specified in 142 the protocol's profile, and "hostname" is the fully qualified host 143 name of the server. When calling the GSS_Init_sec_context, the 144 client MUST pass the integ_req_flag of TRUE (**). If the client will 145 be requesting a security layer, it MUST also supply to the 146 GSS_Init_sec_context a mutual_req_flag of TRUE, and a 147 sequence_req_flag of TRUE. If the client will be requesting a 148 security layer providing confidentiality protection, it MUST also 149 supply to the GSS_Init_sec_context a conf_req_flag of TRUE. The 150 client then responds with the resulting output_token. If 151 GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED, then the client 152 should expect the server to issue a token in a subsequent challenge. 153 The client must pass the token to another call to 154 GSS_Init_sec_context, repeating the actions in this paragraph. 155 156 (*) Clients MAY use name types other than GSS_C_NT_HOSTBASED_SERVICE 157 to import servers' acceptor names, but only when they have a priori 158 knowledge that the servers support alternate name types. Otherwise 159 clients MUST use GSS_C_NT_HOSTBASED_SERVICE for importing acceptor 160 names. 161 162 (**) Note that RFC 2222 [RFC2222] implementations will not work with 163 GSS-API implementations that require integ_req_flag to be true. No 164 implementations of RFC 1964 [KRB5GSS] or RFC 4121 [RFC4121] that 165 require integ_req_flag to be true are believed to exist and it is 166 expected that any future update to [RFC4121] will require that 167 168 169 170Melnikov Standards Track [Page 3] 171 172RFC 4752 SASL GSSAPI Mechanism November 2006 173 174 175 integrity be available even in not explicitly requested by the 176 application. 177 178 When GSS_Init_sec_context returns GSS_S_COMPLETE, the client examines 179 the context to ensure that it provides a level of protection 180 permitted by the client's security policy. In particular, if the 181 integ_avail flag is not set in the context, then no security layer 182 can be offered or accepted. 183 184 If the conf_avail flag is not set in the context, then no security 185 layer with confidentiality can be offered or accepted. If the 186 context is acceptable, the client takes the following actions: If the 187 last call to GSS_Init_sec_context returned an output_token, then the 188 client responds with the output_token, otherwise the client responds 189 with no data. The client should then expect the server to issue a 190 token in a subsequent challenge. The client passes this token to 191 GSS_Unwrap and interprets the first octet of resulting cleartext as a 192 bit-mask specifying the security layers supported by the server and 193 the second through fourth octets as the maximum size output_message 194 the server is able to receive (in network byte order). If the 195 resulting cleartext is not 4 octets long, the client fails the 196 negotiation. The client verifies that the server maximum buffer is 0 197 if the server does not advertise support for any security layer. 198 199 The client then constructs data, with the first octet containing the 200 bit-mask specifying the selected security layer, the second through 201 fourth octets containing in network byte order the maximum size 202 output_message the client is able to receive (which MUST be 0 if the 203 client does not support any security layer), and the remaining octets 204 containing the UTF-8 [UTF8] encoded authorization identity. 205 (Implementation note: The authorization identity is not terminated 206 with the zero-valued (%x00) octet (e.g., the UTF-8 encoding of the 207 NUL (U+0000) character)). The client passes the data to GSS_Wrap 208 with conf_flag set to FALSE and responds with the generated 209 output_message. The client can then consider the server 210 authenticated. 211 2123.2. Server Side of Authentication Protocol Exchange 213 214 A server MUST NOT advertise support for the "GSSAPI" SASL mechanism 215 described in this document unless it has acceptor credential for the 216 Kerberos V GSS-API mechanism [KRB5GSS]. 217 218 The server passes the initial client response to 219 GSS_Accept_sec_context as input_token, setting input_context_handle 220 to 0 (initially), chan_binding of NULL, and a suitable 221 acceptor_cred_handle (see below). If GSS_Accept_sec_context returns 222 GSS_S_CONTINUE_NEEDED, the server returns the generated output_token 223 224 225 226Melnikov Standards Track [Page 4] 227 228RFC 4752 SASL GSSAPI Mechanism November 2006 229 230 231 to the client in challenge and passes the resulting response to 232 another call to GSS_Accept_sec_context, repeating the actions in this 233 paragraph. 234 235 Servers SHOULD use a credential obtained by calling GSS_Acquire_cred 236 or GSS_Add_cred for the GSS_C_NO_NAME desired_name and the Object 237 Identifier (OID) of the Kerberos V5 GSS-API mechanism [KRB5GSS](*). 238 Servers MAY use GSS_C_NO_CREDENTIAL as an acceptor credential handle. 239 Servers MAY use a credential obtained by calling GSS_Acquire_cred or 240 GSS_Add_cred for the server's principal name(s) (**) and the Kerberos 241 V5 GSS-API mechanism [KRB5GSS]. 242 243 (*) Unlike GSS_Add_cred the GSS_Acquire_cred uses an OID set of GSS- 244 API mechanism as an input parameter. The OID set can be created by 245 using GSS_Create_empty_OID_set and GSS_Add_OID_set_member. It can be 246 freed by calling the GSS_Release_oid_set. 247 248 249 (**) Use of server's principal names having 250 GSS_C_NT_HOSTBASED_SERVICE name type and "service@hostname" format, 251 where "service" is the service name specified in the protocol's 252 profile, and "hostname" is the fully qualified host name of the 253 server, is RECOMMENDED. The server name is generated by calling 254 GSS_Import_name with input_name_type of GSS_C_NT_HOSTBASED_SERVICE 255 and input_name_string of "service@hostname". 256 257 Upon successful establishment of the security context (i.e., 258 GSS_Accept_sec_context returns GSS_S_COMPLETE), the server SHOULD 259 verify that the negotiated GSS-API mechanism is indeed Kerberos V5 260 [KRB5GSS]. This is done by examining the value of the mech_type 261 parameter returned from the GSS_Accept_sec_context call. If the 262 value differs, SASL authentication MUST be aborted. 263 264 Upon successful establishment of the security context and if the 265 server used GSS_C_NO_NAME/GSS_C_NO_CREDENTIAL to create acceptor 266 credential handle, the server SHOULD also check using the 267 GSS_Inquire_context that the target_name used by the client matches 268 either 269 270 - the GSS_C_NT_HOSTBASED_SERVICE "service@hostname" name syntax, 271 where "service" is the service name specified in the application 272 protocol's profile, 273 274 or 275 276 - the GSS_KRB5_NT_PRINCIPAL_NAME [KRB5GSS] name syntax for a two- 277 component principal where the first component matches the service 278 name specified in the application protocol's profile. 279 280 281 282Melnikov Standards Track [Page 5] 283 284RFC 4752 SASL GSSAPI Mechanism November 2006 285 286 287 When GSS_Accept_sec_context returns GSS_S_COMPLETE, the server 288 examines the context to ensure that it provides a level of protection 289 permitted by the server's security policy. In particular, if the 290 integ_avail flag is not set in the context, then no security layer 291 can be offered or accepted. If the conf_avail flag is not set in the 292 context, then no security layer with confidentiality can be offered 293 or accepted. 294 295 If the context is acceptable, the server takes the following actions: 296 If the last call to GSS_Accept_sec_context returned an output_token, 297 the server returns it to the client in a challenge and expects a 298 reply from the client with no data. Whether or not an output_token 299 was returned (and after receipt of any response from the client to 300 such an output_token), the server then constructs 4 octets of data, 301 with the first octet containing a bit-mask specifying the security 302 layers supported by the server and the second through fourth octets 303 containing in network byte order the maximum size output_token the 304 server is able to receive (which MUST be 0 if the server does not 305 support any security layer). The server must then pass the plaintext 306 to GSS_Wrap with conf_flag set to FALSE and issue the generated 307 output_message to the client in a challenge. 308 309 The server must then pass the resulting response to GSS_Unwrap and 310 interpret the first octet of resulting cleartext as the bit-mask for 311 the selected security layer, the second through fourth octets as the 312 maximum size output_message the client is able to receive (in network 313 byte order), and the remaining octets as the authorization identity. 314 The server verifies that the client has selected a security layer 315 that was offered and that the client maximum buffer is 0 if no 316 security layer was chosen. The server must verify that the src_name 317 is authorized to act as the authorization identity. After these 318 verifications, the authentication process is complete. The server is 319 not expected to return any additional data with the success 320 indicator. 321 3223.3. Security Layer 323 324 The security layers and their corresponding bit-masks are as follows: 325 326 1 No security layer 327 2 Integrity protection. 328 Sender calls GSS_Wrap with conf_flag set to FALSE 329 4 Confidentiality protection. 330 Sender calls GSS_Wrap with conf_flag set to TRUE 331 332 Other bit-masks may be defined in the future; bits that are not 333 understood must be negotiated off. 334 335 336 337 338Melnikov Standards Track [Page 6] 339 340RFC 4752 SASL GSSAPI Mechanism November 2006 341 342 343 When decoding any received data with GSS_Unwrap, the major_status 344 other than the GSS_S_COMPLETE MUST be treated as a fatal error. 345 346 Note that SASL negotiates the maximum size of the output_message to 347 send. Implementations can use the GSS_Wrap_size_limit call to 348 determine the corresponding maximum size input_message. 349 3504. IANA Considerations 351 352 IANA modified the existing registration for "GSSAPI" as follows: 353 354 Family of SASL mechanisms: NO 355 356 SASL mechanism name: GSSAPI 357 358 Security considerations: See Section 5 of RFC 4752 359 360 Published specification: RFC 4752 361 362 Person & email address to contact for further information: 363 Alexey Melnikov <Alexey.Melnikov@isode.com> 364 365 Intended usage: COMMON 366 367 Owner/Change controller: iesg@ietf.org 368 369 Additional information: This mechanism is for the Kerberos V5 370 mechanism of GSS-API. 371 3725. Security Considerations 373 374 Security issues are discussed throughout this memo. 375 376 When constructing the input_name_string, the client SHOULD NOT 377 canonicalize the server's fully qualified domain name using an 378 insecure or untrusted directory service. 379 380 For compatibility with deployed software, this document requires that 381 the chan_binding (channel bindings) parameter to GSS_Init_sec_context 382 and GSS_Accept_sec_context be NULL, hence disallowing use of GSS-API 383 support for channel bindings. GSS-API channel bindings in SASL is 384 expected to be supported via a new GSS-API family of SASL mechanisms 385 (to be introduced in a future document). 386 387 Additional security considerations are in the [SASL] and [GSS-API] 388 specifications. Additional security considerations for the GSS-API 389 mechanism can be found in [KRB5GSS] and [KERBEROS]. 390 391 392 393 394Melnikov Standards Track [Page 7] 395 396RFC 4752 SASL GSSAPI Mechanism November 2006 397 398 3996. Acknowledgements 400 401 This document replaces Section 7.2 of RFC 2222 [RFC2222] by John G. 402 Myers. He also contributed significantly to this revision. 403 404 Lawrence Greenfield converted text of this document to the XML 405 format. 406 407 Contributions of many members of the SASL mailing list are gratefully 408 acknowledged, in particular comments from Chris Newman, Nicolas 409 Williams, Jeffrey Hutzelman, Sam Hartman, Mark Crispin, and Martin 410 Rex. 411 4127. Changes since RFC 2222 413 414 RFC 2078 [RFC2078] specifies the version of GSS-API used by RFC 2222 415 [RFC2222], which provided the original version of this specification. 416 That version of GSS-API did not provide the integ_integ_avail flag as 417 an input to GSS_Init_sec_context. Instead, integrity was always 418 requested. RFC 4422 [SASL] requires that when possible, the security 419 layer negotiation be integrity protected. To meet this requirement 420 and as part of moving from RFC 2078 [RFC2078] to RFC 2743 [GSS-API], 421 this specification requires that clients request integrity from 422 GSS_Init_sec_context so they can use GSS_Wrap to protect the security 423 layer negotiation. This specification does not require that the 424 mechanism offer the integrity security layer, simply that the 425 security layer negotiation be wrapped. 426 4278. References 428 4298.1. Normative References 430 431 [GSS-API] Linn, J., "Generic Security Service Application Program 432 Interface Version 2, Update 1", RFC 2743, January 2000. 433 434 [KERBEROS] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The 435 Kerberos Network Authentication Service (V5)", RFC 4120, 436 July 2005. 437 438 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 439 Requirement Levels", BCP 14, RFC 2119, March 1997. 440 441 [KRB5GSS] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 442 1964, June 1996. 443 444 445 446 447 448 449 450Melnikov Standards Track [Page 8] 451 452RFC 4752 SASL GSSAPI Mechanism November 2006 453 454 455 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 456 Version 5 Generic Security Service Application Program 457 Interface (GSS-API) Mechanism: Version 2", RFC 4121, July 458 2005. 459 460 [SASL] Melnikov, A. and K. Zeilenga, "Simple Authentication and 461 Security Layer (SASL)", RFC 4422, June 2006. 462 463 [UTF8] Yergeau, F., "UTF-8, a transformation format of ISO 464 10646", STD 63, RFC 3629, November 2003. 465 4668.2. Informative References 467 468 [RFC2078] Linn, J., "Generic Security Service Application Program 469 Interface, Version 2", RFC 2078, January 1997. 470 471 [RFC2222] Myers, J., "Simple Authentication and Security Layer 472 (SASL)", RFC 2222, October 1997. 473 474Editor's Address 475 476 Alexey Melnikov 477 Isode Limited 478 5 Castle Business Village 479 36 Station Road 480 Hampton, Middlesex TW12 2BX 481 UK 482 483 EMail: Alexey.Melnikov@isode.com 484 URI: http://www.melnikov.ca/ 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506Melnikov Standards Track [Page 9] 507 508RFC 4752 SASL GSSAPI Mechanism November 2006 509 510 511Full Copyright Statement 512 513 Copyright (C) The IETF Trust (2006). 514 515 This document is subject to the rights, licenses and restrictions 516 contained in BCP 78, and except as set forth therein, the authors 517 retain all their rights. 518 519 This document and the information contained herein are provided on an 520 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 521 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, 522 AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, 523 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT 524 THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY 525 IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR 526 PURPOSE. 527 528Intellectual Property 529 530 The IETF takes no position regarding the validity or scope of any 531 Intellectual Property Rights or other rights that might be claimed to 532 pertain to the implementation or use of the technology described in 533 this document or the extent to which any license under such rights 534 might or might not be available; nor does it represent that it has 535 made any independent effort to identify any such rights. Information 536 on the procedures with respect to rights in RFC documents can be 537 found in BCP 78 and BCP 79. 538 539 Copies of IPR disclosures made to the IETF Secretariat and any 540 assurances of licenses to be made available, or the result of an 541 attempt made to obtain a general license or permission for the use of 542 such proprietary rights by implementers or users of this 543 specification can be obtained from the IETF on-line IPR repository at 544 http://www.ietf.org/ipr. 545 546 The IETF invites any interested party to bring to its attention any 547 copyrights, patents or patent applications, or other proprietary 548 rights that may cover technology that may be required to implement 549 this standard. Please address the information to the IETF at 550 ietf-ipr@ietf.org. 551 552Acknowledgement 553 554 Funding for the RFC Editor function is currently provided by the 555 Internet Society. 556 557 558 559 560 561 562Melnikov Standards Track [Page 10] 563 564