Network Working Group A. Bittau Internet-Draft D. Boneh Intended status: Informational D. Giffin Expires: September 3, 2016 Stanford University M. Handley University College London D. Mazieres Stanford University E. Smith Kestrel Institute March 2, 2016 Interface Extensions for TCP-ENO draft-bittau-tcpinc-api-01 Abstract TCP-ENO negotiates encryption at the transport layer. It also defines a few parameters that are intended to be used or configured by applications. This document specifies operating system interfaces for access to these TCP-ENO parameters. We describe the interfaces in terms of socket options, the de facto standard API for adjusting per-connection behavior in TCP/IP, and sysctl, a popular mechanism for setting global defaults. Operating systems that lack socket or sysctl functionality can implement similar interfaces in their native frameworks, but should ideally adapt their interfaces from those presented in this document. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on September 3, 2016. Bittau, et al. Expires September 3, 2016 [Page 1] Internet-Draft tcpinc-api March 2016 Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. API extensions . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Per-connection options . . . . . . . . . . . . . . . . . 3 2.2. System-wide options . . . . . . . . . . . . . . . . . . . 7 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1. Cookie-based authentication . . . . . . . . . . . . . . . 8 3.2. Signature-based authentication . . . . . . . . . . . . . 9 4. Security considerations . . . . . . . . . . . . . . . . . . . 9 5. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 6.1. Normative References . . . . . . . . . . . . . . . . . . 10 6.2. Informative References . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 1. Introduction The TCP Encryption Negotiation Option (TCP-ENO) [I-D.ietf-tcpinc-tcpeno] permits hosts to negotiate encryption of a TCP connection. One of TCP-ENO's use cases is to encrypt traffic transparently, unbeknownst to legacy applications. Transparent encryption requires no changes to existing APIs. However, other use cases require applications to interact with TCP-ENO. In particular: o Transparent encryption protects only against passive eavesdroppers. Stronger security requires applications to authenticate a _Session ID_ value associated with each encrypted connection. o Applications that have been updated to authenticate Session IDs must somehow advertise this fact to peers in a backward-compatible way. TCP-ENO carries a two-bit "application-aware" status for Bittau, et al. Expires September 3, 2016 [Page 2] Internet-Draft tcpinc-api March 2016 this purpose, but this status is not accessible through existing interfaces. o Applications employing TCP's simultaneous open feature need a way to supply a symmetry-breaking "role-override" bit to TCP-ENO. o System administrators and applications may wish to set and examine negotiation preferences, such as which encryption schemes (and perhaps versions) to enable and disable. o Applications that perform their own encryption may wish to disable TCP-ENO entirely. The remainder of this document describes an API through which systems can meet the above needs. The API extensions relate back to quantities defined by TCP-ENO. 2. API extensions This section describes an API for per-connection options, followed by a discussion of system-wide configuration options. 2.1. Per-connection options Application should access TCP-ENO options through the same mechanism they use to access other TCP configuration options, such as "TCP_NODELAY" [RFC0896]. With the popular sockets API, this mechanism consists of two socket options, "getsockopt" and "setsockopt", shown in Figure 1. Socket-based TCP-ENO implementations should define a set of new "option_name" values accessible at "level" "IPPROTO_TCP" (generally defined as 6, to match the IP protocol field). int getsockopt(int socket, int level, int option_name, void *option_value, socklen_t *option_len); int setsockopt(int socket, int level, int option_name, const void *option_value, socklen_t option_len); Figure 1: Socket option API Table 1 summarizes the new "option_name" arguments that TCP-ENO introduces to the socket option (or equivalent) system calls. For each option, the table lists whether it is read-only (R) or read- write (RW), as well as the type of the option's value. Read-write options, when read, always return the previously successfully written value or the default if they have not been written. Options of type "bytes" consist of a variable-length array of bytes, while options of Bittau, et al. Expires September 3, 2016 [Page 3] Internet-Draft tcpinc-api March 2016 type "int" consist of a small integer with the exact range indicated in parentheses. We discuss each option in more detail below. +----------------------+----+----------------+ | Option name | RW | Type | +----------------------+----+----------------+ | TCP_ENO_ENABLED | RW | int (-1 - 1) | | TCP_ENO_SESSID | R | bytes | | TCP_ENO_NEGSPEC | R | int (32 - 127) | | TCP_ENO_SPECS | RW | bytes | | TCP_ENO_SELF_AWARE | RW | int (0 - 3) | | TCP_ENO_PEER_AWARE | R | int (0 - 3) | | TCP_ENO_ROLEOVERRIDE | RW | int (0 - 1) | | TCP_ENO_ROLE | R | int (0 - 1) | | TCP_ENO_LOCAL_NAME | R | bytes | | TCP_ENO_PEER_NAME | R | bytes | | TCP_ENO_RAW | RW | bytes | | TCP_ENO_TRANSCRIPT | R | bytes | +----------------------+----+----------------+ Table 1: Suggested new IPPROTO_TCP socket options The socket options must return errors under certain circumstances. These errors are mapped to three suggested error codes shown in Table 2. Most socket-based systems will already have constants for these errors. Non-socket systems should use existing error codes corresponding to the same conditions. "EINVAL" is the existing error returned when setting options on a closed socket. "EISCONN" corresponds to calling connect a second time, while "ENOTCONN" corresponds to requesting the peer address of an unconnected socket. +----------+-----------------------------------------------------+ | Symbol | Description | +----------+-----------------------------------------------------+ | EINVAL | General error signifying bad parameters | | EISCONN | Option no longer valid because socket is connected | | ENOTCONN | Option not (yet) valid because socket not connected | +----------+-----------------------------------------------------+ Table 2: Suggested error codes TCP_ENO_ENABLED When set to 0, completely disables TCP-ENO regardless of any other socket option settings except "TCP_ENO_RAW". When set to 1, enables TCP-ENO. If set to -1, use a system-wide default determined at the time of an "accept" or "connect" system call, as described in Section 2.2. This option must return an error ("EISCONN") after a SYN segment has already been sent. Bittau, et al. Expires September 3, 2016 [Page 4] Internet-Draft tcpinc-api March 2016 TCP_ENO_SESSID Returns the session ID of the connection, as defined by the encryption spec in use. This option must return an error if encryption is disabled ("EINVAL"), the connection is not yet established ("ENOTCONN"), or the transport layer does not implement the negotiated spec ("EINVAL"). TCP_ENO_NEGSPEC Returns the 7-bit code point of the negotiated encryption spec for the current connection. As defined by TCP- ENO, the negotiated spec is the last valid suboption in the "B" host's SYN segment. This option must return an error if encryption is disabled ("EINVAL") or the connection is not yet established ("ENOTCONN"). TCP_ENO_SPECS Allows the application to specify an ordered list of encryption specs different from the system default list. If the list is empty, TCP-ENO is disabled for the connection. Each byte in the list specifies one suboption type from 0x20-0xff. The list contains no suboption data for variable-length suboptions, only the one-byte spec identifier. The high bit ("v") in these bytes is ignored unless future implementations of encryption specs assign it special meaning. The order of the list matters only for the host playing the "B" role. Implementations must return an error ("EISCONN") if an application attempts to set this option after the SYN segment has been sent. Implementations should return an error ("EINVAL") if any of the bytes are below 0x20 or are not implemented by the TCP stack. TCP_ENO_SELF_AWARE The value is an integer from 0-3, allowing applications to specify the "aa" bits in the general suboption sent by the host. When listening on a socket, the value of this option applies to each accepted connection. The default value should be 0. Implementations must return an error ("EISCONN") if an application attempts to set this option after a SYN segment has been sent. TCP_ENO_PEER_AWARE The value is an integer from 0-3 reporting the "aa" bits in the general suboption of the peer's segment. Implementations must return an error ("ENOTCONN") if an application attempts to read this value before the connection is established. TCP_ENO_ROLEOVERRIDE The value is a bit (0 or 1), indicating the value of the "b" bit to set in the host's general suboption. The "b" bit breaks the symmetry of simultaneous open to assign a unique role "A" or "B" to each end of the connection. The host that sets the "b" bit assumes the "B" role (which in non- simultaneous open is by default assigned to the passive opener). Implementations must return an error ("EISCONN") for attempts to Bittau, et al. Expires September 3, 2016 [Page 5] Internet-Draft tcpinc-api March 2016 set this option after the SYN segment has already been sent. The default value should be 0. TCP_ENO_ROLE The value is a bit (0 or 1). TCP-ENO defines two roles, "A" and "B", for the two ends of a connection. After a normal three-way handshake, the active opener is "A" and the passive opener is "B". Simultaneous open uses the role-override bit to assign unique roles. This option returns 0 when the local host has the "A" role, and 1 when the local host has the "B" role. This call must return an error before the connection is established ("ENOTCONN") or if TCP-ENO has failed ("EINVAL"). TCP_ENO_LOCAL_NAME Returns the concatenation of the TCP_ENO_ROLE byte and the TCP_ENO_SESSID. This provides a unique name for the local end of the connection. TCP_ENO_PEER_NAME Returns the concatenation of the negation of the TCP_ENO_ROLE byte and the TCP_ENO_SESSID. This is the same value as returned by TCP_ENO_LOCAL_NAME on the other host, and hence provides a unique name for the remote end of the connection. TCP_ENO_RAW This option is for use by library-level implementations of encryption specs. It allows applications to make use of the TCP-ENO option, potentially including encryption specs not supported by the transport layer, and then entirely bypass any TCP-level encryption so as to encrypt above the transport layer. The default value of this option is a 0-byte vector, which disables RAW mode. If the option is set to any other value, it disables all other socket options described in this section except for TCP_ENO_TRANSCRIPT. The value of the option is a raw ENO option contents (without the kind and length) to be included in the host's SYN segment. In raw mode, the TCP layer considers negotiation successful when the two SYN segments both contain a suboption with the same encryption spec value "cs" >= 0x20. For an active opener in raw mode, the TCP layer automatically sends a two-byte minimal ENO option when negotiation is successful. Note that raw mode performs no sanity checking on the "v" bits or any suboption data, and hence provides slightly less flexibility than a true TCP-level implementation. TCP_ENO_TRANSCRIPT Returns the negotiation transcript as specified by TCP-ENO. Implementations must return an error if negotiation failed ("EINVAL") or has not yet completed ("ENOTCONN"). Bittau, et al. Expires September 3, 2016 [Page 6] Internet-Draft tcpinc-api March 2016 2.2. System-wide options In addition to these per-socket options, implementations should use "sysctl" or an equivalent mechanism to allow administrators to configure a default value for "TCP_ENO_SPECS", as well as default behavior for when "TCP_ENO_ENABLED" is -1. Table 3 provides a table of suggested parameters. The type "words" corresponds to a list of 16-bit unsigned words representing TCP port numbers (similar to the "baddynamic" sysctls that, on some operating systems, blacklist automatic assignment of particular ports). These parameters should be placed alongside most TCP parameters. For example, on BSD derived systems a suitable name would be "net.inet.tcp.eno_specs", while on Linux a more appropriate name would be "net.ipv4.tcp_eno_specs". +-----------------------+-------------+ | Name | Type | +-----------------------+-------------+ | eno_specs | bytes | | eno_enable_connect | int (0 - 1) | | eno_enable_listen | int (0 - 1) | | eno_bad_connect_ports | words | | eno_bad_listen_ports | words | +-----------------------+-------------+ Table 3: Suggested sysctl values "eno_specs" is simply a string of bytes, and provides the default value for the "TCP_ENO_SPECS" socket option. If "TCP_ENO_SPECS" is non-empty, the remaining sysctls determine whether to attempt TCP-ENO negotiation when the "TCP_ENO_ENABLED" option is -1 (the default), using the following rules. o On active openers: If "eno_enable_connect" is 0, then TCP-ENO is disabled. If the remote port number is in "eno_bad_connect_ports", then TCP-ENO is disabled. Otherwise, the host attempts to use TCP-ENO. o On passive openers: If "eno_enable_listen" is 0, then TCP-ENO is disabled. Otherwise, if the local port is in "eno_bad_listen_ports", then TCP-ENO is disabled. Otherwise, if the host receives an SYN segment with an ENO option containing compatible encryption specs, it attempts negotiation. Because initial deployment may run into issues with middleboxes or incur slowdown for unnecessary double-encryption, sites may wish to blacklist particular ports. For example the following command: sysctl net.inet.tcp.eno_bad_connect_ports=443,993 Bittau, et al. Expires September 3, 2016 [Page 7] Internet-Draft tcpinc-api March 2016 would disable ENO encryption on outgoing connections to ports 443 and 993 (which use application-layer encryption for HTTP and IMAP, respectively). If the per-socket "TCP_ENO_ENABLED" is not -1, it overrides the sysctl values. On a server, running: sysctl net.inet.tcp.eno_bad_listen_ports=443 makes it possible to disable TCP-ENO for incoming HTTPS connection without modifying the web server to set "TCP_ENO_ENABLED" to 0. 3. Examples This section provides examples of how applications might authenticate session IDs. Authentication requires exchanging messages over the TCP connection, and hence is not backwards compatible with existing application protocols. To fall back to opportunistic encryption in the event that both applications have not been updated to authenticate the session ID, TCP-ENO provides the application-aware bits. To signal it has been upgraded to support application-level authentication, an application should set "TCP_ENO_SELF_AWARE" to 1 before opening a connection. An application should then check that "TCP_ENO_PEER_AWARE" is non-zero before attempting to send authenticators that would otherwise be misinterpreted as application data. 3.1. Cookie-based authentication In cookie-based authentication, a client and server both share a cryptographically strong random or pseudo-random secret known as a "cookie". Such a cookie is preferably at least 128 bits long. To authenticate a session ID using a cookie, each host computes and sends the following value to the other side: authenticator = PRF(cookie, local-name) Here "PRF" is a pseudo-random function such as HMAC-SHA-256 [RFC6234]. "local-name" is the result of the "TCP_ENO_LOCAL_NAME" socket option. Each side must verify that the other side's authenticator is correct. To do so, software obtains the remote host's local name via the "TCP_ENO_PEER_NAME" socket option. Assuming the authenticators are correct, applications can rely on the TCP-layer encryption for resistance against active network attackers. Note that if the same cookie is used in other contexts besides session ID authentication, appropriate domain separation must be Bittau, et al. Expires September 3, 2016 [Page 8] Internet-Draft tcpinc-api March 2016 employed, such as prefixing "local-name" with a unique prefix to ensure "authenticator" cannot be used out of context. 3.2. Signature-based authentication In signature-based authentication, one or both endpoints of a connection possess a private signature key the public half of which is known to or verifiable by the other endpoint. To authenticate itself, the host with a private key computes the following signature: authenticator = Sign(PrivKey, local-name) The other end verifies this value using the corresponding public key. Whichever side validates an authenticator in this way knows that the other side belongs to a host that possesses the appropriate signature key. Once again, if the same signature key is used in other contexts besides session ID authentication, appropriate domain separation should be employed, such as prefixing "local-name" with a unique prefix to ensure "authenticator" cannot be used out of context. 4. Security considerations The TCP-ENO specification discusses several important security considerations that this document incorporates by reference. The most important one, which bears reiterating, is that until and unless a session ID has been authenticated, TCP-ENO is vulnerable to an active network attacker, through either a downgrade or active man-in- the-middle attack. Because of this vulnerability to active network attackers, it is critical that implementations return appropriate errors for socket options when TCP-ENO is not enabled. Equally critical is that applications must never use these socket options without checking for errors. Applications with high security requirements that rely on TCP-ENO for security must either fail or fall back to application-layer encryption if TCP-ENO fails or session IDs authentication fails. 5. Acknowledgments This work was funded by DARPA CRASH under contract #N66001-10-2-4088. Bittau, et al. Expires September 3, 2016 [Page 9] Internet-Draft tcpinc-api March 2016 6. References 6.1. Normative References [I-D.ietf-tcpinc-tcpeno] Bittau, A., Boneh, D., Giffin, D., Handley, M., Mazieres, D., and E. Smith, "TCP-ENO: Encryption Negotiation Option", draft-ietf-tcpinc-tcpeno-01 (work in progress), February 2016. 6.2. Informative References [RFC0896] Nagle, J., "Congestion Control in IP/TCP Internetworks", RFC 896, DOI 10.17487/RFC0896, January 1984, . [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 10.17487/RFC6234, May 2011, . Authors' Addresses Andrea Bittau Stanford University 353 Serra Mall, Room 288 Stanford, CA 94305 US Email: bittau@cs.stanford.edu Dan Boneh Stanford University 353 Serra Mall, Room 475 Stanford, CA 94305 US Email: dabo@cs.stanford.edu Daniel B. Giffin Stanford University 353 Serra Mall, Room 288 Stanford, CA 94305 US Email: dbg@scs.stanford.edu Bittau, et al. Expires September 3, 2016 [Page 10] Internet-Draft tcpinc-api March 2016 Mark Handley University College London Gower St. London WC1E 6BT UK Email: M.Handley@cs.ucl.ac.uk David Mazieres Stanford University 353 Serra Mall, Room 290 Stanford, CA 94305 US Email: dm@uun.org Eric W. Smith Kestrel Institute 3260 Hillview Avenue Palo Alto, CA 94304 US Email: eric.smith@kestrel.edu Bittau, et al. Expires September 3, 2016 [Page 11]