idnits 2.17.1 draft-bittau-tcpinc-api-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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.) == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 2, 2016) is 2977 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-19) exists of draft-ietf-tcpinc-tcpeno-01 -- Obsolete informational reference (is this intentional?): RFC 896 (Obsoleted by RFC 7805) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bittau 3 Internet-Draft D. Boneh 4 Intended status: Informational D. Giffin 5 Expires: September 3, 2016 Stanford University 6 M. Handley 7 University College London 8 D. Mazieres 9 Stanford University 10 E. Smith 11 Kestrel Institute 12 March 2, 2016 14 Interface Extensions for TCP-ENO 15 draft-bittau-tcpinc-api-01 17 Abstract 19 TCP-ENO negotiates encryption at the transport layer. It also 20 defines a few parameters that are intended to be used or configured 21 by applications. This document specifies operating system interfaces 22 for access to these TCP-ENO parameters. We describe the interfaces 23 in terms of socket options, the de facto standard API for adjusting 24 per-connection behavior in TCP/IP, and sysctl, a popular mechanism 25 for setting global defaults. Operating systems that lack socket or 26 sysctl functionality can implement similar interfaces in their native 27 frameworks, but should ideally adapt their interfaces from those 28 presented in this document. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on September 3, 2016. 47 Copyright Notice 49 Copyright (c) 2016 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 65 2. API extensions . . . . . . . . . . . . . . . . . . . . . . . 3 66 2.1. Per-connection options . . . . . . . . . . . . . . . . . 3 67 2.2. System-wide options . . . . . . . . . . . . . . . . . . . 7 68 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 3.1. Cookie-based authentication . . . . . . . . . . . . . . . 8 70 3.2. Signature-based authentication . . . . . . . . . . . . . 9 71 4. Security considerations . . . . . . . . . . . . . . . . . . . 9 72 5. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 73 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 74 6.1. Normative References . . . . . . . . . . . . . . . . . . 10 75 6.2. Informative References . . . . . . . . . . . . . . . . . 10 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 78 1. Introduction 80 The TCP Encryption Negotiation Option (TCP-ENO) 81 [I-D.ietf-tcpinc-tcpeno] permits hosts to negotiate encryption of a 82 TCP connection. One of TCP-ENO's use cases is to encrypt traffic 83 transparently, unbeknownst to legacy applications. Transparent 84 encryption requires no changes to existing APIs. However, other use 85 cases require applications to interact with TCP-ENO. In particular: 87 o Transparent encryption protects only against passive 88 eavesdroppers. Stronger security requires applications to 89 authenticate a _Session ID_ value associated with each encrypted 90 connection. 92 o Applications that have been updated to authenticate Session IDs 93 must somehow advertise this fact to peers in a backward-compatible 94 way. TCP-ENO carries a two-bit "application-aware" status for 95 this purpose, but this status is not accessible through existing 96 interfaces. 98 o Applications employing TCP's simultaneous open feature need a way 99 to supply a symmetry-breaking "role-override" bit to TCP-ENO. 101 o System administrators and applications may wish to set and examine 102 negotiation preferences, such as which encryption schemes (and 103 perhaps versions) to enable and disable. 105 o Applications that perform their own encryption may wish to disable 106 TCP-ENO entirely. 108 The remainder of this document describes an API through which systems 109 can meet the above needs. The API extensions relate back to 110 quantities defined by TCP-ENO. 112 2. API extensions 114 This section describes an API for per-connection options, followed by 115 a discussion of system-wide configuration options. 117 2.1. Per-connection options 119 Application should access TCP-ENO options through the same mechanism 120 they use to access other TCP configuration options, such as 121 "TCP_NODELAY" [RFC0896]. With the popular sockets API, this 122 mechanism consists of two socket options, "getsockopt" and 123 "setsockopt", shown in Figure 1. Socket-based TCP-ENO 124 implementations should define a set of new "option_name" values 125 accessible at "level" "IPPROTO_TCP" (generally defined as 6, to match 126 the IP protocol field). 128 int getsockopt(int socket, int level, int option_name, 129 void *option_value, socklen_t *option_len); 131 int setsockopt(int socket, int level, int option_name, 132 const void *option_value, socklen_t option_len); 134 Figure 1: Socket option API 136 Table 1 summarizes the new "option_name" arguments that TCP-ENO 137 introduces to the socket option (or equivalent) system calls. For 138 each option, the table lists whether it is read-only (R) or read- 139 write (RW), as well as the type of the option's value. Read-write 140 options, when read, always return the previously successfully written 141 value or the default if they have not been written. Options of type 142 "bytes" consist of a variable-length array of bytes, while options of 143 type "int" consist of a small integer with the exact range indicated 144 in parentheses. We discuss each option in more detail below. 146 +----------------------+----+----------------+ 147 | Option name | RW | Type | 148 +----------------------+----+----------------+ 149 | TCP_ENO_ENABLED | RW | int (-1 - 1) | 150 | TCP_ENO_SESSID | R | bytes | 151 | TCP_ENO_NEGSPEC | R | int (32 - 127) | 152 | TCP_ENO_SPECS | RW | bytes | 153 | TCP_ENO_SELF_AWARE | RW | int (0 - 3) | 154 | TCP_ENO_PEER_AWARE | R | int (0 - 3) | 155 | TCP_ENO_ROLEOVERRIDE | RW | int (0 - 1) | 156 | TCP_ENO_ROLE | R | int (0 - 1) | 157 | TCP_ENO_LOCAL_NAME | R | bytes | 158 | TCP_ENO_PEER_NAME | R | bytes | 159 | TCP_ENO_RAW | RW | bytes | 160 | TCP_ENO_TRANSCRIPT | R | bytes | 161 +----------------------+----+----------------+ 163 Table 1: Suggested new IPPROTO_TCP socket options 165 The socket options must return errors under certain circumstances. 166 These errors are mapped to three suggested error codes shown in 167 Table 2. Most socket-based systems will already have constants for 168 these errors. Non-socket systems should use existing error codes 169 corresponding to the same conditions. "EINVAL" is the existing error 170 returned when setting options on a closed socket. "EISCONN" 171 corresponds to calling connect a second time, while "ENOTCONN" 172 corresponds to requesting the peer address of an unconnected socket. 174 +----------+-----------------------------------------------------+ 175 | Symbol | Description | 176 +----------+-----------------------------------------------------+ 177 | EINVAL | General error signifying bad parameters | 178 | EISCONN | Option no longer valid because socket is connected | 179 | ENOTCONN | Option not (yet) valid because socket not connected | 180 +----------+-----------------------------------------------------+ 182 Table 2: Suggested error codes 184 TCP_ENO_ENABLED When set to 0, completely disables TCP-ENO 185 regardless of any other socket option settings except 186 "TCP_ENO_RAW". When set to 1, enables TCP-ENO. If set to -1, use 187 a system-wide default determined at the time of an "accept" or 188 "connect" system call, as described in Section 2.2. This option 189 must return an error ("EISCONN") after a SYN segment has already 190 been sent. 192 TCP_ENO_SESSID Returns the session ID of the connection, as defined 193 by the encryption spec in use. This option must return an error 194 if encryption is disabled ("EINVAL"), the connection is not yet 195 established ("ENOTCONN"), or the transport layer does not 196 implement the negotiated spec ("EINVAL"). 198 TCP_ENO_NEGSPEC Returns the 7-bit code point of the negotiated 199 encryption spec for the current connection. As defined by TCP- 200 ENO, the negotiated spec is the last valid suboption in the "B" 201 host's SYN segment. This option must return an error if 202 encryption is disabled ("EINVAL") or the connection is not yet 203 established ("ENOTCONN"). 205 TCP_ENO_SPECS Allows the application to specify an ordered list of 206 encryption specs different from the system default list. If the 207 list is empty, TCP-ENO is disabled for the connection. Each byte 208 in the list specifies one suboption type from 0x20-0xff. The list 209 contains no suboption data for variable-length suboptions, only 210 the one-byte spec identifier. The high bit ("v") in these bytes 211 is ignored unless future implementations of encryption specs 212 assign it special meaning. The order of the list matters only for 213 the host playing the "B" role. Implementations must return an 214 error ("EISCONN") if an application attempts to set this option 215 after the SYN segment has been sent. Implementations should 216 return an error ("EINVAL") if any of the bytes are below 0x20 or 217 are not implemented by the TCP stack. 219 TCP_ENO_SELF_AWARE The value is an integer from 0-3, allowing 220 applications to specify the "aa" bits in the general suboption 221 sent by the host. When listening on a socket, the value of this 222 option applies to each accepted connection. The default value 223 should be 0. Implementations must return an error ("EISCONN") if 224 an application attempts to set this option after a SYN segment has 225 been sent. 227 TCP_ENO_PEER_AWARE The value is an integer from 0-3 reporting the 228 "aa" bits in the general suboption of the peer's segment. 229 Implementations must return an error ("ENOTCONN") if an 230 application attempts to read this value before the connection is 231 established. 233 TCP_ENO_ROLEOVERRIDE The value is a bit (0 or 1), indicating the 234 value of the "b" bit to set in the host's general suboption. The 235 "b" bit breaks the symmetry of simultaneous open to assign a 236 unique role "A" or "B" to each end of the connection. The host 237 that sets the "b" bit assumes the "B" role (which in non- 238 simultaneous open is by default assigned to the passive opener). 239 Implementations must return an error ("EISCONN") for attempts to 240 set this option after the SYN segment has already been sent. The 241 default value should be 0. 243 TCP_ENO_ROLE The value is a bit (0 or 1). TCP-ENO defines two 244 roles, "A" and "B", for the two ends of a connection. After a 245 normal three-way handshake, the active opener is "A" and the 246 passive opener is "B". Simultaneous open uses the role-override 247 bit to assign unique roles. This option returns 0 when the local 248 host has the "A" role, and 1 when the local host has the "B" role. 249 This call must return an error before the connection is 250 established ("ENOTCONN") or if TCP-ENO has failed ("EINVAL"). 252 TCP_ENO_LOCAL_NAME Returns the concatenation of the TCP_ENO_ROLE 253 byte and the TCP_ENO_SESSID. This provides a unique name for the 254 local end of the connection. 256 TCP_ENO_PEER_NAME Returns the concatenation of the negation of the 257 TCP_ENO_ROLE byte and the TCP_ENO_SESSID. This is the same value 258 as returned by TCP_ENO_LOCAL_NAME on the other host, and hence 259 provides a unique name for the remote end of the connection. 261 TCP_ENO_RAW This option is for use by library-level implementations 262 of encryption specs. It allows applications to make use of the 263 TCP-ENO option, potentially including encryption specs not 264 supported by the transport layer, and then entirely bypass any 265 TCP-level encryption so as to encrypt above the transport layer. 266 The default value of this option is a 0-byte vector, which 267 disables RAW mode. If the option is set to any other value, it 268 disables all other socket options described in this section except 269 for TCP_ENO_TRANSCRIPT. 271 The value of the option is a raw ENO option contents (without the 272 kind and length) to be included in the host's SYN segment. In raw 273 mode, the TCP layer considers negotiation successful when the two 274 SYN segments both contain a suboption with the same encryption 275 spec value "cs" >= 0x20. For an active opener in raw mode, the 276 TCP layer automatically sends a two-byte minimal ENO option when 277 negotiation is successful. Note that raw mode performs no sanity 278 checking on the "v" bits or any suboption data, and hence provides 279 slightly less flexibility than a true TCP-level implementation. 281 TCP_ENO_TRANSCRIPT Returns the negotiation transcript as specified 282 by TCP-ENO. Implementations must return an error if negotiation 283 failed ("EINVAL") or has not yet completed ("ENOTCONN"). 285 2.2. System-wide options 287 In addition to these per-socket options, implementations should use 288 "sysctl" or an equivalent mechanism to allow administrators to 289 configure a default value for "TCP_ENO_SPECS", as well as default 290 behavior for when "TCP_ENO_ENABLED" is -1. Table 3 provides a table 291 of suggested parameters. The type "words" corresponds to a list of 292 16-bit unsigned words representing TCP port numbers (similar to the 293 "baddynamic" sysctls that, on some operating systems, blacklist 294 automatic assignment of particular ports). These parameters should 295 be placed alongside most TCP parameters. For example, on BSD derived 296 systems a suitable name would be "net.inet.tcp.eno_specs", while on 297 Linux a more appropriate name would be "net.ipv4.tcp_eno_specs". 299 +-----------------------+-------------+ 300 | Name | Type | 301 +-----------------------+-------------+ 302 | eno_specs | bytes | 303 | eno_enable_connect | int (0 - 1) | 304 | eno_enable_listen | int (0 - 1) | 305 | eno_bad_connect_ports | words | 306 | eno_bad_listen_ports | words | 307 +-----------------------+-------------+ 309 Table 3: Suggested sysctl values 311 "eno_specs" is simply a string of bytes, and provides the default 312 value for the "TCP_ENO_SPECS" socket option. If "TCP_ENO_SPECS" is 313 non-empty, the remaining sysctls determine whether to attempt TCP-ENO 314 negotiation when the "TCP_ENO_ENABLED" option is -1 (the default), 315 using the following rules. 317 o On active openers: If "eno_enable_connect" is 0, then TCP-ENO is 318 disabled. If the remote port number is in 319 "eno_bad_connect_ports", then TCP-ENO is disabled. Otherwise, the 320 host attempts to use TCP-ENO. 322 o On passive openers: If "eno_enable_listen" is 0, then TCP-ENO is 323 disabled. Otherwise, if the local port is in 324 "eno_bad_listen_ports", then TCP-ENO is disabled. Otherwise, if 325 the host receives an SYN segment with an ENO option containing 326 compatible encryption specs, it attempts negotiation. 328 Because initial deployment may run into issues with middleboxes or 329 incur slowdown for unnecessary double-encryption, sites may wish to 330 blacklist particular ports. For example the following command: 332 sysctl net.inet.tcp.eno_bad_connect_ports=443,993 334 would disable ENO encryption on outgoing connections to ports 443 and 335 993 (which use application-layer encryption for HTTP and IMAP, 336 respectively). If the per-socket "TCP_ENO_ENABLED" is not -1, it 337 overrides the sysctl values. 339 On a server, running: 341 sysctl net.inet.tcp.eno_bad_listen_ports=443 343 makes it possible to disable TCP-ENO for incoming HTTPS connection 344 without modifying the web server to set "TCP_ENO_ENABLED" to 0. 346 3. Examples 348 This section provides examples of how applications might authenticate 349 session IDs. Authentication requires exchanging messages over the 350 TCP connection, and hence is not backwards compatible with existing 351 application protocols. To fall back to opportunistic encryption in 352 the event that both applications have not been updated to 353 authenticate the session ID, TCP-ENO provides the application-aware 354 bits. To signal it has been upgraded to support application-level 355 authentication, an application should set "TCP_ENO_SELF_AWARE" to 1 356 before opening a connection. An application should then check that 357 "TCP_ENO_PEER_AWARE" is non-zero before attempting to send 358 authenticators that would otherwise be misinterpreted as application 359 data. 361 3.1. Cookie-based authentication 363 In cookie-based authentication, a client and server both share a 364 cryptographically strong random or pseudo-random secret known as a 365 "cookie". Such a cookie is preferably at least 128 bits long. To 366 authenticate a session ID using a cookie, each host computes and 367 sends the following value to the other side: 369 authenticator = PRF(cookie, local-name) 371 Here "PRF" is a pseudo-random function such as HMAC-SHA-256 372 [RFC6234]. "local-name" is the result of the "TCP_ENO_LOCAL_NAME" 373 socket option. Each side must verify that the other side's 374 authenticator is correct. To do so, software obtains the remote 375 host's local name via the "TCP_ENO_PEER_NAME" socket option. 376 Assuming the authenticators are correct, applications can rely on the 377 TCP-layer encryption for resistance against active network attackers. 379 Note that if the same cookie is used in other contexts besides 380 session ID authentication, appropriate domain separation must be 381 employed, such as prefixing "local-name" with a unique prefix to 382 ensure "authenticator" cannot be used out of context. 384 3.2. Signature-based authentication 386 In signature-based authentication, one or both endpoints of a 387 connection possess a private signature key the public half of which 388 is known to or verifiable by the other endpoint. To authenticate 389 itself, the host with a private key computes the following signature: 391 authenticator = Sign(PrivKey, local-name) 393 The other end verifies this value using the corresponding public key. 394 Whichever side validates an authenticator in this way knows that the 395 other side belongs to a host that possesses the appropriate signature 396 key. 398 Once again, if the same signature key is used in other contexts 399 besides session ID authentication, appropriate domain separation 400 should be employed, such as prefixing "local-name" with a unique 401 prefix to ensure "authenticator" cannot be used out of context. 403 4. Security considerations 405 The TCP-ENO specification discusses several important security 406 considerations that this document incorporates by reference. The 407 most important one, which bears reiterating, is that until and unless 408 a session ID has been authenticated, TCP-ENO is vulnerable to an 409 active network attacker, through either a downgrade or active man-in- 410 the-middle attack. 412 Because of this vulnerability to active network attackers, it is 413 critical that implementations return appropriate errors for socket 414 options when TCP-ENO is not enabled. Equally critical is that 415 applications must never use these socket options without checking for 416 errors. 418 Applications with high security requirements that rely on TCP-ENO for 419 security must either fail or fall back to application-layer 420 encryption if TCP-ENO fails or session IDs authentication fails. 422 5. Acknowledgments 424 This work was funded by DARPA CRASH under contract #N66001-10-2-4088. 426 6. References 428 6.1. Normative References 430 [I-D.ietf-tcpinc-tcpeno] 431 Bittau, A., Boneh, D., Giffin, D., Handley, M., Mazieres, 432 D., and E. Smith, "TCP-ENO: Encryption Negotiation 433 Option", draft-ietf-tcpinc-tcpeno-01 (work in progress), 434 February 2016. 436 6.2. Informative References 438 [RFC0896] Nagle, J., "Congestion Control in IP/TCP Internetworks", 439 RFC 896, DOI 10.17487/RFC0896, January 1984, 440 . 442 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 443 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 444 DOI 10.17487/RFC6234, May 2011, 445 . 447 Authors' Addresses 449 Andrea Bittau 450 Stanford University 451 353 Serra Mall, Room 288 452 Stanford, CA 94305 453 US 455 Email: bittau@cs.stanford.edu 457 Dan Boneh 458 Stanford University 459 353 Serra Mall, Room 475 460 Stanford, CA 94305 461 US 463 Email: dabo@cs.stanford.edu 465 Daniel B. Giffin 466 Stanford University 467 353 Serra Mall, Room 288 468 Stanford, CA 94305 469 US 471 Email: dbg@scs.stanford.edu 472 Mark Handley 473 University College London 474 Gower St. 475 London WC1E 6BT 476 UK 478 Email: M.Handley@cs.ucl.ac.uk 480 David Mazieres 481 Stanford University 482 353 Serra Mall, Room 290 483 Stanford, CA 94305 484 US 486 Email: dm@uun.org 488 Eric W. Smith 489 Kestrel Institute 490 3260 Hillview Avenue 491 Palo Alto, CA 94304 492 US 494 Email: eric.smith@kestrel.edu