RFC 1961

GSS-API Authentication Method for SOCKS Version 5

📅 published June 1996, from ietf

GSS-API Authentication Method for SOCKS Version 5 🦋

okay bestie, this is RFC 1961 📜 from the Network Working Group 💖. The title is GSS-API Authentication Method for SOCKS Version 5, and it's Request for Comments: 1961, which is giving main character energy 👑. It was written by P. McMahon from ICL 🫶. The category is Standards Track 🔥, meaning it's a real protocol people are supposed to implement. The date is June 1996 🌸. It doesn't list anything it obsoletes or updates, so it's coming in fresh with zero drama ✨.

Status of This Memo 💅

This doc specifies an Internet standards track protocol for the whole Internet community, and it's literally asking for discussion and suggestions for improvements 🙏. If you want the official standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 📚. And the distribution of this memo is unlimited 🌈, so share it with everyone you know.

Table of Contents 🧚

         1. Purpose ............................................ 1
         2. Introduction ....................................... 1
         3. GSS-API Security Context Establishment ............. 2
         4. GSS-API Protection-level Options ................... 5
         5. GSS-API Per-message Protection ..................... 7
         6. GSS-API Security Context Termination ............... 8
         7. References ......................................... 8
         8. Acknowledgments .................................... 8
         9. Security Considerations ............................ 8
         10. Author's Address .................................. 9

1. Purpose 🎀

So the SOCKS Version 5 spec gives you a generalized framework for using all kinds of authentication protocols in the initial SOCKS connection setup 🔐. This doc is the spec for the SOCKS V5 GSS-API authentication protocol, and it defines a GSS-API-based encapsulation that gives you integrity, authentication, and optional confidentiality 💜.

2. Introduction 🌷

GSS-API is an abstract interface that gives you security services for distributed applications, but it keeps callers separated from specific security mechanisms and implementations 🧩.

GSS-API peers get interoperable by setting up a common security mechanism for security context establishment, either through administrative action or through negotiation 🤝. GSS-API is specified in [RFC 1508], and [RFC 1509]. This spec is meant for use with implementations of GSS-API and the emerging GSS-API V2 specification ✨.

The way SOCKS V5 uses GSS-API is to authenticate the client and server by successfully establishing a GSS-API security context 🫧. That context wraps up any negotiation protocol for mechanism selection, plus the agreement on security service options.

GSS-API lets the context initiator find out which security services the target supports for the chosen mechanism 👀. The level of protection is then agreed through negotiation.

The GSS-API per-message protection calls are then used to encapsulate any further TCP and UDP traffic between client and server 🦋.

3. GSS-API Security Context Establishment 🧦

3.1 Preparation 💌

Before you touch any GSS-API primitives, the client and server SHOULD be locally authenticated and have established default GSS-API credentials 🪪.

The client SHOULD call gss_import_name to get an internal representation of the server name ✨. For maximal portability, the default name_type GSS_C_NULL_OID SHOULD be used to specify the default name space, and the input name_string SHOULD be treated by the client's code as an opaque name-space specific input 🎁.

For example, with Kerberos V5 naming, the imported name may be of the form "SERVICE:socks@socks_server_hostname", where socks_server_hostname is the fully qualified host name of the server with all letters in lower case 🔤. Other mechanisms may, however, have different name forms, so the client SHOULD NOT make assumptions about the name syntax 🙅.

3.2 Client Context Establishment ⚡

The client SHOULD then call gss_init_sec_context, typically passing:

GSS_C_NO_CREDENTIAL into cred_handle to specify the default credential (for initiator usage),
GSS_C_NULL_OID into mech_type to specify the default mechanism,
GSS_C_NO_CONTEXT into context_handle to specify a NULL context (initially), and,
the previously imported server name into target_name.

The client MUST also specify its requirements for replay protection, delegation, and sequence protection through the req_flags parameter of gss_init_sec_context 🔁. It is REQUIRED by this specification that the client always requests these service options (i.e. passes GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG | GSS_C_DELEG_FLAG | GSS_C_SEQUENCE_FLAG into req_flags) 💯.

However, GSS_C_SEQUENCE_FLAG SHOULD only be passed in for TCP-based clients, not for UDP-based clients 🚨.

3.3 Client Context Establishment Major Status codes 🎯

The status code returned by gss_init_sec_context can have two different success values:

If gss_init_sec_context returns GSS_S_CONTINUE_NEEDED, then the client SHOULD expect the server to issue a token in the subsequent subnegotiation response. The client MUST pass the token to another call to gss_init_sec_context and repeat this procedure until "continue" operations are complete 🔄.
If gss_init_sec_context returns GSS_S_COMPLETE, then the client SHOULD respond to the server with any resulting output_token. If there is no output_token, the client SHOULD proceed to send the protected request details, including any required message protection subnegotiation as specified in sections 4 and 5 below 🥳.

3.4 Client initial token 🍓

The client's GSS-API implementation then typically responds with the resulting output_token, which the client sends in a message to the server 📨.

    +------+------+------+.......................+
    + ver  | mtyp | len  |       token           |
    +------+------+------+.......................+
    + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets |
    +------+------+------+.......................+

Where:

ver is the protocol version number, here 1 to represent the first version of the SOCKS/GSS-API protocol 🔢
mtyp is the message type, here 1 to represent an authentication message 🏷️
len is the length of the token field in octets 📏
token is the opaque authentication token emitted by GSS-API 🫥

3.5 Client GSS-API Initialisation Failure 🙅‍♀️

If, however, the client's GSS-API implementation failed during gss_init_sec_context, the client MUST close its connection to the server 🚪.

3.6 Server Context Establishment 🏰

When a client successfully sends a token emitted by gss_init_sec_context() to the server, the server MUST pass the client-supplied token to gss_accept_sec_context as input_token 🎯.

When gss_accept_sec_context() is called for the first time, the context_handle argument is initially set to GSS_C_NO_CONTEXT 🆕.

For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL to specify default credentials (for acceptor usage) 🧸.

If gss_accept_sec_context returns GSS_CONTINUE_NEEDED, the server SHOULD return the generated output_token to the client, and then pass the resulting client-supplied token to another call to gss_accept_sec_context 🔁.

If gss_accept_sec_context returns GSS_S_COMPLETE, then, if an output_token is returned, the server SHOULD return it to the client 📤.

If no token is returned, a zero length token SHOULD be sent by the server to signal to the client that it's ready to receive the client's request 🫡.

3.7 Server Reply 📬

In all continue/confirmation cases, the server uses the same message type as it does for the client -> server interaction 💁.

    +------+------+------+.......................+
    + ver  | mtyp | len  |       token           |
    +------+------+------+.......................+
    + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets |
    +------+------+------+.......................+

3.8 Security Context Failure 💀

If the server refuses the client's connection for any reason (GSS-API authentication failure or otherwise), it will return:

    +------+------+
    + ver  | mtyp |
    +------+------+
    + 0x01 | 0xff |
    +------+------+

Where:

ver is the protocol version number, here 1 to represent the first version of the SOCKS/GSS-API protocol 🔢
mtyp is the message type, here 0xff to represent an abort message 🛑

4. GSS-API Protection-level Options 🛡️

4.1 Message protection ✨

Setting up a GSS-API security context lets communicating peers figure out which per-message protection services they can use. You find that out through the ret_flags from gss_init_sec_context() and gss_accept_sec_context(): GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG, which indicate message integrity and confidentiality services respectively 🧠.

It's necessary to make sure the message protection on the traffic matches how sensitive the data is and how serious the threats are 🕵️‍♀️.

4.2 Message Protection Subnegotiation 🔐

For TCP and UDP clients and servers, the SOCKS V5 protocol supports different levels of protection, so an extra subnegotiation stage is needed to agree on the message protection level 🎚️. Once that subnegotiation finishes successfully, TCP and UDP clients and servers use GSS-API encapsulation as defined in section 5.1 💫.

After a GSS-API security context is successfully established, the client's GSS-API implementation sends its required security context protection level to the server 📤. The server then returns the security context protection level it agrees to, which may or may not take the client's request into account 🤷‍♀️.

The security context protection level sent by client and server MUST be one of the following values:

         1 required per-message integrity
         2 required per-message integrity and confidentiality
         3 selective per-message integrity or confidentiality based on
           local client and server configurations

It is anticipated that most implementations will agree on level 1 or 2, because applying selective controls to messages passed through a socks library is so practically difficult 😩.

4.3 Message Protection Subnegotiation Message Format 📝

The security context protection level is sent from client to server, and vice versa, using the following protected message format 💌:

    +------+------+------+.......................+
    + ver  | mtyp | len  |   token               |
    +------+------+------+.......................+
    + 0x01 | 0x02 | 0x02 | up to 2^16 - 1 octets |
    +------+------+------+.......................+

Where:

ver is the protocol version number, here 1 to represent the first version of the SOCKS/GSS-API protocol 🔢
mtyp is the message type, here 2 to represent a protection-level negotiation message 🏷️
len is the length of the token field in octets 📏
token is the GSS-API encapsulated protection level 🎁

4.4 Message Protection Subnegotiation Message Generation 🧁

The token is produced by encapsulating an octet that contains the required protection level, using gss_seal()/gss_wrap() with conf_req set to FALSE 🍰. The token is verified using gss_unseal()/gss_unwrap() 🔍.

If the server's choice of protection level is unacceptable to the client, then the client MUST close its connection to the server

5. GSS-API Per-message Protection 🦋

Okay bestie, for TCP and UDP clients and servers, implementations shall use the GSS-API functions for encapsulation and de-encapsulation, which means gss_seal()/gss_wrap() and gss_unseal()/gss_unwrap() ✨

The default quality of protection value shall be specified, and conf_req_flag shall be whatever the previous subnegotiation step decided. Here's the vibe: if protection level 1 is agreed, conf_req_flag MUST always be FALSE 🙈 If protection level 2 is agreed, conf_req_flag MUST always be TRUE 💅 And if protection level 3 is agreed, conf_req gets figured out per message by the client and server using their own local configuration 🧚

Every encapsulated message gets wrapped in this framing, no cap 🎀

+------+------+------+.......................+
+ ver  | mtyp | len  |       token           |
+------+------+------+.......................+
+ 0x01 | 0x03 | 0x02 | up to 2^16 - 1 octets |
+------+------+------+.......................+

Here's what each piece is giving:

ver is the protocol version number. It's 1 here, because it's the first version of the SOCKS/GSS-API protocol 💖
mtyp is the message type. It's 3 here, meaning encapsulated user data 🌸
len is the length of the token field, counted in octets 🦋
token is the user data that GSS-API encapsulated 🫶

6. GSS-API Security Context Termination 💜

Ngl this one's short and sweet. The GSS-API context termination message (the one emitted by gss_delete_sec_context) is not used by this protocol, so don't go looking for it 🙅‍♀️

When the connection closes, each peer calls gss_delete_sec_context() and passes GSS_C_NO_BUFFER into the output_token argument. Iconic cleanup behaviour 👑

7. References 📚

[RFC 1508] Linn, J., "Generic Security Service API", September 1993. 🔥
[RFC 1509] Wray, J., "Generic Security Service API : C-bindings", September 1993. 🌈
[SOCKS V5] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and L. Jones, "SOCKS Protocol V5", RFC 1928, April 1996. ⭐

8. Acknowledgment 🫶

This document builds from a previous memo by Marcus Leech (BNR), and his comments are gratefully acknowledged 💖 It also reflects input from the AFT WG, plus comments from implementation experience by Xavier Gosselin (IUT Lyons). Thank you, legends ✨

9. Security Considerations 🚨

Okay, this section is the serious one, so read it slowly 😭

The security services provided through the GSS-API are entirely dependent on the effectiveness of the underlying security mechanisms, and on whether the implementation of the underlying algorithms and protocols is correct. If the underlying stuff is shaky, the whole thing is shaky 💀

The user of a GSS-API service must ensure that the quality of protection provided by the mechanism implementation is consistent with their security policy. That's on you, bestie 🔒

In addition, where negotiation is supported under the GSS-API, constraints on acceptable mechanisms may be imposed to ensure suitability for application to authenticated firewall traversal. So yes, you can lock down which mechanisms are acceptable for firewall traversal 🧱

10. Author's Address 🌸

P. V. McMahon
ICL Enterprises
Kings House
33 Kings Road
Reading, RG1 3PX
UK

EMail: p.v.mcmahon@rea0803.wins.icl.co.uk
Phone: +44 1734 634882
Fax:   +44 1734 855106

And that's the whole thing, besties! 🌈💖🦋

📦 where this page comes from

ietf: rfc1961 1996-06
💖 girlified by claude-haiku-5-5 on 2026-10-15: a language model's rewrite of the original, under its terms