Internet-Draft GSS-API Authentication for SOCKS V5
Expires: 29SEP95 29MAR95
<draft-ietf-aft-gssapi-01.txt> P V McMahon, ICL
GSS-API Authentication Method for SOCKS Version 5
Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts.
Internet-Drafts are draft document valid for a maximum of six months
and may be updated, replaced or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress".
To learn the current status of any Internet-Draft, please check the
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net
(Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific
Rim).
Comments on this document are welcome and should be sent to
aft@unify.com, the mailing list of the Authenticated Firewall
Traversal Working Group of the IETF.
Contents List
1. Purpose
2. Introduction
3. GSS-API Security Context Establishment
4. GSS-API Protection-level Options
5. GSS-API Per-message Protection
6. References
7. Acknowledgments
8. Security Considerations
9. Author's Address
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.
McMahon [Page 1]
Internet-Draft GSS-API Authentication for SOCKS V5
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].
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 gss_init_sec_context() interface enables the context
initiator to know what security services the target supports for the
chosen mechanism.
The GSS-API per-message protection calls are used to encapsulate any
further TCP traffic between client and server, and, for integrity
protection of UDP datagrams.
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 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
is 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.
McMahon [Page 2]
Internet-Draft GSS-API Authentication for SOCKS V5
3.2 Client Context Establishment
The client should then call gss_init_sec_context, typically
passing GSS_C_NO_CREDENTIAL into cred_han 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 targ_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_MUTUAL_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 sending 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 |
+------+------+------+.......................+
McMahon [Page 3]
Internet-Draft GSS-API Authentication for SOCKS V5
If, however, the client's GSS-API implementation failed during
gss_init_sec_context, the the client must close its connection to
the server.
3.5 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.
For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL to
specify default credentials (for acceptor usage). In addition,
context_handle initially set to GSS_C_NO_CONTEXT.
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.6 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.7 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 |
+------+------+
McMahon [Page 4]
Internet-Draft GSS-API Authentication for SOCKS V5
4. GSS-API Protection-level Options
4.1 TCP 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 and GSS_C_CONF 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 UDP Message Protection level
For UDP, SOCKS V5 supports integrity protection only. UDP clients and
servers therefore MUST use integrity protection as defined in [SOCKS
V5] and section 5.2 below. No additional subnegotiation is required.
4.3 TCP Message Protection Subnegotiation
For TCP 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 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.
The security context protection level is sent from client to server and
vice versa using the following protected message format:
McMahon [Page 5]
Internet-Draft GSS-API Authentication for SOCKS V5
+------+------+------+.......................+
+ ver | mtyp | len | token |
+------+------+------+.......................+
+ 0x01 | 0x02 | 0x02 | up to 2^16 - 1 octets |
+------+------+------+.......................+
The token is produced by encapsulating an octet containing the required
protection level using gss_wrap() with conf_req set to FALSE. The
token is verified using 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
5.1 TCP Protection
For TCP clients and servers, the GSS-API functions for encapsulation
and de-encapsulation shall be used by implementations - i.e.
gss_wrap(), and 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
MUST always be FALSE; if protection level 2 is agreed then conf_req
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.
5.2 UDP Protection
When using GSS-API, the authentication key material identified in
[SOCKS V5] for computation of the value for the XCOOKIE digest within
the UDP MAC field is encapsulated by the authentication mechanism.
Therefore, for UDP-based clients, the XCOOKIE digest value for UDP is
derived by invoking gss_get_mic() for the COOKIE from the UDP ASSOCIATE
request.
McMahon [Page 6]
Internet-Draft GSS-API Authentication for SOCKS V5
6. References
[RFC 1508] Generic Security Service API, J Linn,
September 1993
[RFC 1509] Generic Security Service API : C-bindings, J Wray,
September 1993
[SOCKS V5] SOCKS Protocol V5, draft-ietf-aft-socks-proto-v5-01.txt
M Leech, March 1995
7. Acknowledgment
This document builds from a previous draft produced by Marcus Leech
(BNR) - whose comments are gratefully acknowleged.
8. 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.
9. Author's Address
P V McMahon
post: ICL Enterprises, Kings House, 33 Kings Road, Reading, RG1 3PX, UK
email: p.v.mcmahon@rea0803.wins.icl.co.uk
phone: +44 734 634882
fax: +44 734 855106
McMahon [Page 7]
