idnits 2.17.1 draft-bittau-tcpinc-api-00.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 1 instance 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 (August 10, 2015) is 3181 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-02) exists of draft-bittau-tcpinc-tcpeno-01 -- Obsolete informational reference (is this intentional?): RFC 896 (Obsoleted by RFC 7805) -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 3 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: February 11, 2016 Stanford University 6 M. Handley 7 University College London 8 D. Mazieres 9 Stanford University 10 E. Smith 11 Kestrel Institute 12 August 10, 2015 14 Interface Extensions for TCPINC 15 draft-bittau-tcpinc-api-00 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 for 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 February 11, 2016. 47 Copyright Notice 49 Copyright (c) 2015 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 3. Automatic configuration protocol . . . . . . . . . . . . . . 6 67 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 68 4.1. Cookie-based authentication . . . . . . . . . . . . . . . 8 69 4.2. Signature-based authentication . . . . . . . . . . . . . 8 70 5. Security considerations . . . . . . . . . . . . . . . . . . . 9 71 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 72 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 74 7.2. Informative References . . . . . . . . . . . . . . . . . 10 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 77 1. Introduction 79 The TCP Encryption Negotiation Option (TCP-ENO) 80 [I-D.bittau-tcpinc-tcpeno] permits hosts to negotiate encryption of a 81 TCP connection. One of TCP-ENO's use cases is to encrypt traffic 82 transparently, unbeknownst to legacy applications. Transparent 83 encryption requires no changes to existing APIs. However, other use 84 cases require applications to interact with TCP-ENO. In particular: 86 o Transparent encryption protects only against passive 87 eavesdroppers. Stronger security requires applications to 88 authenticate a _Session ID_ value associated with each encrypted 89 connection. 91 o Applications that have been updated to authenticate Session IDs 92 must somehow advertise this fact to peers in a backward-compatible 93 way. TCP-ENO carries a two-bit "application-aware" status for 94 this purpose, but this status is not accessible through existing 95 interfaces. 97 o Applications employing TCP's simultaneous open feature need a way 98 to supply a symmetry-breaking "tie-breaker" bit to TCP-ENO. 100 o System administrators and applications may wish to set and examine 101 negotiation preferences, such as which encryption schemes (and 102 perhaps versions) to enable and disable. 104 o Applications that perform their own encryption may wish to disable 105 TCP-ENO entirely. 107 The remainder of this document describes an API through which systems 108 can meet the above needs. The API extensions relate back to 109 quantities defined by TCP-ENO. 111 2. API extensions 113 Application should access TCP-ENO options through the same mechanism 114 they use to access other TCP configuration options, such as 115 "TCP_NODELAY" [RFC0896]. With the popular sockets API, this 116 mechanism consists of two socket options, "getsockopt" and 117 "setsockopt", shown in Figure 1. Socket-based TCP-ENO 118 implementations should define a set of new "option_name" values 119 accessible at "level" "IPPROTO_TCP" (generally defined as 6, to match 120 the IP protocol field). 122 int getsockopt(int socket, int level, int option_name, 123 void *option_value, socklen_t *option_len); 125 int setsockopt(int socket, int level, int option_name, 126 const void *option_value, socklen_t option_len); 128 Figure 1: Socket option API 130 Table 1 summarizes the new "option_name" arguments that TCP-ENO 131 introduces to the socket option (or equivalent) system calls. For 132 each option, the table lists whether it is read-only (R) or read- 133 write (RW), as well as the type of the option's value. Read-write 134 options, when read, always return the previously successfully written 135 value or the default if they have not been written. Options of type 136 "bytes" consist of a variable-length array of bytes, while options of 137 type "int" consist of a small integer with the exact range indicated 138 in parentheses. We discuss each option in more detail below. 140 +-------------------+----+----------------+ 141 | Option name | RW | Type | 142 +-------------------+----+----------------+ 143 | TCPENO_ENABLED | RW | int (-1 - 1) | 144 | TCPENO_SESSID | R | bytes | 145 | TCPENO_NEGSPEC | R | int (32 - 255) | 146 | TCPENO_SPECS | RW | bytes | 147 | TCPENO_SELF_AWARE | RW | int (0 - 3) | 148 | TCPENO_PEER_AWARE | R | int (0 - 3) | 149 | TCPENO_TIEBREAKER | RW | int (0 - 1) | 150 | TCPENO_ROLE | R | int (0 - 1) | 151 | TCPENO_RAW | RW | bytes | 152 | TCPENO_TRANSCRIPT | R | bytes | 153 +-------------------+----+----------------+ 155 Table 1: Suggested new IPPROTO_TCP socket options 157 TCPENO_ENABLED When set to 0, completely disables TCP-ENO regardless 158 of any other socket option settings except "TCPENO_RAW". When set 159 to 1, enables TCP-ENO. When set to -1 (which should be the 160 default), uses a system default value to determine whether or not 161 to enable TCP-ENO. This option must return an error after a SYN 162 segment has already been sent. 164 TCPENO_SESSID Returns the session ID of the connection, as defined 165 by the encryption spec in use. This option must return an error 166 if encryption is disabled, the connection is not yet established, 167 or the transport layer does not implement the negotiated spec. 169 TCPENO_NEGSPEC Returns the negotiated encryption spec for the 170 current connection. As defined by TCP-ENO, the negotiated spec is 171 the first valid suboption in the "B" host's SYN segment (without 172 any suboption data for variable-length suboptions). This option 173 must return an error if encryption is disabled or the connection 174 is not yet established. 176 TCPENO_SPECS Allows the application to specify an ordered list of 177 encryption specs different from the system default list. If the 178 list is empty, TCP-ENO is disabled for the connection. Each byte 179 in the list specifies one suboption type from 0x20-0xff. The list 180 contains no suboption data for variable-length suboptions, only 181 the one-byte spec identifier. The order of the list matters only 182 for the host playing the "B" role. Implementations must return an 183 error if an application attempts to set this option after the SYN 184 segment has been sent. Implementations should return an error if 185 any of the bytes are below 0x20 or are not implemented by the TCP 186 stack. 188 TCPENO_SELF_AWARE The value is an integer from 0-3, allowing 189 applications to specify the "aa" bits in the general suboption 190 sent by the host. When listening on a socket, the value of this 191 option applies to each accepted connection. Implementations must 192 return an error if an application attempts to set this option 193 after a SYN segment has been sent. 195 TCPENO_PEER_AWARE The value is an integer from 0-3 reporting the 196 "aa" bits in the general suboption of the peer's segment. 197 Implementations must return an error if an application attempts to 198 read this value before the connection is established. 200 TCPENO_TIEBREAKER The value is a bit (0 or 1), indicating the value 201 of the "b" bit to set in the host's general suboption. The "b" 202 bit breaks the symmetry of simultaneous open to assign a unique 203 role "A" or "B" to each end of the connection. The host that sets 204 the "b" bit assumes the "B" role (which in non-simultaneous open 205 is assigned to the passive opener). Implementations must return 206 an error for this options after the SYN segment has already been 207 sent. 209 TCPENO_ROLE The value is a bit (0 or 1). TCP-ENO defines two roles, 210 "A" and "B", for the two ends of a connection. After a normal 211 three-way handshake, the active opener is "A" and the passive 212 opener is "B". Simultaneous open uses the tie-breaker bit to 213 assign unique roles. This option returns 0 when the local host 214 has the "A" role, and 1 when the local host has the "B" role. 215 This call must return an error before the connection is 216 established or if TCP-ENO has failed. 218 TCPENO_RAW This option is for use by library-level implementations 219 of encryption specs. It allows applications to make use of the 220 TCP-ENO option, potentially including encryption specs not 221 supported by the transport layer, and then entirely bypass any 222 TCP-level encryption so as to encrypt above the transport layer. 223 The default value of this option is a 0-byte vector, which 224 disables RAW mode. If the option is set to any other value, it 225 disables all other socket options described in this section except 226 for TCPENO_TRANSCRIPT. 228 The value of the option is a raw ENO option contents (without the 229 kind and length) to be included in the host's SYN segment. In raw 230 mode, the TCP layer considers negotiation successful when the two 231 SYN segments both contain a suboption with the same encryption 232 spec value "cs" >= 0x20. For an active opener in raw mode, the 233 TCP layer automatically sends a two-byte minimal ENO option when 234 negotiation is successful. Note that raw mode performs no sanity 235 checking on the "v" bits or any suboption data, and hence provides 236 slightly less flexibility than a true TCP-level implementation. 238 TCPENO_TRANSCRIPT Returns the negotiation transcript as specified by 239 TCP-ENO. Implementations must return an error if negotiation 240 failed or has not yet completed. 242 In addition to these per-socket options, implementations should use 243 "sysctl" or an equivalent mechanism to allow administrators to 244 configure system-wide defaults for "TCPENO_ENABLED" and 245 "TCPENO_SPECS". These parameters should be named "eno_enabled" and 246 "eno_specs" and placed alongside most TCP parameters. For example, 247 on BSD derived systems a suitable name would be 248 "net.inet.tcp.eno_enabled" and "net.inet.tcp.eno_specs", while on 249 Linux more appropriate names would be "net.ipv4.tcp_eno_enabled" and 250 "net.ipv4.tcp_eno_specs". 252 Because initial deployment may run into issues with middleboxes or 253 incur slowdown for unnecessary double-encryption, implementations 254 should also allow ENO to be blacklisted for particular local and 255 remote ports, via sysctl on "net.inet.tcp.eno_bad_localport" and 256 "net.inet.tcp.eno_bad_remoteport" (or the equivalent under "net.ipv4" 257 for linux), both of which consist of a list of TCP port numbers on 258 which to disable TCP-ENO by default. For example the following 259 command: 261 sysctl net.inet.tcp.eno_bad_remoteport=443,993 263 would disable ENO encryption on outgoing connections to ports 443 and 264 993 (which use application-layer encryption for TLS and IMAP, 265 respectively). 267 The per-socket "TCPENO_ENABLED" option, if not -1, should override 268 both the "eno_enabled" and port-range sysctls. 270 3. Automatic configuration protocol 272 TCP-ENO is designed to fail by reverting to unencrypted TCP. Such 273 behavior is necessary for incremental deployment, and is no worse 274 than the status quo in which there is no TCP-layer encryption. 275 However, one outcome worse than the status quo would be to for TCP- 276 ENO connections to fail completely where unenecrypted connections 277 would work. Fortunately, if TCP-ENO is not supported by both 278 endpoints, or if middleboxes strip the ENO option from packets, then 279 implementations simply revert to unencrypted TCP upon receiving a SYN 280 or initial ACK segment without an ENO option. This fallback approach 281 also applies to interception proxies [RFC3040], which typically 282 terminate TCP connections and hence will not include ENO in their SYN 283 segments if they do not know about it. 285 However, given that the goal of TCP-ENO is to encrypt previously 286 plaintext traffic, there is always the possibility that a middlebox 287 performing deep packet inspection could shut down a connection 288 because the ciphertext does not resemble an expected higher-level 289 application protocol such as HTTP. Such middleboxes would cause TCP- 290 ENO connections to fail. Systems may wish to probe the network so as 291 to enable TCP-ENO only in places where middleboxes do not induce such 292 failures. 294 A precedent for probing middlebox behavior is the STUN protocol 295 [RFC5389], which applications use to characterize NAT. STUN relies 296 on having a known, publicly-accessible server beyond any locally 297 administered middleboxes. STUN is typically invoked by applications 298 that require peer-to-peer communication to decide whether they can 299 accept incoming connections. For TCP-ENO, which affects all TCP 300 connections, it makes more sense to probe for network compatibility 301 at the time network interfaces are configured by DHCP [RFC2131], 302 stateless address autoconfiguration [RFC4862], or other mechanisms. 303 Many DHCP implementation already provide hooks through which such 304 probes can be configured. 306 Like STUN, TCP-ENO probing requires a known external server running 307 an agreed upon protocol. We suggests using HTTP as the protocol, and 308 responding to the path "/tcp-eno/session-id" with a response of type 309 "text/plain". Upon successful TCP-ENO negotiation, servers should 310 reply with the string "encrypted " followed by a lower-case 311 hexadecimal encoding of the tcpcrypt session ID followed by a 312 newline. For connection on which TCP-ENO fails, the same path should 313 return the string "unencrypted\n" (with no session ID). If such a 314 request works with TCP-ENO disabled but hangs or resets with TCP-ENO 315 enabled, then TCP-ENO should be disabled for the host. Otherwise, if 316 probes succeed, even if they return "unencrypted", TCP-ENO should be 317 enabled (for the possible benefit of local connections), as 318 middleboxes may simply be stripping off the option. 320 Hosts should perform the above probe twice, using both port 80 and a 321 different port, we suggest 8080, on the same server. Given the 322 prevalence of interception proxies on port 80, port 80 may experience 323 entirely different failure modes from other ports. If the port 80 324 probe fails, TCP-ENO should be disabled for port 80. If the other 325 probe fails, TCP-ENO should be disabled entirely. 327 4. Examples 329 This section provides examples of how applications might authenticate 330 session IDs. Authentication requires exchanging messages over the 331 TCP connection, and hence is not backwards compatible with existing 332 application protocols. To fall back to opportunistic encryption in 333 the event that both applications have not been updated to 334 authenticate the session ID, TCP-ENO provides the application-aware 335 bits. To signal it has been upgraded to support application-level 336 authentication, applications should set "TCPENO_SELF_AWARE" to 1 337 before opening a connection. An application should then check that 338 "TCPENO_PEER_AWARE" is non-zero before attempting to send 339 authenticators that would otherwise be misinterpreted as application 340 data. 342 4.1. Cookie-based authentication 344 In cookie-based authentication, a client and server both share a 345 cryptographically strong random or pseudo-random secret known as a 346 "cookie". Such a cookie is preferably at least 128 bits long. To 347 authenticate a session ID using a cookie, each computes and sends the 348 following value to the other side: 350 authenticator = PRF(cookie, role || session-ID) 352 Here "PRF" is a psueo-random function such as HMAC-SHA-256 [RFC6234]. 353 "role" is the byte 0 or 1, as returned by the "TCPENO_ROLE" socket 354 options. "session-ID" is the session ID returned by the 355 "TCPENO_SESSID" session ID. The symbol "||" denotes concatenation. 356 Each side must verify that the other side's authenticator is correct. 357 Assuming the authenticators are correct, applications can rely on the 358 TCP-layer encryption for resistance against active network attackers. 360 Note that if the same cookie is used in other contexts besides 361 session ID authentication, appropriate domain separation should be 362 employed, such as prefixing "role || session-ID" with a unique prefix 363 to ensure "authenticator" cannot be used out of context. 365 4.2. Signature-based authentication 367 In signature-based authentication, one or both endpoints of a 368 connection possess a private signature key the public half of which 369 is known to or verifiable by the other endpoint. To authenticate 370 itself, the host with a private key computes the following signature: 372 authenticator = Sign(PrivKey, role || session-ID) 374 The other end verifies this value using the corresponding public key. 375 Whichever side validates an authenticator in this way knows that the 376 other side belongs to a host that possesses the appropriate signature 377 key. 379 Once again, if the same signature key is used in other contexts 380 besides session ID authentication, appropriate domain separation 381 should be employed, such as prefixing "role || session-ID" with a 382 unique prefix to ensure "authenticator" cannot be used out of 383 context. 385 5. Security considerations 387 The TCP-ENO specification discusses several important security 388 considerations that this document incorporates by reference. The 389 most important one, which bears reiterating, is that until and unless 390 a session ID has been authenticated, TCP-ENO is vulnerable to an 391 active network attacker, through either a downgrade or active man-in- 392 the-middle attack. 394 Because of this vulnerability to active network attackers, it is 395 critical that implementations return appropriate errors for socket 396 options when TCP-ENO is not enabled. Equally critical is that 397 applications must never use these socket options without checking for 398 errors. 400 Applications with high security requirements that rely on TCP-ENO for 401 security must either fail or fallback to application-layer encryption 402 if TCP-ENO fails or session IDs authentication fails. 404 6. Acknowledgments 406 This work was funded by DARPA CRASH under contract #N66001-10-2-4088. 408 7. References 410 7.1. Normative References 412 [I-D.bittau-tcpinc-tcpeno] 413 Bittau, A., Boneh, D., Giffin, D., Handley, M., Mazieres, 414 D., and E. Smith, "TCP-ENO: Encryption Negotiation 415 Option", draft-bittau-tcpinc-tcpeno-01 (work in progress), 416 August 2015. 418 7.2. Informative References 420 [RFC0896] Nagle, J., "Congestion Control in IP/TCP Internetworks", 421 RFC 896, DOI 10.17487/RFC0896, January 1984, 422 . 424 [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC 425 2131, DOI 10.17487/RFC2131, March 1997, 426 . 428 [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web 429 Replication and Caching Taxonomy", RFC 3040, DOI 10.17487/ 430 RFC3040, January 2001, 431 . 433 [RFC4862] Thomson, S., Narten, T., and T. Jinmei, "IPv6 Stateless 434 Address Autoconfiguration", RFC 4862, DOI 10.17487/ 435 RFC4862, September 2007, 436 . 438 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 439 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 440 DOI 10.17487/RFC5389, October 2008, 441 . 443 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 444 (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 445 10.17487/RFC6234, May 2011, 446 . 448 Authors' Addresses 450 Andrea Bittau 451 Stanford University 452 353 Serra Mall, Room 288 453 Stanford, CA 94305 454 US 456 Email: bittau@cs.stanford.edu 458 Dan Boneh 459 Stanford University 460 353 Serra Mall, Room 475 461 Stanford, CA 94305 462 US 464 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 473 Mark Handley 474 University College London 475 Gower St. 476 London WC1E 6BT 477 UK 479 Email: M.Handley@cs.ucl.ac.uk 481 David Mazieres 482 Stanford University 483 353 Serra Mall, Room 290 484 Stanford, CA 94305 485 US 487 Email: dm@uun.org 489 Eric W. Smith 490 Kestrel Institute 491 3260 Hillview Avenue 492 Palo Alto, CA 94304 493 US 495 Email: eric.smith@kestrel.edu