RFC 4752

The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism

📅 published November 2006, from ietf

The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism 🎀

okay bestie, this is RFC 4752 💖 It's a Standards Track doc, so it's the real deal 😤 A. Melnikov, Ed. wrote it at Isode, it's dated November 2006, and the copyright belongs to the IETF Trust. The main thing to know is that it obsoletes RFC 2222 (together with RFC 4422). It replaces the "GSSAPI" bit that lived in RFC 2222 Section 7.2, so it's giving glow-up 🦋

Status of This Memo 📜

This is a standards track protocol for the Internet community, and the authors want your discussion and suggestions for improvements 🗣️ For the standardization state and status, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited ✨

Copyright Notice ⚖️

Abstract 🌈

The Simple Authentication and Security Layer (SASL) is a framework for adding authentication support to connection-based protocols 🧚 This doc describes how to use the Generic Security Service Application Program Interface (GSS-API) Kerberos V5 in SASL.

This doc replaces Section 7.2 of RFC 2222, which defined the "GSSAPI" SASL mechanism. Together with RFC 4422, it obsoletes RFC 2222 💅

Table of Contents 📚

   1. Introduction ....................................................2
      1.1. Relationship to Other Documents ............................2
   2. Conventions Used in This Document ...............................2
   3. Kerberos V5 GSS-API Mechanism ...................................2
      3.1. Client Side of Authentication Protocol Exchange ............3
      3.2. Server Side of Authentication Protocol Exchange ............4
      3.3. Security Layer .............................................6
   4. IANA Considerations .............................................7
   5. Security Considerations .........................................7
   6. Acknowledgements ................................................8
   7. Changes since RFC 2222 ..........................................8
   8. References ......................................................8
      8.1. Normative References .......................................8
      8.2. Informative References .....................................9

1. Introduction ✨

okay so this spec documents a Simple Authentication and Security Layer (SASL [SASL]) mechanism that's already currently deployed out in the wild 🔥 It supports the Kerberos V5 [KERBEROS] Generic Security Service Application Program Interface ([GSS-API]) mechanism [RFC4121]. The auth sequence is covered in Section 3.

heads up: the auth sequence has known limitations. It lacks channel bindings, and the number of round-trips needed to finish the auth exchange isn't minimal 💀 The SASL WG is working on a separate doc that should address these limitations 🫶

1.1. Relationship to Other Documents

Bestie, this doc together with RFC 4422 obsoletes RFC 2222 in its entirety 🧚 This doc replaces Section 7.2 of RFC 2222. The remainder is obsoleted as detailed in Section 1.2 of RFC 4422.

2. Conventions Used in This Document 🎀

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as defined in "Key words for use in RFCs to Indicate Requirement Levels" [KEYWORDS].

3. Kerberos V5 GSS-API Mechanism 👑

The SASL mechanism name for the Kerberos V5 GSS-API mechanism [RFC4121] is "GSSAPI". People call it the SASL GSSAPI mechanism, but it's specifically tied to Kerberos V5 and to GSS-API's Kerberos V5 mechanism 🔐

The GSSAPI SASL mechanism is a "client goes first" SASL mechanism. In other words, it starts with the client sending a "response" created as described in the following section 🏃‍♀️

The implementation MAY set any GSS-API flags or arguments not mentioned in this specification, as is necessary for the implementation to enforce its security policy 💖

Note that major status codes returned by GSS_Init_sec_context() or GSS_Accept_sec_context() other than GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED cause authentication failure 💀 Major status codes returned by GSS_Unwrap() other than GSS_S_COMPLETE (without any additional supplementary status codes) cause authentication and/or security layer failure 🙈

3.1. Client Side of Authentication Protocol Exchange 🌸

The client calls GSS_Init_sec_context, passing in input_context_handle of 0 (initially), mech_type of the Kerberos V5 GSS-API mechanism [KRB5GSS], chan_binding of NULL, and targ_name equal to output_name from GSS_Import_Name. That call uses input_name_type of GSS_C_NT_HOSTBASED_SERVICE (*) and input_name_string of "service@hostname". Here "service" is the service name specified in the protocol's profile, and "hostname" is the fully qualified host name of the server 🧚

When calling GSS_Init_sec_context, the client MUST pass the integ_req_flag of TRUE (**). If the client will be requesting a security layer, it MUST also supply to GSS_Init_sec_context a mutual_req_flag of TRUE, and a sequence_req_flag of TRUE. If the client will be requesting a security layer providing confidentiality protection, it MUST also supply to GSS_Init_sec_context a conf_req_flag of TRUE. The client then responds with the resulting output_token. If GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED, then the client should expect the server to issue a token in a subsequent challenge. The client must pass the token to another call to GSS_Init_sec_context, repeating the actions in this paragraph 🔁

(*) Clients MAY use name types other than GSS_C_NT_HOSTBASED_SERVICE to import servers' acceptor names, but only when they have a priori knowledge that the servers support alternate name types. Otherwise, clients MUST use GSS_C_NT_HOSTBASED_SERVICE for importing acceptor names 🫶

(**) Note that RFC 2222 [RFC2222] implementations will not work with GSS-API implementations that require integ_req_flag to be TRUE. No implementations of RFC 1964 [KRB5GSS] or RFC 4121 [RFC4121] that require integ_req_flag to be TRUE are believed to exist, and it is expected that any future update to [RFC4121] will require that integrity be available even when it isn't explicitly requested by the application 👀

When GSS_Init_sec_context returns GSS_S_COMPLETE, the client examines the context to make sure it provides a level of protection permitted by the client's security policy 🛡️ In particular, if the integ_avail flag is not set in the context, then no security layer can be offered or accepted.

If the conf_avail flag is not set in the context, then no security layer with confidentiality can be offered or accepted. If the context is acceptable, the client takes the following actions. If the last call to GSS_Init_sec_context returned an output_token, then the client responds with that output_token. Otherwise, the client responds with no data. The client should then expect the server to issue a token in a subsequent challenge ✨

The client passes this token to GSS_Unwrap and interprets the first octet of the resulting cleartext as a bit-mask specifying the security layers supported by the server. It reads the second through fourth octets as the maximum size output_message the server is able to receive (in network byte order). If the resulting cleartext is not 4 octets long, the client fails the negotiation 💔 The client verifies that the server maximum buffer is 0 if the server does not advertise support for any security layer.

The client then constructs data. The first octet contains the bit-mask specifying the selected security layer. The second through fourth octets contain, in network byte order, the maximum size output_message the client is able to receive (which MUST be 0 if the client does not support any security layer). The remaining octets contain the UTF-8 [UTF8] encoded authorization identity.

(Implementation note: The authorization identity is not terminated with the zero-valued (%x00) octet (e.g., the UTF-8 encoding of the NUL (U+0000) character).) 🙈

The client passes the data to GSS_Wrap with conf_flag set to FALSE and responds with the generated output_message. Then the client can consider the server authenticated 🎉

3.2. Server Side of Authentication Protocol Exchange ✨

okay bestie, the server has its own rules too 💅 A server MUST NOT advertise support for the "GSSAPI" SASL mechanism described in this document unless it has acceptor credential for the Kerberos V GSS-API mechanism [KRB5GSS]. no acceptor creds, no GSSAPI flex 🙅‍♀️

the server passes the initial client response to GSS_Accept_sec_context as input_token. it sets input_context_handle to 0 (initially), chan_binding to NULL, and picks a suitable acceptor_cred_handle (see below) 🎀 if GSS_Accept_sec_context returns GSS_S_CONTINUE_NEEDED, the server sends the generated output_token back to the client in a challenge and passes the resulting response to another call to GSS_Accept_sec_context, repeating the actions in this paragraph. it's a little loop, lowkey so satisfying 🔁

Servers SHOULD use a credential obtained by calling GSS_Acquire_cred or GSS_Add_cred for the GSS_C_NO_NAME desired_name and the Object Identifier (OID) of the Kerberos V5 GSS-API mechanism [KRB5GSS](*). Servers MAY use GSS_C_NO_CREDENTIAL as an acceptor credential handle. Servers MAY use a credential obtained by calling GSS_Acquire_cred or GSS_Add_cred for the server's principal name(s) (**) and the Kerberos V5 GSS-API mechanism [KRB5GSS].

(*) ok footnote time 🧚 unlike GSS_Add_cred, GSS_Acquire_cred takes an OID set of GSS-API mechanisms as an input parameter. the OID set can be made with GSS_Create_empty_OID_set and GSS_Add_OID_set_member, and it can be freed by calling the GSS_Release_oid_set.

(**) this one is the main character 👑 using server principal names with the GSS_C_NT_HOSTBASED_SERVICE name type and the "service@hostname" format is RECOMMENDED. here "service" is the service name from the protocol's profile, and "hostname" is the fully qualified host name of the server. the server name gets generated by calling GSS_Import_name with input_name_type of GSS_C_NT_HOSTBASED_SERVICE and input_name_string of "service@hostname".

Upon successful establishment of the security context (i.e., GSS_Accept_sec_context returns GSS_S_COMPLETE), the server SHOULD verify that the negotiated GSS-API mechanism is indeed Kerberos V5 [KRB5GSS] 🔍 it does this by checking the value of the mech_type parameter returned from the GSS_Accept_sec_context call. if the value differs, SASL authentication MUST be aborted. no vibes check passed, we're out 🚫

Upon successful establishment of the security context and if the server used GSS_C_NO_NAME/GSS_C_NO_CREDENTIAL to create the acceptor credential handle, the server SHOULD also check, using GSS_Inquire_context, that the target_name used by the client matches either

the GSS_C_NT_HOSTBASED_SERVICE "service@hostname" name syntax, where "service" is the service name specified in the application protocol's profile,

the GSS_KRB5_NT_PRINCIPAL_NAME [KRB5GSS] name syntax for a two-component principal where the first component matches the service name specified in the application protocol's profile.

When GSS_Accept_sec_context returns GSS_S_COMPLETE, the server examines the context to make sure it provides a level of protection that the server's security policy allows 🛡️ in particular, if the integ_avail flag is not set in the context, then no security layer can be offered or accepted. and if the conf_avail flag is not set in the context, then no security layer with confidentiality can be offered or accepted. no flag, no layer, periodt 💅

If the context is acceptable, the server does the following. if the last call to GSS_Accept_sec_context returned an output_token, the server sends it back to the client in a challenge and expects a reply from the client with no data. whether or not an output_token was returned (and after receiving any response to that output_token), the server builds 4 octets of data. the first octet holds a bit-mask listing the security layers the server supports, and the second through fourth octets hold, in network byte order, the maximum size output_token the server is able to receive (which MUST be 0 if the server does not support any security layer) 🍓 the server then has to pass the plaintext to GSS_Wrap with conf_flag set to FALSE, and issue the generated output_message to the client in a challenge.

the server then passes the resulting response to GSS_Unwrap and reads the first octet of the resulting cleartext as the bit-mask for the selected security layer. it reads the second through fourth octets as the maximum size output_message the client is able to receive (in network byte order), and the remaining octets as the authorization identity ✨ the server checks that the client picked a security layer that was offered, and that the client's maximum buffer is 0 if no security layer was chosen. the server must also verify that the src_name is authorized to act as the authorization identity. after all of that, the authentication process is complete 🎉 the server isn't expected to return any additional data with the success indicator.

3.3. Security Layer

okay the security layers and their bit-masks go like this 🦋

      1 No security layer
      2 Integrity protection.
        Sender calls GSS_Wrap with conf_flag set to FALSE
      4 Confidentiality protection.
        Sender calls GSS_Wrap with conf_flag set to TRUE

other bit-masks may be defined in the future, and bits that are not understood must be negotiated off 🔮

when decoding any received data with GSS_Unwrap, any major_status other than GSS_S_COMPLETE MUST be treated as a fatal error 💀 no exceptions, bestie.

note that SASL negotiates the maximum size of the output_message to send. implementations can use the GSS_Wrap_size_limit call to figure out the matching maximum size input_message 🧚

4. IANA Considerations

IANA modified the existing registration for "GSSAPI" as follows 📝

   Family of SASL mechanisms:  NO

   SASL mechanism name:  GSSAPI

   Security considerations:  See Section 5 of RFC 4752

   Published specification:  RFC 4752

   Person & email address to contact for further information:
      Alexey Melnikov <Alexey.Melnikov@isode.com>

   Intended usage:  COMMON

   Owner/Change controller:  iesg@ietf.org

   Additional information:  This mechanism is for the Kerberos V5
      mechanism of GSS-API.

5. Security Considerations 🔐

okay this section is serious business, no cap 😭 security issues are discussed throughout this memo.

when constructing the input_name_string, the client SHOULD NOT canonicalize the server's fully qualified domain name using an insecure or untrusted directory service 🚫 don't let a sketchy directory do your server's name for you.

for compatibility with deployed software, this document requires that the chan_binding (channel bindings) parameter to GSS_Init_sec_context and GSS_Accept_sec_context be NULL. that means GSS-API support for channel bindings is disallowed here 🙈 channel bindings in SASL are expected to be supported through a new GSS-API family of SASL mechanisms, which will be introduced in a future document ⭐

additional security considerations are in the [SASL] and [GSS-API] specifications. more security considerations for the GSS-API mechanism can be found in [KRB5GSS] and [KERBEROS] 📚

6. Acknowledgements 🫶

this document replaces Section 7.2 of RFC 2222 [RFC2222] by John G. Myers. he also contributed significantly to this revision 👑

Lawrence Greenfield converted the text of this document to the XML format 🌸

contributions from many members of the SASL mailing list are gratefully acknowledged, in particular comments from Chris Newman, Nicolas Williams, Jeffrey Hutzelman, Sam Hartman, Mark Crispin, and Martin Rex 💜

7. Changes since RFC 2222 🦋

RFC 2078 [RFC2078] specifies the version of GSS-API used by RFC 2222 [RFC2222], which provided the original version of this specification. that version of GSS-API did not provide the integ_integ_avail flag as an input to GSS_Init_sec_context. instead, integrity was always requested. RFC 4422 [SASL] requires that, when possible, the security layer negotiation be integrity protected. to meet this requirement, and as part of moving from RFC 2078 [RFC2078] to RFC 2743 [GSS-API], this specification requires that clients request integrity from GSS_Init_sec_context so they can use GSS_Wrap to protect the security layer negotiation. this specification does not require that the mechanism offer the integrity security layer, only that the security layer negotiation be wrapped 🎀

8. References 📖

8.1. Normative References

[GSS-API] Linn, J., "Generic Security Service Application Program Interface Version 2, Update 1", RFC 2743, January 2000.
[KERBEROS] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The Kerberos Network Authentication Service (V5)", RFC 4120, July 2005.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[KRB5GSS] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 1964, June 1996.
[RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos Version 5 Generic Security Service Application Program Interface (GSS-API) Mechanism: Version 2", RFC 4121, July 2005.
[SASL] Melnikov, A. and K. Zeilenga, "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006.
[UTF8] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.

8.2. Informative References

[RFC2078] Linn, J., "Generic Security Service Application Program Interface, Version 2", RFC 2078, January 1997.
[RFC2222] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997.

Editor's Address 📬

   Alexey Melnikov
   Isode Limited
   5 Castle Business Village
   36 Station Road
   Hampton, Middlesex  TW12 2BX
   UK

   EMail: Alexey.Melnikov@isode.com
   URI:   http://www.melnikov.ca/

Full Copyright Statement ⭐

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property ✨

okay so the IETF is basically saying "we are NOT making any promises 🙅‍♀️" about whether anyone's patents or other rights cover the tech in this doc. they also aren't saying they've checked for any of that. 💅 if you want the rules for rights in RFC docs, go read BCP 78 and BCP 79. those are the ones that actually spell it out, bestie.

copies of IPR disclosures sent to the IETF Secretariat, plus any licensing promises, or the results of trying to get a general license or permission for implementers or users to use those proprietary rights, can be found at the IETF's online IPR repository at http://www.ietf.org/ipr. 🗂️✨

and if you're someone who knows about a copyright, patent, patent application, or other proprietary right that might cover tech needed to implement this standard, the IETF wants you to tell them! 🫶 send it to ietf-ipr@ietf.org. they really do want to hear from you.

Acknowledgement 🌸

funding for the RFC Editor function is currently coming from the Internet Society. 🌈 thank you, ISOC, for keeping the RFC Editor running! 🙌

📦 where this page comes from

ietf: rfc4752 2006-11
💖 girlified by claude-haiku-5-5 on 2026-10-16: a language model's rewrite of the original, under its terms