draft-ietf-aft-gssapi-01.txt   draft-ietf-aft-gssapi-02.txt 
Internet-Draft GSS-API Authentication for SOCKS V5 Internet-Draft GSS-API Authentication for SOCKS V5
Expires: 29SEP95 29MAR95 Expires: 05FEB96 05JUL95
<draft-ietf-aft-gssapi-01.txt> P V McMahon, ICL <draft-ietf-aft-gssapi-02.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),
and its working groups. Note that other groups may also distribute its areas, and its working groups. Note that other groups may
working documents as Internet-Drafts. also distribute working documents as Internet-Drafts.
Internet-Drafts are draft document valid for a maximum of six months Internet-Drafts are draft document valid for a maximum of six
and may be updated, replaced or obsoleted by other documents at any months and may be updated, replaced or obsoleted by other
time. It is inappropriate to use Internet-Drafts as reference documents at any time. It is inappropriate to use Internet
material or to cite them other than as "work in progress". -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 To learn the current status of any Internet-Draft, please check
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow the "1id-abstracts.txt" listing contained in the Internet
Directories on ds.internic.net (US East Coast), nic.nordu.net -Drafts Shadow Directories on ds.internic.net (US East Coast),
(Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or
Rim). munnari.oz.au (Pacific 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 Security Context Establishment 3. GSS-API Security Context Establishment
4. GSS-API Protection-level Options 4. GSS-API Protection-level Options
5. GSS-API Per-message Protection 5. GSS-API Per-message Protection
6. References 6. GSS-API Security Context Termination
7. Acknowledgments 7. References
8. Security Considerations 8. Acknowledgments
9. Author's Address 9. Security Considerations
10. 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
framework for the use of arbitrary authentication protocols in the generalized framework for the use of arbitrary authentication
initial SOCKS connection setup. This document provides the protocols in the initial SOCKS connection setup. This document
specification for the SOCKS V5 GSS-API authentication protocol, and provides the specification for the SOCKS V5 GSS-API authentication
defines a GSS-API-based encapsulation for provision of integrity, protocol, and defines a GSS-API-based encapsulation for provision
authentication and optional confidentiality. of integrity, authentication and optional confidentiality.
2. Introduction 2. Introduction
GSS-API provides an abstract interface which provides security services GSS-API provides an abstract interface which provides security
for use in distributed applications, but isolates callers from specific services for use in distributed applications, but isolates callers
security mechanisms and implementations. from specific 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
administrative action, or through negotiation. GSS-API is specified in through administrative action, or through negotiation. GSS-API is
[RFC 1508], and [RFC 1509]. 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 The approach for use of GSS-API in SOCKS V5 is to authenticate the
client and server by successfully establishing a GSS-API security client and server by successfully establishing a GSS-API security
context - such that the GSS-API encapsulates any negotiation protocol context - such that the GSS-API encapsulates any negotiation
for mechanism selection, and the agreement of security service options. protocol for mechanism selection, and the agreement of security
The GSS-API gss_init_sec_context() interface enables the context service options.
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 The GSS-API enables the context initiator to know what security
further TCP traffic between client and server, and, for integrity services the target supports for the chosen mechanism. The
protection of UDP datagrams. 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. 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 default 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's code 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 may be 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. Other mechanisms may, the server with all letters in lower case. Other mechanisms may,
however, have different name forms, so the client should not make however, have different name forms, so the client should not make
assumptions about the name syntax. 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:
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, GSS_C_NO_CREDENTIAL into cred_handle to specify the default
delegation, and sequence protection via the gss_init_sec_context credential (for initiator usage),
req_flags parameter. It is required by this specification that the
client always requests these service options (i.e. passes GSS_C_NULL_OID into mech_type to specify the default
GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG | GSS_C_DELEG_FLAG | mechanism,
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. 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 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
success values: different 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
subnegotiation response. The client must pass the token to another subsequent subnegotiation response. The client must pass the
call to gss_init_sec_context, and repeat this procedure until token to another call to gss_init_sec_context, and repeat this
continue operations are complete. procedure until "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.
there is no output_token, the client should proceed to sending the
protected request details, including any required message protection If there is no output_token, the client should proceed to send
subnegotiation as specified in sections 4 and 5 below. the 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
resulting output_token which the client sends in a message to the 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 |
+------+------+------+.......................+ +------+------+------+.......................+
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 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 client must close its connection to
the server. the server.
3.5 Server Context Establishment 3.6 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
specify default credentials (for acceptor usage). In addition, When calling gss_accept_sec_context() for the first time, the
context_handle initially set to GSS_C_NO_CONTEXT. 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 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
to gss_accept_sec_context. 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 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 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
the client's request. the client's request.
3.6 Server Reply 3.7 Server Reply
In all continue/confirmation cases, the server uses the same message In all continue/confirmation cases, the server uses the same
type as for the client -> server interaction. message type as for the client -> server interaction.
+------+------+------+.......................+ +------+------+------+.......................+
+ 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 |
+------+------+------+.......................+ +------+------+------+.......................+
3.7 Security Context Failure 3.8 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-
authentication failure or otherwise), it will return: API authentication failure or otherwise), it will return:
+------+------+ +------+------+
+ ver | mtyp | + ver | mtyp |
+------+------+ +------+------+
+ 0x01 | 0xff | + 0x01 | 0xff |
+------+------+ +------+------+
4. GSS-API Protection-level Options
4.1 TCP Message protection Where:
Establishment of a GSS-API security context enables comunicating peers - "ver" is the protocol version number, here 1 to represent the
to determine which per-message protection services are available to first version of the SOCKS/GSS-API protocol
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 - "mtyp" is the message type, here 0xff to represent an abort
traffic is appropriate to the sensitivity of the data, and the severity message
of the threats. 4. GSS-API Protection-level Options
4.2 UDP Message Protection level 4.1 Message protection
For UDP, SOCKS V5 supports integrity protection only. UDP clients and Establishment of a GSS-API security context enables comunicating
servers therefore MUST use integrity protection as defined in [SOCKS peers to determine which per-message protection services are
V5] and section 5.2 below. No additional subnegotiation is required. 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.
4.3 TCP Message Protection Subnegotiation 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.
For TCP clients and servers, different levels of protection are 4.2 Message Protection Subnegotiation
possible in the SOCKS V5 protocol, so an additional subnegotiation
stage is needed to agree the message protection level. After For TCP and UDP clients and servers, different levels of
successful completion of this subnegotiation, TCP clients and servers protection are possible in the SOCKS V5 protocol, so an additional
use GSS-API encapsulation as defined in section 5.1. 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 After successful establishment of a GSS-API security context, the
client's GSS-API implementation sends its required security context client's GSS-API implementation sends its required security
protection level to the server. The server then returns the security context protection level to the server. The server then returns
context protection level which it agrees to - which may or may not take the security context protection level which it agrees to - which
the the client's request into account. may or may not take the the client's request into account.
The security context protection level sent by client and server must be The security context protection level sent by client and server
one of the following values:- must be one of the following values:-
1 required per-message integrity 1 required per-message integrity
2 required per-message integrity and confidentiality 2 required per-message integrity and confidentiality
3 selective per-message integrity or confidentiality based on 3 selective per-message integrity or confidentiality based on
local client and server configurations local client and server configurations
It is anticipated that most implementations will agree on level 1 or 2 It is anticipated that most implementations will agree on level 1
due to the practical difficulties in applying selective controls to or 2 due to the practical difficulties in applying selective
messages passed through a socks library. controls to messages passed through a socks library.
The security context protection level is sent from client to server and 4.3 Message Protection Subnegotiation Message Format
vice versa using the following protected 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 | + ver | mtyp | len | token |
+------+------+------+.......................+ +------+------+------+.......................+
+ 0x01 | 0x02 | 0x02 | up to 2^16 - 1 octets | + 0x01 | 0x02 | 0x02 | up to 2^16 - 1 octets |
+------+------+------+.......................+ +------+------+------+.......................+
The token is produced by encapsulating an octet containing the required Where:
protection level using gss_wrap() with conf_req set to FALSE. The
token is verified using gss_unwrap(). - "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 If the server's choice of protection level is unacceptable to the
client, then the client must close its connection to the server client, then the client must close its connection to the server
5. GSS-API Per-message Protection 5. GSS-API Per-message Protection
5.1 TCP 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().
For TCP clients and servers, the GSS-API functions for encapsulation The default value of quality of protection shall be specified, and
and de-encapsulation shall be used by implementations - i.e. the use of conf_req_flag shall be as determined by the previous
gss_wrap(), and gss_unwrap(). 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.
The default value of quality of protection shall be specified, and the All encapsulated messages are prefixed by the following framing:
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 +------+------+------+.......................+
+ ver | mtyp | len | token |
+------+------+------+.......................+
+ 0x01 | 0x03 | 0x02 | up to 2^16 - 1 octets |
+------+------+------+.......................+
When using GSS-API, the authentication key material identified in Where:
[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 - "ver" is the protocol version number, here 1 to represent the
derived by invoking gss_get_mic() for the COOKIE from the UDP ASSOCIATE first version of the SOCKS/GSS-API protocol
request.
6. References - "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] 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-03.txt
7. Acknowledgment 8. Acknowledgment
This document builds from a previous draft produced by Marcus Leech This document builds from a previous draft produced by Marcus
(BNR) - whose comments are gratefully acknowleged. 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).
8. Security Considerations 9. 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
and the correctness of the implementation of the underlying algorithms mechanisms, and the correctness of the implementation of the
and protocols. underlying algorithms 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
their security policy. with 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.
9. Author's Address 10. 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 1734 634882
fax: +44 734 855106 fax: +44 1734 855106
 End of changes. 59 change blocks. 
146 lines changed or deleted 230 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/