idnits 2.17.1 draft-ietf-aft-gssapi-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-27) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 45 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 199: '...ervers therefore MUST use integrity pr...' RFC 2119 keyword, line 254: '... MUST always be FALSE; if protectio...' RFC 2119 keyword, line 255: '... MUST always be TRUE; and if protec...' Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 1508 (Obsoleted by RFC 2078) ** Obsolete normative reference: RFC 1509 (Obsoleted by RFC 2744) -- No information found for draft-ietf-aft-socks-proto-v5 - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SOCKS V5' Summary: 13 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft GSS-API Authentication for SOCKS V5 2 Expires: 29SEP95 29MAR95 3 P V McMahon, ICL 5 GSS-API Authentication Method for SOCKS Version 5 7 Status of this Memo 9 This document is an Internet-Draft. Internet-Drafts are working 10 documents of the Internet Engineering Task Force (IETF), its areas, 11 and its working groups. Note that other groups may also distribute 12 working documents as Internet-Drafts. 14 Internet-Drafts are draft document valid for a maximum of six months 15 and may be updated, replaced or obsoleted by other documents at any 16 time. It is inappropriate to use Internet-Drafts as reference 17 material or to cite them other than as "work in progress". 19 To learn the current status of any Internet-Draft, please check the 20 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 21 Directories on ds.internic.net (US East Coast), nic.nordu.net 22 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 23 Rim). 25 Comments on this document are welcome and should be sent to 26 aft@unify.com, the mailing list of the Authenticated Firewall 27 Traversal Working Group of the IETF. 29 Contents List 31 1. Purpose 32 2. Introduction 33 3. GSS-API Security Context Establishment 34 4. GSS-API Protection-level Options 35 5. GSS-API Per-message Protection 36 6. References 37 7. Acknowledgments 38 8. Security Considerations 39 9. Author's Address 41 1. Purpose 43 The protocol specification for SOCKS Version 5 specifies a generalized 44 framework for the use of arbitrary authentication protocols in the 45 initial SOCKS connection setup. This document provides the 46 specification for the SOCKS V5 GSS-API authentication protocol, and 47 defines a GSS-API-based encapsulation for provision of integrity, 48 authentication and optional confidentiality. 50 2. Introduction 52 GSS-API provides an abstract interface which provides security services 53 for use in distributed applications, but isolates callers from specific 54 security mechanisms and implementations. 56 GSS-API peers achieve interoperability by establishing a common 57 security mechanism for security context establishment - either through 58 administrative action, or through negotiation. GSS-API is specified in 59 [RFC 1508], and [RFC 1509]. 61 The approach for use of GSS-API in SOCKS V5 is to authenticate the 62 client and server by successfully establishing a GSS-API security 63 context - such that the GSS-API encapsulates any negotiation protocol 64 for mechanism selection, and the agreement of security service options. 65 The GSS-API gss_init_sec_context() interface enables the context 66 initiator to know what security services the target supports for the 67 chosen mechanism. 69 The GSS-API per-message protection calls are used to encapsulate any 70 further TCP traffic between client and server, and, for integrity 71 protection of UDP datagrams. 73 3. GSS-API Security Context Establishment 75 3.1 Preparation 77 Prior to use of GSS-API primitives, the client and server should 78 be locally authenticated, and have established GSS-API credentials. 80 The client should call gss_import_name to obtain an internal 81 representation of the server name. For maximal portability 82 the default name_type GSS_C_NULL_OID should be used to specify 83 the default name space, and the input name_string should 84 treated by the client's code as an opaque name-space specific input. 85 For example, when using Kerberos V5 naming, the imported name 86 is of the form "SERVICE:socks@socks_server_hostname" where 87 "socks_server_hostname" is the fully qualified host name of 88 the server with all letters in lower case. Other mechanisms may, 89 however, have different name forms, so the client should not make 90 assumptions about the name syntax. 92 3.2 Client Context Establishment 94 The client should then call gss_init_sec_context, typically 95 passing GSS_C_NO_CREDENTIAL into cred_han to specify the default 96 credential (for initiator usage), GSS_C_NULL_OID into mech_type to 97 specify the default mechanism, GSS_C_NO_CONTEXT into context_handle to 98 specify a NULL context (initially), and the previously imported server 99 name into targ_name. 101 The client must also specify its requirements for replay protection, 102 delegation, and sequence protection via the gss_init_sec_context 103 req_flags parameter. It is required by this specification that the 104 client always requests these service options (i.e. passes 105 GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG | GSS_C_DELEG_FLAG | 106 GSS_C_MUTUAL_FLAG into req_flags). However, GSS_C_SEQUENCE_FLAG should 107 only be passed in for TCP-based clients, not for UDP-based clients. 109 3.3 Client Context Establishment Major Status codes 111 The gss_init_sec_context returned status code can take two different 112 success values: 114 - If gss_init_sec_context returns GSS_S_CONTINUE_NEEDED, then the 115 client should expect the server to issue a token in the subsequent 116 subnegotiation response. The client must pass the token to another 117 call to gss_init_sec_context, and repeat this procedure until 118 continue operations are complete. 120 - If gss_init_sec_context returns GSS_S_COMPLETE, then the client 121 should respond to the server with any resulting output_token. If 122 there is no output_token, the client should proceed to sending the 123 protected request details, including any required message protection 124 subnegotiation as specified in sections 4 and 5 below. 126 3.4 Client initial token 128 The client's GSS-API implementation then typically responds with the 129 resulting output_token which the client sends in a message to 130 the server. 132 +------+------+------+.......................+ 133 + ver | mtyp | len | token | 134 +------+------+------+.......................+ 135 + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets | 136 +------+------+------+.......................+ 137 If, however, the client's GSS-API implementation failed during 138 gss_init_sec_context, the the client must close its connection to 139 the server. 141 3.5 Server Context Establishment 143 For the case where a client successfully sends a token emitted by 144 gss_init_sec_context() to the server, the server must pass the 145 client-supplied token to gss_accept_sec_context as input_token. 146 For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL to 147 specify default credentials (for acceptor usage). In addition, 148 context_handle initially set to GSS_C_NO_CONTEXT. 150 If gss_accept_sec_context returns GSS_CONTINUE_NEEDED, the server 151 should return the generated output_token to the client, and 152 subsequently pass the resulting client supplied token to another call 153 to gss_accept_sec_context. 155 If gss_accept_sec_context returns GSS_S_COMPLETE, then if an 156 output_token is returned, the server should return it to the client. 157 If no token is returned, a zero length token should be sent 158 by the server to signal to the client that it is ready to receive 159 the client's request. 161 3.6 Server Reply 163 In all continue/confirmation cases, the server uses the same message 164 type as for the client -> server interaction. 166 +------+------+------+.......................+ 167 + ver | mtyp | len | token | 168 +------+------+------+.......................+ 169 + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets | 170 +------+------+------+.......................+ 172 3.7 Security Context Failure 174 If the server refuses the client's connection for any reason (GSS-API 175 authentication failure or otherwise), it will return: 177 +------+------+ 178 + ver | mtyp | 179 +------+------+ 180 + 0x01 | 0xff | 181 +------+------+ 182 4. GSS-API Protection-level Options 184 4.1 TCP Message protection 186 Establishment of a GSS-API security context enables comunicating peers 187 to determine which per-message protection services are available to 188 them through the gss_init_sec_context() and gss_accept_sec_context() 189 ret_flags GSS_C_INTEG and GSS_C_CONF which respectively indicate 190 message integrity and confidentiality services. 192 It is necessary to ensure that the message protection applied to the 193 traffic is appropriate to the sensitivity of the data, and the severity 194 of the threats. 196 4.2 UDP Message Protection level 198 For UDP, SOCKS V5 supports integrity protection only. UDP clients and 199 servers therefore MUST use integrity protection as defined in [SOCKS 200 V5] and section 5.2 below. No additional subnegotiation is required. 202 4.3 TCP Message Protection Subnegotiation 204 For TCP clients and servers, different levels of protection are 205 possible in the SOCKS V5 protocol, so an additional subnegotiation 206 stage is needed to agree the message protection level. After 207 successful completion of this subnegotiation, TCP clients and servers 208 use GSS-API encapsulation as defined in section 5.1. 210 After successful establishment of a GSS-API security context, the 211 client's GSS-API implementation sends its required security context 212 protection level to the server. The server then returns the security 213 context protection level which it agrees to - which may or may not take 214 the the client's request into account. 216 The security context protection level sent by client and server must be 217 one of the following values:- 218 1 required per-message integrity 219 2 required per-message integrity and confidentiality 220 3 selective per-message integrity or confidentiality based on 221 local client and server configurations 223 It is anticipated that most implementations will agree on level 1 or 2 224 due to the practical difficulties in applying selective controls to 225 messages passed through a socks library. 227 The security context protection level is sent from client to server and 228 vice versa using the following protected message format: 230 +------+------+------+.......................+ 231 + ver | mtyp | len | token | 232 +------+------+------+.......................+ 233 + 0x01 | 0x02 | 0x02 | up to 2^16 - 1 octets | 234 +------+------+------+.......................+ 236 The token is produced by encapsulating an octet containing the required 237 protection level using gss_wrap() with conf_req set to FALSE. The 238 token is verified using gss_unwrap(). 240 If the server's choice of protection level is unacceptable to the 241 client, then the client must close its connection to the server 243 5. GSS-API Per-message Protection 245 5.1 TCP Protection 247 For TCP clients and servers, the GSS-API functions for encapsulation 248 and de-encapsulation shall be used by implementations - i.e. 249 gss_wrap(), and gss_unwrap(). 251 The default value of quality of protection shall be specified, and the 252 use of conf_req_flag shall be as determined by the previous 253 subnegotiation step. If protection level 1 is agreed then conf_req 254 MUST always be FALSE; if protection level 2 is agreed then conf_req 255 MUST always be TRUE; and if protection level 3 is agreed then conf_req 256 is determined on a per-message basis by client and server using local 257 configuration. 259 5.2 UDP Protection 261 When using GSS-API, the authentication key material identified in 262 [SOCKS V5] for computation of the value for the XCOOKIE digest within 263 the UDP MAC field is encapsulated by the authentication mechanism. 265 Therefore, for UDP-based clients, the XCOOKIE digest value for UDP is 266 derived by invoking gss_get_mic() for the COOKIE from the UDP ASSOCIATE 267 request. 269 6. References 271 [RFC 1508] Generic Security Service API, J Linn, 272 September 1993 274 [RFC 1509] Generic Security Service API : C-bindings, J Wray, 275 September 1993 277 [SOCKS V5] SOCKS Protocol V5, draft-ietf-aft-socks-proto-v5-01.txt 278 M Leech, March 1995 280 7. Acknowledgment 282 This document builds from a previous draft produced by Marcus Leech 283 (BNR) - whose comments are gratefully acknowleged. 285 8. Security Considerations 287 The security services provided through the GSS-API are entirely 288 dependent on the effectiveness of the underlying security mechanisms, 289 and the correctness of the implementation of the underlying algorithms 290 and protocols. 292 The user of a GSS-API service must ensure that the quality of 293 protection provided by the mechanism implementation is consistent with 294 their security policy. 296 In addition, where negotiation is supported under the GSS-API, 297 constraints on acceptable mechanisms may be imposed to ensure 298 suitability for application to authenticated firewall traversal. 300 9. Author's Address 302 P V McMahon 303 post: ICL Enterprises, Kings House, 33 Kings Road, Reading, RG1 3PX, UK 304 email: p.v.mcmahon@rea0803.wins.icl.co.uk 305 phone: +44 734 634882 306 fax: +44 734 855106