Skip to main content

Cryptographic protection of TCP Streams (tcpcrypt)
draft-ietf-tcpinc-tcpcrypt-05

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 8548.
Authors Andrea Bittau, Dan Boneh , Daniel B. Giffin , Mike Hamburg , Mark J. Handley , David Mazieres , Quinn Slack , Eric W. Smith
Last updated 2017-02-15
Replaces draft-bittau-tcpinc-tcpcrypt
RFC stream Internet Engineering Task Force (IETF)
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state WG Document
Document shepherd (None)
IESG IESG state Became RFC 8548 (Experimental)
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD Mirja Kühlewind
Send notices to (None)
draft-ietf-tcpinc-tcpcrypt-05
Network Working Group                                          A. Bittau
Internet-Draft                                                    Google
Intended status: Experimental                                   D. Boneh
Expires: August 19, 2017                                       D. Giffin
                                                              M. Hamburg
                                                     Stanford University
                                                              M. Handley
                                               University College London
                                                             D. Mazieres
                                                                Q. Slack
                                                     Stanford University
                                                                E. Smith
                                                       Kestrel Institute
                                                       February 15, 2017

           Cryptographic protection of TCP Streams (tcpcrypt)
                     draft-ietf-tcpinc-tcpcrypt-05

Abstract

   This document specifies tcpcrypt, a TCP encryption protocol designed
   for use in conjunction with the TCP Encryption Negotiation Option
   (TCP-ENO) [I-D.ietf-tcpinc-tcpeno].  Tcpcrypt coexists with
   middleboxes by tolerating resegmentation, NATs, and other
   manipulations of the TCP header.  The protocol is self-contained and
   specifically tailored to TCP implementations, which often reside in
   kernels or other environments in which large external software
   dependencies can be undesirable.  Because the size of TCP options is
   limited, the protocol requires one additional one-way message latency
   to perform key exchange before application data may be transmitted.
   However, this cost can be avoided between two hosts that have
   recently established a previous tcpcrypt connection.

Status of This Memo";
       reference
         "RFC 8783: Distributed Denial-of-Service Open Threat
                    Signaling (DOTS) Data Channel Specification";
     }

     typedef activation-type {
       type enumeration {
         enum activate-when-mitigating {
           value 1;
           description
             "The Access Control List (ACL) is installed only when
              a mitigation is active for the DOTS client.";
         }
         enum immediate {
           value 2;
           description
             "The ACL is immediately activated.";
         }
         enum deactivate {
           value 3;
           description
             "The ACL is maintained by the DOTS server, but it is
              deactivated.";
         }
       }
       description
         "Indicates the activation type of an ACL.";
     }

     typedef operator {
       type bits {
         bit not {
           position 0;
           description
             "If set, logical negation of operation.";
         }
         bit match {
           position 1;
           description
             "Match bit.  This is a bitwise match operation
              defined as '(data & value) == value'.";
         }
         bit any {
           position 3;
           description
             "Any bit.  This is a match on any of the bits in
              bitmask.  It evaluates to 'true' if any of the bits
              in the value mask are set in the data,
              i.e., '(data & value) != 0'.";
         }
       }
       description
         "Specifies how to apply the defined bitmask.
          'any' and 'match' bits must not be set simultaneously.";
     }

     grouping tcp-flags {
       leaf operator {
         type operator;
         default "match";
         description
           "Specifies how to interpret the TCP flags.";
       }
       leaf bitmask {
         type uint16;
         mandatory true;
         description
           "The bitmask matches the last 4 bits of byte 12
            and byte 13 of the TCP header.  For clarity, the 4 bits
            of byte 12 corresponding to the TCP data offset field
            are not included in any matching.";
       }
       description
         "Operations on TCP flags.";
     }

     typedef fragment-type {
       type bits {
         bit df {
           position 0;
           description
             "Don't fragment bit for IPv4.
              Must be set to 0 when it appears in an IPv6 filter.";
         }
         bit isf {
           position 1;
           description
             "Is a fragment.";
         }
         bit ff {
           position 2;
           description
             "First fragment.";
         }
         bit lf {
           position 3;
           description
             "Last fragment.";
         }
       }
       description
         "Different fragment types to match against.";
     }

     grouping target {
       description
         "Specifies the targets of the mitigation request.";
       leaf-list target-prefix {
         type inet:ip-prefix;
         description
           "IPv4 or IPv6 prefix identifying the target.";
       }
       list target-port-range {
         key "lower-port";
         description
           "Port range.  When only lower-port is
            present, it represents a single port number.";
         leaf lower-port {
           type inet:port-number;
           mandatory true;
           description
             "Lower port number of the port range.&

   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."

Bittau, et al.           Expires August 19, 2017                [Page 1]
Internet-Draft                  tcpcrypt                   February 2017quot;;
         }
         leaf upper-port {
           type inet:port-number;
           must '. >= ../lower-port' {
             error-message
               "The upper-port number must be greater than
                or equal to the lower-port number.";
           }
           description
             "Upper port number of the port range.";
         }
       }
       leaf-list target-protocol {
         type uint8;
         description
           "Identifies the target protocol number.

            Values are taken from the IANA protocol registry:
            https://www.iana.org/assignments/protocol-numbers/

            For example, 6 for TCP or 17 for UDP.";
       }
       leaf-list target-fqdn {
         type inet:domain-name;
         description
           "FQDN identifying the target.";
       }
       leaf-list target-uri {
         type inet:uri;
         description
           "URI identifying the target.";
       }
     }

     grouping fragment-fields {
       leaf operator {
         type operator;
         default "match";
         description
           "Specifies how to interpret the fragment type.";
       }
       leaf type {
         type fragment-type;
         mandatory true;
         description
           "Indicates what fragment type to look for.";
       }
       description
         "Operations on fragment types.";
     }

     grouping aliases {
       description
         "Top-level container for aliases.";
       list alias {
         key "name";
         description
           "List of aliases.";
         leaf name {
           type string;
           description
             "The name of the alias.";
         }
         uses target;
         leaf pending-lifetime {
           type int32;
           units "minutes";
           config false;
           description
             "Indicates the pending validity lifetime of the alias
              entry.";
         }
       }
     }

     grouping ports {
       choice source-port {
         container source-port-range-or-operator {
           uses packet-fields:port-range-or-operator;
           description
             "Source port definition.";
         }
         description
           "Choice of specifying the source port or referring to
            a group of source port numbers.";
       }
       choice destination-port {
         container destination-port-range-or-operator {
           uses packet-fields:port-range-or-operator;
           description
             "Destination port definition.";
         }
         description
           "Choice of specifying a destination port or referring
            to a group of destination port numbers.";
       }
       description
         "Choice of specifying a source or destination port numbers.";
     }

     grouping access-lists {
       description
         "Specifies the ordered set of Access Control Lists.";
       list acl {
         key "name";
         ordered-by user;
         description
           "An ACL is an ordered list of Access Control Entries (ACE).
            Each ACE has a list of match criteria and a list of
            actions.";
         leaf name {
           type string {
             length "1..64";
           }
           description
             "The name of the access list.";
           reference
             "RFC 8519: YANG Data Model for Network Access
                        Control Lists (ACLs)";
         }
         leaf type {
           type ietf-acl:acl-type;
           description
             "Type of access control list.  Indicates the primary
              intended type of match criteria (e.g., IPv4, IPv6)
              used in the list instance.";
           reference
             "RFC 8519: YANG Data Model for Network Access
                        Control Lists (ACLs)";
         }
         leaf activation-type {
           type activation-type;
           default "activate-when-mitigating";
           description
             "Indicates the activation type of an ACL.  An ACL can be
              deactivated, installed immediately, or installed when
              a mitigation is active.";
         }
         leaf pending-lifetime {
           type int32;
           units "minutes";
           config false;
           description
             "Indicates the pending validity lifetime of the ACL
              entry.";
         }
         container aces {
           description
             "The Access Control Entries container contains
              a list of ACEs.";
           list ace {
             key "name";
             ordered-by user;
             description
               "List of access list entries.";
             leaf name {
               type string {
                 length "1..64";
               }
               description
                 "A unique name identifying this ACE.";
               reference
                 "RFC 8519: YANG Data Model for Network Access
                            Control Lists (ACLs)";
             }
             container matches {
               description
                 "The rules in this set determine what fields will be
                  matched upon before any action is taken on them.

                  If no matches are defined in a particular container,
                  then any packet will match that container.

                  If no matches are specified at all in an ACE, then any
                  packet will match the ACE.";
               reference
                 "RFC 8519: YANG Data Model for Network Access
                            Control Lists (ACLs)";
               choice l3 {
                 container ipv4 {
                   when "derived-from(../../../../type, "
                      + "'ietf-acl:ipv4-acl-type')";
                   uses packet-fields:acl-ip-header-fields;
                   uses packet-fields:acl-ipv4-header-fields;
                   container fragment {
                     description
                       "Indicates how to handle IPv4 fragments.";
                     uses fragment-fields;
                   }
                   description
                     "Rule set that matches IPv4 header.";
                 }
                 container ipv6 {
                   when "derived-from(../../../../type, "
                      + "'ietf-acl:ipv6-acl-type')";
                   uses packet-fields:acl-ip-header-fields;
                   uses packet-fields:acl-ipv6-header-fields;
                   container fragment {
                     description
                       "Indicates how to handle IPv6 fragments.";
                     uses fragment-fields;
                   }
                   description
                     "Rule set that matches IPv6 header.";
                 }
                 description
                   &

   This Internet-Draft will expire on August 19, 2017.

Copyright Notice

   Copyright (c) 2017 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.

   This document may contain material from IETF Documents or IETF
   Contributions published or made publicly available before November
   10, 2008.  The person(s) controlling the copyright in some of this
   material may not have granted the IETF Trust the right to allow
   modifications of such material outside the IETF Standards Process.
   Without obtaining an adequate license from the person(s) controlling
   the copyright in such materials, this document may not be modified
   outside the IETF Standards Process, and derivative works of it may
   not be created outside the IETF Standards Process, except to format
   it for publication as an RFC or to translate it into languages other
   than English.

Table of Contents

   1.  Requirements language . . . . . . . . . . . . . . . . . . . .   3
   2.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Encryption protocol . . . . . . . . . . . . . . . . . . . . .   3
     3.1.  Cryptographic algorithms  . . . . . . . . . . . . . . . .   4
     3.2.  Protocol negotiation  . . . . . . . . . . . . . . . . . .   5
     3.3.  Key exchange  . . . . . . . . . . . . . . . . . . . . . .   6
     3.4.  Session ID  . . . . . . . . . . . . . . . . . . . . . . .   8
     3.5.  Session caching . . . . . . . . . . . . . . . . . . . . .   8
     3.6.  Data encryption and authentication  . . . . . . . . . . .  11
     3.7.  TCP header protection . . . . . . . . . . . . . . . . . .  12
     3.8.  Re-keying . . . . . . . . . . . . . . . . . . . . . . . .  12
     3.9.  Keep-alive  . . . . . . . . . . . . . . . . . . . . . . .  13
   4.  Encodings . . . . . . . . . . . . . . . . . . . . . . . . . .  14
     4.1.  Key exchange messages . . . . . . . . . . . . . . . . . .  14
     4.2.  Application frames  . . . . . . . . . . . . . . . . . . .  16
       4.2.1.  Plaintext . . . . . . . . . . . . . . . . . . . . . .  16
       4.2.2.  Associated data . . . . . . . . . . . . . . . . . . .  17

Bittau, et al.           Expires August 19, 2017                [Page 2]
Internet-Draft                  tcpcrypt                   February 2017

       4.2.3.  Frame nonce . . . . . . . . . . . . . . . . . . . . .  17
   5.  Key agreement schemes . . . . . . . . . . . . . . . . . . . .  18
   6.  AEAD algorithms . . . . . . . . . . . . . . . . . . . . . . .  19
   7.  IANA considerations . . . . . . . . . . . . . . . . . . . . .  19
   8.  Security considerations . . . . . . . . . . . . . . . . . . .  20
   9.  Design notes  . . . . . . . . . . . . . . . . . . . . . . . .  21
     9.1.  Asymmetric roles  . . . . . . . . . . . . . . . . . . . .  21
     9.2.  Verified liveness . . . . . . . . . . . . . . . . . . . .  21
   10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .  22
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  22
     11.1.  Normative References . . . . . . . . . . . . . . . . . .  22
     11.2.  Informative References . . . . . . . . . . . . . . . . .  23
   Appendix A.  Protocol constant values . . . . . . . . . . . . . .  23
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  24

1.  Requirements language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

2.  Introduction

   This document describes tcpcrypt, an extension to TCP for
   cryptographic protection of session data.  Tcpcrypt was designed to
   meet the following goals:

   o  Meet the requirements of the TCP Encryption Negotiation Option
      (TCP-ENO) [I-D.ietf-tcpinc-tcpeno] for protecting connection data.

   o  Be amenable to small, self-contained implementations inside TCP
      stacks.

   o  Minimize additional latency at connection startup.

   o  As much as possible, prevent connection failure in the presence of
      NATs and other middleboxes that might normalize traffic or
      otherwise manipulate TCP segments.

   o  Operate independently of IP addresses, making it possible to
      authenticate resumed sessions efficiently even when either end
      changes IP address.

3.  Encryption protocol

   This section describes the tcpcrypt protocol at an abstract level.
   The concrete format of all messages is specified in Section 4.

Bittau, et al.           Expires August 19, 2017                [Page 3]
Internet-Draft                  tcpcrypt                   February 2017

3.1.  Cryptographic algorithms

   Setting up a tcpcrypt connection employs three types of cryptographic
   algorithms:

   o  A _key agreement scheme_ is used with a short-lived public key to
      agree upon a shared secret.

   o  An _extract function_ is used to generate a pseudo-random key from
      some initial keying material, typically the output of the key
      agreement scheme.  The notation Extract(S, IKM) denotes the output
      of the extract function with salt S and initial keying material
      IKM.

   o  A _collision-resistant pseudo-random function (CPRF)_ is used to
      generate multiple cryptographic keys from a pseudo-random key,
      typically the output of the extract function.  We use the notation
      CPRF(K, CONST, L) to designate the output of L bytes of the
      pseudo-random function identified by key K on CONST.

   The Extract and CPRF functions used by default are the Extract and
   Expand functions of HKDF [RFC5869].  These are defined as follows in
   terms of the PRF "HMAC-Hash(key, value)" for a negotiated "Hash"
   function:

           HKDF-Extract(salt, IKM) -> PRK
              PRK = HMAC-Hash(salt, IKM)

           HKDF-Expand(PRK, CONST, L) -> OKM
              T(0) = empty string (zero length)
              T(1) = HMAC-Hash(PRK, T(0) | CONST | 0x01)
              T(2) = HMAC-Hash(PRK, T(1) | CONST | 0x02)
              T(3) = HMAC-Hash(PRK, T(2) | CONST | 0x03)
              ...

              OKM  = first L octets of T(1) | T(2) | T(3) | ...

       Figure 1: The symbol | denotes concatenation, and the counter
           concatenated to the right of CONST is a single octet.

   Lastly, once tcpcrypt has been successfully set up and encryption
   keys have been derived, an algorithm for Authenticated Encryption
   with Associated Data (AEAD) is used to protect the confidentiality
   and integrity of all transmitted application data.  AEAD algorithms
   use a single key to encrypt their input data and also to generate a
   cryptographic tag to accompany the resulting ciphertext; when
   decryption is performed, the tag allows authentication of the
   encrypted data and of optional, associated plaintext data.

Bittau, et al.           Expires August 19, 2017                [Page 4]
Internet-Draft                  tcpcrypt                   February 2017

3.2.  Protocol negotiation

   Tcpcrypt depends on TCP-ENO [I-D.ietf-tcpinc-tcpeno] to negotiate
   whether encryption will be enabled for a connection, and also which
   key agreement scheme to use.  TCP-ENO negotiates the use of a
   particular TCP encryption protocol or _TEP_ by including protocol
   identifiers in ENO suboptions.  This document associates four TEP
   identifiers with the tcpcrypt protocol, as listed in Table 1.  Each
   identifier indicates the use of a particular key-agreement scheme.
   Future standards may associate additional identifiers with tcpcrypt.

   An active opener that wishes to negotiate the use of tcpcrypt
   includes an ENO option in its SYN segment.  That option includes
   suboptions with tcpcrypt TEP identifiers indicating the key-agreement
   schemes it is willing to enable.  The active opener MAY additionally
   include suboptions indicating support for encryption protocols other
   than tcpcrypt, as well as global suboptions as specified by TCP-ENO.

   If a passive opener receives an ENO option including tcpcrypt TEPs it
   supports, it MAY then attach an ENO option to its SYN-ACK segment,
   including _solely_ the TEP it wishes to enable.

   To establish distinct roles for the two hosts in each connection,
   tcpcrypt depends on the role-negotiation mechanism of TCP-ENO.  As
   one result of the negotiation process, TCP-ENO assigns hosts unique
   roles abstractly called "A" at one end of the connection and "B" at
   the other.  Generally, an active opener plays the "A" role and a
   passive opener plays the "B" role; but in the case of simultaneous
   open, an additional mechanism breaks the symmetry and assigns
   different roles to the two hosts.  This document adopts the terms
   "host A" and "host B" to identify each end of a connection uniquely,
   following TCP-ENO's designation.

   ENO suboptions include a flag "v" which indicates the presence of
   associated, variable-length data.  In order to propose fresh key
   agreement with a particular tcpcrypt TEP, a host sends a one-byte
   suboption containing the TEP identifier and "v = 0".  In order to
   propose session resumption (described further below) with a
   particular TEP, a host sends a variable-length suboption containing
   the TEP identifier, the flag "v = 1", and an identifier for a session
   previously negotiated with the same host and the same TEP.

   Once two hosts have exchanged SYN segments, TCP-ENO defines the
   _negotiated TEP_ to be the last valid TEP identifier in the SYN
   segment of host B (that is, the passive opener in the absence of
   simultaneous open) that also occurs in that of host A.  If there is
   no such TEP, hosts MUST disable TCP-ENO and tcpcrypt.

quot;Either IPv4 or IPv6.";
               }
               choice l4 {
                 container tcp {
                   uses packet-fields:acl-tcp-header-fields;
                   container flags-bitmask {
                     description
                       "Indicates how to handle TCP flags.";
                     uses tcp-flags;
                   }
                   uses ports;
                   description
                     "Rule set that matches TCP header.";
                 }
                 container udp {
                   uses packet-fields:acl-udp-header-fields;
                   uses ports;
                   description
                     "Rule set that matches UDP header.";
                 }
                 container icmp {
                   uses packet-fields:acl-icmp-header-fields;
                   description
                     "Rule set that matches ICMP/ICMPv6 header.";
                 }
                 description
                   "Can be TCP, UDP, or ICMP/ICMPv6";
               }
             }
             container actions {
               description
                 "Definitions of action for this ACE.";
               leaf forwarding {
                 type identityref {
                   base ietf-acl:forwarding-action;
                 }
                 mandatory true;
                 description
                   "Specifies the forwarding action per ACE.";
                 reference
                   "RFC 8519: YANG Data Model for Network Access
                              Control Lists (ACLs)";
               }
               leaf rate-limit {
                 when "../forwarding = 'ietf-acl:accept'" {
                   description
                     "Rate-limit is valid only when accept action is
                      used.";
                 }
                 type decimal64 {
                   fraction-digits 2;
                 }
                 units "bytes per second";
                 description
                   "Specifies how to rate-limit the traffic.";
               }
             }
             container statistics {
               config false;
               description
                 "Aggregate statistics.";
               uses ietf-acl:acl-counters;
             }
           }
         }
       }
     }

     container dots-data {
       description
         "Main container for DOTS data channel.";
       list dots-client {
         key "cuid";
         description
           "List of DOTS clients.";
         leaf cuid {
           type string;
           description
             "A unique identifier that is generated by a DOTS client
              to prevent request collisions.";
           reference
             "RFC 8782: Distributed Denial-of-Service Open Threat
                     Signaling (DOTS) Signal Channel Specification";
         }
         leaf cdid {
           type string;
           description
             "A client domain identifier conveyed by a
              server-domain DOTS gateway to a remote DOTS server.";
           reference
             "RFC 8782: Distributed Denial-of-Service Open Threat
                     Signaling (DOTS) Signal Channel Specification";
         }
         container aliases {
           description
             "Set of aliases that are bound to a DOTS client.";
           uses aliases;
         }
         container acls {
           description
             "Access lists that are bound to a DOTS client.";
           uses access-lists;
         }
       }
       container capabilities {
         config false;
         description
           "Match capabilities";
         leaf-list address-family {
           type enumeration {
             enum ipv4 {
               description
                 "IPv4 is supported.";
             }
             enum ipv6 {
               description
                 "IPv6 is supported.";
             }
           }
           description
             "Indicates the IP address families supported by
              the DOTS server.";
         }
         leaf-list forwarding-actions {
           type identityref {
             base ietf-acl:forwarding-action;
           }
           description
             "Supported forwarding action(s).";
         }
         leaf rate-limit {
           type boolean;
           description
             "Support of rate-limit action.";
         }
         leaf-list transport-protocols {
           type uint8;
           description
             "Upper-layer protocol associated with a filtering rule.

              Values are taken from the IANA protocol registry:
              https://www.iana.org/assignments/protocol-numbers/

              For example, this field contains 1 for ICMP, 6 for TCP
              17 for UDP, or 58 for ICMPv6.";
         }
         container ipv4 {
           description
             "Indicates IPv4 header fields that are supported to enforce
              ACLs.";
           leaf dscp {
             type boolean;
             description
               "Support of filtering based on Differentiated Services
                Code Point (DSCP).";
           }
           leaf ecn {
             type boolean;
             description
               "Support of filtering based on Explicit Congestion
                Notification (ECN).";
           }
           leaf length {
             type boolean;
             description
               "Support of filtering based on the Total Length.";
           }
           leaf ttl {
             type boolean;
             description
               "Support of filtering based on the Time to Live (TTL).";
           }
           leaf protocol {
             type boolean;
             description
               "Support of filtering based on protocol field.";
           }
           leaf ihl {
             type boolean;
             description
               "Support of filtering based on the Internet Header
                Length (IHL).";
           }
           leaf flags {
             type boolean;
             description
               "Support of filtering based on the 'flags'.";
           }
           leaf offset {
             type boolean;
             description
               "Support of filtering based on the 'offset'.";
           }
           leaf identification {
             type boolean;
             description
               "Support of filtering based on the 'identification'.";
           }
           leaf source-prefix {
             type boolean;
             description
               "Support of filtering based on the source prefix.&Bittau, et al.           Expires August 19, 2017                [Page 5]
Internet-Draft                  tcpcrypt                   February 2017

   If the negotiated TEP was sent by host B with "v = 0", it means that
   fresh key agreement will be performed as described below in
   Section 3.3.  If it had "v = 1", the key-exchange messages will be
   omitted in favor of determining keys via session-caching as described
   in Section 3.5, and protected application data may immediately be
   sent as detailed in Section 3.6.

   Note that the negotiated TEP is determined without reference to the
   "v" bits in ENO suboptions, so if host A offers resumption with a
   particular TEP and host B replies with a non-resumption suboption
   with the same TEP, that may become the negotiated TEP and fresh key
   agreement will be performed.  That is, sending a resumption suboption
   also implies willingness to perform fresh key agreement with the
   indicated TEP.

   As required by TCP-ENO, once a host has both sent and received an ACK
   segment containing a valid ENO option, encryption MUST be enabled and
   plaintext application data MUST NOT ever be exchanged on the
   connection.  If the negotiated TEP is among those listed in Table 1,
   a host MUST follow the protocol described in this document.

3.3.  Key exchange

   Following successful negotiation of a tcpcrypt TEP, all further
   signaling is performed in the Data portion of TCP segments.  Except
   when resumption was negotiated (described below in Section 3.5), the
   two hosts perform key exchange through two messages, "Init1" and
   "Init2", at the start of the data streams of host A and host B,
   respectively.  These messages may span multiple TCP segments and need
   not end at a segment boundary.  However, the segment containing the
   last byte of an "Init1" or "Init2" message SHOULD have TCP's PSH bit
   set.

   The key exchange protocol, in abstract, proceeds as follows:

       A -> B:  Init1 = { INIT1_MAGIC, sym-cipher-list, N_A, PK_A }
       B -> A:  Init2 = { INIT2_MAGIC, sym-cipher, N_B, PK_B }

   The concrete format of these messages is specified in Section 4.1.

   The parameters are defined as follows:

   o  "INIT1_MAGIC", "INIT2_MAGIC": constants defined in Table 3.

   o  "sym-cipher-list": a list of symmetric ciphers (AEAD algorithms)
      acceptable to host A.  These are specified in Table 2.

Bittau, et al.           Expires August 19, 2017                [Page 6]
Internet-Draft                  tcpcrypt                   February 2017

   o  "sym-cipher": the symmetric cipher selected by host B from the
      "sym-cipher-list" sent by host A.

   o  "N_A", "N_B": nonces chosen at random by hosts A and B,
      respectively.

   o  "PK_A", "PK_B": ephemeral public keys for hosts A and B,
      respectively.  These, as well as their corresponding private keys,
      are short-lived values that SHOULD be refreshed periodically.  The
      private keys SHOULD NOT ever be written to persistent storage.

   The ephemeral secret ("ES") is the result of the key-agreement
   algorithm (see Section 5) indicated by the negotiated TEP.  The
   inputs to the algorithm are the local host's ephemeral private key
   and the remote host's ephemeral public key.  For example, host A
   would compute "ES" using its own private key (not transmitted) and
   host B's public key, "PK_B".

   The two sides then compute a pseudo-random key ("PRK"), from which
   all session keys are derived, as follows:

          PRK = Extract(N_A, eno-transcript | Init1 | Init2 | ES)

   Above, "|" denotes concatenation; "eno-transcript" is the protocol-
   negotiation transcript defined in TCP-ENO; and "Init1" and "Init2"
   are the transmitted encodings of the messages described in
   Section 4.1.

   A series of "session secrets" are then computed from "PRK" as
   follows:

                 ss[0] = PRK
                 ss[i] = CPRF(ss[i-1], CONST_NEXTK, K_LEN)

   The value "ss[0]" is used to generate all key material for the
   current connection.  The values "ss[i]" for "i > 0" can be used to
   avoid public key cryptography when establishing subsequent
   connections between the same two hosts, as described in Section 3.5.
   The "CONST_*" values are constants defined in Table 3.  The length
   "K_LEN" depends on the tcpcrypt TEP in use, and is specified in
   Section 5.

   Given a session secret "ss", the two sides compute a series of master
   keys as follows:

                 mk[0] = CPRF(ss, CONST_REKEY, K_LEN)
                 mk[i] = CPRF(mk[i-1], CONST_REKEY, K_LEN)

Bittau, et al.           Expires August 19, 2017                [Page 7]
Internet-Draft                  tcpcrypt                   February 2017

   The particular master key in use is advanced as described in
   Section 3.8.

   Finally, each master key "mk" is used to generate keys for
   authenticated encryption for the "A" and "B" roles.  Key "k_ab" is
   used by host A to encrypt and host B to decrypt, while "k_ba" is used
   by host B to encrypt and host A to decrypt.

                  k_ab = CPRF(mk, CONST_KEY_A, ae_keylen)
                  k_ba = CPRF(mk, CONST_KEY_B, ae_keylen)

   The value "ae_keylen" depends on the authenticated-encryption
   algorithm selected, and is given under "Key Length" in Table 2.

   After host B sends "Init2" or host A receives it, that host may
   immediately begin transmitting protected application data as
   described in Section 3.6.

   If host A receives "Init2" with a "sym-cipher" value that was not
   present in the "sym-cipher-list" it previously transmitted in
   "Init1", it MUST abort the connection and raise an error condition
   distinct from the end-of-file condition.

3.4.  Session ID

   TCP-ENO requires each TEP to define a _session ID_ value that
   uniquely identifies each encrypted connection.

   As required, a tcpcrypt session ID begins with the negotiated TEP
   identifier along with the "v";
           }
           leaf destination-prefix {
             type boolean;
             description
               "Support of filtering based on the destination prefix.";
           }
           leaf fragment {
             type boolean;
             description
               "Indicates the capability of a DOTS server to
                enforce filters on IPv4 fragments.  That is, the match
                functionality based on the Layer 3 'fragment' clause
                is supported.";
           }
         }
         container ipv6 {
           description
             "Indicates IPv6 header fields that are supported to enforce
              ACLs.";
           leaf dscp {
             type boolean;
             description
               "Support of filtering based on DSCP.";
           }
           leaf ecn {
             type boolean;
             description
               "Support of filtering based on ECN.";
           }
           leaf length {
             type boolean;
             description
               "Support of filtering based on the Payload Length.";
           }
           leaf hoplimit {
             type boolean;
             description
               "Support of filtering based on the Hop Limit.";
           }
           leaf protocol {
             type boolean;
             description
               "Support of filtering based on the Next Header field.";
           }
           leaf destination-prefix {
             type boolean;
             description
               "Support of filtering based on the destination prefix.";
           }
           leaf source-prefix {
             type boolean;
             description
               "Support of filtering based on the source prefix.";
           }
           leaf flow-label {
             type boolean;
             description
               "Support of filtering based on the Flow Label.";
           }
           leaf fragment {
             type boolean;
             description
               "Indicates the capability of a DOTS server to
                enforce filters on IPv6 fragments.";
           }
         }
         container tcp {
           description
             "Set of TCP fields that are supported by the DOTS server
              to enforce filters.";
           leaf sequence-number {
             type boolean;
             description
               "Support of filtering based on the TCP sequence number.";
           }
           leaf acknowledgement-number {
             type boolean;
             description
               "Support of filtering based on the TCP acknowledgement
                number.";
           }
           leaf data-offset {
             type boolean;
             description
               "Support of filtering based on the TCP data-offset.";
           }
           leaf reserved {
             type boolean;
             description
               "Support of filtering based on the TCP reserved field.";
           }
           leaf flags {
             type boolean;
             description
               "Support of filtering, as defined in RFC 8519, based
                on the TCP flags.";
           }
           leaf window-size {
             type boolean;
             description
               "Support of filtering based on the TCP window size.";
           }
           leaf urgent-pointer {
             type boolean;
             description
               "Support of filtering based on the TCP urgent pointer.";
           }
           leaf options {
             type boolean;
             description
               "Support of filtering based on the TCP options.";
           }
           leaf flags-bitmask {
             type boolean;
             description
               "Support of filtering based on the TCP flags bitmask.";
           }
           leaf source-port {
             type boolean;
             description
               "Support of filtering based on the source port number.";
           }
           leaf destination-port {
             type boolean;
             description
               "Support of filtering based on the destination port
                number.";
           }
           leaf port-range {
             type boolean;
             description
               "Support of filtering based on a port range.

                This includes filtering based on a source port range,
                destination port range, or both.  All operators
                (i.e, less than or equal to, greater than or equal to,
                equal to, and not equal to) are supported.

                In particular, this means that the implementation
                supports filtering based on
                source-port-range-or-operator and
                destination-port-range-or-operator.";
           }
         }
         container udp {
           description
             "Set of UDP fields that are supported by the DOTS server
              to enforce filters.";
           leaf length {
             type boolean;
             description
               "Support of filtering based on the UDP length.";
           }
           leaf source-port {
             type boolean;
             description
               "Support of filtering based on the source port number.";
           }
           leaf destination-port {
             type boolean;
             description
               "Support of filtering based on the destination port
                number.";
           }
           leaf port-range {
             type boolean;
             description
               "Support of filtering based on a port range.

                This includes filtering based on a source port range,
                destination port range, or both.  All operators
                (i.e, less than or equal, greater than or equal,
                equal to, and not equal to) are supported.

                In particular, this means that the implementation
                supports filtering based on
                source-port-range-or-operator and
                destination-port-range-or-operator.";
           }
         }
         container icmp {
           description
             "Set of ICMP/ICMPv6 fields that are supported by the DOTS
              server to enforce filters.";
           leaf type {
             type boolean;
             description
               "Support of filtering based on the ICMP/ICMPv6 type.";
           }
           leaf code {
             type boolean;
             description
               "Support of filtering based on the ICMP/ICMPv6 code.";
           }
           leaf rest-of-header {
             type boolean;
             description
               "Support of filtering based on the ICMP four-byte
                field / the ICMPv6 message body.";
           }
         }
       }
     }
   }
   <CODE ENDS>

5.  Managing DOTS Clients

5.1.  Registering DOTS Clients

   In order to make use of the DOTS data channel, a DOTS client MUST
   register with its DOTS server(s) by creating a DOTS client ('dots-
   client') resource.  To that aim, DOTS clients SHOULD send a POST
   request (shown in Figure 11).

    POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1
    Host: {host}:{port}
    Content-Type: application/yang-data+json

    {
      "ietf-dots-data-channel:dots-client": [
        {
          "cuid": "string"
        }
      ]
    }

                     Figure 11: POST to Register Schema

   The 'cuid' (client unique identifier) parameter is described below:

   cuid:  A globally unique identifier that is meant to prevent
      collisions among DOTS clients.  This attribute has the same
      meaning, syntax, and processing rules as the 'cuid' attribute
      defined in [RFC8782].

      DOTS clients MUST use the same 'cuid' for both signal and data
      channels.

      This is a mandatory attribute.

   In deployments where server-domain DOTS gateways are enabled,
   identity information about the origin source client domain SHOULD be
   supplied to the DOTS server.  That information is meant to assist the
   DOTS server to enforce some policies.  These policies can be enforced
   per client, per client domain, or both.  Figure 12 shows a schema of
   a register request relayed by a server-domain DOTS gateway.

    POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1
    Host: {host}:{port}
    Content-Type: application/yang-data+json

    {
      "ietf-dots-data-channel:dots-client": [
        {
          "cuid": "string",
          "cdid": "string"
        }
      ]
    }

   Figure 12: POST to Register Schema (via a Server-Domain DOTS Gateway)

   A server-domain DOTS gateway SHOULD add the following attribute:

   cdid:  This attribute has the same meaning, syntax, and processing
      rules as the 'cdid' attribute defined in [RFC8782].

      In deployments where server-domain DOTS gateways are enabled,
      'cdid' does not need to be inserted when relaying DOTS methods to
      manage aliases (Section 6) or filtering rules (Section 7).  DOTS
      servers are responsible for maintaining the association between
      'cdid' and 'cuid' for policy enforcement purposes.

      This is an optional attribute.

   An example request to create a 'dots-client' resource is depicted in
   Figure 13.  This request is relayed by a server-domain DOTS gateway
   as hinted by the presence of the 'cdid' attribute.

    POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1
    Host: example.com
    Content-Type: application/yang-data+json

    {
      "ietf-dots-data-channel:dots-client": [
        {
          "cuid": " bit as transmitted by host B.  The
   remainder of the ID is derived from the session secret, as follows:

        session_id[i] = TEP-byte | CPRF(ss[i], CONST_SESSID, K_LEN)

   Again, the length "K_LEN" depends on the TEP, and is specified in
   Section 5.

3.5.  Session caching

   When two hosts have already negotiated session secret "ss[i-1]", they
   can establish a new connection without public-key operations using
   "ss[i]".  A host signals willingness to resume with a particular
   session secret by sending a SYN segment with a resumption suboption:
   that is, an ENO suboption containing the negotiated TEP identifier
   from the original session and part of an identifier for the session.

   The resumption identifier is calculated from a session secret "ss[i]"
   as follows:

Bittau, et al.           Expires August 19, 2017                [Page 8]
Internet-Draft                  tcpcrypt                   February 2017

                 resume[i] = CPRF(ss[i], CONST_RESUME, 18)

   To name a session for resumption, a host sends either the first or
   second half of the resumption identifier, according to the role it
   played in the original session with secret "ss[0]".

   A host that originally played role A and wishes to resume from a
   cached session sends a suboption with the first half of the
   resumption identifier:

       byte     0        1                  9      (10 bytes total)
            +--------+--------+---...---+--------+
            |  TEP-  |      resume[i]{0..8}      |
            |  byte  |                           |
            +--------+--------+---...---+--------+

    Figure 2: Resumption suboption sent when original role was A.  The
          TEP-byte contains a tcpcrypt TEP identifier and v = 1.

   Similarly, a host that originally played role B sends a suboption
   with the second half of the resumption identifier:

       byte     0        1                  9      (10 bytes total)
            +--------+--------+---...---+--------+
            |  TEP-  |      resume[i]{9..17}     |
            |  byte  |                           |
            +--------+--------+---...---+--------+

    Figure 3: Resumption suboption sent when original role was B.  The
          TEP-byte contains a tcpcrypt TEP identifier and v = 1.

   If a passive opener recognizes the identifier-half in a resumption
   suboption it has received and knows "ss[i]", it SHOULD (with
   exceptions specified below) agree to resume from the cached session
   by sending its own resumption suboption, which will contain the other
   half of the identifier.

   If it does not agree to resumption with a particular TEP, the passive
   opener may either request fresh key exchange by responding with a
   non-resumption suboption using the same TEP, or else respond to any
   other received suboption.

   If an active opener receives a resumption suboption for a particular
   TEP and the received identifier-half does not match the "resume[i]"
   value whose other half it previously sent in a resumption suboption
   for the same TEP, it MUST ignore that suboption.  In the typical case
   that this was the only ENO suboption received, this means the host

Bittau, et al.           Expires August 19, 2017                [Page 9]
Internet-Draft                  tcpcrypt                   February 2017

   MUST disable TCP-ENO and tcpcrypt: that is, it MUST NOT send any more
   ENO options and MUST NOT encrypt the connection.

   When a host concludes that TCP-ENO negotiation has succeeded for some
   TEP that was received in a resumption suboption, it MUST then enable
   encryption with that TEP, using the cached session secret, as
   described in Section 3.6.

   The session ID (Section 3.4) is constructed in the same way for
   resumed sessions as it is for fresh ones.  In this case the first
   byte will always have "v = 1".  The remainder of the ID is derived
   from the cached session secret.

   In the case of simultaneous open where TCP-ENO is able to establish
   asymmetric roles, two hosts that simultaneously send SYN segments
   with compatible resumption suboptions may resume the associated
   session.

   In a particular SYN segment, a host SHOULD NOT send more than one
   resumption suboption, and MUST NOT send more than one resumption
   suboption with the same TEP identifier.  But in addition to any
   resumption suboptions, an active opener MAY include non-resumption
   suboptions describing other key-agreement schemes it supports (in
   addition to that indicated by the TEP in the resumption suboption).

   After using "ss[i]" to compute "mk[0]", implementations SHOULD
   compute and cache "ss[i+1]" for possible use by a later session, then
   erase "ss[i]" from memory.  Hosts SHOULD retain "ss[i+1]" until it is
   used or the memory needs to be reclaimed.  Hosts SHOULD NOT write a
   cached "ss[i+1]" value to non-volatile storage.

   When proposing resumption, the active opener MUST use the lowest
   value of "i" that has not already been used (successfully or not) to
   negotiate resumption with the same host and for the same pre-session
   key "ss[0]".

   A host MUST NOT resume with a session secret if it has ever
   successfully negotiated resumption in the past, in either role, with
   the same secret.  In the event that two hosts simultaneously send SYN
   segments to each other that propose resumption with the same session
   secret but the two segments are not part of a simultaneous open, both
   connections will have to revert to fresh key-exchange.  To avoid this
   limitation, implementations MAY choose to implement session caching
   such that a given pre-session key "ss[0]" is only used for either
   passive or active opens at the same host, not both.

Bittau, et al.           Expires August 19, 2017               [Page 10]
Internet-Draft                  tcpcrypt                   February 2017

   When two hosts have previously negotiated a tcpcrypt session, either
   host may initiate session resumption regardless of which host was the
   active opener or played the "A" role in the previous session.

   However, a given host must either encrypt with "k_ab" for all
   sessions derived from the same pre-session key "ss[0]", or with
   "k_ba".  Thus, which keys a host uses to send segments is not
   affected by the role it plays in the current connection: it depends
   only on whether the host played the "A" or "B" role in the initial
   session.

   Implementations that perform session caching MUST provide a means for
   applications to control session caching, including flushing cached
   session secrets associated with an ESTABLISHED connection or
   disabling the use of caching for a particular connection.

3.6.  Data encryption and authentication

   Following key exchange (or its omission via session caching), all
   further communication in a tcpcrypt-enabled connection is carried out
   within delimited _application frames_ that are encrypted and
   authenticated using the agreed keys.

   This protection is provided via algorithms for Authenticated
   Encryption with Associated Data (AEAD).  The particular algorithms
   that may be used are listed in Table 2.  One algorithm is selected
   during the negotiation described in Section 3.3.

   The format of an application frame is specified in Section 4.2.  A
   sending host breaks its stream of application data into a series of
   chunks.  Each chunk is placed in the "data" portion of a "plaintext"
   value, which is then encrypted to yield a frame's "ciphertext" field.
   Chunks must be small enough that the ciphertext (whose length depends
   on the AEAD cipher used, and is generally slightly longer than the
   plaintext) has length less than 2^16 bytes.

   An "associated data" value (see Section 4.2.2) is constructed for the
   frame.  It contains the frame's "control" field and the length of the
   ciphertext.

   A "frame nonce" value (see Section 4.2.3) is also constructed for the
   frame but not explicitly transmitted.  It contains an "offset" field
   whose integer value is the zero-indexed byte offset of the beginning
   of the current application frame in the underlying TCP datastream.
   (That is, the offset in the framing stream, not the plaintext
   application stream.)  Because it is strictly necessary for the
   security of the AEAD algorithm, an implementation MUST NOT ever
   transmit distinct frames with the same nonce value under the same

Bittau, et al.           Expires August 19, 2017               [Page 11]
Internet-Draft                  tcpcrypt                   February 2017

   encryption key.  In particular, a retransmitted TCP segment MUST
   contain the same payload bytes for the same TCP sequence numbers, and
   a host MUST NOT transmit more than 2^64 bytes in the underlying TCP
   datastream (which would cause the "offset" field to wrap) before re-
   keying.

   With reference to the "AEAD Interface" described in Section 2 of
   [RFC5116], tcpcrypt invokes the AEAD algorithm with the secret key
   "K" set to k_ab or k_ba, according to the host's role as described in
   Section 3.3.  The plaintext value serves as "P", the associated data
   as "A", and the frame nonce as "N".  The output of the encryption
   operation, "C", is transmitted in the frame's "ciphertext" field.

   When a frame is received, tcpcrypt reconstructs the associated data
   and frame nonce values (the former contains only data sent in the
   clear, and the latter is implicit in the TCP stream), and provides
   these and the ciphertext value to the the AEAD decryption operation.
   The output of this operation is either a plaintext value "P" or the
   special symbol FAIL.  In the latter case, the implementation MUST
   either ignore the frame or abort the connection; but if it aborts,
   the implementation MUST raise an error condition distinct from the
   end-of-file condition.

3.7.  TCP header protection

   The "ciphertext" field of the application frame contains protected
   versions of certain TCP header values.

   When "URGp" is set, the "urgent" value indicates an offset from the
   current frame's beginning offset; the sum of these offsets gives the
   index of the last byte of urgent data in the application datastream.

   When "FINp" is set, it indicates that the sender will send no more
   application data after this frame.  When the TCP FIN flag differs
   from "FINp", a receiving host MUST either ignore the segment
   altogether or abort the connection and raise an error condition
   distinct from the end-of-file condition.

3.8.  Re-keying

   Re-keying allows hosts to wipe from memory keys that could decrypt
   previously transmitted segments.  It also allows the use of AEAD
   ciphers that can securely encrypt only a bounded number of messages
   under a given key.

   We refer to the two encryption keys (k_ab, k_ba) as a _key-set_.  We
   refer to the key-set generated by mk[i] as the key-set with
   _generation number_ "i" within a session.  Each host maintains a

Bittau, et al.           Expires August 19, 2017               [Page 12]
Internet-Draft                  tcpcrypt                   February 2017

   _local generation number_ that determines which key-set it uses to
   encrypt outgoing frames, and a _remote generation number_ equal to
   the highest generation used in frames received from its peer.
   Initially, these two values are set to zero.

   A host MAY increment its local generation number beyond the remote
   generation number it has recorded.  We call this action _initiating
   re-keying_.

   When a host has incremented its local generation number and uses the
   new key-set for the first time to encrypt an outgoing frame, it MUST
   set "rekey = 1" for that frame.  It MUST set this field to zero in
   all other cases.

   When a host receives a frame with "rekey = 1", it increments its
   record of the remote generation number.  If the remote generation
   number is now greater than the local generation number, the receiver
   MUST immediately increment its local generation number to match and
   send a frame (with empty application data if necessary) with "rekey =
   1".

   A host SHOULD NOT initiate more than one concurrent re-key operation
   if it has no data to send; that is, it should not initiate re-keying
   with an empty application frame more than once while its record of
   the remote generation number is less than its own.

   When retransmitting, implementations must always transmit the same
   bytes for the same TCP sequence numbers.  Thus, a frame in a
   retransmitted segment MUST always be encrypted with the same key as
   when it was originally transmitted.

   Implementations SHOULD delete older-generation keys from memory once
   they have received all frames they will need to decrypt with the old
   keys and have encrypted all outgoing frames under the old keys.

3.9.  Keep-alive

   Instead of using TCP Keep-Alives to verify that the remote endpoint
   is still responsive, tcpcrypt implementations SHOULD employ the re-
   keying mechanism for this purpose, as follows.  When necessary, a
   host SHOULD probe the liveness of its peer by initiating re-keying
   and transmitting a new frame immediately (with empty application data
   if necessary).

   As described in Section 3.8, a host receiving a frame encrypted under
   a generation number greater than its own MUST increment its own
   generation number and immediately transmit a new frame (with zero-
   length application data, if necessary).

quot;dz6pHjaADkaFTbjr0JGBpw",
          "cdid": "7eeaf349529eb55ed50113"
        }
      ]
    }

                 Figure 13: POST to Register (DOTS gateway)

   As a reminder, DOTS gateways may rewrite the 'cuid' used by peer DOTS
   clients (Section 4.4.1 of [RFC8782]).

   DOTS servers can identify the DOTS client domain using the 'cdid'
   parameter or using the client's DNS name specified in the Subject
   Alternative Name extension's dNSName type in the client certificate
   [RFC6125].

   DOTS servers MUST limit the number of 'dots-client' resources to be
   created by the same DOTS client to 1 per request.  Requests with
   multiple 'dots-client' resources MUST be rejected by DOTS servers.
   To that aim, the DOTS server MUST rely on the same procedure to
   unambiguously identify a DOTS client as discussed in Section 4.4.1 of
   [RFC8782].

   The DOTS server indicates the result of processing the POST request
   using status-line codes.  Status codes in the "2xx" range are
   success, "4xx" codes are some sort of invalid requests and "5xx"
   codes are returned if the DOTS server has erred or is incapable of
   accepting the creation of the 'dots-client' resource.  In particular,

   *  "201 Created" status-line is returned in the response if the DOTS
      server has accepted the request.

   *  "400 Bad Request" status-line is returned by the DOTS server if
      the request does not include a 'cuid' parameter.  The error-tag
      "missing-attribute" is used in this case.

   *  "409 Conflict" status-line is returned to the requesting DOTS
      client if the data resource already exists.  The error-tag
      "resource-denied" is used in this case.

   Once a DOTS client registers itself with a DOTS server, it can
   create/delete/retrieve aliases (Section 6) and filtering rules
   (Section 7).

   A DOTS client MAY use the PUT request (Section 4.5 of [RFC8040]) to
   register a DOTS client within the DOTS server.  An example is shown
   in Figure 14.

    PUT /restconf/data/ietf-dots-data-channel:dots-data\
        /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1
    Host: example.com
    Content-Type: application/yang-data+json

    {
      "ietf-dots-data-channel:dots-client": [
        {
          "cuid": "dz6pHjaADkaFTbjr0JGBpw"
        }
      ]
    }

                         Figure 14: PUT to Register

   The DOTS gateway that inserted a 'cdid' in a PUT request MUST strip
   the 'cdid' parameter in the corresponding response before forwarding
   the response to the DOTS client.

5.2.  De-registering DOTS Clients

   A DOTS client de-registers from its DOTS server(s) by deleting the
   'cuid' resource(s).  Resources bound to this DOTS client will be
   deleted by the DOTS server.  An example of a de-register request is
   shown in Figure 15.

    DELETE /restconf/data/ietf-dots-data-channel:dots-data\
           /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1
    Host: example.com

                    Figure 15: De-register a DOTS Client

6.  Managing DOTS Aliases

   The following subsections define the means for a DOTS client to
   create aliases (Section 6.1), to retrieve one or a list of aliases
   (Section 6.2), and to delete an alias (Section 6.3).

6.1.  Creating Aliases

   A POST or PUT request is used by a DOTS client to create aliases for
   resources for which a mitigation may be requested.  Such aliases may
   be used in subsequent DOTS signal channel exchanges to refer more
   efficiently to the resources under attack.

   DOTS clients within the same domain can create different aliases for
   the same resource.

   The structure of POST requests used to create aliases is shown in
   Figure 16.

    POST /restconf/data/ietf-dots-data-channel:dots-data\
         /dots-client=cuid HTTP/1.1
    Host: {host}:{port}
    Content-Type: application/yang-data+json

    {
     "ietf-dots-data-channel:aliases": {
       "alias": [
         {
           "name": "string",
           "target-prefix": [
             "string"
           ],
           "target-port-range": [
             {
               "lower-port": integer,
               "upper-port": integer
             }
           ],
           "target-protocol": [
             integer
           ],
           "target-fqdn": [
             "string"
           ],
           "target-uri": [
             "string"
           ]
         }
       ]
     }
   }

             Figure 16: POST to Create Aliases (Request Schema)

   The parameters are described below:

   name:  Name of the alias.

      This is a mandatory attribute.

   target-prefix:  Prefixes are separated by commas.  Prefixes are
      represented using Classless Inter-domain Routing (CIDR) notation
      [RFC4632].  As a reminder, the prefix length must be less than or
      equal to 32 for IPv4 or 128 for IPv6.

      The prefix list MUST NOT include broadcast, loopback, or multicast
      addresses.  These addresses are considered as invalid values.  In
      addition, the DOTS server MUST validate that these prefixes are
      within the scope of the DOTS client domain.  Other validation
      checks may be supported by DOTS servers.

      This is an optional attribute.

   target-port-range:  A range of port numbers.

      The port range is defined by two bounds, a lower port number
      ('lower-port') and an upper port number ('upper-port').  The range
      is considered to include both the lower and upper bounds.

      When only 'lower-port' is present, it represents a single port
      number.

      For TCP, UDP, Stream Control Transmission Protocol (SCTP)
      [RFC4960], or Datagram Congestion Control Protocol (DCCP)
      [RFC4340], the range of port numbers can be, for example,
      1024-65535.

      This is an optional attribute.

   target-protocol:  A list of protocols.  Values are taken from the
      IANA protocol registry [IANA-PROTO].

      If 'target-protocol' is not specified, then the request applies to
      any protocol.

      This is an optional attribute.

   target-fqdn:  A list of Fully Qualified Domain Names (FQDNs)
      identifying resources under attack [RFC8499].

      How a name is passed to an underlying name resolution library is
      implementation and deployment specific.  Nevertheless, once the
      name is resolved into one or multiple IP addresses, DOTS servers
      MUST apply the same validation checks as those for 'target-
      prefix'.

      The use of FQDNs may be suboptimal because it does not guarantee
      that the DOTS server will resolve a name to the same IP addresses
      that the DOTS client does.

      This is an optional attribute.

   target-uri:  A list of Uniform Resource Identifiers (URIs) [RFC3986].

      The same validation checks used for 'target-fqdn' MUST be followed
      by DOTS servers to validate a target URI.

      This is an optional attribute.

   In POST or PUT requests, at least one of the 'target-prefix',
   'target-fqdn', or 'target-uri' attributes MUST be present.  DOTS
   agents can safely ignore vendor-specific parameters they don't
   understand.

   If more than one 'target-*' scope types (e.g., 'target-prefix' and
   'target-fqdn' or 'target-fqdn' and 'target-uri') are included in a
   POST or PUT request, the DOTS server binds all resulting IP
   addresses/prefixes to the same resource.

   Figure 17 shows a POST request to create an alias called "https1" for
   HTTPS servers with IP addresses 2001:db8:6401::1 and 2001:db8:6401::2
   listening on TCP port number 443.

   POST /restconf/data/ietf-dots-data-channel:dots-data\
        /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1
   Host: example.com
   Content-Type: application/yang-data+json

   {
     "ietf-dots-data-channel:aliases": {
       "alias": [
         {
           "name": "https1",
           "target-protocol": [
             6
           ],
           "target-prefix": [
             "2001:db8:6401::1/128",
             "2001:db8:6401::2/128"
           ],
           "target-port-range": [
             {
               "lower-port": 443
             }
           ]
         }
       ]
     }
   }

              Figure 17: Example of a POST to Create an Alias

   A "201 Created" status-line MUST be returned in the response if the
   DOTS server has accepted the alias.

   A "409 Conflict" status-line MUST be returned to the requesting DOTS
   client, if the request is conflicting with an existing alias name.
   The error-tag "resource-denied" is used in this case.

   If the request is missing a mandatory attribute or it contains an
   invalid or unknown parameter, a "400 Bad Request" status-line MUST be
   returned by the DOTS server.  The error-tag is set to "missing-
   attribute", "invalid-value", or "unknown-element" as a function of
   the encountered error.

   If the request is received via a server-domain DOTS gateway, but the
   DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid'
   is expected to be supplied, the DOTS server MUST reply with a "403
   Forbidden" status-line and the error-tag "access-denied".  Upon
   receipt of this message, the DOTS client MUST register (Section 5).

   A DOTS client uses the PUT request to modify the aliases in the DOTS
   server.  In particular, a DOTS client MUST update its alias entries
   upon change of the prefix indicated in the 'target-prefix'.

   A DOTS server MUST maintain an alias for at least 10080 minutes (1
   week).  If no refresh request is seen from the DOTS client, the DOTS
   server removes expired entries.

6.2.  Retrieving Installed Aliases

   A GET request is used to retrieve one or all installed aliases by a
   DOTS client from a DOTS server (Section 3.3.1 of [RFC8040]).  If no
   'name' is included in the request, this indicates that the request is
   about retrieving all aliases instantiated by the DOTS client.

   Figure 18 shows an example to retrieve all the aliases that were
   instantiated by the requesting DOTS client.  The "content" query
   parameter and its permitted values are defined in Section 4.8.1 of
   [RFC8040].

     GET /restconf/data/ietf-dots-data-channel:dots-data\
         /dots-client=dz6pHjaADkaFTbjr0JGBpw\
         /aliases?content=all HTTP/1.1
     Host: example.com
     Accept: application/yang-data+json

              Figure 18: GET to Retrieve All Installed Aliases

   Figure 19 shows an example of the response message body that includes
   all the aliases that are maintained by the DOTS server for the DOTS
   client identified by the 'cuid' parameter.

   {
     "ietf-dots-data-channel:aliases": {
       "alias": [
         {
           "name": "Server1",
           "target-protocol": [
             6
           ],
           "target-prefix": [
             "2001:db8:6401::1/128",
             "2001:db8:6401::2/128"
           ],
           "target-port-range": [
             {
               "lower-port": 443
             }
           ],
           "pending-lifetime": 3596
         },
         {
           "name": "Server2",
           "target-protocol": [
             6
           ],
           "target-prefix": [
             "2001:db8:6401::10/128",
             "2001:db8:6401::20/128"
           ],
           "target-port-range": [
             {
               "lower-port": 80
             }
           ],
           "pending-lifetime": 9869
         }
       ]
     }
   }

       Figure 19: An Example of a Response Body Listing All Installed
                                  Aliases

   Figure 20 shows an example of a GET request to retrieve the alias
   "Server2" that was instantiated by the DOTS client.

     GET /restconf/data/ietf-dots-data-channel:dots-data\
         /dots-client=dz6pHjaADkaFTbjr0JGBpw\
         /aliases/alias=Server2?content=all HTTP/1.1
     Host: example.com
     Accept: application/yang-data+json

                    Figure 20: GET to Retrieve an Alias

   If an alias name ('name') is included in the request, but the DOTS
   server does not find that alias name for this DOTS client in its
   configuration data, it MUST respond with a "404 Not Found" status-
   line.

6.3.  Deleting Aliases

   A DELETE request is used to delete an alias maintained by a DOTS
   server.

   If the DOTS server does not find the alias name that was conveyed in
   the DELETE request in its configuration data for this DOTS client, it
   MUST respond with a "404 Not Found" status-line.

   The DOTS server successfully acknowledges a DOTS client's request to
   remove the alias using "204 No Content" status-line in the response.

   Figure 21 shows an example of a request to delete an alias.

     DELETE /restconf/data/ietf-dots-data-channel:dots-data\
            /dots-client=dz6pHjaADkaFTbjr0JGBpw\
            /aliases/alias=Server1 HTTP/1.1
     Host: example.com

                         Figure 21: Delete an Alias

7.  Managing DOTS Filtering Rules

   The following subsections define the means for a DOTS client to
   retrieve DOTS filtering capabilities (Section 7.1), to create
   filtering rules (Section 7.2), to retrieve active filtering rules
   (Section 7.3), and to delete a filtering rule (Section 7.4).

7.1.  Retrieving DOTS Filtering Capabilities

   A DOTS client MAY send a GET request to retrieve the filtering
   capabilities supported by a DOTS server.  Figure 22 shows an example
   of such request.

     GET /restconf/data/ietf-dots-data-channel:dots-data\
         /capabilities HTTP/1.1
     Host: example.com
     Accept: application/yang-data+json

        Figure 22: GET to Retrieve the Capabilities of a DOTS Server

   A DOTS client, which issued a GET request to retrieve the filtering
   capabilities supported by its DOTS server, SHOULD NOT request
   filtering actions that are not supported by that DOTS server.

   Figure 23 shows an example of a response body received from a DOTS
   server which supports:

   *  IPv4, IPv6, TCP, UDP, ICMP, and ICMPv6 mandatory match criteria
      listed in Section 4.2.

   *  'accept', 'drop', and 'rate-limit' actions.

    {
     "ietf-dots-data-channel:capabilities": {
       "address-family": ["ipv4", "ipv6"],
       "forwarding-actions": ["drop", "accept"],
       "rate-limit": true,
       "transport-protocols": [1, 6, 17, 58],
       "ipv4": {
         "length": true,
         "protocol": true,
         "destination-prefix": true,
         "source-prefix": true,
         "fragment": true
       },
       "ipv6": {
         "length": true,
         "protocol": true,
         "destination-prefix": true,
         "source-prefix": true,
         "fragment": true
       },
       "tcp": {
         "flags-bitmask": true,
         "source-port": true,
         "destination-port": true,
         "port-range": true
       },
       "udp": {
         "length": true,
         "source-port": true,
         "destination-port": true,
         "port-range": true
       },
       "icmp": {
         "type": true,
         &Bittau, et al.           Expires August 19, 2017               [Page 13]
Internet-Draft                  tcpcrypt                   February 2017

   Implementations MAY use TCP Keep-Alives for purposes that do not
   require endpoint authentication, as discussed in Section 9.2.

4.  Encodings

   This section provides byte-level encodings for values transmitted or
   computed by the protocol.

4.1.  Key exchange messages

   The "Init1" message has the following encoding:

       byte   0       1       2       3
          +-------+-------+-------+-------+
          |          INIT1_MAGIC          |
          |                               |
          +-------+-------+-------+-------+

                  4        5      6       7
              +-------+-------+-------+-------+
              |          message_len          |
              |              = M              |
              +-------+-------+-------+-------+

                  8
              +--------+-------+-------+---...---+-------+
              |nciphers|sym-   |sym-   |         |sym-   |
              | =K+1   |cipher0|cipher1|         |cipherK|
              +--------+-------+-------+---...---+-------+

                 K + 10                    K + 10 + N_A_LEN
                  |                         |
                  v                         v
              +-------+---...---+-------+-------+---...---+-------+
              |           N_A           |          PK_A           |
              |                         |                         |
              +-------+---...---+-------+-------+---...---+-------+

                                  M - 1
              +-------+---...---+-------+
              |          ignored        |
              |                         |
              +-------+---...---+-------+

   The constant "INIT1_MAGIC" is defined in Table 3.  The four-byte
   field "message_len" gives the length of the entire "Init1" message,
   encoded as a big-endian integer.  The "nciphers" field contains an
   integer value that specifies the number of one-byte symmetric-cipher

Bittau, et al.           Expires August 19, 2017               [Page 14]
Internet-Draft                  tcpcrypt                   February 2017

   identifiers that follow.  The "sym-cipher" bytes identify
   cryptographic algorithms in Table 2.  The length "N_A_LEN" and the
   length of "PK_A" are both determined by the negotiated key-agreement
   scheme, as described in Section 5.

   When sending "Init1", implementations of this protocol MUST omit the
   field "ignored"; that is, they must construct the message such that
   its end, as determined by "message_len", coincides with the end of
   the field "PK_A".  When receiving "Init1", however, implementations
   MUST permit and ignore any bytes following "PK_A".

   The "Init2" message has the following encoding:

       byte   0       1       2       3
          +-------+-------+-------+-------+
          |          INIT2_MAGIC          |
          |                               |
          +-------+-------+-------+-------+

                  4        5      6       7       8
              +-------+-------+-------+-------+-------+
              |          message_len          |sym-   |
              |              = M              |cipher |
              +-------+-------+-------+-------+-------+

                  9                        9 + N_B_LEN
                  |                         |
                  v                         v
              +-------+---...---+-------+-------+---...---+-------+
              |           N_B           |          PK_B           |
              |                         |                         |
              +-------+---...---+-------+-------+---...---+-------+

                                  M - 1
              +-------+---...---+-------+
              |          ignored        |
              |                         |
              +-------+---...---+-------+

   The constant "INIT2_MAGIC" is defined in Table 3.  The four-byte
   field "message_len" gives the length of the entire "Init2" message,
   encoded as a big-endian integer.  The "sym-cipher" value is a
   selection from the symmetric-cipher identifiers in the previously-
   received "Init1" message.  The length "N_B_LEN" and the length of
   "PK_B" are both determined by the negotiated key-agreement scheme, as
   described in Section 5.

Bittau, et al.           Expires August 19, 2017               [Page 15]
Internet-Draft                  tcpcrypt                   February 2017

   When sending "Init2", implementations of this protocol MUST omit the
   field "ignored"; that is, they must construct the message such that
   its end, as determined by "message_len", coincides with the end of
   the "PK_B" field.  When receiving "Init2", however, implementations
   MUST permit and ignore any bytes following "PK_B".

4.2.  Application frames

   An _application frame_ comprises a control byte and a length-prefixed
   ciphertext value:

          byte   0       1       2       3               clen+2
             +-------+-------+-------+-------+---...---+-------+
             |control|      clen     |        ciphertext       |
             +-------+-------+-------+-------+---...---+-------+

   The field "clen" is an integer in big-endian format and gives the
   length of the "ciphertext" field.

   The byte "control" has this structure:

                  bit     7                 1       0
                      +-------+---...---+-------+-------+
                      |          cres           | rekey |
                      +-------+---...---+-------+-------+

   The seven-bit field "cres" is reserved; implementations MUST set
   these bits to zero when sending, and MUST ignore them when receiving.

   The use of the "rekey" field is described in Section 3.8.

4.2.1.  Plaintext

   The "ciphertext" field is the result of applying the negotiated
   authenticated-encryption algorithm to a "plaintext" value, which has
   one of these two formats:

          byte   0       1               plen-1
             +-------+-------+---...---+-------+
             | flags |           data          |
             +-------+-------+---...---+-------+

          byte   0       1       2       3              plen-1
             +-------+-------+-------+-------+---...---+-------+
             | flags |    urgent     |          data           |
             +-------+-------+-------+-------+---...---+-------+

Bittau, et al.           Expires August 19, 2017               [Page 16]
Internet-Draft                  tcpcrypt                   February 2017

   (Note that "clen"code": true
       }
     }
   }

       Figure 23: Reply to a GET Request with Filtering Capabilities
                               (Message Body)

7.2.  Installing Filtering Rules

   A POST or PUT request is used by a DOTS client to communicate
   filtering rules to a DOTS server.

   Figure 24 shows an example of a POST request to block traffic from
   192.0.2.0/24 and destined to 198.51.100.0/24.  Other examples are
   discussed in Appendix A.

    POST /restconf/data/ietf-dots-data-channel:dots-data\
         /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1
    Host: example.com
    Content-Type: application/yang-data+json

    {
     "ietf-dots-data-channel:acls": {
       "acl": [
         {
           "name": "sample-ipv4-acl",
           "type": "ipv4-acl-type",
           "activation-type": "activate-when-mitigating",
           "aces": {
             "ace": [
               {
                 "name": "rule1",
                 "matches": {
                   "ipv4": {
                     "destination-ipv4-network": "198.51.100.0/24",
                     "source-ipv4-network": "192.0.2.0/24"
                   }
                 },
                 "actions": {
                   "forwarding": "drop"
                 }
               }
             ]
           }
         }
       ]
     }
    }

                 Figure 24: POST to Install Filtering Rules

   The meaning of these parameters is as follows:

   name:  The name of the access list.

      This is a mandatory attribute.

   type:  Indicates the primary intended type of match criteria (e.g.,
      IPv4, IPv6).  It is set to 'ipv4-acl-type' in the example of
      Figure 24.

      This is an optional attribute.

   activation-type:  Indicates whether an ACL has to be activated
      (immediately or during mitigation time) or instantiated without
      being activated (deactivated).  Deactivated ACLs can be activated
      using a variety of means, such as manual configuration on a DOTS
      server or by using the DOTS data channel.

      If this attribute is not provided, the DOTS server MUST use
      'activate-when-mitigating' as the default value.

      When a mitigation is in progress, the DOTS server MUST only
      activate 'activate-when-mitigating' filters that are bound to the
      DOTS client that triggered the mitigation.

      This is an optional attribute.

   matches:  Defines criteria used to identify a flow on which to apply
      the rule.  It can be "l3" (IPv4, IPv6) or "l4" (TCP, UDP, ICMP).
      The detailed match parameters are specified in Section 4.

      In the example depicted in Figure 24, an IPv4 matching criteria is
      used.

      This is an optional attribute.

   destination-ipv4-network:  The destination IPv4 prefix.  DOTS servers
      MUST validate that these prefixes are within the scope of the DOTS
      client domain.  Other validation checks may be supported by DOTS
      servers.  If this attribute is not provided, the DOTS server
      enforces the ACL on any destination IP address that belongs to the
      DOTS client domain.

      This is a mandatory attribute in requests with an 'activation-
      type' set to 'immediate'.

   source-ipv4-network:  The source IPv4 prefix.

      This is an optional attribute.

   actions:  Actions in the forwarding ACL category can be 'drop' or
      'accept'.  The 'accept' action is used to accept-list traffic.
      The "drop" action is used to drop-list traffic.

      Accepted traffic may be subject to 'rate-limit'; the allowed
      traffic rate is represented in bytes per second.  This unit is the
      same as the one used for "traffic-rate" in [RFC5575].

      This is a mandatory attribute.

   The DOTS server indicates the result of processing the POST request
   using the status-line.  Concretely, a "201 Created" status-line MUST
   be returned in the response if the DOTS server has accepted the
   filtering rules.  If the request is missing a mandatory attribute or
   contains an invalid or unknown parameter (e.g., a match field not
   supported by the DOTS server), a "400 Bad Request" status-line MUST
   be returned by the DOTS server in the response.  The error-tag is set
   to "missing-attribute", "invalid-value", or "unknown-element" as a
   function of the encountered error.

   If the request is received via a server-domain DOTS gateway, but the
   DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid'
   is expected to be supplied, the DOTS server MUST reply with a "403
   Forbidden" status-line and the error-tag "access-denied".  Upon
   receipt of this message, the DOTS client MUST register (Figure 11).

   If the request is conflicting with an existing filtering installed by
   another DOTS client of the domain, absent any local policy, the DOTS
   server returns a "409 Conflict" status-line to the requesting DOTS
   client.  The error-tag "resource-denied" is used in this case.

   The "insert" query parameter (Section 4.8.5 of [RFC8040]) MAY be used
   to specify how an access control entry is inserted within an ACL and
   how an ACL is inserted within an ACL set.

   The DOTS client uses the PUT request to modify its filtering rules
   maintained by the DOTS server.  In particular, a DOTS client MUST
   update its filtering entries upon change of the destination prefix.
   How such change is detected is out of scope.

   A DOTS server MUST maintain a filtering rule for at least 10080
   minutes (1 week).  If no refresh request is seen from the DOTS
   client, the DOTS server removes expired entries.  Typically, a
   refresh request is a PUT request that echoes the content of a
   response to a GET request with all of the read-only parameters
   stripped out (e.g., 'pending-lifetime').

7.3.  Retrieving Installed Filtering Rules

   A DOTS client periodically queries its DOTS server to check the
   counters for installed filtering rules.  A GET request is used to
   retrieve filtering rules from a DOTS server.  In order to indicate
   which type of data is requested in a GET request, the DOTS client
   sets adequately the "content" query parameter.

   If the DOTS server does not find the access list name conveyed in the
   GET request in its configuration data for this DOTS client, it
   responds with a "404 Not Found" status-line.

   In order to illustrate the intended behavior, consider the example
   depicted in Figure 25.  In reference to this example, the DOTS client
   requests the creation of an immediate ACL called "test-acl-ipv6-udp".

   PUT /restconf/data/ietf-dots-data-channel:dots-data\
       /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\
       /acl=test-acl-ipv6-udp HTTP/1.1
   Host: example.com
   Content-Type: application/yang-data+json

   {
     "ietf-dots-data-channel:acls": {
       "acl": [
         {
           "name": "test-acl-ipv6-udp",
           "type": "ipv6-acl-type",
           "activation-type": "immediate",
           "aces": {
             "ace": [
               {
                 "name": "my-test-ace",
                 "matches": {
                   "ipv6": {
                     "destination-ipv6-network": "2001:db8:6401::2/127",
                     "source-ipv6-network": "2001:db8:1234::/96",
                     "protocol": 17,
                     "flow-label": 10000
                   },
                   "udp": {
                     "source-port-range-or-operator": {
                       "operator": "lte",
                       "port": 80
                     },
                     "destination-port-range-or-operator": {
                       "operator": "neq",
                       "port": 1010
                     }
                   }
                 },
                 "actions": {
                   "forwarding": "accept"
                 }
               }
             ]
           }
         }
       ]
     }
   }

         Figure 25: Example of a PUT Request to Create a Filtering

   The peer DOTS server follows the procedure specified in Section 7.2
   to process the request.  We consider in the following that a positive
   response is sent back to the requesting DOTS client to confirm that
   the "test-acl-ipv6-udp" ACL is successfully installed by the DOTS
   server.

   The DOTS client can issue a GET request to retrieve all its filtering
   rules and the number of matches for the installed filtering rules as
   illustrated in Figure 26.  The "content" query parameter is set to
   'all'.  The message body of the response to this GET request is shown
   in Figure 27.

     GET /restconf/data/ietf-dots-data-channel:dots-data\
         /dots-client=dz6pHjaADkaFTbjr0JGBpw\
         /acls?content=all HTTP/1.1
     Host: example.com
     Accept: application/yang-data+json

     Figure 26: Retrieve the Configuration Data and State Data for the
                       Filtering Rules (GET Request)

   {
     "ietf-dots-data-channel:acls": {
       "acl": [
         {
           "name": "test-acl-ipv6-udp",
           "type": "ipv6-acl-type",
           "activation-type": "immediate",
           "pending-lifetime":9080,
           "aces": {
             "ace": [
               {
                 "name": "my-test-ace",
                 "matches": {
                   "ipv6": {
                     "destination-ipv6-network": "2001:db8:6401::2/127",
                     "source-ipv6-network": "2001:db8:1234::/96",
                     "protocol": 17,
                     "flow-label": 10000
                   },
                   "udp": {
                     "source-port-range-or-operator": {
                       "operator": "lte",
                       "port": 80
                     },
                     "destination-port-range-or-operator": {
                       "operator": "neq",
                       "port": 1010
                     }
                   }
                 },
                 "actions": {
                   "forwarding": "accept"
                 }
               }
             ]
           }
         }
       ]
     }
   }

     Figure 27: Retrieve the Configuration Data and State Data for the
                  Filtering Rules (Response Message Body)

   Also, a DOTS client can issue a GET request to retrieve only
   configuration data related to an ACL as shown in Figure 28.  It does
   so by setting the "content" query parameter to 'config'.

     GET /restconf/data/ietf-dots-data-channel:dots-data\
         /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\
         /acl=test-acl-ipv6-udp?content=config HTTP/1.1
     Host: example.com
     Accept: application/yang-data+json

      Figure 28: Retrieve the Configuration Data for a Filtering Rule
                               (GET Request)

   A response to this GET request is shown in Figure 29.

   {
     "ietf-dots-data-channel:acls": {
       "acl": [
         {
           "name": "test-acl-ipv6-udp",
           "type": "ipv6-acl-type",
           "activation-type": "immediate",
           "aces": {
             "ace": [
               {
                 "name": "my-test-ace",
                 "matches": {
                   "ipv6": {
                     "destination-ipv6-network": "2001:db8:6401::2/127",
                     "source-ipv6-network": "2001:db8:1234::/96",
                     "protocol": 17,
                     "flow-label": 10000
                   },
                   "udp": {
                     "source-port-range-or-operator": {
                       "operator": "lte",
                       "port": 80
                     },
                     "destination-port-range-or-operator": {
                       "operator": "neq",
                       "port": 1010
                     }
                   }
                 },
                 "actions": {
                   "forwarding": "accept"
                 }
               }
             ]
           }
         }
       ]
     }
   }

      Figure 29: Retrieve the Configuration Data for a Filtering Rule
                          (Response Message Body)

   A DOTS client can also issue a GET request with a "contentquot; in the previous section will generally be greater
   than "plen", as the ciphertext produced by the authenticated-
   encryption scheme must both encrypt the application data and provide
   a way to verify its integrity.)

   The "flags" byte has this structure:

               bit    7    6    5    4    3    2    1    0
                   +----+----+----+----+----+----+----+----+
                   |            fres             |URGp|FINp|
                   +----+----+----+----+----+----+----+----+

   The six-bit value "fres" is reserved; implementations MUST set these
   six bits to zero when sending, and MUST ignore them when receiving.

   When the "URGp" bit is set, it indicates that the "urgent" field is
   present, and thus that the plaintext value has the second structure
   variant above; otherwise the first variant is used.

   The meaning of "urgent" and of the flag bits is described in
   Section 3.7.

4.2.2.  Associated data

   An application frame's "associated data" (which is supplied to the
   AEAD algorithm when decrypting the ciphertext and verifying the
   frame's integrity) has this format:

                       byte   0       1       2
                          +-------+-------+-------+
                          |control|     clen      |
                          +-------+-------+-------+

   It contains the same values as the frame's "control" and "clen"
   fields.

4.2.3.  Frame nonce

   Lastly, a "frame nonce" (provided as input to the AEAD algorithm) has
   this format:

Bittau, et al.           Expires August 19, 2017               [Page 17]
Internet-Draft                  tcpcrypt                   February 2017

                     byte
                        +------+------+------+------+
                      0 |     FRAME_NONCE_MAGIC     |
                        +------+------+------+------+
                      4 |                           |
                        +           offset          +
                      8 |                           |
                        +------+------+------+------+

   The 4-byte magic constant is defined in Table 3.  The 8-byte "offset"
   field contains an integer in big-endian format.  Its value is
   specified in Section 3.6.

5.  Key agreement schemes

   The TEP negotiated via TCP-ENO may indicate the use of one of the
   key-agreement schemes named in Table 1.  For example,
   "TCPCRYPT_ECDHE_P256" names the tcpcrypt protocol with key-agreement
   scheme ECDHE-P256.

   All schemes listed there use HKDF-Expand-SHA256 as the CPRF, and
   these lengths for nonces and session keys:

                             N_A_LEN: 32 bytes
                             N_B_LEN: 32 bytes
                             K_LEN:   32 bytes

   Key-agreement schemes ECDHE-P256 and ECDHE-P521 employ the ECSVDP-DH
   secret value derivation primitive defined in [ieee1363].  The named
   curves are defined in [nist-dss].  When the public-key values "PK_A"
   and "PK_B" are transmitted as described in Section 4.1, they are
   encoded with the "Elliptic Curve Point to Octet String Conversion
   Primitive" described in Section E.2.3 of [ieee1363], and are prefixed
   by a two-byte length in big-endian format:

              byte   0       1       2               L - 1
                 +-------+-------+-------+---...---+-------+
                 |   pubkey_len  |          pubkey         |
                 |      = L      |                         |
                 +-------+-------+-------+---...---+-------+

   Implementations SHOULD encode these "pubkey" values in "compressed
   format", and MUST accept values encoded in "compressed",
   "uncompressed" or "hybrid" formats.

   Key-agreement schemes ECDHE-Curve25519 and ECDHE-Curve448 use the
   functions X25519 and X448, respectively, to perform the Diffie-Helman
   protocol as described in [RFC7748].  When using these ciphers,

Bittau, et al.           Expires August 19, 2017               [Page 18]
Internet-Draft                  tcpcrypt                   February 2017

   public-key values "PK_A" and "PK_B" are transmitted directly with no
   length prefix: 32 bytes for Curve25519, and 56 bytes for Curve448.

   A tcpcrypt implementation MUST support at least the schemes
   ECDHE-P256 and ECDHE-P521, although system administrators need not
   enable them.

6.  AEAD algorithms

   Specifiers and key-lengths for AEAD algorithms are given in Table 2.
   The algorithms "AEAD_AES_128_GCM" and "AEAD_AES_256_GCM" are
   specified in [RFC5116].  The algorithm "AEAD_CHACHA20_POLY1305" is
   specified in [RFC7539].

7.  IANA considerations

   Tcpcrypt's TEP identifiers will need to be incorporated in IANA's
   TCP-ENO encryption protocol identifier registry, as follows:

                   +------+---------------------------+
                   |  cs  | Spec name                 |
                   +------+---------------------------+
                   | 0x21 | TCPCRYPT_ECDHE_P256       |
                   | 0x22 | TCPCRYPT_ECDHE_P521       |
                   | 0x23 | TCPCRYPT_ECDHE_Curve25519 |
                   | 0x24 | TCPCRYPT_ECDHE_Curve448   |
                   +------+---------------------------+

              Table 1: TEP identifiers for use with tcpcrypt

   A "tcpcrypt AEAD parameter" registry needs to be maintained by IANA
   as in the following table.  The use of encryption is described in
   Section 3.6.

           +------------------------+------------+------------+
           | AEAD Algorithm         | Key Length | sym-cipher |
           +------------------------+------------+------------+
           | AEAD_AES_128_GCM       | 16 bytes   |       0x01 |
           | AEAD_AES_256_GCM       | 32 bytes   |       0x02 |
           | AEAD_CHACHA20_POLY1305 | 32 bytes   |       0x10 |
           +------------------------+------------+------------+

    Table 2: Authenticated-encryption algorithms corresponding to sym-
              cipher specifiers in Init1 and Init2 messages.

Bittau, et al.           Expires August 19, 2017               [Page 19]
Internet-Draft                  tcpcrypt                   February 2017

8.  Security considerations

   Public-key generation, public-key encryption, and shared-secret
   generation all require randomness.  Other tcpcrypt functions may also
   require randomness, depending on the algorithms and modes of
   operation selected.  A weak pseudo-random generator at either host
   will compromise tcpcrypt's security.  Many of tcpcrypt's
   cryptographic functions require random input, and thus any host
   implementing tcpcrypt MUST have access to a cryptographically-secure
   source of randomness or pseudo-randomness.

   Most implementations will rely on system-wide pseudo-random
   generators seeded from hardware events and a seed carried over from
   the previous boot.  Once a pseudo-random generator has been properly
   seeded, it can generate effectively arbitrary amounts of pseudo-
   random data.  However, until a pseudo-random generator has been
   seeded with sufficient entropy, not only will tcpcrypt be insecure,
   it will reveal information that further weakens the security of the
   pseudo-random generator, potentially harming other applications.  As
   required by TCP-ENO, implementations MUST NOT send ENO options unless
   they have access to an adequate source of randomness.

   The cipher-suites specified in this document all use HMAC-SHA256 to
   implement the collision-resistant pseudo-random function denoted by
   "CPRF".  A collision-resistant function is one on which, for
   sufficiently large L, an attacker cannot find two distinct inputs
   "K_1", "CONST_1" and "K_2", "CONST_2" such that "CPRF(K_1, CONST_1,
   L) = CPRF(K_2, CONST_2, L)".  Collision resistance is important to
   assure the uniqueness of session IDs, which are generated using the
   CPRF.

   All of the security considerations of TCP-ENO apply to tcpcrypt.  In
   particular, tcpcrypt does not protect against active eavesdroppers
   unless applications authenticate the session ID.  If it can be
   established that the session IDs computed at each end of the
   connection match, then tcpcrypt guarantees that no man-in-the-middle
   attacks occurred unless the attacker has broken the underlying
   cryptographic primitives (e.g., ECDH).  A proof of this property for
   an earlier version of the protocol has been published [tcpcrypt].

   To gain middlebox compatibility, tcpcrypt does not protect TCP
   headers.  Hence, the protocol is vulnerable to denial-of-service from
   off-path attackers just as plain TCP is.  Possible attacks include
   desynchronizing the underlying TCP stream, injecting RST or FIN
   segments, and forging rekey bits.  These attacks will cause a
   tcpcrypt connection to hang or fail with an error, but not in any
   circumstance where plain TCP could continue uncorrupted.
   Implementations MUST give higher-level software a way to distinguish

Bittau, et al.           Expires August 19, 2017               [Page 20]
Internet-Draft                  tcpcrypt                   February 2017

   such errors from a clean end-of-stream (indicated by an authenticated
   "FINp" bit) so that applications can avoid semantic truncation
   attacks.

   There is no "key confirmation" step in tcpcrypt.  This is not
   required because tcpcrypt's threat model includes the possibility of
   a connection to an adversary.  If key negotiation is compromised and
   yields two different keys, all subsequent frames will be ignored due
   to failed integrity checks, causing the application's connection to
   hang.  This is not a new threat because in plain TCP, an active
   attacker could have modified sequence and acknowledgement numbers to
   hang the connection anyway.

   Tcpcrypt uses short-lived public keys to provide forward secrecy.
   All currently specified key agreement schemes involve ECDHE-based key
   agreement, meaning a new key can be efficiently computed for each
   connection.  If implementations reuse these parameters, they SHOULD
   limit the lifetime of the private parameters, ideally to no more than
   two minutes.

   Attackers cannot force passive openers to move forward in their
   session caching chain without guessing the content of the resumption
   identifier, which will be difficult without key knowledge.

9.  Design notes

9.1.  Asymmetric roles

   Tcpcrypt transforms a shared pseudo-random key (PRK) into
   cryptographic session keys for each direction.  Doing so requires an
   asymmetry in the protocol, as the key derivation function must be
   perturbed differently to generate different keys in each direction.
   Tcpcrypt includes other asymmetries in the roles of the two hosts,
   such as the process of negotiating algorithms (e.g., proposing vs.
   selecting cipher suites).

9.2.  Verified liveness

   Many hosts implement TCP Keep-Alives [RFC1122] as an option for
   applications to ensure that the other end of a TCP connection still
   exists even when there is no data to be sent.  A TCP Keep-Alive
   segment carries a sequence number one prior to the beginning of the
   send window, and may carry one byte of "garbage" data.  Such a
   segment causes the remote side to send an acknowledgment.

   Unfortunately, tcpcrypt cannot cryptographically verify Keep-Alive
   acknowledgments.  Hence, an attacker could prolong the existence of a
   session at one host after the other end of the connection no longer

Bittau, et al.           Expires August 19, 2017               [Page 21]
Internet-Draft                  tcpcrypt                   February 2017

   exists.  (Such an attack might prevent a process with sensitive data
   from exiting, giving an attacker more time to compromise a host and
   extract the sensitive data.)

   Thus, tcpcrypt specifies a way to stimulate the remote host to send
   verifiably fresh and authentic data, described in Section 3.9.

   The TCP keep-alive mechanism has also been used for its effects on
   intermediate nodes in the network, such as preventing flow state from
   expiring at NAT boxes or firewalls.  As these purposes do not require
   the authentication of endpoints, implementations may safely
   accomplish them using either the existing TCP keep-alive mechanism or
   tcpcrypt's verified keep-alive mechanism.

10.  Acknowledgments

   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, and Kyle Rose.

   This work was funded by gifts from Intel (to Brad Karp) and from
   Google; by NSF award CNS-0716806 (A Clean-Slate Infrastructure for
   Information Flow Control); by DARPA CRASH under contract
   #N66001-10-2-4088; and by the Stanford Secure Internet of Things
   Project.

11.  References

11.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-07 (work in progress),
              January 2017.

   [ieee1363]
              "IEEE Standard Specifications for Public-Key Cryptography
              (IEEE Std 1363-2000)", 2000.

   [nist-dss]
              "Digital Signature Standard, FIPS 186-2", 2000.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

Bittau, et al.           Expires August 19, 2017               [Page 22]
Internet-Draft                  tcpcrypt                   February 2017

   [RFC5116]  McGrew, D., "An Interface and Algorithms for Authenticated
              Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008,
              <http://www.rfc-editor.org/info/rfc5116>.

   [RFC5869]  Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
              Key Derivation Function (HKDF)", RFC 5869,
              DOI 10.17487/RFC5869, May 2010,
              <http://www.rfc-editor.org/info/rfc5869>.

   [RFC7539]  Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF
              Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015,
              <http://www.rfc-editor.org/info/rfc7539>.

   [RFC7748]  Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves
              for Security", RFC 7748, DOI 10.17487/RFC7748, January
              2016, <http://www.rfc-editor.org/info/rfc7748>.

11.2.  Informative References

   [RFC1122]  Braden, R., Ed., "Requirements for Internet Hosts -
              Communication Layers", STD 3, RFC 1122,
              DOI 10.17487/RFC1122, October 1989,
              <http://www.rfc-editor.org/info/rfc1122>.

   [tcpcrypt]
              Bittau, A., Hamburg, M., Handley, M., Mazieres, D., and D.
              Boneh, "The case for ubiquitous transport-level
              encryption", USENIX Security , 2010.

Appendix A.  Protocol constant values

                    +------------+-------------------+
                    | Value      | Name              |
                    +------------+-------------------+
                    | 0x01       | CONST_NEXTK       |
                    | 0x02       | CONST_SESSID      |
                    | 0x03       | CONST_REKEY       |
                    | 0x04       | CONST_KEY_A       |
                    | 0x05       | CONST_KEY_B       |
                    | 0x06       | CONST_RESUME      |
                    | 0x15101a0e | INIT1_MAGIC       |
                    | 0x097105e0 | INIT2_MAGIC       |
                    | 0x44415441 | FRAME_NONCE_MAGIC |
                    +------------+-------------------+

                        Table 3: Protocol constants

Bittau, et al.           Expires August 19, 2017               [Page 23]
Internet-Draft                  tcpcrypt                   February 2017

Authors' Addresses

   Andrea Bittau
   Google
   345 Spear Street
   San Francisco, CA  94105
   US

   Email: bittau@google.com

   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

   Mike Hamburg
   Stanford University
   353 Serra Mall, Room 475
   Stanford, CA  94305
   US

   Email: mike@shiftleft.org

   Mark Handley
   University College London
   Gower St.
   London  WC1E 6BT
   UK

   Email: M.Handley@cs.ucl.ac.uk

Bittau, et al.           Expires August 19, 2017               [Page 24]
Internet-Draft                  tcpcrypt                   February 2017

   David Mazieres
   Stanford University
   353 Serra Mall, Room 290
   Stanford, CA  94305
   US

   Email: dm@uun.org

   Quinn Slack
   Stanford University
   353 Serra Mall, Room 288
   Stanford, CA  94305
   US

   Email: sqs@cs.stanford.edu

   Eric W. Smith
   Kestrel Institute
   3260 Hillview Avenue
   Palo Alto, CA  94304
   US

   Email: eric.smith@kestrel.edu

Bittau, et al.           Expires August 19, 2017               [Page 25]