doc/specification/draft-ietf-sasl-gssapi-08.txt

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