draft-ietf-aft-gssapi-00.txt   draft-ietf-aft-gssapi-01.txt 
Internet-Draft GSS-API Authentication for SOCKS V5 Internet-Draft GSS-API Authentication for SOCKS V5
Expires: 25SEP95 24MAR95 Expires: 29SEP95 29MAR95
<draft-ietf-aft-gssapi-00.txt> P V McMahon, ICL <draft-ietf-aft-gssapi-01.txt> P V McMahon, ICL
GSS-API Authentication Method for SOCKS Version 5 GSS-API Authentication Method for SOCKS Version 5
Status of this Memo Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts. working documents as Internet-Drafts.
skipping to change at page 1, line 35 skipping to change at page 1, line 34
Rim). Rim).
Comments on this document are welcome and should be sent to Comments on this document are welcome and should be sent to
aft@unify.com, the mailing list of the Authenticated Firewall aft@unify.com, the mailing list of the Authenticated Firewall
Traversal Working Group of the IETF. Traversal Working Group of the IETF.
Contents List Contents List
1. Purpose 1. Purpose
2. Introduction 2. Introduction
3. GSS-API Call Specification for SOCKS V5 3. GSS-API Security Context Establishment
4. References 4. GSS-API Protection-level Options
5. Acknowledgments 5. GSS-API Per-message Protection
6. Security Considerations 6. References
7. Author's Address 7. Acknowledgments
8. Security Considerations
9. Author's Address
1. Purpose 1. Purpose
The protocol specification for SOCKS Version 5 specifies a generalized The protocol specification for SOCKS Version 5 specifies a generalized
framework for the use of arbitrary authentication protocols in the framework for the use of arbitrary authentication protocols in the
initial SOCKS connection setup. initial SOCKS connection setup. This document provides the
specification for the SOCKS V5 GSS-API authentication protocol, and
This document provides the specification for the SOCKS V5 GSS-API defines a GSS-API-based encapsulation for provision of integrity,
authentication protocol, and defines an GSS-API authentication method authentication and optional confidentiality.
encapsulation that provides integrity, authentication and optional
confidentiality.
Internet-Draft GSS-API Authentication for SOCKS V5
2. Introduction 2. Introduction
GSS-API provides an abstract interface which provides security services GSS-API provides an abstract interface which provides security services
for use in distributed applications, but isolates callers from specific for use in distributed applications, but isolates callers from specific
security mechanisms and implementations. security mechanisms and implementations.
GSS-API peers achieve interoperability by establishing a common GSS-API peers achieve interoperability by establishing a common
security mechanism for security context establishment - either through security mechanism for security context establishment - either through
administrative action, or through negotiation. GSS-API is specified in administrative action, or through negotiation. GSS-API is specified in
skipping to change at page 2, line 30 skipping to change at page 2, line 28
context - such that the GSS-API encapsulates any negotiation protocol context - such that the GSS-API encapsulates any negotiation protocol
for mechanism selection, and the agreement of security service options. for mechanism selection, and the agreement of security service options.
The GSS-API gss_init_sec_context() interface enables the context The GSS-API gss_init_sec_context() interface enables the context
initiator to know what security services the target supports for the initiator to know what security services the target supports for the
chosen mechanism. chosen mechanism.
The GSS-API per-message protection calls are used to encapsulate any The GSS-API per-message protection calls are used to encapsulate any
further TCP traffic between client and server, and, for integrity further TCP traffic between client and server, and, for integrity
protection of UDP datagrams. protection of UDP datagrams.
3. GSS-API Call Specification for SOCKS V5 3. GSS-API Security Context Establishment
3.1 Preparation 3.1 Preparation
Prior to use of GSS-API primitives, the client and server should Prior to use of GSS-API primitives, the client and server should
be locally authenticated, and have established GSS-API credentials. be locally authenticated, and have established GSS-API credentials.
The client should call gss_import_name to obtain an internal The client should call gss_import_name to obtain an internal
representation of the server name. For maximal portability representation of the server name. For maximal portability
the default name_type GSS_C_NULL_OID should be used to specify the default name_type GSS_C_NULL_OID should be used to specify
the default name space, and the input name_string should the default name space, and the input name_string should
treated by the client as an opaque name-space specific input. treated by the client's code as an opaque name-space specific input.
For example, when using Kerberos V5 naming, the imported name For example, when using Kerberos V5 naming, the imported name
is of the form "SERVICE:socks@socks_server_hostname" where is of the form "SERVICE:socks@socks_server_hostname" where
"socks_server_hostname" is the fully qualified host name of "socks_server_hostname" is the fully qualified host name of
the server with all letters in lower case. 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 3.2 Client Context Establishment
The client should then call gss_init_sec_context, typically The client should then call gss_init_sec_context, typically
passing GSS_C_NO_CREDENTIAL into cred_han to specify the default passing GSS_C_NO_CREDENTIAL into cred_han to specify the default
credential (for initiator usage), GSS_C_NULL_OID into mech_type to 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 the default mechanism, GSS_C_NO_CONTEXT into context_handle to
Internet-Draft GSS-API Authentication for SOCKS V5
specify a NULL context (initially), and the previously imported server specify a NULL context (initially), and the previously imported server
name into targ_name. name into targ_name.
The client must also specify its requirements The client must also specify its requirements for replay protection,
for replay protection, delegation, and sequence protection via delegation, and sequence protection via the gss_init_sec_context
the gss_init_sec_context req_flags parameter. It is required by this req_flags parameter. It is required by this specification that the
specification that the client always requests these service options client always requests these service options (i.e. passes
(i.e. passes GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG | GSS_C_DELEG_FLAG | 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 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. only be passed in for TCP-based clients, not for UDP-based clients.
3.3 Client Context Establishment Major Status codes 3.3 Client Context Establishment Major Status codes
The gss_init_sec_context returned status code can take two different The gss_init_sec_context returned status code can take two different
success values: success values:
- If gss_init_sec_context returns GSS_S_CONTINUE_NEEDED, then the - If gss_init_sec_context returns GSS_S_CONTINUE_NEEDED, then the
client should expect the server to issue a token in the subsequent client should expect the server to issue a token in the subsequent
subnegotiation response. The client must pass the token to another subnegotiation response. The client must pass the token to another
call to gss_init_sec_context, and repeat this procedure until call to gss_init_sec_context, and repeat this procedure until
continue operations are complete. continue operations are complete.
- If gss_init_sec_context returns GSS_S_COMPLETE, then the client - If gss_init_sec_context returns GSS_S_COMPLETE, then the client
should respond to the server with any resulting output_token. If should respond to the server with any resulting output_token. If
there is no output_token, the client should proceed to sending the there is no output_token, the client should proceed to sending the
protected request details. protected request details, including any required message protection
subnegotiation as specified in sections 4 and 5 below.
3.4 Client initial token 3.4 Client initial token
The client's GSS-API implementation then typically responds with the The client's GSS-API implementation then typically responds with the
resulting output_token which the client sends in a message to resulting output_token which the client sends in a message to
the server. the server.
+------+------+------+.......................+ +------+------+------+.......................+
+ ver | mtyp | len | token | + ver | mtyp | len | token |
+------+------+------+.......................+ +------+------+------+.......................+
skipping to change at page 3, line 45 skipping to change at page 4, line 4
The client's GSS-API implementation then typically responds with the The client's GSS-API implementation then typically responds with the
resulting output_token which the client sends in a message to resulting output_token which the client sends in a message to
the server. the server.
+------+------+------+.......................+ +------+------+------+.......................+
+ ver | mtyp | len | token | + ver | mtyp | len | token |
+------+------+------+.......................+ +------+------+------+.......................+
+ 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets | + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets |
+------+------+------+.......................+ +------+------+------+.......................+
If, however, the client's GSS-API implementation failed during If, however, the client's GSS-API implementation failed during
gss_init_sec_context, the the client must close its connection to gss_init_sec_context, the the client must close its connection to
the server. the server.
3.5 Server Context Establishment 3.5 Server Context Establishment
For the case where a client successfully sends a token emitted by For the case where a client successfully sends a token emitted by
gss_init_sec_context() to the server, the server must pass the gss_init_sec_context() to the server, the server must pass the
client-supplied token to gss_accept_sec_context as input_token. client-supplied token to gss_accept_sec_context as input_token.
For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL to
Internet-Draft GSS-API Authentication for SOCKS V5 specify default credentials (for acceptor usage). In addition,
context_handle initially set to GSS_C_NO_CONTEXT.
For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL
(for acceptor usage), context_handle initially set to GSS_C_NO_CONTEXT.
If gss_accept_sec_context returns GSS_CONTINUE_NEEDED, the server If gss_accept_sec_context returns GSS_CONTINUE_NEEDED, the server
should return the generated output_token to the client, and should return the generated output_token to the client, and
subsequently pass the resulting client supplied token to another call subsequently pass the resulting client supplied token to another call
to gss_accept_sec_context. to gss_accept_sec_context.
If gss_accept_sec_context returns GSS_S_COMPLETE, then if an If gss_accept_sec_context returns GSS_S_COMPLETE, then if an
output_token is returned, the server should return it to the client. output_token is returned, the server should return it to the client.
If no token is returned, a zero length token should be sent 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 by the server to signal to the client that it is ready to receive
skipping to change at page 4, line 42 skipping to change at page 5, line 4
3.7 Security Context Failure 3.7 Security Context Failure
If the server refuses the client's connection for any reason (GSS-API If the server refuses the client's connection for any reason (GSS-API
authentication failure or otherwise), it will return: authentication failure or otherwise), it will return:
+------+------+ +------+------+
+ ver | mtyp | + ver | mtyp |
+------+------+ +------+------+
+ 0x01 | 0xff | + 0x01 | 0xff |
+------+------+ +------+------+
4. GSS-API Protection-level Options
3.8 UDP Protection 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:
+------+------+------+.......................+
+ 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 When using GSS-API, the authentication key material identified in
[SOCKS V5] for computation of the value for the XCOOKIE digest within [SOCKS V5] for computation of the value for the XCOOKIE digest within
the UDP MAC field is encapsulated by the authentication mechanism. the UDP MAC field is encapsulated by the authentication mechanism.
Therefore, for UDP-based clients, the XCOOKIE digest value for UDP is 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 derived by invoking gss_get_mic() for the COOKIE from the UDP ASSOCIATE
request. request.
Internet-Draft GSS-API Authentication for SOCKS V5 6. References
4. References
[RFC 1508] Generic Security Service API, J Linn, [RFC 1508] Generic Security Service API, J Linn,
September 1993 September 1993
[RFC 1509] Generic Security Service API : C-bindings, J Wray, [RFC 1509] Generic Security Service API : C-bindings, J Wray,
September 1993 September 1993
[SOCKS V5] SOCKS Protocol V5, draft-ietf-aft-socks-proto-v5-01.txt [SOCKS V5] SOCKS Protocol V5, draft-ietf-aft-socks-proto-v5-01.txt
5. Acknowledgment 7. Acknowledgment
This document builds from a previous draft produced by Marcus Leech This document builds from a previous draft produced by Marcus Leech
(BNR) - whose comments are gratefully acknowleged. (BNR) - whose comments are gratefully acknowleged.
6. Security Considerations 8. Security Considerations
The security services provided through the GSS-API are entirely The security services provided through the GSS-API are entirely
dependent on the effectiveness of the underlying security mechanisms, dependent on the effectiveness of the underlying security mechanisms,
and the correctness of the implementation of the underlying algorithms and the correctness of the implementation of the underlying algorithms
and protocols. and protocols.
The user of a GSS-API service must ensure that the quality of The user of a GSS-API service must ensure that the quality of
protection provided by the mechanism implementation is consistent with protection provided by the mechanism implementation is consistent with
their security policy. their security policy.
In addition, where negotiation is supported under the GSS-API, In addition, where negotiation is supported under the GSS-API,
constraints on acceptable mechanisms may be imposed to ensure constraints on acceptable mechanisms may be imposed to ensure
suitability for application to authenticated firewall traversal. suitability for application to authenticated firewall traversal.
7. Author's Address 9. Author's Address
P V McMahon P V McMahon
post: ICL Enterprises, Kings House, 33 Kings Road, Reading, RG1 3PX, UK post: ICL Enterprises, Kings House, 33 Kings Road, Reading, RG1 3PX, UK
email: p.v.mcmahon@rea0803.wins.icl.co.uk email: p.v.mcmahon@rea0803.wins.icl.co.uk
phone: +44 734 634882 phone: +44 734 634882
fax: +44 734 855106 fax: +44 734 855106
 End of changes. 18 change blocks. 
41 lines changed or deleted 109 lines changed or added

This html diff was produced by rfcdiff 1.34. The latest version is available from http://tools.ietf.org/tools/rfcdiff/