draft-ietf-tcpinc-api-04.txt   draft-ietf-tcpinc-api-05.txt 
skipping to change at page 1, line 17 skipping to change at page 1, line 17
Stanford University 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
September 29, 2017 September 29, 2017
Interface Extensions for TCP-ENO and tcpcrypt Interface Extensions for TCP-ENO and tcpcrypt
draft-ietf-tcpinc-api-04 draft-ietf-tcpinc-api-05
Abstract Abstract
TCP-ENO and tcpcrypt perform encryption at the transport layer. They TCP-ENO and tcpcrypt perform encryption at the transport layer. They
also define a few parameters that are intended to be used or also define a few parameters that are intended to be used or
configured by applications. This document specifies operating system configured by applications. This document specifies operating system
interfaces for access to these parameters. We describe the interfaces for access to these parameters. We describe the
interfaces in terms of socket options, the de facto standard API for interfaces in terms of socket options, the de facto standard API for
adjusting per-connection behavior in TCP/IP, and sysctl, a popular adjusting per-connection behavior in TCP/IP, and sysctl, a popular
mechanism for setting global defaults. Operating systems that lack mechanism for setting global defaults. Operating systems that lack
skipping to change at page 2, line 25 skipping to change at page 2, line 25
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. TCP-ENO 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 . . . . . . . . . . . . . . . . . . . . . 7 2.2. System-wide options . . . . . . . . . . . . . . . . . . . 7
3. tcpcrypt API extensions . . . . . . . . . . . . . . . . . . . 8 3. tcpcrypt API extensions . . . . . . . . . . . . . . . . . . . 8
3.1. Per-connection options . . . . . . . . . . . . . . . . . 8 3.1. Per-connection options . . . . . . . . . . . . . . . . . 8
3.2. Global options . . . . . . . . . . . . . . . . . . . . . 9 3.2. System-wide options . . . . . . . . . . . . . . . . . . . 9
4. Example API mappings . . . . . . . . . . . . . . . . . . . . 9 4. Example API mappings . . . . . . . . . . . . . . . . . . . . 9
4.1. Socket options for per-connection settings . . . . . . . 10 4.1. Socket options for per-connection settings . . . . . . . 10
4.2. Setting System-wide options with sysctl . . . . . . . . . 10 4.2. Setting System-wide options with sysctl . . . . . . . . . 10
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. Cookie-based authentication . . . . . . . . . . . . . . . 11 5.1. Cookie-based authentication . . . . . . . . . . . . . . . 11
5.2. Signature-based authentication . . . . . . . . . . . . . 11 5.2. Signature-based authentication . . . . . . . . . . . . . 11
6. Security considerations . . . . . . . . . . . . . . . . . . . 11 6. Security considerations . . . . . . . . . . . . . . . . . . . 11
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
8.1. Normative References . . . . . . . . . . . . . . . . . . 12 8.1. Normative References . . . . . . . . . . . . . . . . . . 12
skipping to change at page 4, line 31 skipping to change at page 4, line 31
| TCP_ENO_PEER_NAME | R | bytes | | TCP_ENO_PEER_NAME | R | bytes |
| TCP_ENO_RAW | RW | bytes | | TCP_ENO_RAW | RW | bytes |
| TCP_ENO_TRANSCRIPT | R | 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 error codes corresponding to
corresponding to the same conditions. "EINVAL" is the existing error the same conditions. "EINVAL" is the existing error returned when
returned when attempting to set options or otherwise operate on a attempting to set options or otherwise operate on a socket that has
closed socket. "EISCONN" corresponds to calling connect a second been shut down or is otherwise no longer valid. "EISCONN"
time, while "ENOTCONN" corresponds to requesting the peer address of corresponds to calling connect a second time, while "ENOTCONN"
an unconnected socket. corresponds to requesting the peer address of an unconnected socket.
+----------+--------------------------------------------------------+ +----------+--------------------------------------------------------+
| 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 With ENO, a connection can be in one of three high-level states:
an error if ENO is disabled ("EINVAL"), the connection is not yet negotiating or ready to negotiate encryption, encrypting, or
established ("ENOTCONN"), the connection is established and ENO disabled. Unless otherwise specified, all of the read-only options
failed to negotiate encryption ("EINVAL"), or the connection is in (R) succeed only when a connection is in the encrypting state.
raw mode ("EINVAL"). Specifically, attempts to read options should return "ENOTCONN" while
the connection is in the negotiating state and "EINVAL" if ENO is
disabled.
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. When set to -1, uses 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. Attempts to set this option must return described in Section 2.2. Attempts to set this option must return
an error ("EISCONN") after a SYN segment has already been sent. an error ("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. encryption spec in use.
TCP_ENO_NEGTEP TCP_ENO_NEGTEP
Returns a byte in which the lower 7 bits correspond to the TEP Returns a byte in which the lower 7 bits correspond to the TEP
identifier of the negotiated TEP for the current connection, and identifier of the negotiated TEP for the current connection, and
the high bit is 1 if there was suboption data present. As defined the high bit is 1 if the "v" bit was set (i.e., there was
by TCP-ENO, the negotiated spec is the last valid TEP suboption in suboption data present) in the suboption of the SYN segment sent
the SYN segment sent by host "B". by host "B".
TCP_ENO_TEPS TCP_ENO_TEPS
Allows the application to specify an ordered list of TEPs to Allows the application to specify an ordered list of TEPs to
negotiate different from the system default list. If the list is negotiate 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 ENO suboption type from 0x20-0x7f (32-127). list specifies one ENO suboption type from 0x20-0x7f (32-127).
For future extensibility, the high bit ("v") in these bytes should For future extensibility, the high bit ("v") in these bytes should
be set to 0 by applications and ignored by implementations. The be set to 0 by applications and ignored by implementations. The
order of the list matters only for the host playing the "B" role. order of the list matters only for the host playing the "B" role.
Implementations must return an error ("EISCONN") if an application Implementations must return an error ("EISCONN") if an application
skipping to change at page 5, line 50 skipping to change at page 6, line 5
TCP_ENO_SELF_GOPT TCP_ENO_SELF_GOPT
Gets or sets the 5-bit value of the local host's global suboption. Gets or sets the 5-bit value of the local host's global suboption.
The default value should initially be 0. In accordance the ENO The default value should initially be 0. In accordance the ENO
specification, regardless of any value set by the application, the specification, regardless of any value set by the application, the
least significant bit--termed the _passive role bit_--is forced to least significant bit--termed the _passive role bit_--is forced to
1 when a connection is configured for passive open (i.e., 1 when a connection is configured for passive open (i.e.,
following a "listen" call). Implementations must return an error following a "listen" call). Implementations must return an error
("EISCONN") if an application attempts to set this option after a ("EISCONN") if an application attempts to set this option after a
SYN segment has been sent. SYN segment has been sent.
TCP_ENO_PEER_GOPT
Returns an integer from 0-31 reporting the value of the global
suboption in the peer's SYN segment.
TCP_ENO_AA_MANDATORY TCP_ENO_AA_MANDATORY
If set to 1, enables mandatory application-aware mode in which the 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 local host will disable TCP-ENO unless the remote host has set the
application-aware bit (the second-least significant bit in its application-aware bit (the second-least significant bit in its
global suboption). The default value is 0. Implementations must global suboption). The default value is 0. Implementations must
return an error ("EISCONN") if an application attempts to set this return an error ("EISCONN") if an application attempts to set this
option after a SYN segment has been sent. option after a SYN segment has been sent.
TCP_ENO_TEP_MANDATORY TCP_ENO_TEP_MANDATORY
If set to 1, enables mandatory encryption mode in which the local If set to 1, enables mandatory encryption mode in which the local
host will abort the entire TCP connection if TCP-ENO fails to host will abort the entire TCP connection if TCP-ENO fails to
negotiate encryption. The default value is 0. Setting this negotiate encryption. The default value is 0. Setting this
option to 1 may permit optimizations (such as SYN data) that could option to 1 may permit optimizations (such as SYN data) that could
prevent falling back transparently to unencrypted TCP. prevent falling back transparently to unencrypted TCP.
Immediately aborts the connection if set to 1 on an established Immediately aborts the connection if set to 1 on an established
unencrypted connection. unencrypted connection.
TCP_ENO_PEER_GOPT
Returns an integer from 0-31 reporting the value of the global
suboption in the peer's SYN segment.
TCP_ENO_ROLE TCP_ENO_ROLE
Returns 0 on host "A" and 1 on host "B", according to the roles Returns 0 on host "A" and 1 on host "B", according to the roles
defined by TCP-ENO. When successful, the value is always equal to defined by TCP-ENO. When successful, the value is always equal to
the least significant bit of the value returned by the least significant bit of the value returned by
TCP_ENO_SELF_GOPT. TCP_ENO_SELF_GOPT.
TCP_ENO_SELF_NAME TCP_ENO_SELF_NAME
Returns the concatenation of one byte containing the value of Returns the concatenation of one byte containing the value of
TCP_ENO_ROLE (0 or 1) and the TCP_ENO_SESSID, thereby providing a TCP_ENO_ROLE (0 or 1) and the TCP_ENO_SESSID, thereby providing a
unique name for the local end of the connection. unique name for the local end of the connection.
skipping to change at page 7, line 18 skipping to change at page 7, line 18
SYN segments both contain a suboption with the same TEP identifier SYN segments both contain a suboption with the same TEP identifier
"cs" >= 0x20. For an active opener in raw mode, the TCP layer "cs" >= 0x20. For an active opener in raw mode, the TCP layer
automatically sends a two-byte minimal ENO option when negotiation automatically sends a two-byte minimal ENO option when negotiation
is successful. Note that raw mode performs no sanity checking on is successful. Note that raw mode performs no sanity checking on
the "v" bits or any suboption data, and hence provides slightly the "v" bits or any suboption data, and hence provides slightly
less flexibility than a true TCP-level implementation. 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.
Unlike any of the other read-only options, this option also works Unlike any of the other read-only options, this option also works
in conjunction with TCP_ENO_RAW to allow application-layer in conjunction with "TCP_ENO_RAW" to allow application-layer
encryption to determine what was negotiated. encryption to determine what was negotiated.
2.2. Global options 2.2. System-wide 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 system-wide configuration mechanism to allow administrators to
default value for "TCP_ENO_TEPS", as well as default behavior for configure a default value for "TCP_ENO_TEPS", as well as default
when "TCP_ENO_ENABLED" is -1. These defaults can be system-wide, or behavior for when "TCP_ENO_ENABLED" is -1. These defaults can be
per network namespace on systems that provide network namespaces. truly system-wide, or else scoped to a 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"
corresponds to a list of 16-bit unsigned words representing TCP port corresponds to a list of 16-bit unsigned words representing TCP port
numbers (similar to the "baddynamic" sysctls that, on some operating numbers (similar to the "baddynamic" sysctls that, on some operating
systems, blacklist automatic assignment of particular port numbers). systems, blacklist automatic assignment of particular port numbers).
+-----------------------+-------------+ +-----------------------+-------------+
| Name | Type | | Name | Type |
+-----------------------+-------------+ +-----------------------+-------------+
| eno_teps | bytes | | eno_teps | bytes |
| eno_enable_connect | int (0 - 1) | | eno_enable_connect | int (0 - 1) |
| eno_enable_listen | int (0 - 1) | | eno_enable_listen | int (0 - 1) |
| eno_bad_connect_ports | words | | eno_bad_connect_ports | words |
| eno_bad_listen_ports | words | | eno_bad_listen_ports | words |
+-----------------------+-------------+ +-----------------------+-------------+
Table 3: Suggested global parameters Table 3: Suggested system-wide parameters
"eno_teps" is simply a string of bytes; it provides the default value "eno_teps" is simply a string of bytes; it provides the default value
for the "TCP_ENO_TEPS" socket option. If "TCP_ENO_TEPS" is non- for the "TCP_ENO_TEPS" socket option. If "TCP_ENO_TEPS" is non-
empty, the remaining sysctls determine whether to attempt TCP-ENO empty, the remaining sysctls determine whether to attempt TCP-ENO
negotiation when the "TCP_ENO_ENABLED" option is -1 (the default), negotiation when the "TCP_ENO_ENABLED" option is -1 (the default),
using the following rules. using the following rules.
o On active openers: If "eno_enable_connect" is 0, then TCP-ENO is o On active openers: If "eno_enable_connect" is 0, then TCP-ENO is
disabled. If the remote port number is in disabled. If the remote port number is in
"eno_bad_connect_ports", then TCP-ENO is disabled. Otherwise, the "eno_bad_connect_ports", then TCP-ENO is disabled. Otherwise, the
skipping to change at page 9, line 23 skipping to change at page 9, line 23
Set of allowed symmetric ciphers (AEAD algorithms) this host Set of allowed symmetric ciphers (AEAD algorithms) this host
advertises in "Init1" messages. These bytes are encoded exactly advertises in "Init1" messages. These bytes are encoded exactly
as the bytes "sym-cipher0 ... sym-cipherK" in section "Key as the bytes "sym-cipher0 ... sym-cipherK" in section "Key
exchange messages" of [I-D.ietf-tcpinc-tcpcrypt]; that is, each is exchange messages" of [I-D.ietf-tcpinc-tcpcrypt]; that is, each is
one of the "sym-cipher" bytes from the table of AEAD algorithms. one of the "sym-cipher" bytes from the table of AEAD algorithms.
The order of these bytes is immaterial. The order of these bytes is immaterial.
TCP_CRYPT_BCONF TCP_CRYPT_BCONF
Order of preference of symmetric ciphers. These bytes are encoded Order of preference of symmetric ciphers. These bytes are encoded
in the same way as for "TCP_CRYPT_ACONF" above, except they in the same way as for "TCP_CRYPT_ACONF" above, except they
indicate the decreasing order of preference used to determine indicate the increasing order of preference used to determine
which "sym-cipher" value to choose when sending an "Init2" which "sym-cipher" value to choose when sending an "Init2"
message. message.
3.2. Global options 3.2. System-wide options
+-------------+-------+ +-------------+-------+
| Name | Type | | Name | Type |
+-------------+-------+ +-------------+-------+
| crypt_aconf | bytes | | crypt_aconf | bytes |
| crypt_bconf | bytes | | crypt_bconf | bytes |
+-------------+-------+ +-------------+-------+
Table 5: Suggested tcrypt-specific global parameters Table 5: Suggested tcrypt-specific global parameters
System administrators should also be able to set defaults for the System administrators should also be able to set defaults for the
per-socket connection parameters. Table 5 lists the system-wide per-socket connection parameters. Table 5 lists the system-wide
parameters for doing so, which can exist alongside the general ENO parameters for doing so, which can exist alongside the system-wide
parameters described in Table 3. ENO parameters described in Table 3.
4. Example API mappings 4. Example API mappings
The previous sections presented abstract APIs for per-connection and The previous sections presented abstract APIs for per-connection and
global options. One implementation strategy would be to map these global options. One implementation strategy would be to map these
APIs to existing per-socket and global configuration mechanisms. By APIs to existing per-socket and global configuration mechanisms. By
way of example, this section describes a way to map the per- way of example, this section describes a way to map the per-
connection settings to BSD socket options and the global connection settings to BSD socket options and the global
configuration settings to the Unix "sysctl" interface. configuration settings to the Unix "sysctl" interface.
 End of changes. 15 change blocks. 
32 lines changed or deleted 35 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/