draft-ietf-tcpinc-api-00.txt   draft-ietf-tcpinc-api-01.txt 
Network Working Group A. Bittau Network Working Group A. Bittau
Internet-Draft D. Boneh Internet-Draft Google
Intended status: Informational D. Giffin Intended status: Informational D. Boneh
Expires: January 9, 2017 Stanford University Expires: May 4, 2017 D. Giffin
Stanford University
M. Handley M. Handley
University College London University College London
D. Mazieres D. Mazieres
Stanford University Stanford University
E. Smith E. Smith
Kestrel Institute Kestrel Institute
July 8, 2016 October 31, 2016
Interface Extensions for TCP-ENO Interface Extensions for TCP-ENO and tcpcrypt
draft-ietf-tcpinc-api-00 draft-ietf-tcpinc-api-01
Abstract Abstract
TCP-ENO negotiates encryption at the transport layer. It also TCP-ENO and tcpcrypt perform encryption at the transport layer. They
defines a few parameters that are intended to be used or configured also define a few parameters that are intended to be used or
by applications. This document specifies operating system interfaces configured by applications. This document specifies operating system
for access to these TCP-ENO parameters. We describe the interfaces interfaces for access to these parameters. We describe the
in terms of socket options, the de facto standard API for adjusting interfaces in terms of socket options, the de facto standard API for
per-connection behavior in TCP/IP, and sysctl, a popular mechanism adjusting per-connection behavior in TCP/IP, and sysctl, a popular
for setting global defaults. Operating systems that lack socket or mechanism for setting global defaults. Operating systems that lack
sysctl functionality can implement similar interfaces in their native socket or sysctl functionality can implement similar interfaces in
frameworks, but should ideally adapt their interfaces from those their native frameworks, but should ideally adapt their interfaces
presented in this document. from those presented in this document.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 9, 2017. This Internet-Draft will expire on May 4, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. API extensions . . . . . . . . . . . . . . . . . . . . . . . 3 2. TCP-ENO API extensions . . . . . . . . . . . . . . . . . . . 3
2.1. Per-connection options . . . . . . . . . . . . . . . . . 3 2.1. Per-connection options . . . . . . . . . . . . . . . . . 3
2.2. Global options . . . . . . . . . . . . . . . . . . . . . 6 2.2. Global options . . . . . . . . . . . . . . . . . . . . . 7
3. Example API mappings . . . . . . . . . . . . . . . . . . . . 8 3. tcpcrypt API extensions . . . . . . . . . . . . . . . . . . . 8
3.1. Socket options for per-connection settings . . . . . . . 8 3.1. Per-connection options . . . . . . . . . . . . . . . . . 8
3.2. Setting System-wide options with sysctl . . . . . . . . . 8 3.2. Global options . . . . . . . . . . . . . . . . . . . . . 9
4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. Example API mappings . . . . . . . . . . . . . . . . . . . . 9
4.1. Cookie-based authentication . . . . . . . . . . . . . . . 9 4.1. Socket options for per-connection settings . . . . . . . 9
4.2. Signature-based authentication . . . . . . . . . . . . . 9 4.2. Setting System-wide options with sysctl . . . . . . . . . 10
5. Security considerations . . . . . . . . . . . . . . . . . . . 10 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 10
6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 5.1. Cookie-based authentication . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.2. Signature-based authentication . . . . . . . . . . . . . 11
7.1. Normative References . . . . . . . . . . . . . . . . . . 10 6. Security considerations . . . . . . . . . . . . . . . . . . . 11
7.2. Informative References . . . . . . . . . . . . . . . . . 10 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
8.1. Normative References . . . . . . . . . . . . . . . . . . 12
8.2. Informative References . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
1. Introduction 1. Introduction
The TCP Encryption Negotiation Option (TCP-ENO) The TCP Encryption Negotiation Option (TCP-ENO)
[I-D.ietf-tcpinc-tcpeno] permits hosts to negotiate encryption of a [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 TCP connection. One of TCP-ENO's use cases is to encrypt traffic
transparently, unbeknownst to legacy applications. Transparent transparently, unbeknownst to legacy applications. Transparent
encryption requires no changes to existing APIs. However, other use encryption requires no changes to existing APIs. However, other use
cases require applications to interact with TCP-ENO. In particular: cases require applications to interact with TCP-ENO. In particular:
o Transparent encryption protects only against passive o Transparent encryption protects only against passive
eavesdroppers. Stronger security requires applications to eavesdroppers. Stronger security requires applications to
authenticate a _Session ID_ value associated with each encrypted authenticate a _Session ID_ value associated with each encrypted
connection. connection.
o Applications that have been updated to authenticate Session IDs o Applications that have been updated to authenticate Session IDs
must somehow advertise this fact to peers in a backward-compatible must somehow advertise this fact to peers in a backward-compatible
way. TCP-ENO carries an "application-aware" bit for this purpose, way. TCP-ENO carries an "application-aware" bit for this purpose,
as well as a "middleware" bit, but these bits are not accessible but the bit is not accessible through existing interfaces.
through existing interfaces.
o Applications employing TCP's simultaneous open feature need a way o Applications employing TCP's simultaneous open feature need a way
to configure a passive-role bit to break symmetry for TCP-ENO. to configure a passive-role bit to break symmetry for TCP-ENO.
o System administrators and applications may wish to set and examine o System administrators and applications may wish to set and examine
negotiation preferences, such as which encryption schemes (and negotiation preferences, such as which encryption schemes (and
perhaps versions) to enable and disable. perhaps versions) to enable and disable.
o Applications that perform their own encryption may wish to disable o Applications that perform their own encryption may wish to disable
TCP-ENO entirely. TCP-ENO entirely.
The remainder of this document describes an API through which systems The tcpcrypt protocol [I-D.ietf-tcpinc-tcpcrypt] may be negotiated
via TCP-ENO, and can operate without configuration. But users may
wish to control a few operational details of the protocol:
o Users or system administrators may wish to specify which symmetric
ciphers they accept or prefer, or to inspect which cipher has been
negotiated for a particular connection. (The key-exchange schemes
used by tcpcrypt may be configured via the TCP-ENO API.)
o If connection tampering has been detected via session
authentication failure, it may be prudent to purge cached session
keys.
The remainder of this document describes APIs through which systems
can meet the above needs. The API extensions relate back to can meet the above needs. The API extensions relate back to
quantities defined by TCP-ENO. quantities defined by TCP-ENO and tcpcrypt.
2. API extensions 2. TCP-ENO API extensions
This section describes an API for per-connection options, followed by This section describes an API for per-connection options, followed by
a discussion of system-wide configuration options. a discussion of system-wide configuration options.
2.1. Per-connection options 2.1. Per-connection options
Table 1 summarizes a set of options that TCP-ENO implementations Table 1 summarizes a set of options that TCP-ENO implementations
should provide on a per-socket basis. For each option, the table should provide on a per-socket basis. For each option, the table
lists whether it is read-only (R) or read-write (RW), as well as the 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 type of the option's value. Read-write options, when read, always
return the previously successfully written value or the default if return the previously successfully written value or the default if
they have not been written. Options of type "bytes" consist of a they have not been written. Options of type "bytes" consist of a
variable-length array of bytes, while options of type "int" consist variable-length array of bytes, while options of type "int" consist
of a small integer with the exact range indicated in parentheses. We of a small integer with the exact range indicated in parentheses. We
discuss each option in more detail below. discuss each option in more detail below.
+--------------------+----+----------------+ +----------------------+----+-----------------------+
| Option name | RW | Type | | Option name | RW | Type |
+--------------------+----+----------------+ +----------------------+----+-----------------------+
| TCP_ENO_ENABLED | RW | int (-1 - 1) | | TCP_ENO_ENABLED | RW | int (-1, 0, or 1) |
| TCP_ENO_SESSID | R | bytes | | TCP_ENO_SESSID | R | bytes |
| TCP_ENO_NEGSPEC | R | int (32 - 127) | | TCP_ENO_NEGSPEC | R | int (32-127, 160-255) |
| TCP_ENO_SPECS | RW | bytes | | TCP_ENO_SPECS | RW | bytes |
| TCP_ENO_SELF_GOPT | RW | int (0 - 31) | | TCP_ENO_SELF_GOPT | RW | int (0-31) |
| TCP_ENO_PEER_GOPT | R | int (0 - 31) | | TCP_ENO_PEER_GOPT | R | int (0-31) |
| TCP_ENO_ROLE | R | int (0 - 1) | | TCP_ENO_AA_MANDATORY | RW | int (0 or 1) |
| TCP_ENO_LOCAL_NAME | R | bytes | | TCP_ENO_ROLE | R | int (0 or 1) |
| TCP_ENO_PEER_NAME | R | bytes | | TCP_ENO_SELF_NAME | R | bytes |
| TCP_ENO_RAW | RW | bytes | | TCP_ENO_PEER_NAME | R | bytes |
| TCP_ENO_TRANSCRIPT | R | bytes | | TCP_ENO_RAW | RW | bytes |
+--------------------+----+----------------+ | TCP_ENO_TRANSCRIPT | R | bytes |
+----------------------+----+-----------------------+
Table 1: Suggested per-connection options Table 1: Suggested per-connection options
The socket options must return errors under certain circumstances. The socket options must return errors under certain circumstances.
These errors are mapped to three suggested error codes shown in These errors are mapped to three suggested error codes shown in
Table 2. Systems based on sockets already have constants for these Table 2. Systems based on sockets already have constants for these
errors. Non-socket systems should use existing error codes errors. Non-socket systems should use existing error codes
corresponding to the same conditions. "EINVAL" is the existing error corresponding to the same conditions. "EINVAL" is the existing error
returned when attempting to set options or otherwise operate on a returned when attempting to set options or otherwise operate on a
closed socket. "EISCONN" corresponds to calling connect a second closed socket. "EISCONN" corresponds to calling connect a second
skipping to change at page 4, line 44 skipping to change at page 4, line 48
| Symbol | Description | | Symbol | Description |
+----------+--------------------------------------------------------+ +----------+--------------------------------------------------------+
| EINVAL | General error signifying bad parameters | | EINVAL | General error signifying bad parameters |
| EISCONN | Option no longer valid because connection established | | EISCONN | Option no longer valid because connection established |
| ENOTCONN | Option not (yet) valid because no connection | | ENOTCONN | Option not (yet) valid because no connection |
| | established | | | established |
+----------+--------------------------------------------------------+ +----------+--------------------------------------------------------+
Table 2: Suggested error codes Table 2: Suggested error codes
Unless otherwise specified, all of the read-only options (R) return
an error if ENO is disabled ("EINVAL"), the connection is not yet
established ("ENOTCONN"), the connection is established and ENO
failed to negotiate encryption ("EINVAL"), or the connection is in
raw mode ("EINVAL").
TCP_ENO_ENABLED TCP_ENO_ENABLED
When set to 0, completely disables TCP-ENO regardless of any other When set to 0, completely disables TCP-ENO regardless of any other
socket option settings except "TCP_ENO_RAW". When set to 1, socket option settings except "TCP_ENO_RAW". When set to 1,
enables TCP-ENO. If set to -1, use a system-wide default enables TCP-ENO. When set to -1, uses a system-wide default
determined at the time of an "accept" or "connect" system call, as determined at the time of an "accept" or "connect" system call, as
described in Section 2.2. This option must return an error described in Section 2.2. This option must return an error
("EISCONN") after a SYN segment has already been sent. ("EISCONN") after a SYN segment has already been sent.
TCP_ENO_SESSID TCP_ENO_SESSID
Returns the session ID of the connection, as defined by the Returns the session ID of the connection, as defined by the
encryption spec in use. This option must return an error if encryption spec in use.
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 TCP_ENO_NEGSPEC
Returns a byte in which the lower 7 bits correspond to the spec Returns a byte in which the lower 7 bits correspond to the spec
identifier of the negotiated encryption spec for the current identifier of the negotiated encryption spec for the current
connection, and the high bit is 1 if there was suboption data connection, and the high bit is 1 if there was suboption data
present. As defined by TCP-ENO, the negotiated spec is the last present. As defined by TCP-ENO, the negotiated spec is the last
valid suboption in host B's SYN segment. This option must return valid TEP suboption in the SYN segment sent by host "B".
an error if encryption is disabled ("EINVAL") or the connection is
not yet established ("ENOTCONN").
TCP_ENO_SPECS TCP_ENO_SPECS
Allows the application to specify an ordered list of encryption Allows the application to specify an ordered list of encryption
specs different from the system default list. If the list is specs different from the system default list. If the list is
empty, TCP-ENO is disabled for the connection. Each byte in the empty, TCP-ENO is disabled for the connection. Each byte in the
list specifies one suboption type from 0x20-0xff. The list list specifies one suboption type from 0x20-0x7f (32-127). For
contains no suboption data for variable-length suboptions, only future extensibility, the high bit ("v") in these bytes should be
the one-byte spec identifier. The high bit ("v") in these bytes set to 0 by applications and ignored by implementations. The
is ignored unless future implementations of encryption specs order of the list matters only for the host playing the "B" role.
assign it special meaning. The order of the list matters only for Implementations must return an error ("EISCONN") if an application
the host playing the "B" role. Implementations must return an attempts to set this option after the SYN segment has been sent.
error ("EISCONN") if an application attempts to set this option Implementations should return an error ("EINVAL") if any of the
after the SYN segment has been sent. Implementations should bytes are below 0x20, are between 0x80-0xa0, or are not
return an error ("EINVAL") if any of the bytes are below 0x20 or implemented by the TCP stack.
are not implemented by the TCP stack.
TCP_ENO_SELF_GOPT TCP_ENO_SELF_GOPT
The value is an integer from 0-31 specifying the 5-bit value of Sets the 5-bit value of the hosts global suboption. The default
the general suboption. The default value should initially be 0, value should initially be 0. In accordance the ENO specification,
but the low bit must be forced to 1 if the application configures regardless of any value set by the application, the least
the connection for a passive open. significant bit--termed the _passive role bit_--is forced to 1
when a connection is configured for passive open (i.e., following
a "listen" call). Implementations must return an error
("EISCONN") if an application attempts to set this option after a
SYN segment has been sent.
TCP_ENO_AA_MANDATORY
If set to 1, enables mandatory application-aware mode in which the
local host will disable TCP-ENO unless the remote host has set the
application-aware bit (the second-least significant bit in its
global suboption). The default value is 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_GOPT TCP_ENO_PEER_GOPT
The value is an integer from 0-31 reporting the value of the Returns an integer from 0-31 reporting the value of the global
general suboption in the peer's connection. suboption in the peer's SYN segment.
TCP_ENO_ROLE TCP_ENO_ROLE
The value is a bit (0 or 1). TCP-ENO defines two roles, "A" and Returns 0 on host "A" and 1 on host "B", according to the roles
"B", for the two ends of a connection. After a normal three-way defined by TCP-ENO. When successful, the value is always equal to
handshake, the active opener is "A" and the passive opener is "B". the least significant bit of the value returned by
Simultaneous open uses the role-override bit to assign unique TCP_ENO_SELF_GOPT.
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 TCP_ENO_SELF_NAME
Returns the concatenation of the TCP_ENO_ROLE byte and the Returns one byte containing the value of TCP_ENO_ROLE (0 or 1)
TCP_ENO_SESSID. This provides a unique name for the local end of prepended to the TCP_ENO_SESSID, thereby providing a unique name
the connection. for the local end of the connection.
TCP_ENO_PEER_NAME TCP_ENO_PEER_NAME
Returns the concatenation of the negation of the TCP_ENO_ROLE byte Like TCP_ENO_SELF_NAME, but negates the first byte, thereby
and the TCP_ENO_SESSID. This is the same value as returned by providing a unique name for the remote end of the connection.
TCP_ENO_LOCAL_NAME on the other host, and hence provides a unique (When successful, TCP_ENO_SELF_NAME at one end of a connection
name for the remote end of the connection. should always equal TCP_ENO_PEER_NAME at the other.)
TCP_ENO_RAW TCP_ENO_RAW
This option is for use by library-level implementations of This option is for use by library-level TEP implementations. It
encryption specs. It allows applications to make use of the TCP- allows applications to make use of the TCP-ENO option, potentially
ENO option, potentially including encryption specs not supported including encryption specs not supported by the transport layer,
by the transport layer, and then entirely bypass any TCP-level and then entirely bypass any TCP-level encryption so as to encrypt
encryption so as to encrypt above the transport layer. The above the transport layer. The default value of this option is a
default value of this option is a 0-byte vector, which disables 0-byte vector, which disables RAW mode. If the option is set to
RAW mode. If the option is set to any other value, it disables any other value, it disables all other socket options described in
all other socket options described in this section except for this section except for TCP_ENO_TRANSCRIPT.
TCP_ENO_TRANSCRIPT.
The value of the option is a raw ENO option contents (without the 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 kind and length) to be included in the host's SYN segment. In raw
mode, the TCP layer considers negotiation successful when the two mode, the TCP layer considers negotiation successful when the two
SYN segments both contain a suboption with the same encryption SYN segments both contain a suboption with the same encryption
spec value "cs" >= 0x20. For an active opener in raw mode, the spec value "cs" >= 0x20. For an active opener in raw mode, the
TCP layer automatically sends a two-byte minimal ENO option when TCP layer automatically sends a two-byte minimal ENO option when
negotiation is successful. Note that raw mode performs no sanity negotiation is successful. Note that raw mode performs no sanity
checking on the "v" bits or any suboption data, and hence provides checking on the "v" bits or any suboption data, and hence provides
slightly less flexibility than a true TCP-level implementation. slightly less flexibility than a true TCP-level implementation.
TCP_ENO_TRANSCRIPT TCP_ENO_TRANSCRIPT
Returns the negotiation transcript as specified by TCP-ENO. Returns the negotiation transcript as specified by TCP-ENO.
Implementations must return an error if negotiation failed Unlike any of the other read-only options, this option works in
("EINVAL") or has not yet completed ("ENOTCONN"). conjunction with TCP_ENO_RAW to allow application-layer encryption
to determine what was negotiated.
2.2. Global options 2.2. Global options
In addition to these per-socket options, implementations should use a In addition to these per-socket options, implementations should use a
global configuration mechanism to allow administrators to configure a global configuration mechanism to allow administrators to configure a
default value for "TCP_ENO_SPECS", as well as default behavior for default value for "TCP_ENO_SPECS", as well as default behavior for
when "TCP_ENO_ENABLED" is -1. These defaults can be system-wide, or when "TCP_ENO_ENABLED" is -1. These defaults can be system-wide, or
per network namespace on systems that provide network namespaces. per network namespace on systems that provide network namespaces.
Table 3 provides a table of suggested parameters. The type "words" Table 3 provides a table of suggested parameters. The type "words"
skipping to change at page 8, line 5 skipping to change at page 8, line 17
blacklist particular ports. For example setting blacklist particular ports. For example setting
"eno_bad_connect_ports" to 443,993 would disable ENO encryption on "eno_bad_connect_ports" to 443,993 would disable ENO encryption on
outgoing connections to ports 443 and 993 (which use application- outgoing connections to ports 443 and 993 (which use application-
layer encryption for HTTP and IMAP, respectively). If the per-socket layer encryption for HTTP and IMAP, respectively). If the per-socket
"TCP_ENO_ENABLED" is not -1, it overrides the sysctl values. "TCP_ENO_ENABLED" is not -1, it overrides the sysctl values.
Similarly, on a server, setting "eno_bad_listen_ports" to 443 makes Similarly, on a server, setting "eno_bad_listen_ports" to 443 makes
it possible to disable TCP-ENO for incoming HTTPS connection without it possible to disable TCP-ENO for incoming HTTPS connection without
modifying the web server to set "TCP_ENO_ENABLED" to 0. modifying the web server to set "TCP_ENO_ENABLED" to 0.
3. Example API mappings 3. tcpcrypt API extensions
Section 2 presented abstract APIs for per-connection and global This section recommends further extensions to the API set forth in
options. One implementation strategy would be to map these APIs to Section 2 that are specific to the tcpcrypt TEP. Future TEPs may
existing per-socket and global configuration mechanisms. By way of similarly provide TEP-specific options.
example, this section describes a way to map the per-connection
settings to BSD sockets options and global configuration to the Unix
"sysctl" interface.
3.1. Socket options for per-connection settings 3.1. Per-connection options
+-----------------------+----+-------------+
| Option name | RW | Type |
+-----------------------+----+-------------+
| TCP_CRYPT_CONF | R | int (0-255) |
| TCP_CRYPT_CACHE_FLUSH | W | int (1) |
| TCP_CRYPT_ACONF | RW | bytes |
| TCP_CRYPT_BCONF | RW | bytes |
+-----------------------+----+-------------+
Table 4: Suggested per-connection tcpcrypt-specific options
Table 4 summarizes the proposed tcpcrypt-specific per-connection
options.
TCP_CRYPT_CONF
Returns the one-byte specifier for the authenticated encryption
algorithm in use by the connection.
TCP_CRYPT_CACHE_FLUSH
Setting this option to the value 1 wipes cached session keys as
specified in section "Session caching" of
[I-D.ietf-tcpinc-tcpcrypt]. Useful if application-level
authentication discovers a man in the middle attack, to prevent
the next connection from using session caching.
TCP_CRYPT_ACONF
Set of allowed symmetric ciphers (AEAD algorithms) this host
advertises in "Init1" messages. These bytes are encoded exactly
as the bytes "sym-cipher0 ... sym-cipherK" in section "Key
exchange messages" of [I-D.ietf-tcpinc-tcpcrypt]; that is, each is
one of the "sym-cipher" bytes from the table of AEAD algorithms.
The order of these bytes is immaterial.
TCP_CRYPT_BCONF
Order of preference of symmetric ciphers. These bytes are encoded
in the same way as for "TCP_CRYPT_ACONF" above, except they
indicate the decreasing order of preference used to determine
which "sym-cipher" value to choose when sending an "Init2"
message.
3.2. Global options
+-------------+-------+
| Name | Type |
+-------------+-------+
| crypt_aconf | bytes |
| crypt_bconf | bytes |
+-------------+-------+
Table 5: Suggested tcrypt-specific global parameters
System administrators should also be able to set defaults for the
per-socket connection parameters. Table 5 lists the system-wide
parameters for doing so, which can exist along side the general ENO
parameters described in Table 3.
4. Example API mappings
The previous sections presented abstract APIs for per-connection and
global options. One implementation strategy would be to map these
APIs to existing per-socket and global configuration mechanisms. By
way of example, this section describes a way to map the per-
connection settings to BSD sockets options and global configuration
to the Unix "sysctl" interface.
4.1. Socket options for per-connection settings
Systems with sockets can allow applications to configure TCP-ENO Systems with sockets can allow applications to configure TCP-ENO
through the same mechanism they use for other TCP connection through the same mechanism they use for other TCP connection
configuration such as "TCP_NODELAY" [RFC0896], namely the configuration such as "TCP_NODELAY" [RFC0896], namely the
"getsockopt" and "setsockopt" system calls shown in Figure 1. "getsockopt" and "setsockopt" system calls shown in Figure 1.
int getsockopt(int socket, int level, int option_name, int getsockopt(int socket, int level, int option_name,
void *option_value, socklen_t *option_len); void *option_value, socklen_t *option_len);
int setsockopt(int socket, int level, int option_name, int setsockopt(int socket, int level, int option_name,
const void *option_value, socklen_t option_len); const void *option_value, socklen_t option_len);
Figure 1: Socket option API Figure 1: Socket option API
Socket-based TCP-ENO implementations can define a set of new Socket-based TCP-ENO implementations can define a set of new
"option_name" values accessible at "level" "IPPROTO_TCP" (generally "option_name" values accessible at "level" "IPPROTO_TCP" (generally
defined as 6, to match the IP protocol field), where each entry in defined as 6, to match the IP protocol field), where each entry in
Table 1 corresponds to a unique "option_name" constant. Table 1 corresponds to a unique "option_name" constant.
3.2. Setting System-wide options with sysctl 4.2. Setting System-wide options with sysctl
User-level implementations of TCP-ENO can use a configuration file to User-level implementations of TCP-ENO can use a configuration file to
set global options. However, such an approach may be awkward for set global options. However, such an approach may be awkward for
kernel-based implementations. Instead, kernel-level implementations kernel-based implementations. Instead, kernel-level implementations
can use the "sysctl" configuration tool. With this approach, TCP-ENO can use the "sysctl" configuration tool. With this approach, TCP-ENO
parameters should be placed alongside most TCP parameters. For parameters should be placed alongside most TCP parameters. For
example, on BSD derived systems a suitable name would be example, on BSD derived systems a suitable name would be
"net.inet.tcp.eno.specs", while on Linux a more appropriate name "net.inet.tcp.eno.specs", while on Linux a more appropriate name
would be "net.ipv4.tcp_eno_specs". would be "net.ipv4.tcp_eno_specs".
4. Examples 5. Examples
This section provides examples of how applications might authenticate This section provides examples of how applications might authenticate
session IDs. Authentication requires exchanging messages over the session IDs. Authentication requires exchanging messages over the
TCP connection, and hence is not backwards compatible with existing TCP connection, and hence is not backwards compatible with existing
application protocols. To fall back to opportunistic encryption in application protocols. To fall back to opportunistic encryption in
the event that both applications have not been updated to the event that both applications have not been updated to
authenticate the session ID, TCP-ENO provides the application-aware authenticate the session ID, TCP-ENO provides the application-aware
bits. To signal it has been upgraded to support application-level bit. To signal it has been upgraded to support application-level
authentication, an application should set "TCP_ENO_SELF_AWARE" to 1 authentication, an application should set the second-least
before opening a connection. An application should then check that significant bit of "TCP_ENO_SELF_GOPT" before opening a connection.
"TCP_ENO_PEER_AWARE" is non-zero before attempting to send An application should then check that "TCP_ENO_PEER_GOPT" has this
authenticators that would otherwise be misinterpreted as application bit set before attempting to send authenticators that would otherwise
data. be misinterpreted as application data.
4.1. Cookie-based authentication 5.1. Cookie-based authentication
In cookie-based authentication, a client and server both share a In cookie-based authentication, a client and server both share a
cryptographically strong random or pseudo-random secret known as a cryptographically strong random or pseudo-random secret known as a
"cookie". Such a cookie is preferably at least 128 bits long. To "cookie". Such a cookie is preferably at least 128 bits long. To
authenticate a session ID using a cookie, each host computes and authenticate a session ID using a cookie, each host computes and
sends the following value to the other side: sends the following value to the other side:
authenticator = PRF(cookie, local-name) authenticator = PRF(cookie, local-name)
Here "PRF" is a pseudo-random function such as HMAC-SHA-256 Here "PRF" is a pseudo-random function such as HMAC-SHA-256
[RFC6234]. "local-name" is the result of the "TCP_ENO_LOCAL_NAME" [RFC6234]. "local-name" is the result of the "TCP_ENO_LOCAL_NAME"
socket option. Each side must verify that the other side's socket option. Each side must verify that the other side's
authenticator is correct. To do so, software obtains the remote authenticator is correct. To do so, software obtains the remote
host's local name via the "TCP_ENO_PEER_NAME" socket option. host's name via the "TCP_ENO_PEER_NAME" socket option. Assuming the
Assuming the authenticators are correct, applications can rely on the authenticators are correct, applications can rely on the TCP-layer
TCP-layer encryption for resistance against active network attackers. encryption for resistance against active network attackers.
Note that if the same cookie is used in other contexts besides Note that if the same cookie is used in other contexts besides
session ID authentication, appropriate domain separation must be session ID authentication, appropriate domain separation must be
employed, such as prefixing "local-name" with a unique prefix to employed, such as prefixing "local-name" with a unique prefix to
ensure "authenticator" cannot be used out of context. ensure "authenticator" cannot be used out of context.
4.2. Signature-based authentication 5.2. Signature-based authentication
In signature-based authentication, one or both endpoints of a In signature-based authentication, one or both endpoints of a
connection possess a private signature key the public half of which connection possess a private signature key the public half of which
is known to or verifiable by the other endpoint. To authenticate is known to or verifiable by the other endpoint. To authenticate
itself, the host with a private key computes the following signature: itself, the host with a private key computes the following signature:
authenticator = Sign(PrivKey, local-name) authenticator = Sign(PrivKey, local-name)
The other end verifies this value using the corresponding public key. The other end verifies this value using the corresponding public key.
Whichever side validates an authenticator in this way knows that the Whichever side validates an authenticator in this way knows that the
other side belongs to a host that possesses the appropriate signature other side belongs to a host that possesses the appropriate signature
key. key.
Once again, if the same signature key is used in other contexts Once again, if the same signature key is used in other contexts
besides session ID authentication, appropriate domain separation besides session ID authentication, appropriate domain separation
should be employed, such as prefixing "local-name" with a unique should be employed, such as prefixing "local-name" with a unique
prefix to ensure "authenticator" cannot be used out of context. prefix to ensure "authenticator" cannot be used out of context.
5. Security considerations 6. Security considerations
The TCP-ENO specification discusses several important security The TCP-ENO specification [I-D.ietf-tcpinc-tcpeno] discusses several
considerations that this document incorporates by reference. The important security considerations that this document incorporates by
most important one, which bears reiterating, is that until and unless reference. The most important one, which bears reiterating, is that
a session ID has been authenticated, TCP-ENO is vulnerable to an until and unless a session ID has been authenticated, TCP-ENO is
active network attacker, through either a downgrade or active man-in- vulnerable to an active network attacker, through either a downgrade
the-middle attack. or active man-in-the-middle attack.
Because of this vulnerability to active network attackers, it is Because of this vulnerability to active network attackers, it is
critical that implementations return appropriate errors for socket critical that implementations return appropriate errors as suggested
options when TCP-ENO is not enabled. Equally critical is that in this document for socket options when TCP-ENO is not enabled. An
applications must never use these socket options without checking for example of an API design with potentially catastrophic consequences
errors. would be to attempt to communicate TCP-ENO failure by successfully
returning a zero-length or zero-valued session ID. 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 Applications with high security requirements that rely on TCP-ENO for
security must either fail or fall back to application-layer security must either fail or fall back to application-layer
encryption if TCP-ENO fails or session IDs authentication fails. encryption if TCP-ENO fails or session ID authentication fails.
6. Acknowledgments 7. Acknowledgments
This work was funded by DARPA CRASH under contract #N66001-10-2-4088. We are grateful for contributions, help, discussions, and feedback
from the TCPINC working group, including Marcelo Bagnulo, David
Black, Bob Briscoe, Jana Iyengar, Tero Kivinen, Mirja Kuhlewind, Yoav
Nir, Christoph Paasch, Eric Rescorla, Kyle Rose, and Joe Touch. This
work was partially funded by DARPA CRASH and the Stanford Secure
Internet of Things Project.
7. References 8. References
7.1. Normative References 8.1. Normative References
[I-D.ietf-tcpinc-tcpcrypt]
Bittau, A., Boneh, D., Giffin, D., Hamburg, M., Handley,
M., Mazieres, D., Slack, Q., and E. Smith, "Cryptographic
protection of TCP Streams (tcpcrypt)", draft-ietf-tcpinc-
tcpcrypt-03 (work in progress), October 2016.
[I-D.ietf-tcpinc-tcpeno] [I-D.ietf-tcpinc-tcpeno]
Bittau, A., Boneh, D., Giffin, D., Handley, M., Mazieres, Bittau, A., Boneh, D., Giffin, D., Handley, M., Mazieres,
D., and E. Smith, "TCP-ENO: Encryption Negotiation D., and E. Smith, "TCP-ENO: Encryption Negotiation
Option", draft-ietf-tcpinc-tcpeno-01 (work in progress), Option", draft-ietf-tcpinc-tcpeno-06 (work in progress),
February 2016. October 2016.
7.2. Informative References 8.2. Informative References
[RFC0896] Nagle, J., "Congestion Control in IP/TCP Internetworks", [RFC0896] Nagle, J., "Congestion Control in IP/TCP Internetworks",
RFC 896, DOI 10.17487/RFC0896, January 1984, RFC 896, DOI 10.17487/RFC0896, January 1984,
<http://www.rfc-editor.org/info/rfc896>. <http://www.rfc-editor.org/info/rfc896>.
[RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
(SHA and SHA-based HMAC and HKDF)", RFC 6234, (SHA and SHA-based HMAC and HKDF)", RFC 6234,
DOI 10.17487/RFC6234, May 2011, DOI 10.17487/RFC6234, May 2011,
<http://www.rfc-editor.org/info/rfc6234>. <http://www.rfc-editor.org/info/rfc6234>.
skipping to change at page 11, line 6 skipping to change at page 13, line 4
[RFC0896] Nagle, J., "Congestion Control in IP/TCP Internetworks", [RFC0896] Nagle, J., "Congestion Control in IP/TCP Internetworks",
RFC 896, DOI 10.17487/RFC0896, January 1984, RFC 896, DOI 10.17487/RFC0896, January 1984,
<http://www.rfc-editor.org/info/rfc896>. <http://www.rfc-editor.org/info/rfc896>.
[RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
(SHA and SHA-based HMAC and HKDF)", RFC 6234, (SHA and SHA-based HMAC and HKDF)", RFC 6234,
DOI 10.17487/RFC6234, May 2011, DOI 10.17487/RFC6234, May 2011,
<http://www.rfc-editor.org/info/rfc6234>. <http://www.rfc-editor.org/info/rfc6234>.
Authors' Addresses Authors' Addresses
Andrea Bittau Andrea Bittau
Stanford University Google
353 Serra Mall, Room 288 345 Spear Street
Stanford, CA 94305 San Francisco, CA 94105
US US
Email: bittau@cs.stanford.edu Email: bittau@google.com
Dan Boneh Dan Boneh
Stanford University Stanford University
353 Serra Mall, Room 475 353 Serra Mall, Room 475
Stanford, CA 94305 Stanford, CA 94305
US US
Email: dabo@cs.stanford.edu Email: dabo@cs.stanford.edu
Daniel B. Giffin Daniel B. Giffin
 End of changes. 46 change blocks. 
147 lines changed or deleted 249 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/