SOCKS5 GSS-API: GSS-API Authentication Method for SOCKS Version 5
How a SOCKS version 5 client and server prove who they are and protect traffic using GSS-API.
McMahon, P., "GSS-API Authentication Method for SOCKS Version 5", RFC 1961, DOI 10.17487/RFC1961, June 1996, <https://www.rfc-editor.org/info/rfc1961>.
@misc{rfc1961,
series = {Request for Comments},
number = 1961,
howpublished = {RFC 1961},
publisher = {RFC Editor},
doi = {10.17487/RFC1961},
url = {https://www.rfc-editor.org/info/rfc1961},
author = {P. McMahon},
title = {{GSS-API Authentication Method for SOCKS Version 5}},
pagetotal = 9,
year = 1996,
month = jun,
} RFC text
Contents
Network Working Group P. McMahon
Request for Comments: 1961 ICL
Category: Standards Track June 1996
GSS-API Authentication Method for SOCKS Version 5
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
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
The protocol specification for SOCKS Version 5 specifies a
generalized framework for the use of arbitrary authentication
protocols in the initial SOCKS connection setup. This document
provides the specification for the SOCKS V5 GSS-API authentication
protocol, and defines a GSS-API-based encapsulation for provision of
integrity, authentication and optional confidentiality.
2. Introduction
GSS-API provides an abstract interface which provides security
services for use in distributed applications, but isolates callers
from specific security mechanisms and implementations.
GSS-API peers achieve interoperability by establishing 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 specification is
intended for use with implementations of GSS-API, and the emerging
GSS-API V2 specification.
The approach for use of GSS-API in SOCKS V5 is to authenticate the
client and server by successfully establishing a GSS-API security
context - such that the GSS-API encapsulates any negotiation protocol
for mechanism selection, and the agreement of security service
options.
The GSS-API enables the context initiator to know what security
services the target supports for the chosen mechanism. The required
level of protection is then agreed by negotiation.
The GSS-API per-message protection calls are subsequently used to
encapsulate any further TCP and UDP traffic between client and
server.
3. GSS-API Security Context Establishment
3.1 Preparation
Prior to use of 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 obtain 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 treated by the
client's code as an opaque name-space specific input.
For example, when using 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 via the gss_init_sec_context
req_flags parameter. 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 gss_init_sec_context returned status code can take 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
For the case where 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 calling gss_accept_sec_context() 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
subsequently 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 is ready to receive the
client's request.
3.7 Server Reply
In all continue/confirmation cases, the server uses the same message
type as 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
Establishment of a GSS-API security context enables comunicating
peers to determine which per-message protection services are
available to them through the gss_init_sec_context() and
gss_accept_sec_context() ret_flags GSS_C_INTEG_FLAG and
GSS_C_CONF_FLAG which respectively indicate message integrity and
confidentiality services.
It is necessary to ensure that the message protection applied to the
traffic is appropriate to the sensitivity of the data, and the
severity of the threats.
4.2 Message Protection Subnegotiation
For TCP and UDP clients and servers, different levels of protection
are possible in the SOCKS V5 protocol, so an additional
subnegotiation stage is needed to agree the message protection level.
After successful completion of this subnegotiation, TCP and UDP
clients and servers use GSS-API encapsulation as defined in section
5.1.
After successful establishment of a GSS-API security context, 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 which it agrees to - which may or may not
take the 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 due to the practical difficulties in applying selective controls to
messages passed through a socks library.
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 containing 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
For TCP and UDP clients and servers, the GSS-API functions for
encapsulation and de-encapsulation shall be used by implementations -
i.e. gss_seal()/gss_wrap(), and gss_unseal()/ gss_unwrap().
The default value of quality of protection shall be specified, and
the use of conf_req_flag shall be as determined by the previous
subnegotiation step. If protection level 1 is agreed then
conf_req_flag MUST always be FALSE; if protection level 2 is agreed
then conf_req_flag MUST always be TRUE; and if protection level 3 is
agreed then conf_req is determined on a per-message basis by client
and server using local configuration.
All encapsulated messages are prefixed by the following framing:
+------+------+------+.......................+
+ ver | mtyp | len | token |
+------+------+------+.......................+
+ 0x01 | 0x03 | 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 3 to represent encapulated user
data
- "len" is the length of the "token" field in octets
- "token" is the user data encapsulated by GSS-API
6. GSS-API Security Context Termination
The GSS-API context termination message (emitted by
gss_delete_sec_context) is not used by this protocol.
When the connection is closed, each peer invokes
gss_delete_sec_context() passing GSS_C_NO_BUFFER into the
output_token argument.
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 produced by Marcus Leech
(BNR) - whose comments are gratefully acknowleged. It also reflects
input from the AFT WG, and comments arising from implementation
experience by Xavier Gosselin (IUT Lyons).
9. Security Considerations
The security services provided through the GSS-API are entirely
dependent on the effectiveness of the underlying security mechanisms,
and the correctness of the implementation of the underlying
algorithms and protocols.
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.
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.
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
AI ELI5
On this page
§1Purpose and Approach
The SOCKS Version 5 specification (RFC 1928) defines a general framework for using arbitrary authentication protocols when a connection is first set up. RFC 1961 supplies one such method: the GSS-API authentication method. It also defines an encapsulation that provides integrity, authentication and optional confidentiality.
GSS-API is an abstract interface that offers security services to distributed applications while hiding the specific security mechanism underneath. It is specified in RFC 1508 and RFC 1509. Two peers interoperate by agreeing on a common mechanism, either by administrative action or by negotiation.
The approach is to authenticate client and server by successfully establishing a GSS-API security context. GSS-API itself handles any negotiation of the mechanism and of the security service options. The per-message protection calls are then used to wrap all further TCP and UDP traffic between client and server.
Instead of inventing its own way to check IDs, SOCKS borrows a general ID-checking toolkit. Once the IDs are checked, everything the two sides say is sealed in envelopes.
§2Establishing the Security Context
Before using any GSS-API calls, client and server should be locally authenticated and have default GSS-API credentials. The client calls gss_import_name to turn the server name into an internal form. It should use the default name type GSS_C_NULL_OID and treat the name string as opaque. With Kerberos V5 naming the name may look like SERVICE:socks@socks_server_hostname, but other mechanisms may use other forms, so the client should not assume a syntax.
The client then calls gss_init_sec_context, typically passing the default credential, the default mechanism, a null context and the imported server name. The client must always request mutual authentication, replay protection, delegation and sequence protection by passing GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG | GSS_C_DELEG_FLAG | GSS_C_SEQUENCE_FLAG. However, GSS_C_SEQUENCE_FLAG should be passed only by TCP-based clients, not UDP-based ones.
If the call returns GSS_S_CONTINUE_NEEDED, the client expects a token from the server in the next reply, feeds it into another call, and repeats until the continue operations are done. If it returns GSS_S_COMPLETE, the client sends any resulting output token to the server. If there is no output token, it goes on to send its protected request details. If GSS-API fails during initialisation, the client must close its connection.
On the server, the client's token is passed to gss_accept_sec_context as input. On the first call the context handle is GSS_C_NO_CONTEXT and the credential is GSS_C_NO_CREDENTIAL for default acceptor credentials. The server returns any output token to the client and keeps going on a continue result. If the call completes with no token to return, the server sends a zero-length token to signal that it is ready to receive the client's request.
You and the doorman pass notes back and forth showing your ID cards until each of you is satisfied. If either of you fails the check, the door shuts.
§3Message Framing
Every message in this method has a small frame: a ver field, a mtyp field, a len field giving the length of the token in octets, and then the token, which can be up to 2^16 - 1 octets. The ver value is 1 for this first version of the SOCKS/GSS-API protocol.
The message type tells what the token carries. Type 1 is an authentication message, used for the client's initial token and for the server's continue and confirmation replies. Type 2 is a protection-level negotiation message. Type 3 is encapsulated user data.
When the server refuses the connection for any reason, whether GSS-API authentication failure or otherwise, it returns a short abort message containing only ver and mtyp, where mtyp is 0xff.
Every note has a label on the outside saying what kind of note it is and how long it is. A special red-stamped note means the doorman said no.
| Field | Name | Size | Value | Description |
|---|---|---|---|---|
VER | ver | 1 byte | 1 | Protocol version; 1 for the first version of SOCKS/GSS-API. |
MTYP | mtyp | 1 byte | Message type: 1 authentication, 2 protection level, 3 user data, 0xff abort. | |
LEN | len | 2 bytes | Length of the token field in octets. |
§4Agreeing a Protection Level
Once a context exists, the peers can learn which per-message services are available from the return flags GSS_C_INTEG_FLAG (integrity) and GSS_C_CONF_FLAG (confidentiality). The protection applied should fit the sensitivity of the data and the severity of the threats.
Because different levels of protection are possible for TCP and UDP, a further subnegotiation follows. The client sends the protection level it requires, and the server answers with the level it agrees to, which may or may not take the client's request into account. The level must be one of three 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.
The RFC anticipates that most implementations will agree on level 1 or 2, because selective controls are hard to apply to messages passing through a SOCKS library.
The level travels in a type 2 message. The token is made by wrapping an octet holding the level with gss_seal()/gss_wrap() with conf_req set to FALSE, and is checked with gss_unseal()/gss_unwrap(). If the server's choice is unacceptable, the client must close its connection.
Next you decide how careful to be. Either just seal the envelope so nobody can change it, or seal it and hide the writing too.
- 1Integrity — Required per-message integrity; conf_req_flag is always FALSE.
- 2Integrity and confidentiality — Required per-message integrity and confidentiality; conf_req_flag is always TRUE.
- 3Selective — Integrity or confidentiality chosen per message from local configuration.
§5Protecting Traffic and Closing Down
After the subnegotiation, TCP and UDP clients and servers must use the GSS-API wrapping functions, gss_seal()/gss_wrap() and gss_unseal()/gss_unwrap(), for all encapsulation. The default quality of protection is used, and conf_req_flag follows the agreed level. At level 1 it MUST always be FALSE. At level 2 it MUST always be TRUE. At level 3 each side decides per message from local configuration.
Each wrapped message is framed with message type 3, and its token holds the user data encapsulated by GSS-API.
The GSS-API context termination message, which gss_delete_sec_context would emit, is not used by this protocol. When the connection is closed, each peer calls gss_delete_sec_context() passing GSS_C_NO_BUFFER as the output token argument.
From now on, everything you say to the doorman goes inside a sealed envelope, in the style you both chose. When you leave, each of you just tears up your own copy of the ID card.
§6Security Considerations
The security services provided through GSS-API depend entirely on how effective the underlying mechanisms are and on the correctness of their algorithms, protocols and implementations. Users of a GSS-API service must make sure the quality of protection that the mechanism provides is consistent with their security policy.
Where GSS-API supports negotiation, constraints on acceptable mechanisms may be imposed so that the result is suitable for authenticated firewall traversal.
The envelopes are only as strong as the lock inside them, so check that your lock is good enough for what you are sending.