draft-ietf-tcpinc-api-01.txt   draft-ietf-tcpinc-api-02.txt 
Network Working Group A. Bittau Network Working Group A. Bittau
Internet-Draft Google Internet-Draft Google
Intended status: Informational D. Boneh Intended status: Informational D. Boneh
Expires: May 4, 2017 D. Giffin Expires: July 24, 2017 D. Giffin
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
October 31, 2016 January 20, 2017
Interface Extensions for TCP-ENO and tcpcrypt Interface Extensions for TCP-ENO and tcpcrypt
draft-ietf-tcpinc-api-01 draft-ietf-tcpinc-api-02
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 1, line 47 skipping to change at page 1, line 47
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 May 4, 2017. This Internet-Draft will expire on July 24, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2017 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
skipping to change at page 2, line 30 skipping to change at page 2, line 30
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. Global 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. Global options . . . . . . . . . . . . . . . . . . . . . 9
4. Example API mappings . . . . . . . . . . . . . . . . . . . . 9 4. Example API mappings . . . . . . . . . . . . . . . . . . . . 9
4.1. Socket options for per-connection settings . . . . . . . 9 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 . . . . . . . . . . . . . . . 10 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
8.2. Informative References . . . . . . . . . . . . . . . . . 12 8.2. Informative References . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13
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:
skipping to change at page 4, line 8 skipping to change at page 4, line 8
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, 0, or 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, 160-255) | | 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_AA_MANDATORY | RW | int (0 or 1) | | TCP_ENO_AA_MANDATORY | RW | int (0 or 1) |
| TCP_ENO_ROLE | R | int (0 or 1) | | TCP_ENO_TEP_MANDATORY | RW | int (0 or 1) |
| TCP_ENO_SELF_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 6, line 11 skipping to change at page 6, line 11
SYN segment has been sent. SYN segment has been sent.
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
If set to 1, enables mandatory encryption mode in which the local
host will abort the entire TCP connection if TCP-ENO fails to
negotiate encryption. The default value is 0. Setting this
option to 1 may permit optimizations (such as SYN data) that could
prevent falling back transparently to unencrypted TCP. Causes an
immediate connection abort if set to 1 on an established
unencrypted connection.
TCP_ENO_PEER_GOPT TCP_ENO_PEER_GOPT
Returns an integer from 0-31 reporting the value of the global Returns an integer from 0-31 reporting the value of the global
suboption in the peer's SYN segment. 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.
 End of changes. 10 change blocks. 
24 lines changed or deleted 34 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/