[PATCH net 0/3] Documentation: tls: add offload documentation

[PATCH net 0/3] Documentation: tls: add offload documentation

[Jakub Kicinski]

Hi!

This set adds documentation for TLS offload. It starts
by making the networking documentation a little easier
to navigate by hiding driver docs a little deeper.
It then RSTifys the existing Kernel TLS documentation.
Last but not least TLS offload documentation is added.
This should help vendors navigate the TLS offload, and
help ensure different implementations stay aligned from
user perspective.

---
Dave, this just documents existing code, so I ventured
to post during the merge window, not 100% sure it is
appropriate at this stage..

Jakub Kicinski (3):
  Documentation: net: move device drivers docs to a submenu
  Documentation: tls: RSTify the ktls documentation
  Documentation: add TLS offload documentation

 .../networking/device_drivers/index.rst       |  30 ++
 Documentation/networking/index.rst            |  16 +-
 .../networking/tls-offload-layers.svg         |   1 +
 .../networking/tls-offload-reorder-bad.svg    |   1 +
 .../networking/tls-offload-reorder-good.svg   |   1 +
 Documentation/networking/tls-offload.rst      | 438 ++++++++++++++++++
 Documentation/networking/{tls.txt => tls.rst} |  44 +-
 7 files changed, 505 insertions(+), 26 deletions(-)
 create mode 100644 Documentation/networking/device_drivers/index.rst
 create mode 100644 Documentation/networking/tls-offload-layers.svg
 create mode 100644 Documentation/networking/tls-offload-reorder-bad.svg
 create mode 100644 Documentation/networking/tls-offload-reorder-good.svg
 create mode 100644 Documentation/networking/tls-offload.rst
 rename Documentation/networking/{tls.txt => tls.rst} (88%)

-- 
2.21.0

[PATCH net 1/3] Documentation: net: move device drivers docs to a submenu

[Jakub Kicinski]

Some of the device drivers have really long document titles
making the networking table of contents hard to look through.
Place vendor drivers under a submenu.

Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com>
Acked-by: Dave Watson <davejwatson@fb.com>
Acked-by: Alexei Starovoitov <ast@kernel.org>
---
 .../networking/device_drivers/index.rst       | 30 +++++++++++++++++++
 Documentation/networking/index.rst            | 14 +--------
 2 files changed, 31 insertions(+), 13 deletions(-)
 create mode 100644 Documentation/networking/device_drivers/index.rst

diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
new file mode 100644
index 000000000000..75fa537763a4
--- /dev/null
+++ b/Documentation/networking/device_drivers/index.rst
@@ -0,0 +1,30 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+Vendor Device Drivers
+=====================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   freescale/dpaa2/index
+   intel/e100
+   intel/e1000
+   intel/e1000e
+   intel/fm10k
+   intel/igb
+   intel/igbvf
+   intel/ixgb
+   intel/ixgbe
+   intel/ixgbevf
+   intel/i40e
+   intel/iavf
+   intel/ice
+
+.. only::  subproject
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index f390fe3cfdfb..7a2bfad6a762 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -11,19 +11,7 @@ Linux Networking Documentation
    batman-adv
    can
    can_ucan_protocol
-   device_drivers/freescale/dpaa2/index
-   device_drivers/intel/e100
-   device_drivers/intel/e1000
-   device_drivers/intel/e1000e
-   device_drivers/intel/fm10k
-   device_drivers/intel/igb
-   device_drivers/intel/igbvf
-   device_drivers/intel/ixgb
-   device_drivers/intel/ixgbe
-   device_drivers/intel/ixgbevf
-   device_drivers/intel/i40e
-   device_drivers/intel/iavf
-   device_drivers/intel/ice
+   device_drivers/index
    dsa/index
    devlink-info-versions
    ieee802154
-- 
2.21.0

[PATCH net 2/3] Documentation: tls: RSTify the ktls documentation

[Jakub Kicinski]

Convert the TLS doc to RST.  Use C code blocks for the code
samples, and mark hyperlinks.

Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com>
Acked-by: Dave Watson <davejwatson@fb.com>
Acked-by: Alexei Starovoitov <ast@kernel.org>
---
 Documentation/networking/index.rst            |  1 +
 Documentation/networking/{tls.txt => tls.rst} | 42 +++++++++++++------
 2 files changed, 30 insertions(+), 13 deletions(-)
 rename Documentation/networking/{tls.txt => tls.rst} (88%)

diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 7a2bfad6a762..f0f97eef091c 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -28,6 +28,7 @@ Linux Networking Documentation
    checksum-offloads
    segmentation-offloads
    scaling
+   tls
 
 .. only::  subproject
 
diff --git a/Documentation/networking/tls.txt b/Documentation/networking/tls.rst
similarity index 88%
rename from Documentation/networking/tls.txt
rename to Documentation/networking/tls.rst
index 58b5ef75f1b7..482bd73f18a2 100644
--- a/Documentation/networking/tls.txt
+++ b/Documentation/networking/tls.rst
@@ -1,3 +1,7 @@
+==========
+Kernel TLS
+==========
+
 Overview
 ========
 
@@ -12,6 +16,8 @@ Creating a TLS connection
 
 First create a new TCP socket and set the TLS ULP.
 
+.. code-block:: c
+
   sock = socket(AF_INET, SOCK_STREAM, 0);
   setsockopt(sock, SOL_TCP, TCP_ULP, "tls", sizeof("tls"));
 
@@ -21,6 +27,8 @@ handshake is complete, we have all the parameters required to move the
 data-path to the kernel. There is a separate socket option for moving
 the transmit and the receive into the kernel.
 
+.. code-block:: c
+
   /* From linux/tls.h */
   struct tls_crypto_info {
           unsigned short version;
@@ -58,6 +66,8 @@ After setting the TLS_TX socket option all application data sent over this
 socket is encrypted using TLS and the parameters provided in the socket option.
 For example, we can send an encrypted hello world record as follows:
 
+.. code-block:: c
+
   const char *msg = "hello world\n";
   send(sock, msg, strlen(msg));
 
@@ -67,6 +77,8 @@ to the encrypted kernel send buffer if possible.
 The sendfile system call will send the file's data over TLS records of maximum
 length (2^14).
 
+.. code-block:: c
+
   file = open(filename, O_RDONLY);
   fstat(file, &stat);
   sendfile(sock, file, &offset, stat.st_size);
@@ -89,6 +101,8 @@ After setting the TLS_RX socket option, all recv family socket calls
 are decrypted using TLS parameters provided.  A full TLS record must
 be received before decryption can happen.
 
+.. code-block:: c
+
   char buffer[16384];
   recv(sock, buffer, 16384);
 
@@ -97,12 +111,12 @@ large enough, and no additional allocations occur.  If the userspace
 buffer is too small, data is decrypted in the kernel and copied to
 userspace.
 
-EINVAL is returned if the TLS version in the received message does not
+``EINVAL`` is returned if the TLS version in the received message does not
 match the version passed in setsockopt.
 
-EMSGSIZE is returned if the received message is too big.
+``EMSGSIZE`` is returned if the received message is too big.
 
-EBADMSG is returned if decryption failed for any other reason.
+``EBADMSG`` is returned if decryption failed for any other reason.
 
 Send TLS control messages
 -------------------------
@@ -113,9 +127,11 @@ These messages can be sent over the socket by providing the TLS record type
 via a CMSG. For example the following function sends @data of @length bytes
 using a record of type @record_type.
 
-/* send TLS control message using record_type */
+.. code-block:: c
+
+  /* send TLS control message using record_type */
   static int klts_send_ctrl_message(int sock, unsigned char record_type,
-                                  void *data, size_t length)
+                                    void *data, size_t length)
   {
         struct msghdr msg = {0};
         int cmsg_len = sizeof(record_type);
@@ -151,6 +167,8 @@ type passed via cmsg.  If no cmsg buffer is provided, an error is
 returned if a control message is received.  Data messages may be
 received without a cmsg buffer set.
 
+.. code-block:: c
+
   char buffer[16384];
   char cmsg[CMSG_SPACE(sizeof(unsigned char))];
   struct msghdr msg = {0};
@@ -186,12 +204,10 @@ Integrating in to userspace TLS library
 At a high level, the kernel TLS ULP is a replacement for the record
 layer of a userspace TLS library.
 
-A patchset to OpenSSL to use ktls as the record layer is here:
-
-https://github.com/Mellanox/openssl/commits/tls_rx2
-
-An example of calling send directly after a handshake using
-gnutls.  Since it doesn't implement a full record layer, control
-messages are not supported:
+A patchset to OpenSSL to use ktls as the record layer is
+`here <https://github.com/Mellanox/openssl/commits/tls_rx2>`_.
 
-https://github.com/ktls/af_ktls-tool/commits/RX
+`An example <https://github.com/ktls/af_ktls-tool/commits/RX>`_
+of calling send directly after a handshake using gnutls.
+Since it doesn't implement a full record layer, control
+messages are not supported.
-- 
2.21.0

[PATCH net 3/3] Documentation: add TLS offload documentation

[Jakub Kicinski]

Describe existing kernel TLS offload (added back in Linux 4.19) -
the mechanism, the expected behavior and the notable corner cases.

This documentation is mostly targeting hardware vendors who want
to implement offload, to ensure consistency between implementations.

Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com>
Acked-by: Dave Watson <davejwatson@fb.com>
Acked-by: Alexei Starovoitov <ast@kernel.org>
---
 Documentation/networking/index.rst            |   1 +
 .../networking/tls-offload-layers.svg         |   1 +
 .../networking/tls-offload-reorder-bad.svg    |   1 +
 .../networking/tls-offload-reorder-good.svg   |   1 +
 Documentation/networking/tls-offload.rst      | 438 ++++++++++++++++++
 Documentation/networking/tls.rst              |   2 +
 6 files changed, 444 insertions(+)
 create mode 100644 Documentation/networking/tls-offload-layers.svg
 create mode 100644 Documentation/networking/tls-offload-reorder-bad.svg
 create mode 100644 Documentation/networking/tls-offload-reorder-good.svg
 create mode 100644 Documentation/networking/tls-offload.rst

diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index f0f97eef091c..a46fca264bee 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -29,6 +29,7 @@ Linux Networking Documentation
    segmentation-offloads
    scaling
    tls
+   tls-offload
 
 .. only::  subproject
 
diff --git a/Documentation/networking/tls-offload-layers.svg b/Documentation/networking/tls-offload-layers.svg
new file mode 100644
index 000000000000..cf72f05dbb21
--- /dev/null
+++ b/Documentation/networking/tls-offload-layers.svg
@@ -0,0 +1 @@
+<svg version="1.1" viewBox="0.0 0.0 460.0 500.0" fill="none" stroke="none" stroke-linecap="square" stroke-miterlimit="10" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg"><clipPath id="p.0"><path d="m0 0l960.0 0l0 720.0l-960.0 0l0 -720.0z" clip-rule="nonzero"/></clipPath><g clip-path="url(#p.0)"><path fill="#000000" fill-opacity="0.0" d="m0 0l960.0 0l0 720.0l-960.0 0z" fill-rule="evenodd"/><path fill="#cfe2f3" d="m117.02887 0l72.28346 0l0 40.25197l-72.28346 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m117.02887 0l72.28346 0l0 40.25197l-72.28346 0z" fill-rule="evenodd"/><path fill="#000000" d="m135.71944 27.045982l0 -9.671875l1.46875 0l0 1.46875q0.5625 -1.03125 1.03125 -1.359375q0.484375 -0.328125 1.0625 -0.328125q0.828125 0 1.6875 0.53125l-0.5625 1.515625q-0.609375 -0.359375 -1.203125 -0.359375q-0.546875 0 -0.96875 0.328125q-0.421875 0.328125 -0.609375 0.890625q-0.28125 0.875 -0.28125 1.921875l0 5.0625l-1.625 0zm12.853302 -3.109375l1.6875 0.203125q-0.40625 1.484375 -1.484375 2.3125q-1.078125 0.8125 -2.765625 0.8125q-2.125 0 -3.375 -1.296875q-1.234375 -1.3125 -1.234375 -3.671875q0 -2.453125 1.25 -3.796875q1.265625 -1.34375 3.265625 -1.34375q1.9375 0 3.15625 1.328125q1.234375 1.3125 1.234375 3.703125q0 0.15625 0 0.4375l-7.21875 0q0.09375 1.59375 0.90625 2.453125q0.8125 0.84375 2.015625 0.84375q0.90625 0 1.546875 -0.46875q0.640625 -0.484375 1.015625 -1.515625zm-5.390625 -2.65625l5.40625 0q-0.109375 -1.21875 -0.625 -1.828125q-0.78125 -0.953125 -2.03125 -0.953125q-1.125 0 -1.90625 0.765625q-0.765625 0.75 -0.84375 2.015625zm15.453842 4.578125q-0.921875 0.765625 -1.765625 1.09375q-0.828125 0.3125 -1.796875 0.3125q-1.59375 0 -2.453125 -0.78125q-0.859375 -0.78125 -0.859375 -1.984375q0 -0.71875 0.328125 -1.296875q0.328125 -0.59375 0.84375 -0.9375q0.53125 -0.359375 1.1875 -0.546875q0.46875 -0.125 1.453125 -0.25q1.984375 -0.234375 2.921875 -0.5625q0.015625 -0.34375 0.015625 -0.421875q0 -1.0 -0.46875 -1.421875q-0.625 -0.546875 -1.875 -0.546875q-1.15625 0 -1.703125 0.40625q-0.546875 0.40625 -0.8125 1.421875l-1.609375 -0.21875q0.21875 -1.015625 0.71875 -1.640625q0.5 -0.640625 1.453125 -0.984375q0.953125 -0.34375 2.1875 -0.34375q1.25 0 2.015625 0.296875q0.78125 0.28125 1.140625 0.734375q0.375 0.4375 0.515625 1.109375q0.078125 0.421875 0.078125 1.515625l0 2.1875q0 2.28125 0.109375 2.890625q0.109375 0.59375 0.40625 1.15625l-1.703125 0q-0.265625 -0.515625 -0.328125 -1.1875zm-0.140625 -3.671875q-0.890625 0.375 -2.671875 0.625q-1.015625 0.140625 -1.4375 0.328125q-0.421875 0.1875 -0.65625 0.53125q-0.21875 0.34375 -0.21875 0.78125q0 0.65625 0.5 1.09375q0.5 0.4375 1.453125 0.4375q0.9375 0 1.671875 -0.40625q0.75 -0.421875 1.09375 -1.140625q0.265625 -0.5625 0.265625 -1.640625l0 -0.609375zm10.469467 4.859375l0 -1.21875q-0.90625 1.4375 -2.703125 1.4375q-1.15625 0 -2.125 -0.640625q-0.96875 -0.640625 -1.5 -1.78125q-0.53125 -1.140625 -0.53125 -2.625q0 -1.453125 0.484375 -2.625q0.484375 -1.1875 1.4375 -1.8125q0.96875 -0.625 2.171875 -0.625q0.875 0 1.546875 0.375q0.6875 0.359375 1.109375 0.953125l0 -4.796875l1.640625 0l0 13.359375l-1.53125 0zm-5.171875 -4.828125q0 1.859375 0.78125 2.78125q0.78125 0.921875 1.84375 0.921875q1.078125 0 1.828125 -0.875q0.75 -0.890625 0.75 -2.6875q0 -1.984375 -0.765625 -2.90625q-0.765625 -0.9375 -1.890625 -0.9375q-1.078125 0 -1.8125 0.890625q-0.734375 0.890625 -0.734375 2.8125z" fill-rule="nonzero"/><path fill="#cfe2f3" d="m309.02887 0l72.28348 0l0 40.25197l-72.28348 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m309.02887 0l72.28348 0l0 40.25197l-72.28348 0z" fill-rule="evenodd"/><path fill="#000000" d="m328.4915 27.045982l-2.96875 -9.671875l1.703125 0l1.53125 5.578125l0.578125 2.078125q0.046875 -0.15625 0.5 -2.0l1.546875 -5.65625l1.6875 0l1.4375 5.609375l0.484375 1.84375l0.5625 -1.859375l1.65625 -5.59375l1.59375 0l-3.03125 9.671875l-1.703125 0l-1.53125 -5.796875l-0.375 -1.640625l-1.953125 7.4375l-1.71875 0zm11.676086 0l0 -9.671875l1.46875 0l0 1.46875q0.5625 -1.03125 1.03125 -1.359375q0.484375 -0.328125 1.0625 -0.328125q0.828125 0 1.6875 0.53125l-0.5625 1.515625q-0.609375 -0.359375 -1.203125 -0.359375q-0.546875 0 -0.96875 0.328125q-0.421875 0.328125 -0.609375 0.890625q-0.28125 0.875 -0.28125 1.921875l0 5.0625l-1.625 0zm6.228302 -11.46875l0 -1.890625l1.640625 0l0 1.890625l-1.640625 0zm0 11.46875l0 -9.671875l1.640625 0l0 9.671875l-1.640625 0zm7.722931 -1.46875l0.234375 1.453125q-0.6875 0.140625 -1.234375 0.140625q-0.890625 0 -1.390625 -0.28125q-0.484375 -0.28125 -0.6875 -0.734375q-0.203125 -0.46875 -0.203125 -1.9375l0 -5.578125l-1.203125 0l0 -1.265625l1.203125 0l0 -2.390625l1.625 -0.984375l0 3.375l1.65625 0l0 1.265625l-1.65625 0l0 5.671875q0 0.6875 0.078125 0.890625q0.09375 0.203125 0.28125 0.328125q0.203125 0.109375 0.578125 0.109375q0.265625 0 0.71875 -0.0625zm8.230194 -1.640625l1.6875 0.203125q-0.40625 1.484375 -1.484375 2.3125q-1.078125 0.8125 -2.765625 0.8125q-2.125 0 -3.375 -1.296875q-1.234375 -1.3125 -1.234375 -3.671875q0 -2.453125 1.25 -3.796875q1.265625 -1.34375 3.265625 -1.34375q1.9375 0 3.15625 1.328125q1.234375 1.3125 1.234375 3.703125q0 0.15625 0 0.4375l-7.21875 0q0.09375 1.59375 0.90625 2.453125q0.8125 0.84375 2.015625 0.84375q0.90625 0 1.546875 -0.46875q0.640625 -0.484375 1.015625 -1.515625zm-5.390625 -2.65625l5.40625 0q-0.109375 -1.21875 -0.625 -1.828125q-0.78125 -0.953125 -2.03125 -0.953125q-1.125 0 -1.90625 0.765625q-0.765625 0.75 -0.84375 2.015625z" fill-rule="nonzero"/><path fill="#cfe2f3" d="m73.64304 101.46588l351.0551 0l0 53.70079l-351.0551 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m73.64304 101.46588l351.0551 0l0 53.70079l-351.0551 0z" fill-rule="evenodd"/><path fill="#000000" d="m215.67503 135.23627l0 -13.359367l1.640625 0l0 7.6249924l3.890625 -3.9374924l2.109375 0l-3.6875 3.5937424l4.0625 6.078125l-2.015625 0l-3.203125 -4.953125l-1.15625 1.125l0 3.828125l-1.640625 0zm12.90625 -1.46875l0.234375 1.453125q-0.6875 0.140625 -1.234375 0.140625q-0.890625 0 -1.390625 -0.28125q-0.484375 -0.28125 -0.6875 -0.734375q-0.203125 -0.46875 -0.203125 -1.9375l0 -5.5781174l-1.203125 0l0 -1.265625l1.203125 0l0 -2.390625l1.625 -0.984375l0 3.375l1.65625 0l0 1.265625l-1.65625 0l0 5.6718674q0 0.6875 0.078125 0.890625q0.09375 0.203125 0.28125 0.328125q0.203125 0.109375 0.578125 0.109375q0.265625 0 0.71875 -0.0625zm1.5583038 1.46875l0 -13.359367l1.640625 0l0 13.359367l-1.640625 0zm3.5354462 -2.890625l1.625 -0.25q0.125 0.96875 0.75 1.5q0.625 0.515625 1.75 0.515625q1.125 0 1.671875 -0.453125q0.546875 -0.46875 0.546875 -1.09375q0 -0.546875 -0.484375 -0.875q-0.328125 -0.21875 -1.671875 -0.546875q-1.8125 -0.46875 -2.515625 -0.796875q-0.6875 -0.328125 -1.046875 -0.90625q-0.359375 -0.59375 -0.359375 -1.3125q0 -0.6406174 0.296875 -1.1874924q0.296875 -0.5625 0.8125 -0.921875q0.375 -0.28125 1.03125 -0.46875q0.671875 -0.203125 1.421875 -0.203125q1.140625 0 2.0 0.328125q0.859375 0.328125 1.265625 0.890625q0.421875 0.5625 0.578125 1.4999924l-1.609375 0.21875q-0.109375 -0.7499924 -0.640625 -1.1718674q-0.515625 -0.421875 -1.46875 -0.421875q-1.140625 0 -1.625 0.375q-0.46875 0.375 -0.46875 0.875q0 0.31249237 0.1875 0.5781174q0.203125 0.265625 0.640625 0.4375q0.234375 0.09375 1.4375 0.421875q1.75 0.453125 2.4375 0.75q0.6875 0.296875 1.078125 0.859375q0.390625 0.5625 0.390625 1.40625q0 0.828125 -0.484375 1.546875q-0.46875 0.71875 -1.375 1.125q-0.90625 0.390625 -2.046875 0.390625q-1.875 0 -2.875 -0.78125q-0.984375 -0.78125 -1.25 -2.328125zm24.136429 -10.468742l1.765625 0l0 7.7187424q0 2.015625 -0.453125 3.203125q-0.453125 1.1875 -1.640625 1.9375q-1.1875 0.734375 -3.125 0.734375q-1.875 0 -3.078125 -0.640625q-1.1875 -0.65625 -1.703125 -1.875q-0.5 -1.234375 -0.5 -3.359375l0 -7.7187424l1.765625 0l0 7.7187424q0 1.734375 0.3125 2.5625q0.328125 0.8125 1.109375 1.265625q0.796875 0.453125 1.9375 0.453125q1.953125 0 2.78125 -0.890625q0.828125 -0.890625 0.828125 -3.390625l0 -7.7187424zm4.629181 13.359367l0 -13.359367l1.78125 0l0 11.781242l6.5625 0l0 1.578125l-8.34375 0zm10.453857 0l0 -13.359367l5.046875 0q1.328125 0 2.03125 0.125q0.96875 0.171875 1.640625 0.640625q0.671875 0.453125 1.078125 1.28125q0.40625 0.828125 0.40625 1.828125q0 1.703125 -1.09375 2.8906174q-1.078125 1.171875 -3.921875 1.171875l-3.421875 0l0 5.421875l-1.765625 0zm1.765625 -7.0l3.453125 0q1.71875 0 2.4375 -0.6406174q0.71875 -0.640625 0.71875 -1.796875q0 -0.84375 -0.421875 -1.4375q-0.421875 -0.59375 -1.125 -0.78125q-0.4375 -0.125 -1.640625 -0.125l-3.421875 0l0 4.7812424z" fill-rule="nonzero"/><path fill="#cfe2f3" d="m73.64304 216.38058l351.0551 0l0 53.700775l-351.0551 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m73.64304 216.38058l351.0551 0l0 53.700775l-351.0551 0z" fill-rule="evenodd"/><path fill="#000000" d="m211.16338 250.15097l0 -11.78125l-4.40625 0l0 -1.578125l10.578125 0l0 1.578125l-4.40625 0l0 11.78125l-1.765625 0zm17.52098 -4.6875l1.765625 0.453125q-0.5625 2.171875 -2.0 3.328125q-1.4375 1.140625 -3.53125 1.140625q-2.15625 0 -3.515625 -0.875q-1.34375 -0.890625 -2.0625 -2.546875q-0.703125 -1.671875 -0.703125 -3.59375q0 -2.078125 0.796875 -3.625q0.796875 -1.5625 2.265625 -2.359375q1.484375 -0.8125 3.25 -0.8125q2.0 0 3.359375 1.015625q1.375 1.015625 1.90625 2.875l-1.734375 0.40625q-0.46875 -1.453125 -1.359375 -2.109375q-0.875 -0.671875 -2.203125 -0.671875q-1.546875 0 -2.578125 0.734375q-1.03125 0.734375 -1.453125 1.984375q-0.421875 1.234375 -0.421875 2.5625q0 1.703125 0.5 2.96875q0.5 1.265625 1.546875 1.90625q1.046875 0.625 2.265625 0.625q1.484375 0 2.515625 -0.859375q1.03125 -0.859375 1.390625 -2.546875zm3.9416962 4.6875l0 -13.359375l5.046875 0q1.328125 0 2.03125 0.125q0.96875 0.171875 1.640625 0.640625q0.671875 0.453125 1.078125 1.28125q0.40625 0.828125 0.40625 1.828125q0 1.703125 -1.09375 2.890625q-1.078125 1.171875 -3.921875 1.171875l-3.421875 0l0 5.421875l-1.765625 0zm1.765625 -7.0l3.453125 0q1.71875 0 2.4375 -0.640625q0.71875 -0.640625 0.71875 -1.796875q0 -0.84375 -0.421875 -1.4375q-0.421875 -0.59375 -1.125 -0.78125q-0.4375 -0.125 -1.640625 -0.125l-3.421875 0l0 4.78125zm14.664642 4.109375l1.625 -0.25q0.125 0.96875 0.75 1.5q0.625 0.515625 1.75 0.515625q1.125 0 1.671875 -0.453125q0.546875 -0.46875 0.546875 -1.09375q0 -0.546875 -0.484375 -0.875q-0.328125 -0.21875 -1.671875 -0.546875q-1.8125 -0.46875 -2.515625 -0.796875q-0.6875 -0.328125 -1.046875 -0.90625q-0.359375 -0.59375 -0.359375 -1.3125q0 -0.640625 0.296875 -1.1875q0.296875 -0.5625 0.8125 -0.921875q0.375 -0.28125 1.03125 -0.46875q0.671875 -0.203125 1.421875 -0.203125q1.140625 0 2.0 0.328125q0.859375 0.328125 1.2656097 0.890625q0.421875 0.5625 0.578125 1.5l-1.6093597 0.21875q-0.109375 -0.75 -0.640625 -1.171875q-0.515625 -0.421875 -1.46875 -0.421875q-1.140625 0 -1.625 0.375q-0.46875 0.375 -0.46875 0.875q0 0.3125 0.1875 0.578125q0.203125 0.265625 0.640625 0.4375q0.234375 0.09375 1.4375 0.421875q1.75 0.453125 2.4375 0.75q0.68748474 0.296875 1.0781097 0.859375q0.390625 0.5625 0.390625 1.40625q0 0.828125 -0.484375 1.546875q-0.46875 0.71875 -1.3749847 1.125q-0.90625 0.390625 -2.046875 0.390625q-1.875 0 -2.875 -0.78125q-0.984375 -0.78125 -1.25 -2.328125zm13.562485 1.421875l0.234375 1.453125q-0.6875 0.140625 -1.234375 0.140625q-0.890625 0 -1.390625 -0.28125q-0.484375 -0.28125 -0.6875 -0.734375q-0.203125 -0.46875 -0.203125 -1.9375l0 -5.578125l-1.203125 0l0 -1.265625l1.203125 0l0 -2.390625l1.625 -0.984375l0 3.375l1.65625 0l0 1.265625l-1.65625 0l0 5.671875q0 0.6875 0.078125 0.890625q0.09375 0.203125 0.28125 0.328125q0.203125 0.109375 0.578125 0.109375q0.265625 0 0.71875 -0.0625zm7.917694 0.28125q-0.921875 0.765625 -1.765625 1.09375q-0.828125 0.3125 -1.796875 0.3125q-1.59375 0 -2.453125 -0.78125q-0.859375 -0.78125 -0.859375 -1.984375q0 -0.71875 0.328125 -1.296875q0.328125 -0.59375 0.84375 -0.9375q0.53125 -0.359375 1.1875 -0.546875q0.46875 -0.125 1.453125 -0.25q1.984375 -0.234375 2.921875 -0.5625q0.015625 -0.34375 0.015625 -0.421875q0 -1.0 -0.46875 -1.421875q-0.625 -0.546875 -1.875 -0.546875q-1.15625 0 -1.703125 0.40625q-0.546875 0.40625 -0.8125 1.421875l-1.609375 -0.21875q0.21875 -1.015625 0.71875 -1.640625q0.5 -0.640625 1.453125 -0.984375q0.953125 -0.34375 2.1875 -0.34375q1.25 0 2.015625 0.296875q0.78125 0.28125 1.140625 0.734375q0.375 0.4375 0.515625 1.109375q0.078125 0.421875 0.078125 1.515625l0 2.1875q0 2.28125 0.109375 2.890625q0.109375 0.59375 0.40625 1.15625l-1.703125 0q-0.265625 -0.515625 -0.328125 -1.1875zm-0.140625 -3.671875q-0.890625 0.375 -2.671875 0.625q-1.015625 0.140625 -1.4375 0.328125q-0.421875 0.1875 -0.65625 0.53125q-0.21875 0.34375 -0.21875 0.78125q0 0.65625 0.5 1.09375q0.5 0.4375 1.453125 0.4375q0.9375 0 1.671875 -0.40625q0.75 -0.421875 1.09375 -1.140625q0.265625 -0.5625 0.265625 -1.640625l0 -0.609375zm10.516327 1.3125l1.609375 0.21875q-0.265625 1.65625 -1.359375 2.609375q-1.078125 0.9375 -2.671875 0.9375q-1.984375 0 -3.1875 -1.296875q-1.203125 -1.296875 -1.203125 -3.71875q0 -1.578125 0.515625 -2.75q0.515625 -1.171875 1.578125 -1.75q1.0625 -0.59375 2.3125 -0.59375q1.578125 0 2.578125 0.796875q1.0 0.796875 1.28125 2.265625l-1.59375 0.234375q-0.234375 -0.96875 -0.8125 -1.453125q-0.578125 -0.5 -1.390625 -0.5q-1.234375 0 -2.015625 0.890625q-0.78125 0.890625 -0.78125 2.8125q0 1.953125 0.75 2.84375q0.75 0.875 1.953125 0.875q0.96875 0 1.609375 -0.59375q0.65625 -0.59375 0.828125 -1.828125zm3.015625 3.546875l0 -13.359375l1.640625 0l0 7.625l3.890625 -3.9375l2.109375 0l-3.6875 3.59375l4.0625 6.078125l-2.015625 0l-3.203125 -4.953125l-1.15625 1.125l0 3.828125l-1.640625 0z" fill-rule="nonzero"/><path fill="#cfe2f3" d="m73.64304 331.2953l351.0551 0l0 53.700775l-351.0551 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m73.64304 331.2953l351.0551 0l0 53.700775l-351.0551 0z" fill-rule="evenodd"/><path fill="#000000" d="m225.73463 365.06567l0 -13.359375l4.609375 0q1.546875 0 2.375 0.203125q1.140625 0.25 1.953125 0.953125q1.0625 0.890625 1.578125 2.28125q0.53125 1.390625 0.53125 3.171875q0 1.515625 -0.359375 2.703125q-0.359375 1.171875 -0.921875 1.9375q-0.546875 0.765625 -1.203125 1.21875q-0.65625 0.4375 -1.59375 0.671875q-0.9375 0.21875 -2.140625 0.21875l-4.828125 0zm1.765625 -1.578125l2.859375 0q1.3125 0 2.0625 -0.234375q0.75 -0.25 1.203125 -0.703125q0.625 -0.625 0.96875 -1.6875q0.359375 -1.0625 0.359375 -2.578125q0 -2.09375 -0.6875 -3.21875q-0.6875 -1.125 -1.671875 -1.5q-0.703125 -0.28125 -2.28125 -0.28125l-2.8125 0l0 10.203125zm11.488571 1.578125l0 -9.671875l1.46875 0l0 1.46875q0.5625 -1.03125 1.03125 -1.359375q0.484375 -0.328125 1.0625 -0.328125q0.828125 0 1.6875 0.53125l-0.5625 1.515625q-0.609375 -0.359375 -1.203125 -0.359375q-0.546875 0 -0.96875 0.328125q-0.421875 0.328125 -0.609375 0.890625q-0.28125 0.875 -0.28125 1.921875l0 5.0625l-1.625 0zm6.228302 -11.46875l0 -1.890625l1.640625 0l0 1.890625l-1.640625 0zm0 11.46875l0 -9.671875l1.640625 0l0 9.671875l-1.640625 0zm6.832321 0l-3.6875 -9.671875l1.734375 0l2.078125 5.796875q0.328125 0.9375 0.625 1.9375q0.203125 -0.765625 0.609375 -1.828125l2.140625 -5.90625l1.6874847 0l-3.6562347 9.671875l-1.53125 0zm13.26561 -3.109375l1.6875 0.203125q-0.40625 1.484375 -1.484375 2.3125q-1.078125 0.8125 -2.765625 0.8125q-2.125 0 -3.375 -1.296875q-1.234375 -1.3125 -1.234375 -3.671875q0 -2.453125 1.25 -3.796875q1.265625 -1.34375 3.265625 -1.34375q1.9375 0 3.15625 1.328125q1.234375 1.3125 1.234375 3.703125q0 0.15625 0 0.4375l-7.21875 0q0.09375 1.59375 0.90625 2.453125q0.8125 0.84375 2.015625 0.84375q0.90625 0 1.546875 -0.46875q0.640625 -0.484375 1.015625 -1.515625zm-5.390625 -2.65625l5.40625 0q-0.109375 -1.21875 -0.625 -1.828125q-0.78125 -0.953125 -2.03125 -0.953125q-1.125 0 -1.90625 0.765625q-0.765625 0.75 -0.84375 2.015625zm9.125732 5.765625l0 -9.671875l1.46875 0l0 1.46875q0.5625 -1.03125 1.03125 -1.359375q0.484375 -0.328125 1.0625 -0.328125q0.828125 0 1.6875 0.53125l-0.5625 1.515625q-0.609375 -0.359375 -1.203125 -0.359375q-0.546875 0 -0.96875 0.328125q-0.421875 0.328125 -0.609375 0.890625q-0.28125 0.875 -0.28125 1.921875l0 5.0625l-1.625 0z" fill-rule="nonzero"/><path fill="#cfe2f3" d="m73.64304 446.20996l351.0551 0l0 53.700806l-351.0551 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m73.64304 446.20996l351.0551 0l0 53.700806l-351.0551 0z" fill-rule="evenodd"/><path fill="#000000" d="m222.09538 479.98038l0 -13.359375l4.609375 0q1.546875 0 2.375 0.203125q1.140625 0.25 1.953125 0.953125q1.0625 0.890625 1.578125 2.28125q0.53125 1.390625 0.53125 3.171875q0 1.515625 -0.359375 2.703125q-0.359375 1.171875 -0.921875 1.9375q-0.546875 0.765625 -1.203125 1.21875q-0.65625 0.4375 -1.59375 0.671875q-0.9375 0.21875 -2.140625 0.21875l-4.828125 0zm1.765625 -1.578125l2.859375 0q1.3125 0 2.0625 -0.234375q0.75 -0.25 1.203125 -0.703125q0.625 -0.625 0.96875 -1.6875q0.359375 -1.0625 0.359375 -2.578125q0 -2.09375 -0.6875 -3.21875q-0.6875 -1.125 -1.671875 -1.5q-0.703125 -0.28125 -2.28125 -0.28125l-2.8125 0l0 10.203125zm18.129196 -1.53125l1.6875 0.203125q-0.40625 1.484375 -1.484375 2.3125q-1.078125 0.8125 -2.765625 0.8125q-2.125 0 -3.375 -1.296875q-1.234375 -1.3125 -1.234375 -3.671875q0 -2.453125 1.25 -3.796875q1.265625 -1.34375 3.265625 -1.34375q1.9375 0 3.15625 1.328125q1.234375 1.3125 1.234375 3.703125q0 0.15625 0 0.4375l-7.21875 0q0.09375 1.59375 0.90625 2.453125q0.8125 0.84375 2.015625 0.84375q0.90625 0 1.546875 -0.46875q0.640625 -0.484375 1.015625 -1.515625zm-5.390625 -2.65625l5.40625 0q-0.109375 -1.21875 -0.625 -1.828125q-0.78125 -0.953125 -2.03125 -0.953125q-1.125 0 -1.90625 0.765625q-0.765625 0.75 -0.84375 2.015625zm11.828842 5.765625l-3.6875 -9.671875l1.734375 0l2.078125 5.796875q0.328125 0.9375 0.625 1.9375q0.203125 -0.765625 0.609375 -1.828125l2.140625 -5.90625l1.6875 0l-3.65625 9.671875l-1.53125 0zm6.640625 -11.46875l0 -1.890625l1.6406097 0l0 1.890625l-1.6406097 0zm0 11.46875l0 -9.671875l1.6406097 0l0 9.671875l-1.6406097 0zm10.457321 -3.546875l1.609375 0.21875q-0.265625 1.65625 -1.359375 2.609375q-1.078125 0.9375 -2.671875 0.9375q-1.984375 0 -3.1875 -1.296875q-1.203125 -1.296875 -1.203125 -3.71875q0 -1.578125 0.515625 -2.75q0.515625 -1.171875 1.578125 -1.75q1.0625 -0.59375 2.3125 -0.59375q1.578125 0 2.578125 0.796875q1.0 0.796875 1.28125 2.265625l-1.59375 0.234375q-0.234375 -0.96875 -0.8125 -1.453125q-0.578125 -0.5 -1.390625 -0.5q-1.234375 0 -2.015625 0.890625q-0.78125 0.890625 -0.78125 2.8125q0 1.953125 0.75 2.84375q0.75 0.875 1.953125 0.875q0.96875 0 1.609375 -0.59375q0.65625 -0.59375 0.828125 -1.828125zm9.640625 0.4375l1.6875 0.203125q-0.40625 1.484375 -1.484375 2.3125q-1.078125 0.8125 -2.765625 0.8125q-2.125 0 -3.375 -1.296875q-1.234375 -1.3125 -1.234375 -3.671875q0 -2.453125 1.25 -3.796875q1.265625 -1.34375 3.265625 -1.34375q1.9375 0 3.15625 1.328125q1.234375 1.3125 1.234375 3.703125q0 0.15625 0 0.4375l-7.21875 0q0.09375 1.59375 0.90625 2.453125q0.8125 0.84375 2.015625 0.84375q0.90625 0 1.546875 -0.46875q0.640625 -0.484375 1.015625 -1.515625zm-5.390625 -2.65625l5.40625 0q-0.109375 -1.21875 -0.625 -1.828125q-0.78125 -0.953125 -2.03125 -0.953125q-1.125 0 -1.90625 0.765625q-0.765625 0.75 -0.84375 2.015625z" fill-rule="nonzero"/><path fill="#000000" fill-opacity="0.0" d="m153.17061 40.25197l0 0" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m153.17061 40.25197l0 0" fill-rule="evenodd"/><path fill="#000000" fill-opacity="0.0" d="m48.435696 73.03937l402.67715 0" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" stroke-dasharray="4.0,3.0" d="m48.435696 73.03937l402.67715 0" fill-rule="evenodd"/><path fill="#cfe2f3" d="m177.95801 71.49061l-12.393707 0l0 12.897636l-24.7874 0l0 -12.897636l-12.393692 0l24.7874 -12.89764z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m177.95801 71.49061l-12.393707 0l0 12.897636l-24.7874 0l0 -12.897636l-12.393692 0l24.7874 -12.89764z" fill-rule="evenodd"/><path fill="#cfe2f3" d="m320.3832 71.49061l12.393707 0l0 -12.89764l24.787384 0l0 12.89764l12.393707 0l-24.787415 12.897636z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m320.3832 71.49061l12.393707 0l0 -12.89764l24.787384 0l0 12.89764l12.393707 0l-24.787415 12.897636z" fill-rule="evenodd"/><path fill="#cfe2f3" d="m177.95801 188.3931l-12.393707 0l0 12.897629l-24.7874 0l0 -12.897629l-12.393692 0l24.7874 -12.897644z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m177.95801 188.3931l-12.393707 0l0 12.897629l-24.7874 0l0 -12.897629l-12.393692 0l24.7874 -12.897644z" fill-rule="evenodd"/><path fill="#cfe2f3" d="m320.3832 188.3931l12.393707 0l0 -12.897644l24.787384 0l0 12.897644l12.393707 0l-24.787415 12.897629z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m320.3832 188.3931l12.393707 0l0 -12.897644l24.787384 0l0 12.897644l12.393707 0l-24.787415 12.897629z" fill-rule="evenodd"/><path fill="#cfe2f3" d="m177.95801 301.4256l-12.393707 0l0 12.897644l-24.7874 0l0 -12.897644l-12.393692 0l24.7874 -12.897644z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m177.95801 301.4256l-12.393707 0l0 12.897644l-24.7874 0l0 -12.897644l-12.393692 0l24.7874 -12.897644z" fill-rule="evenodd"/><path fill="#cfe2f3" d="m320.3832 301.4256l12.393707 0l0 -12.897644l24.787384 0l0 12.897644l12.393707 0l-24.787415 12.897644z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m320.3832 301.4256l12.393707 0l0 -12.897644l24.787384 0l0 12.897644l12.393707 0l-24.787415 12.897644z" fill-rule="evenodd"/><path fill="#cfe2f3" d="m177.95801 415.4906l-12.393707 0l0 12.897644l-24.7874 0l0 -12.897644l-12.393692 0l24.7874 -12.897644z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m177.95801 415.4906l-12.393707 0l0 12.897644l-24.7874 0l0 -12.897644l-12.393692 0l24.7874 -12.897644z" fill-rule="evenodd"/><path fill="#cfe2f3" d="m320.3832 415.4906l12.393707 0l0 -12.897644l24.787384 0l0 12.897644l12.393707 0l-24.787415 12.897644z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m320.3832 415.4906l12.393707 0l0 -12.897644l24.787384 0l0 12.897644l12.393707 0l-24.787415 12.897644z" fill-rule="evenodd"/><path fill="#000000" fill-opacity="0.0" d="m198.14961 44.009186l109.44881 0l0 53.70079l-109.44881 0z" fill-rule="evenodd"/><path fill="#000000" d="m224.98174 70.929184l2.78125 -13.359375l1.65625 0l-1.0 4.78125q0.78125 -0.71875 1.421875 -1.015625q0.640625 -0.296875 1.328125 -0.296875q1.359375 0 2.265625 1.015625q0.90625 1.0 0.90625 2.9375q0 1.28125 -0.375 2.359375q-0.359375 1.0625 -0.890625 1.78125q-0.53125 0.71875 -1.109375 1.15625q-0.578125 0.4375 -1.1875 0.640625q-0.59375 0.21875 -1.140625 0.21875q-0.96875 0 -1.703125 -0.5q-0.71875 -0.515625 -1.125 -1.546875l-0.390625 1.828125l-1.4375 0zm2.4375 -3.96875l-0.015625 0.3125q0 1.234375 0.59375 1.890625q0.59375 0.640625 1.484375 0.640625q0.859375 0 1.578125 -0.609375q0.734375 -0.609375 1.1875 -1.890625q0.46875 -1.28125 0.46875 -2.375q0 -1.21875 -0.59375 -1.890625q-0.578125 -0.671875 -1.4375 -0.671875q-0.90625 0 -1.65625 0.6875q-0.734375 0.6875 -1.234375 2.125q-0.375 1.0625 -0.375 1.78125zm14.531967 2.21875q-1.734375 1.96875 -3.5625 1.96875q-1.109375 0 -1.796875 -0.640625q-0.6875 -0.640625 -0.6875 -1.578125q0 -0.609375 0.296875 -2.09375l1.171875 -5.578125l1.65625 0l-1.296875 6.1875q-0.171875 0.765625 -0.171875 1.203125q0 0.546875 0.328125 0.859375q0.34375 0.296875 0.984375 0.296875q0.703125 0 1.359375 -0.328125q0.65625 -0.34375 1.125 -0.921875q0.484375 -0.578125 0.796875 -1.359375q0.1875 -0.5 0.453125 -1.765625l0.875 -4.171875l1.65625 0l-2.03125 9.671875l-1.515625 0l0.359375 -1.75zm4.000717 1.75l1.765625 -8.40625l-1.484375 0l0.265625 -1.265625l1.484375 0l0.28125 -1.375q0.21875 -1.03125 0.4375 -1.484375q0.234375 -0.453125 0.75 -0.75q0.53125 -0.296875 1.4375 -0.296875q0.625 0 1.828125 0.265625l-0.296875 1.4375q-0.84375 -0.21875 -1.40625 -0.21875q-0.484375 0 -0.734375 0.25q-0.25 0.234375 -0.4375 1.125l-0.21875 1.046875l1.84375 0l-0.265625 1.265625l-1.84375 0l-1.75 8.40625l-1.65625 0zm5.183304 0l1.765625 -8.40625l-1.484375 0l0.265625 -1.265625l1.484375 0l0.28125 -1.375q0.21875 -1.03125 0.4375 -1.484375q0.234375 -0.453125 0.75 -0.75q0.53125 -0.296875 1.4375 -0.296875q0.625 0 1.828125 0.265625l-0.296875 1.4375q-0.84375 -0.21875 -1.40625 -0.21875q-0.484375 0 -0.734375 0.25q-0.25 0.234375 -0.4375 1.125l-0.21875 1.046875l1.84375 0l-0.265625 1.265625l-1.84375 0l-1.75 8.40625l-1.65625 0zm12.058319 -3.28125l1.609375 0.15625q-0.34375 1.1875 -1.59375 2.265625q-1.234375 1.078125 -2.96875 1.078125q-1.0625 0 -1.96875 -0.5q-0.890625 -0.5 -1.359375 -1.4375q-0.46875 -0.953125 -0.46875 -2.15625q0 -1.59375 0.734375 -3.078125q0.734375 -1.484375 1.890625 -2.203125q1.171875 -0.734375 2.53125 -0.734375q1.734375 0 2.765625 1.078125q1.03125 1.0625 1.03125 2.921875q0 0.71875 -0.125 1.46875l-7.125 0q-0.046875 0.28125 -0.046875 0.5q0 1.359375 0.625 2.078125q0.625 0.71875 1.53125 0.71875q0.84375 0 1.65625 -0.546875q0.828125 -0.5625 1.28125 -1.609375zm-4.78125 -2.40625l5.421875 0q0.015625 -0.25 0.015625 -0.359375q0 -1.234375 -0.625 -1.890625q-0.625 -0.671875 -1.59375 -0.671875q-1.0625 0 -1.9375 0.734375q-0.859375 0.71875 -1.28125 2.1875zm8.063202 5.6875l2.015625 -9.671875l1.453125 0l-0.40625 1.96875q0.75 -1.109375 1.453125 -1.640625q0.71875 -0.546875 1.46875 -0.546875q0.5 0 1.21875 0.359375l-0.671875 1.53125q-0.4375 -0.3125 -0.9375 -0.3125q-0.875 0 -1.78125 0.96875q-0.90625 0.953125 -1.4375 3.46875l-0.8125 3.875l-1.5625 0zm6.368927 -3.3125l1.640625 -0.09375q0 0.703125 0.21875 1.21875q0.21875 0.5 0.796875 0.8125q0.59375 0.3125 1.375 0.3125q1.09375 0 1.640625 -0.4375q0.546875 -0.4375 0.546875 -1.015625q0 -0.4375 -0.328125 -0.8125q-0.328125 -0.390625 -1.640625 -0.953125q-1.3125 -0.5625 -1.671875 -0.78125q-0.609375 -0.375 -0.921875 -0.875q-0.3125 -0.515625 -0.3125 -1.171875q0 -1.140625 0.90625 -1.953125q0.921875 -0.828125 2.5625 -0.828125q1.828125 0 2.765625 0.84375q0.953125 0.84375 1.0 2.21875l-1.609375 0.109375q-0.046875 -0.875 -0.625 -1.390625q-0.578125 -0.515625 -1.65625 -0.515625q-0.84375 0 -1.328125 0.40625q-0.46875 0.390625 -0.46875 0.84375q0 0.453125 0.40625 0.796875q0.28125 0.234375 1.421875 0.734375q1.890625 0.8125 2.375 1.28125q0.78125 0.765625 0.78125 1.84375q0 0.71875 -0.4375 1.421875q-0.4375 0.6875 -1.34375 1.109375q-0.90625 0.40625 -2.140625 0.40625q-1.671875 0 -2.84375 -0.828125q-1.1875 -0.828125 -1.109375 -2.703125z" fill-rule="nonzero"/><path fill="#000000" fill-opacity="0.0" d="m198.14961 164.00919l109.44881 0l0 53.70079l-109.44881 0z" fill-rule="evenodd"/><path fill="#000000" d="m211.6696 187.61668l1.640625 -0.09375q0 0.703125 0.21875 1.21875q0.21875 0.5 0.796875 0.8125q0.59375 0.3125 1.375 0.3125q1.09375 0 1.640625 -0.4375q0.546875 -0.4375 0.546875 -1.015625q0 -0.4375 -0.328125 -0.8125q-0.328125 -0.390625 -1.640625 -0.953125q-1.3125 -0.5625 -1.671875 -0.78125q-0.609375 -0.375 -0.921875 -0.875q-0.3125 -0.515625 -0.3125 -1.171875q0 -1.140625 0.90625 -1.953125q0.921875 -0.828125 2.5625 -0.828125q1.828125 0 2.765625 0.84375q0.953125 0.84375 1.0 2.21875l-1.609375 0.109375q-0.046875 -0.875 -0.625 -1.390625q-0.578125 -0.515625 -1.65625 -0.515625q-0.84375 0 -1.328125 0.40625q-0.46875 0.390625 -0.46875 0.84375q0 0.453125 0.40625 0.796875q0.28125 0.234375 1.421875 0.734375q1.890625 0.8125 2.375 1.28125q0.78125 0.765625 0.78125 1.84375q0 0.71875 -0.4375 1.421875q-0.4375 0.6875 -1.34375 1.109375q-0.90625 0.40625 -2.140625 0.40625q-1.671875 0 -2.84375 -0.828125q-1.1875 -0.828125 -1.109375 -2.703125zm15.84375 -0.21875l1.65625 0.171875q-0.625 1.8125 -1.765625 2.703125q-1.140625 0.875 -2.609375 0.875q-1.578125 0 -2.5625 -1.015625q-0.96875 -1.03125 -0.96875 -2.859375q0 -1.578125 0.625 -3.109375q0.640625 -1.53125 1.796875 -2.328125q1.171875 -0.796875 2.6875 -0.796875q1.546875 0 2.453125 0.875q0.921875 0.875 0.921875 2.328125l-1.625 0.109375q-0.015625 -0.921875 -0.546875 -1.4375q-0.515625 -0.515625 -1.359375 -0.515625q-1.0 0 -1.734375 0.625q-0.71875 0.625 -1.140625 1.90625q-0.40625 1.28125 -0.40625 2.46875q0 1.234375 0.546875 1.859375q0.546875 0.609375 1.34375 0.609375q0.796875 0 1.53125 -0.609375q0.734375 -0.609375 1.15625 -1.859375zm9.171875 2.328125q-0.859375 0.734375 -1.65625 1.078125q-0.78125 0.34375 -1.6875 0.34375q-1.34375 0 -2.171875 -0.78125q-0.8125 -0.796875 -0.8125 -2.03125q0 -0.796875 0.375 -1.421875q0.375 -0.625 0.984375 -1.0q0.609375 -0.390625 1.484375 -0.546875q0.5625 -0.109375 2.109375 -0.171875q1.5625 -0.0625 2.234375 -0.328125q0.1875 -0.671875 0.1875 -1.125q0 -0.578125 -0.421875 -0.90625q-0.5625 -0.453125 -1.671875 -0.453125q-1.03125 0 -1.703125 0.46875q-0.65625 0.453125 -0.953125 1.296875l-1.671875 -0.140625q0.515625 -1.4375 1.609375 -2.203125q1.109375 -0.765625 2.796875 -0.765625q1.796875 0 2.84375 0.859375q0.796875 0.625 0.796875 1.65625q0 0.765625 -0.21875 1.796875l-0.53125 2.40625q-0.265625 1.140625 -0.265625 1.859375q0 0.453125 0.203125 1.3125l-1.671875 0q-0.125 -0.46875 -0.1875 -1.203125zm0.609375 -3.703125q-0.34375 0.140625 -0.75 0.21875q-0.390625 0.0625 -1.3125 0.15625q-1.4375 0.125 -2.03125 0.328125q-0.59375 0.1875 -0.90625 0.625q-0.296875 0.421875 -0.296875 0.9375q0 0.6875 0.484375 1.140625q0.484375 0.4375 1.359375 0.4375q0.828125 0 1.578125 -0.421875q0.75 -0.4375 1.1875 -1.203125q0.4375 -0.78125 0.6875 -2.21875zm7.094467 3.5625l-0.265625 1.359375q-0.59375 0.140625 -1.15625 0.140625q-0.984375 0 -1.5625 -0.46875q-0.4375 -0.375 -0.4375 -1.0q0 -0.3125 0.234375 -1.46875l1.171875 -5.625l-1.296875 0l0.265625 -1.265625l1.296875 0l0.5 -2.375l1.890625 -1.140625l-0.734375 3.515625l1.625 0l-0.28125 1.265625l-1.609375 0l-1.125 5.359375q-0.203125 1.015625 -0.203125 1.21875q0 0.28125 0.15625 0.4375q0.171875 0.15625 0.5625 0.15625q0.546875 0 0.96875 -0.109375zm5.183304 0l-0.265625 1.359375q-0.59375 0.140625 -1.15625 0.140625q-0.984375 0 -1.5625 -0.46875q-0.4375 -0.375 -0.4375 -1.0q0 -0.3125 0.234375 -1.46875l1.171875 -5.625l-1.296875 0l0.265625 -1.265625l1.296875 0l0.5 -2.375l1.890625 -1.140625l-0.734375 3.515625l1.625 0l-0.28125 1.265625l-1.609375 0l-1.125 5.359375q-0.203125 1.015625 -0.203125 1.21875q0 0.28125 0.15625 0.4375q0.171875 0.15625 0.5625 0.15625q0.546875 0 0.96875 -0.109375zm8.433304 -1.9375l1.609375 0.15625q-0.34375 1.1875 -1.59375 2.265625q-1.234375 1.078125 -2.96875 1.078125q-1.0625 0 -1.96875 -0.5q-0.890625 -0.5 -1.359375 -1.4375q-0.46875 -0.953125 -0.46875 -2.15625q0 -1.59375 0.734375 -3.078125q0.734375 -1.484375 1.890625 -2.203125q1.171875 -0.734375 2.53125 -0.734375q1.734375 0 2.765625 1.078125q1.03125 1.0625 1.03125 2.921875q0 0.71875 -0.125 1.46875l-7.125 0q-0.046875 0.28125 -0.046875 0.5q0 1.359375 0.625 2.078125q0.625 0.71875 1.53125 0.71875q0.84375 0 1.65625 -0.546875q0.828125 -0.5625 1.28125 -1.609375zm-4.78125 -2.40625l5.421875 0q0.015625 -0.25 0.015625 -0.359375q0 -1.234375 -0.625 -1.890625q-0.625 -0.671875 -1.59375 -0.671875q-1.0625 0 -1.9375 0.734375q-0.859375 0.71875 -1.28125 2.1875zm8.063202 5.6875l2.015625 -9.671875l1.453125 0l-0.40625 1.96875q0.75 -1.109375 1.453125 -1.640625q0.71875 -0.546875 1.46875 -0.546875q0.5 0 1.21875 0.359375l-0.671875 1.53125q-0.4375 -0.3125 -0.9375 -0.3125q-0.875 0 -1.78125 0.96875q-0.90625 0.953125 -1.4375 3.46875l-0.8125 3.875l-1.5625 0zm11.255371 0l2.796875 -13.359375l1.640625 0l-2.78125 13.359375l-1.65625 0zm6.613556 -11.484375l0.40625 -1.875l1.625 0l-0.390625 1.875l-1.640625 0zm-2.390625 11.484375l2.015625 -9.671875l1.65625 0l-2.03125 9.671875l-1.640625 0zm4.3635864 -3.3125l1.640625 -0.09375q0 0.703125 0.21875 1.21875q0.21875 0.5 0.796875 0.8125q0.59375 0.3125 1.375 0.3125q1.09375 0 1.640625 -0.4375q0.546875 -0.4375 0.546875 -1.015625q0 -0.4375 -0.328125 -0.8125q-0.328125 -0.390625 -1.640625 -0.953125q-1.3125 -0.5625 -1.671875 -0.78125q-0.609375 -0.375 -0.921875 -0.875q-0.3125 -0.515625 -0.3125 -1.171875q0 -1.140625 0.90625 -1.953125q0.921875 -0.828125 2.5625 -0.828125q1.828125 0 2.765625 0.84375q0.953125 0.84375 1.0 2.21875l-1.609375 0.109375q-0.046875 -0.875 -0.625 -1.390625q-0.578125 -0.515625 -1.65625 -0.515625q-0.84375 0 -1.328125 0.40625q-0.46875 0.390625 -0.46875 0.84375q0 0.453125 0.40625 0.796875q0.28125 0.234375 1.421875 0.734375q1.890625 0.8125 2.375 1.28125q0.78125 0.765625 0.78125 1.84375q0 0.71875 -0.4375 1.421875q-0.4375 0.6875 -1.34375 1.109375q-0.90625 0.40625 -2.140625 0.40625q-1.671875 0 -2.84375 -0.828125q-1.1875 -0.828125 -1.109375 -2.703125zm13.015625 1.96875l-0.265625 1.359375q-0.59375 0.140625 -1.15625 0.140625q-0.984375 0 -1.5625 -0.46875q-0.4375 -0.375 -0.4375 -1.0q0 -0.3125 0.234375 -1.46875l1.171875 -5.625l-1.296875 0l0.265625 -1.265625l1.296875 0l0.5 -2.375l1.890625 -1.140625l-0.734375 3.515625l1.625 0l-0.28125 1.265625l-1.609375 0l-1.125 5.359375q-0.203125 1.015625 -0.203125 1.21875q0 0.28125 0.15625 0.4375q0.171875 0.15625 0.5625 0.15625q0.546875 0 0.96875 -0.109375z" fill-rule="nonzero"/><path fill="#000000" fill-opacity="0.0" d="m198.14961 280.1392l109.44881 0l0 53.700806l-109.44881 0z" fill-rule="evenodd"/><path fill="#000000" d="m223.58026 303.7467l1.640625 -0.09375q0 0.703125 0.21875 1.21875q0.21875 0.5 0.796875 0.8125q0.59375 0.3125 1.375 0.3125q1.09375 0 1.640625 -0.4375q0.546875 -0.4375 0.546875 -1.015625q0 -0.4375 -0.328125 -0.8125q-0.328125 -0.390625 -1.640625 -0.953125q-1.3125 -0.5625 -1.671875 -0.78125q-0.609375 -0.375 -0.921875 -0.875q-0.3125 -0.515625 -0.3125 -1.171875q0 -1.140625 0.90625 -1.953125q0.921875 -0.828125 2.5625 -0.828125q1.828125 0 2.765625 0.84375q0.953125 0.84375 1.0 2.21875l-1.609375 0.109375q-0.046875 -0.875 -0.625 -1.390625q-0.578125 -0.515625 -1.65625 -0.515625q-0.84375 0 -1.328125 0.40625q-0.46875 0.390625 -0.46875 0.84375q0 0.453125 0.40625 0.796875q0.28125 0.234375 1.421875 0.734375q1.890625 0.8125 2.375 1.28125q0.78125 0.765625 0.78125 1.84375q0 0.71875 -0.4375 1.421875q-0.4375 0.6875 -1.34375 1.109375q-0.90625 0.40625 -2.140625 0.40625q-1.671875 0 -2.84375 -0.828125q-1.1875 -0.828125 -1.109375 -2.703125zm9.1875 3.3125l2.796875 -13.359375l1.640625 0l-1.734375 8.28125l4.8125 -4.59375l2.171875 0l-4.125 3.609375l2.5 6.0625l-1.8125 0l-1.921875 -4.96875l-2.015625 1.734375l-0.671875 3.234375l-1.640625 0zm7.5 3.703125l0 -1.1875l10.875 0l0 1.1875l-10.875 0zm12.188217 -3.703125l2.78125 -13.359375l1.6562653 0l-1.0000153 4.78125q0.78126526 -0.71875 1.4218903 -1.015625q0.640625 -0.296875 1.328125 -0.296875q1.359375 0 2.265625 1.015625q0.90625 1.0 0.90625 2.9375q0 1.28125 -0.375 2.359375q-0.359375 1.0625 -0.890625 1.78125q-0.53125 0.71875 -1.109375 1.15625q-0.578125 0.4375 -1.1875 0.640625q-0.59375 0.21875 -1.140625 0.21875q-0.96875 0 -1.7031403 -0.5q-0.71875 -0.515625 -1.125 -1.546875l-0.390625 1.828125l-1.4375 0zm2.4375 -3.96875l-0.015625 0.3125q0 1.234375 0.59375 1.890625q0.59376526 0.640625 1.4843903 0.640625q0.859375 0 1.578125 -0.609375q0.734375 -0.609375 1.1875 -1.890625q0.46875 -1.28125 0.46875 -2.375q0 -1.21875 -0.59375 -1.890625q-0.578125 -0.671875 -1.4375 -0.671875q-0.90625 0 -1.65625 0.6875q-0.73439026 0.6875 -1.2343903 2.125q-0.375 1.0625 -0.375 1.78125zm14.531967 2.21875q-1.734375 1.96875 -3.5625 1.96875q-1.109375 0 -1.796875 -0.640625q-0.6875 -0.640625 -0.6875 -1.578125q0 -0.609375 0.296875 -2.09375l1.171875 -5.578125l1.65625 0l-1.296875 6.1875q-0.171875 0.765625 -0.171875 1.203125q0 0.546875 0.328125 0.859375q0.34375 0.296875 0.984375 0.296875q0.703125 0 1.359375 -0.328125q0.65625 -0.34375 1.125 -0.921875q0.484375 -0.578125 0.796875 -1.359375q0.1875 -0.5 0.453125 -1.765625l0.875 -4.171875l1.65625 0l-2.03125 9.671875l-1.515625 0l0.359375 -1.75zm4.0007324 1.75l1.765625 -8.40625l-1.484375 0l0.265625 -1.265625l1.484375 0l0.28125 -1.375q0.21875 -1.03125 0.4375 -1.484375q0.234375 -0.453125 0.75 -0.75q0.53125 -0.296875 1.4375 -0.296875q0.625 0 1.828125 0.265625l-0.296875 1.4375q-0.84375 -0.21875 -1.40625 -0.21875q-0.484375 0 -0.734375 0.25q-0.25 0.234375 -0.4375 1.125l-0.21875 1.046875l1.84375 0l-0.265625 1.265625l-1.84375 0l-1.75 8.40625l-1.65625 0zm5.1832886 0l1.765625 -8.40625l-1.484375 0l0.265625 -1.265625l1.484375 0l0.28125 -1.375q0.21875 -1.03125 0.4375 -1.484375q0.234375 -0.453125 0.75 -0.75q0.53125 -0.296875 1.4375 -0.296875q0.625 0 1.828125 0.265625l-0.296875 1.4375q-0.84375 -0.21875 -1.40625 -0.21875q-0.484375 0 -0.734375 0.25q-0.25 0.234375 -0.4375 1.125l-0.21875 1.046875l1.84375 0l-0.265625 1.265625l-1.84375 0l-1.75 8.40625l-1.65625 0z" fill-rule="nonzero"/><path fill="#000000" fill-opacity="0.0" d="m163.81627 395.2362l178.11024 0l0 53.700806l-178.11024 0z" fill-rule="evenodd"/><path fill="#000000" d="m195.60925 418.62497l1.65625 0.171875q-0.625 1.8125 -1.765625 2.703125q-1.140625 0.875 -2.609375 0.875q-1.578125 0 -2.5625 -1.015625q-0.96875 -1.03125 -0.96875 -2.859375q0 -1.578125 0.625 -3.109375q0.640625 -1.53125 1.796875 -2.328125q1.171875 -0.796875 2.6875 -0.796875q1.546875 0 2.453125 0.875q0.921875 0.875 0.921875 2.328125l-1.625 0.109375q-0.015625 -0.921875 -0.546875 -1.4375q-0.515625 -0.515625 -1.359375 -0.515625q-1.0 0 -1.734375 0.625q-0.71875 0.625 -1.140625 1.90625q-0.40625 1.28125 -0.40625 2.46875q0 1.234375 0.546875 1.859375q0.546875 0.609375 1.34375 0.609375q0.796875 0 1.53125 -0.609375q0.734375 -0.609375 1.15625 -1.859375zm2.9375 -0.140625q0 -2.828125 1.671875 -4.6875q1.375 -1.53125 3.609375 -1.53125q1.75 0 2.8125 1.09375q1.078125 1.09375 1.078125 2.953125q0 1.65625 -0.671875 3.09375q-0.671875 1.4375 -1.921875 2.203125q-1.25 0.765625 -2.625 0.765625q-1.125 0 -2.046875 -0.484375q-0.921875 -0.484375 -1.421875 -1.359375q-0.484375 -0.890625 -0.484375 -2.046875zm1.65625 -0.15625q0 1.359375 0.65625 2.0625q0.65625 0.703125 1.65625 0.703125q0.53125 0 1.046875 -0.203125q0.53125 -0.21875 0.96875 -0.65625q0.453125 -0.4375 0.765625 -1.0q0.3125 -0.5625 0.5 -1.203125q0.28125 -0.90625 0.28125 -1.734375q0 -1.3125 -0.65625 -2.03125q-0.65625 -0.734375 -1.65625 -0.734375q-0.78125 0 -1.421875 0.375q-0.625 0.375 -1.140625 1.09375q-0.515625 0.703125 -0.765625 1.640625q-0.234375 0.9375 -0.234375 1.6875zm8.438217 3.828125l2.015625 -9.671875l1.5 0l-0.359375 1.6875q0.96875 -1.0 1.8125 -1.453125q0.859375 -0.453125 1.734375 -0.453125q1.1875 0 1.84375 0.640625q0.671875 0.625 0.671875 1.703125q0 0.53125 -0.234375 1.6875l-1.234375 5.859375l-1.640625 0l1.28125 -6.125q0.1875 -0.890625 0.1875 -1.328125q0 -0.484375 -0.328125 -0.78125q-0.328125 -0.296875 -0.953125 -0.296875q-1.28125 0 -2.265625 0.90625q-0.984375 0.90625 -1.453125 3.125l-0.9375 4.5l-1.640625 0zm14.219467 -1.34375l-0.265625 1.359375q-0.59375 0.140625 -1.15625 0.140625q-0.984375 0 -1.5625 -0.46875q-0.4375 -0.375 -0.4375 -1.0q0 -0.3125 0.234375 -1.46875l1.171875 -5.625l-1.296875 0l0.265625 -1.265625l1.296875 0l0.5 -2.375l1.890625 -1.140625l-0.734375 3.515625l1.625 0l-0.28125 1.265625l-1.609375 0l-1.125 5.359375q-0.203125 1.015625 -0.203125 1.21875q0 0.28125 0.15625 0.4375q0.171875 0.15625 0.5625 0.15625q0.546875 0 0.96875 -0.109375zm8.433304 -1.9375l1.609375 0.15625q-0.34375 1.1875 -1.59375 2.265625q-1.234375 1.078125 -2.96875 1.078125q-1.0625 0 -1.96875 -0.5q-0.890625 -0.5 -1.359375 -1.4375q-0.46875 -0.953125 -0.46875 -2.15625q0 -1.59375 0.734375 -3.078125q0.734375 -1.484375 1.890625 -2.203125q1.171875 -0.734375 2.53125 -0.734375q1.734375 0 2.765625 1.078125q1.03125 1.0625 1.03125 2.921875q0 0.71875 -0.125 1.46875l-7.125 0q-0.046875 0.28125 -0.046875 0.5q0 1.359375 0.625 2.078125q0.625 0.71875 1.53125 0.71875q0.84375 0 1.65625 -0.546875q0.828125 -0.5625 1.28125 -1.609375zm-4.78125 -2.40625l5.421875 0q0.015625 -0.25 0.015625 -0.359375q0 -1.234375 -0.625 -1.890625q-0.625 -0.671875 -1.59375 -0.671875q-1.0625 0 -1.9375 0.734375q-0.859375 0.71875 -1.28125 2.1875zm7.406967 5.6875l4.21875 -4.90625l-2.421875 -4.765625l1.828125 0l0.8125 1.71875q0.453125 0.96875 0.828125 1.84375l2.78125 -3.5625l2.015625 0l-4.0625 4.890625l2.4375 4.78125l-1.8125 0l-0.96875 -1.96875q-0.3125 -0.625 -0.703125 -1.5625l-2.875 3.53125l-2.078125 0zm13.828125 -1.34375l-0.265625 1.359375q-0.59375 0.140625 -1.15625 0.140625q-0.984375 0 -1.5625 -0.46875q-0.4375 -0.375 -0.4375 -1.0q0 -0.3125 0.234375 -1.46875l1.171875 -5.625l-1.296875 0l0.265625 -1.265625l1.296875 0l0.5 -2.375l1.890625 -1.140625l-0.734375 3.515625l1.625 0l-0.28125 1.265625l-1.609375 0l-1.125 5.359375q-0.203125 1.015625 -0.203125 1.21875q0 0.28125 0.15625 0.4375q0.171875 0.15625 0.5625 0.15625q0.546875 0 0.96875 -0.109375zm11.210358 -0.8125l0 -3.671875l-3.640625 0l0 -1.515625l3.640625 0l0 -3.640625l1.546875 0l0 3.640625l3.640625 0l0 1.515625l-3.640625 0l0 3.671875l-1.546875 0zm11.390778 2.15625l2.78125 -13.359375l1.65625 0l-1.0 4.78125q0.78125 -0.71875 1.421875 -1.015625q0.640625 -0.296875 1.328125 -0.296875q1.359375 0 2.265625 1.015625q0.90625 1.0 0.90625 2.9375q0 1.28125 -0.375 2.359375q-0.359375 1.0625 -0.890625 1.78125q-0.53125 0.71875 -1.109375 1.15625q-0.578125 0.4375 -1.1875 0.640625q-0.59375 0.21875 -1.140625 0.21875q-0.96875 0 -1.703125 -0.5q-0.71875 -0.515625 -1.125 -1.546875l-0.390625 1.828125l-1.4375 0zm2.4375 -3.96875l-0.015625 0.3125q0 1.234375 0.59375 1.890625q0.59375 0.640625 1.484375 0.640625q0.859375 0 1.578125 -0.609375q0.734375 -0.609375 1.1875 -1.890625q0.46875 -1.28125 0.46875 -2.375q0 -1.21875 -0.59375 -1.890625q-0.578125 -0.671875 -1.4375 -0.671875q-0.90625 0 -1.65625 0.6875q-0.734375 0.6875 -1.234375 2.125q-0.375 1.0625 -0.375 1.78125zm14.531952 2.21875q-1.734375 1.96875 -3.5625 1.96875q-1.109375 0 -1.796875 -0.640625q-0.6875 -0.640625 -0.6875 -1.578125q0 -0.609375 0.296875 -2.09375l1.171875 -5.578125l1.65625 0l-1.296875 6.1875q-0.171875 0.765625 -0.171875 1.203125q0 0.546875 0.328125 0.859375q0.34375 0.296875 0.984375 0.296875q0.703125 0 1.359375 -0.328125q0.65625 -0.34375 1.125 -0.921875q0.484375 -0.578125 0.796875 -1.359375q0.1875 -0.5 0.453125 -1.765625l0.875 -4.171875l1.65625 0l-2.03125 9.671875l-1.515625 0l0.359375 -1.75zm4.0007324 1.75l1.765625 -8.40625l-1.484375 0l0.265625 -1.265625l1.484375 0l0.28125 -1.375q0.21875 -1.03125 0.4375 -1.484375q0.234375 -0.453125 0.75 -0.75q0.53125 -0.296875 1.4375 -0.296875q0.625 0 1.828125 0.265625l-0.296875 1.4375q-0.84375 -0.21875 -1.40625 -0.21875q-0.484375 0 -0.734375 0.25q-0.25 0.234375 -0.4375 1.125l-0.21875 1.046875l1.84375 0l-0.265625 1.265625l-1.84375 0l-1.75 8.40625l-1.65625 0zm5.1832886 0l1.765625 -8.40625l-1.484375 0l0.265625 -1.265625l1.484375 0l0.28125 -1.375q0.21875 -1.03125 0.4375 -1.484375q0.234375 -0.453125 0.75 -0.75q0.53125 -0.296875 1.4375 -0.296875q0.625 0 1.828125 0.265625l-0.296875 1.4375q-0.84375 -0.21875 -1.40625 -0.21875q-0.484375 0 -0.734375 0.25q-0.25 0.234375 -0.4375 1.125l-0.21875 1.046875l1.84375 0l-0.265625 1.265625l-1.84375 0l-1.75 8.40625l-1.65625 0zm12.058319 -3.28125l1.609375 0.15625q-0.34375 1.1875 -1.59375 2.265625q-1.234375 1.078125 -2.96875 1.078125q-1.0625 0 -1.96875 -0.5q-0.890625 -0.5 -1.359375 -1.4375q-0.46875 -0.953125 -0.46875 -2.15625q0 -1.59375 0.734375 -3.078125q0.734375 -1.484375 1.890625 -2.203125q1.171875 -0.734375 2.53125 -0.734375q1.734375 0 2.765625 1.078125q1.03125 1.0625 1.03125 2.921875q0 0.71875 -0.125 1.46875l-7.125 0q-0.046875 0.28125 -0.046875 0.5q0 1.359375 0.625 2.078125q0.625 0.71875 1.53125 0.71875q0.84375 0 1.65625 -0.546875q0.828125 -0.5625 1.28125 -1.609375zm-4.78125 -2.40625l5.421875 0q0.015625 -0.25 0.015625 -0.359375q0 -1.234375 -0.625 -1.890625q-0.625 -0.671875 -1.59375 -0.671875q-1.0625 0 -1.9375 0.734375q-0.859375 0.71875 -1.28125 2.1875zm8.063202 5.6875l2.015625 -9.671875l1.453125 0l-0.40625 1.96875q0.75 -1.109375 1.453125 -1.640625q0.71875 -0.546875 1.46875 -0.546875q0.5 0 1.21875 0.359375l-0.671875 1.53125q-0.4375 -0.3125 -0.9375 -0.3125q-0.875 0 -1.78125 0.96875q-0.90625 0.953125 -1.4375 3.46875l-0.8125 3.875l-1.5625 0z" fill-rule="nonzero"/><path fill="#cfe2f3" d="m0 165.96588l118.74016 0l0 40.25197l-118.74016 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m0 165.96588l118.74016 0l0 40.25197l-118.74016 0z" fill-rule="evenodd"/><path fill="#000000" d="m23.145836 190.12123l1.625 -0.25q0.125 0.96875 0.75 1.5q0.625 0.515625 1.75 0.515625q1.125 0 1.671875 -0.453125q0.546875 -0.46875 0.546875 -1.09375q0 -0.546875 -0.484375 -0.875q-0.328125 -0.21875 -1.671875 -0.546875q-1.8125 -0.46875 -2.515625 -0.796875q-0.6875 -0.328125 -1.046875 -0.90625q-0.359375 -0.59375 -0.359375 -1.3125q0 -0.640625 0.296875 -1.1875q0.296875 -0.5625 0.8125 -0.921875q0.375 -0.28125 1.03125 -0.46875q0.671875 -0.203125 1.421875 -0.203125q1.140625 0 2.0 0.328125q0.859375 0.328125 1.265625 0.890625q0.421875 0.5625 0.578125 1.5l-1.609375 0.21875q-0.109375 -0.75 -0.640625 -1.171875q-0.515625 -0.421875 -1.46875 -0.421875q-1.140625 0 -1.625 0.375q-0.46875 0.375 -0.46875 0.875q0 0.3125 0.1875 0.578125q0.203125 0.265625 0.640625 0.4375q0.234375 0.09375 1.4375 0.421875q1.75 0.453125 2.4375 0.75q0.6875 0.296875 1.078125 0.859375q0.390625 0.5625 0.390625 1.40625q0 0.828125 -0.484375 1.546875q-0.46875 0.71875 -1.375 1.125q-0.90625 0.390625 -2.046875 0.390625q-1.875 0 -2.875 -0.78125q-0.984375 -0.78125 -1.25 -2.328125zm13.5625 1.421875l0.234375 1.453125q-0.6875 0.140625 -1.234375 0.140625q-0.890625 0 -1.390625 -0.28125q-0.484375 -0.28125 -0.6875 -0.734375q-0.203125 -0.46875 -0.203125 -1.9375l0 -5.578125l-1.203125 0l0 -1.265625l1.203125 0l0 -2.390625l1.625 -0.984375l0 3.375l1.65625 0l0 1.265625l-1.65625 0l0 5.671875q0 0.6875 0.078125 0.890625q0.09375 0.203125 0.28125 0.328125q0.203125 0.109375 0.578125 0.109375q0.265625 0 0.71875 -0.0625zm1.5895538 1.46875l0 -9.671875l1.46875 0l0 1.46875q0.5625 -1.03125 1.03125 -1.359375q0.484375 -0.328125 1.0625 -0.328125q0.828125 0 1.6875 0.53125l-0.5625 1.515625q-0.609375 -0.359375 -1.203125 -0.359375q-0.546875 0 -0.96875 0.328125q-0.421875 0.328125 -0.609375 0.890625q-0.28125 0.875 -0.28125 1.921875l0 5.0625l-1.625 0zm6.228302 3.703125l0 -13.375l1.484375 0l0 1.25q0.53125 -0.734375 1.1875 -1.09375q0.671875 -0.375 1.625 -0.375q1.234375 0 2.171875 0.640625q0.953125 0.625 1.4375 1.796875q0.484375 1.15625 0.484375 2.546875q0 1.484375 -0.53125 2.671875q-0.53125 1.1875 -1.546875 1.828125q-1.015625 0.625 -2.140625 0.625q-0.8125 0 -1.46875 -0.34375q-0.65625 -0.34375 -1.0625 -0.875l0 4.703125l-1.640625 0zm1.484375 -8.484375q0 1.859375 0.75 2.765625q0.765625 0.890625 1.828125 0.890625q1.09375 0 1.875 -0.921875q0.78125 -0.9375 0.78125 -2.875q0 -1.84375 -0.765625 -2.765625q-0.75 -0.921875 -1.8125 -0.921875q-1.046875 0 -1.859375 0.984375q-0.796875 0.96875 -0.796875 2.84375zm15.203842 3.59375q-0.921875 0.765625 -1.765625 1.09375q-0.828125 0.3125 -1.796875 0.3125q-1.59375 0 -2.453125 -0.78125q-0.859375 -0.78125 -0.859375 -1.984375q0 -0.71875 0.328125 -1.296875q0.328125 -0.59375 0.84375 -0.9375q0.53125 -0.359375 1.1875 -0.546875q0.46875 -0.125 1.453125 -0.25q1.984375 -0.234375 2.921875 -0.5625q0.015625 -0.34375 0.015625 -0.421875q0 -1.0 -0.46875 -1.421875q-0.625 -0.546875 -1.875 -0.546875q-1.15625 0 -1.703125 0.40625q-0.546875 0.40625 -0.8125 1.421875l-1.609375 -0.21875q0.21875 -1.015625 0.71875 -1.640625q0.5 -0.640625 1.453125 -0.984375q0.953125 -0.34375 2.1875 -0.34375q1.25 0 2.015625 0.296875q0.78125 0.28125 1.140625 0.734375q0.375 0.4375 0.515625 1.109375q0.078125 0.421875 0.078125 1.515625l0 2.1875q0 2.28125 0.109375 2.890625q0.109375 0.59375 0.40625 1.15625l-1.703125 0q-0.265625 -0.515625 -0.328125 -1.1875zm-0.140625 -3.671875q-0.890625 0.375 -2.671875 0.625q-1.015625 0.140625 -1.4375 0.328125q-0.421875 0.1875 -0.65625 0.53125q-0.21875 0.34375 -0.21875 0.78125q0 0.65625 0.5 1.09375q0.5 0.4375 1.453125 0.4375q0.9375 0 1.671875 -0.40625q0.75 -0.421875 1.09375 -1.140625q0.265625 -0.5625 0.265625 -1.640625l0 -0.609375zm4.188217 4.859375l0 -9.671875l1.46875 0l0 1.46875q0.5625 -1.03125 1.03125 -1.359375q0.484375 -0.328125 1.0625 -0.328125q0.828125 0 1.6875 0.53125l-0.5625 1.515625q-0.609375 -0.359375 -1.203125 -0.359375q-0.546875 0 -0.96875 0.328125q-0.421875 0.328125 -0.609375 0.890625q-0.28125 0.875 -0.28125 1.921875l0 5.0625l-1.625 0zm5.572052 -2.890625l1.625 -0.25q0.125 0.96875 0.75 1.5q0.625 0.515625 1.75 0.515625q1.125 0 1.671875 -0.453125q0.546875 -0.46875 0.546875 -1.09375q0 -0.546875 -0.484375 -0.875q-0.328125 -0.21875 -1.671875 -0.546875q-1.8125 -0.46875 -2.515625 -0.796875q-0.6875 -0.328125 -1.046875 -0.90625q-0.359375 -0.59375 -0.359375 -1.3125q0 -0.640625 0.296875 -1.1875q0.296875 -0.5625 0.8125 -0.921875q0.375 -0.28125 1.03125 -0.46875q0.671875 -0.203125 1.421875 -0.203125q1.140625 0 2.0 0.328125q0.859375 0.328125 1.265625 0.890625q0.421875 0.5625 0.578125 1.5l-1.609375 0.21875q-0.109375 -0.75 -0.640625 -1.171875q-0.515625 -0.421875 -1.46875 -0.421875q-1.140625 0 -1.625 0.375q-0.46875 0.375 -0.46875 0.875q0 0.3125 0.1875 0.578125q0.203125 0.265625 0.640625 0.4375q0.234375 0.09375 1.4375 0.421875q1.75 0.453125 2.4375 0.75q0.6875 0.296875 1.078125 0.859375q0.390625 0.5625 0.390625 1.40625q0 0.828125 -0.484375 1.546875q-0.46875 0.71875 -1.375 1.125q-0.90625 0.390625 -2.046875 0.390625q-1.875 0 -2.875 -0.78125q-0.984375 -0.78125 -1.25 -2.328125zm16.609375 -0.21875l1.6875 0.203125q-0.40625 1.484375 -1.484375 2.3125q-1.078125 0.8125 -2.765625 0.8125q-2.125 0 -3.375 -1.296875q-1.234375 -1.3125 -1.234375 -3.671875q0 -2.453125 1.25 -3.796875q1.265625 -1.34375 3.265625 -1.34375q1.9375 0 3.15625 1.328125q1.234375 1.3125 1.234375 3.703125q0 0.15625 0 0.4375l-7.21875 0q0.09375 1.59375 0.90625 2.453125q0.8125 0.84375 2.015625 0.84375q0.90625 0 1.546875 -0.46875q0.640625 -0.484375 1.015625 -1.515625zm-5.390625 -2.65625l5.40625 0q-0.109375 -1.21875 -0.625 -1.828125q-0.78125 -0.953125 -2.03125 -0.953125q-1.125 0 -1.90625 0.765625q-0.765625 0.75 -0.84375 2.015625zm9.125717 5.765625l0 -9.671875l1.46875 0l0 1.46875q0.5625 -1.03125 1.03125 -1.359375q0.484375 -0.328125 1.0625 -0.328125q0.828125 0 1.6875 0.53125l-0.5625 1.515625q-0.609375 -0.359375 -1.203125 -0.359375q-0.546875 0 -0.96875 0.328125q-0.421875 0.328125 -0.609375 0.890625q-0.28125 0.875 -0.28125 1.921875l0 5.0625l-1.625 0z" fill-rule="nonzero"/></g></svg>
diff --git a/Documentation/networking/tls-offload-reorder-bad.svg b/Documentation/networking/tls-offload-reorder-bad.svg
new file mode 100644
index 000000000000..d107aaf0f71e
--- /dev/null
+++ b/Documentation/networking/tls-offload-reorder-bad.svg
@@ -0,0 +1 @@
+<svg version="1.1" viewBox="0.0 0.0 672.0 68.0" fill="none" stroke="none" stroke-linecap="square" stroke-miterlimit="10" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg"><clipPath id="p.0"><path d="m0 0l960.0 0l0 720.0l-960.0 0l0 -720.0z" clip-rule="nonzero"/></clipPath><g clip-path="url(#p.0)"><path fill="#000000" fill-opacity="0.0" d="m0 0l960.0 0l0 720.0l-960.0 0z" fill-rule="evenodd"/><path fill="#b6d7a8" d="m0 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m0 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" d="m15.953125 52.942722l-1.640625 0l0 -10.453125q-0.59375 0.5625 -1.5625 1.140625q-0.953125 0.5625 -1.71875 0.84375l0 -1.59375q1.375 -0.640625 2.40625 -1.5625q1.03125 -0.921875 1.453125 -1.78125l1.0625 0l0 13.40625z" fill-rule="nonzero"/><path fill="#c9daf8" d="m340.69897 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m340.69897 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" d="m355.73022 52.942722l0 -3.203125l-5.796875 0l0 -1.5l6.09375 -8.65625l1.34375 0l0 8.65625l1.796875 0l0 1.5l-1.796875 0l0 3.203125l-1.640625 0zm0 -4.703125l0 -6.015625l-4.1875 6.015625l4.1875 0z" fill-rule="nonzero"/><path fill="#cfe2f3" d="m225.37527 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m225.37527 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" d="m235.15652 49.411472l1.640625 -0.21875q0.28125 1.40625 0.953125 2.015625q0.6875 0.609375 1.65625 0.609375q1.15625 0 1.953125 -0.796875q0.796875 -0.796875 0.796875 -1.984375q0 -1.125 -0.734375 -1.859375q-0.734375 -0.734375 -1.875 -0.734375q-0.46875 0 -1.15625 0.171875l0.1875 -1.4375q0.15625 0.015625 0.265625 0.015625q1.046875 0 1.875 -0.546875q0.84375 -0.546875 0.84375 -1.671875q0 -0.90625 -0.609375 -1.5q-0.609375 -0.59375 -1.578125 -0.59375q-0.953125 0 -1.59375 0.609375q-0.640625 0.59375 -0.8125 1.796875l-1.640625 -0.296875q0.296875 -1.640625 1.359375 -2.546875q1.0625 -0.90625 2.65625 -0.90625q1.09375 0 2.0 0.46875q0.921875 0.46875 1.40625 1.28125q0.5 0.8125 0.5 1.71875q0 0.859375 -0.46875 1.578125q-0.46875 0.703125 -1.375 1.125q1.1875 0.28125 1.84375 1.140625q0.65625 0.859375 0.65625 2.15625q0 1.734375 -1.28125 2.953125q-1.265625 1.21875 -3.21875 1.21875q-1.765625 0 -2.921875 -1.046875q-1.15625 -1.046875 -1.328125 -2.71875z" fill-rule="nonzero"/><path fill="#cfe2f3" d="m572.3295 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m572.3295 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" d="m590.72015 51.364597l0 1.578125l-8.828125 0q-0.015625 -0.59375 0.1875 -1.140625q0.34375 -0.90625 1.078125 -1.78125q0.75 -0.875 2.15625 -2.015625q2.171875 -1.78125 2.9375 -2.828125q0.765625 -1.046875 0.765625 -1.96875q0 -0.984375 -0.703125 -1.640625q-0.6875 -0.671875 -1.8125 -0.671875q-1.1875 0 -1.90625 0.71875q-0.703125 0.703125 -0.703125 1.953125l-1.6875 -0.171875q0.171875 -1.890625 1.296875 -2.875q1.140625 -0.984375 3.03125 -0.984375q1.921875 0 3.046875 1.0625q1.125 1.0625 1.125 2.640625q0 0.796875 -0.328125 1.578125q-0.328125 0.78125 -1.09375 1.640625q-0.75 0.84375 -2.53125 2.34375q-1.46875 1.234375 -1.890625 1.6875q-0.421875 0.4375 -0.6875 0.875l6.546875 0z" fill-rule="nonzero"/><path fill="#e06666" d="m615.56793 24.999102l6.5512085 0l0 42.04725l-6.5512085 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m615.56793 24.999102l6.5512085 0l0 42.04725l-6.5512085 0z" fill-rule="evenodd"/><path fill="#c9daf8" d="m456.51425 24.999102l99.02365 0l0 42.04725l-99.02365 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m456.51425 24.999102l99.02365 0l0 42.04725l-99.02365 0z" fill-rule="evenodd"/><path fill="#000000" d="m466.2955 49.442722l1.71875 -0.140625q0.1875 1.25 0.875 1.890625q0.703125 0.625 1.6875 0.625q1.1875 0 2.0 -0.890625q0.828125 -0.890625 0.828125 -2.359375q0 -1.40625 -0.796875 -2.21875q-0.78125 -0.8125 -2.0625 -0.8125q-0.78125 0 -1.421875 0.359375q-0.640625 0.359375 -1.0 0.9375l-1.546875 -0.203125l1.296875 -6.859375l6.640625 0l0 1.5625l-5.328125 0l-0.71875 3.59375q1.203125 -0.84375 2.515625 -0.84375q1.75 0 2.953125 1.21875q1.203125 1.203125 1.203125 3.109375q0 1.8125 -1.046875 3.140625q-1.296875 1.625 -3.515625 1.625q-1.8125 0 -2.96875 -1.015625q-1.15625 -1.03125 -1.3125 -2.71875z" fill-rule="nonzero"/><path fill="#e06666" d="m391.1985 24.999102l6.551178 0l0 42.04725l-6.551178 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m391.1985 24.999102l6.551178 0l0 42.04725l-6.551178 0z" fill-rule="evenodd"/><path fill="#000000" fill-opacity="0.0" d="m114.43843 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" stroke-dasharray="4.0,3.0" d="m114.43843 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" fill-opacity="0.0" d="m163.95024 24.999102c0 -12.5 114.47246 -25.007874 228.9449 -25.0c114.47241 0.007874016 228.94489 12.531496 228.94489 25.062992" fill-rule="evenodd"/><path stroke="#000000" stroke-width="2.0" stroke-linejoin="round" stroke-linecap="butt" d="m163.95024 24.9991c0 -12.499998 114.47246 -25.007872 228.9449 -24.999998c57.236206 0.003937008 114.47244 3.136811 157.3996 7.835138c21.463562 2.3491635 39.349915 5.0896897 51.8703 8.026144c3.130127 0.7341137 5.9248657 1.4804726 8.356262 2.236023c0.30395508 0.09444237 0.6022339 0.1890316 0.89471436 0.28375435l0.37457275 0.12388611" fill-rule="evenodd"/><path fill="#000000" stroke="#000000" stroke-width="2.0" stroke-linecap="butt" d="m609.98517 21.270555l9.406311 2.1936665l-5.7955933 -7.7266836z" fill-rule="evenodd"/><path fill="#e06666" d="m47.56793 24.999102l6.551182 0l0 42.04725l-6.551182 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m47.56793 24.999102l6.551182 0l0 42.04725l-6.551182 0z" fill-rule="evenodd"/></g></svg>
diff --git a/Documentation/networking/tls-offload-reorder-good.svg b/Documentation/networking/tls-offload-reorder-good.svg
new file mode 100644
index 000000000000..10e17d91f70c
--- /dev/null
+++ b/Documentation/networking/tls-offload-reorder-good.svg
@@ -0,0 +1 @@
+<svg version="1.1" viewBox="0.0 0.0 672.0 68.0" fill="none" stroke="none" stroke-linecap="square" stroke-miterlimit="10" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg"><clipPath id="p.0"><path d="m0 0l960.0 0l0 720.0l-960.0 0l0 -720.0z" clip-rule="nonzero"/></clipPath><g clip-path="url(#p.0)"><path fill="#000000" fill-opacity="0.0" d="m0 0l960.0 0l0 720.0l-960.0 0z" fill-rule="evenodd"/><path fill="#b6d7a8" d="m0 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m0 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" d="m15.953125 52.942722l-1.640625 0l0 -10.453125q-0.59375 0.5625 -1.5625 1.140625q-0.953125 0.5625 -1.71875 0.84375l0 -1.59375q1.375 -0.640625 2.40625 -1.5625q1.03125 -0.921875 1.453125 -1.78125l1.0625 0l0 13.40625z" fill-rule="nonzero"/><path fill="#b6d7a8" d="m340.69897 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m340.69897 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" d="m355.73022 52.942722l0 -3.203125l-5.796875 0l0 -1.5l6.09375 -8.65625l1.34375 0l0 8.65625l1.796875 0l0 1.5l-1.796875 0l0 3.203125l-1.640625 0zm0 -4.703125l0 -6.015625l-4.1875 6.015625l4.1875 0z" fill-rule="nonzero"/><path fill="#cfe2f3" d="m225.37527 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m225.37527 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" d="m235.15652 49.411472l1.640625 -0.21875q0.28125 1.40625 0.953125 2.015625q0.6875 0.609375 1.65625 0.609375q1.15625 0 1.953125 -0.796875q0.796875 -0.796875 0.796875 -1.984375q0 -1.125 -0.734375 -1.859375q-0.734375 -0.734375 -1.875 -0.734375q-0.46875 0 -1.15625 0.171875l0.1875 -1.4375q0.15625 0.015625 0.265625 0.015625q1.046875 0 1.875 -0.546875q0.84375 -0.546875 0.84375 -1.671875q0 -0.90625 -0.609375 -1.5q-0.609375 -0.59375 -1.578125 -0.59375q-0.953125 0 -1.59375 0.609375q-0.640625 0.59375 -0.8125 1.796875l-1.640625 -0.296875q0.296875 -1.640625 1.359375 -2.546875q1.0625 -0.90625 2.65625 -0.90625q1.09375 0 2.0 0.46875q0.921875 0.46875 1.40625 1.28125q0.5 0.8125 0.5 1.71875q0 0.859375 -0.46875 1.578125q-0.46875 0.703125 -1.375 1.125q1.1875 0.28125 1.84375 1.140625q0.65625 0.859375 0.65625 2.15625q0 1.734375 -1.28125 2.953125q-1.265625 1.21875 -3.21875 1.21875q-1.765625 0 -2.921875 -1.046875q-1.15625 -1.046875 -1.328125 -2.71875z" fill-rule="nonzero"/><path fill="#e06666" d="m271.56793 24.999102l6.551178 0l0 42.04725l-6.551178 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m271.56793 24.999102l6.551178 0l0 42.04725l-6.551178 0z" fill-rule="evenodd"/><path fill="#cfe2f3" d="m572.3295 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m572.3295 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" d="m590.72015 51.364597l0 1.578125l-8.828125 0q-0.015625 -0.59375 0.1875 -1.140625q0.34375 -0.90625 1.078125 -1.78125q0.75 -0.875 2.15625 -2.015625q2.171875 -1.78125 2.9375 -2.828125q0.765625 -1.046875 0.765625 -1.96875q0 -0.984375 -0.703125 -1.640625q-0.6875 -0.671875 -1.8125 -0.671875q-1.1875 0 -1.90625 0.71875q-0.703125 0.703125 -0.703125 1.953125l-1.6875 -0.171875q0.171875 -1.890625 1.296875 -2.875q1.140625 -0.984375 3.03125 -0.984375q1.921875 0 3.046875 1.0625q1.125 1.0625 1.125 2.640625q0 0.796875 -0.328125 1.578125q-0.328125 0.78125 -1.09375 1.640625q-0.75 0.84375 -2.53125 2.34375q-1.46875 1.234375 -1.890625 1.6875q-0.421875 0.4375 -0.6875 0.875l6.546875 0z" fill-rule="nonzero"/><path fill="#b6d7a8" d="m456.51425 24.999102l99.02365 0l0 42.04725l-99.02365 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m456.51425 24.999102l99.02365 0l0 42.04725l-99.02365 0z" fill-rule="evenodd"/><path fill="#000000" d="m466.2955 49.442722l1.71875 -0.140625q0.1875 1.25 0.875 1.890625q0.703125 0.625 1.6875 0.625q1.1875 0 2.0 -0.890625q0.828125 -0.890625 0.828125 -2.359375q0 -1.40625 -0.796875 -2.21875q-0.78125 -0.8125 -2.0625 -0.8125q-0.78125 0 -1.421875 0.359375q-0.640625 0.359375 -1.0 0.9375l-1.546875 -0.203125l1.296875 -6.859375l6.640625 0l0 1.5625l-5.328125 0l-0.71875 3.59375q1.203125 -0.84375 2.515625 -0.84375q1.75 0 2.953125 1.21875q1.203125 1.203125 1.203125 3.109375q0 1.8125 -1.046875 3.140625q-1.296875 1.625 -3.515625 1.625q-1.8125 0 -2.96875 -1.015625q-1.15625 -1.03125 -1.3125 -2.71875z" fill-rule="nonzero"/><path fill="#e06666" d="m503.1985 24.999102l6.551178 0l0 42.04725l-6.551178 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m503.1985 24.999102l6.551178 0l0 42.04725l-6.551178 0z" fill-rule="evenodd"/><path fill="#000000" fill-opacity="0.0" d="m114.43843 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" stroke-dasharray="4.0,3.0" d="m114.43843 24.999102l99.02362 0l0 42.04725l-99.02362 0z" fill-rule="evenodd"/><path fill="#000000" fill-opacity="0.0" d="m163.95024 24.999102c0 -12.5 114.47246 -25.007874 228.9449 -25.0c114.47241 0.007874016 228.94489 12.531496 228.94489 25.062992" fill-rule="evenodd"/><path stroke="#000000" stroke-width="2.0" stroke-linejoin="round" stroke-linecap="butt" d="m163.95024 24.9991c0 -12.499998 114.47246 -25.007872 228.9449 -24.999998c57.236206 0.003937008 114.47244 3.136811 157.3996 7.835138c21.463562 2.3491635 39.349915 5.0896897 51.8703 8.026144c3.130127 0.7341137 5.9248657 1.4804726 8.356262 2.236023c0.30395508 0.09444237 0.6022339 0.1890316 0.89471436 0.28375435l0.37457275 0.12388611" fill-rule="evenodd"/><path fill="#000000" stroke="#000000" stroke-width="2.0" stroke-linecap="butt" d="m609.98517 21.270555l9.406311 2.1936665l-5.7955933 -7.7266836z" fill-rule="evenodd"/><path fill="#e06666" d="m47.56793 24.999102l6.551182 0l0 42.04725l-6.551182 0z" fill-rule="evenodd"/><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m47.56793 24.999102l6.551182 0l0 42.04725l-6.551182 0z" fill-rule="evenodd"/></g></svg>
diff --git a/Documentation/networking/tls-offload.rst b/Documentation/networking/tls-offload.rst
new file mode 100644
index 000000000000..32fecb3fbc4c
--- /dev/null
+++ b/Documentation/networking/tls-offload.rst
@@ -0,0 +1,438 @@
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+
+==================
+Kernel TLS offload
+==================
+
+Kernel TLS operation
+====================
+
+Linux kernel provides TLS connection offload infrastructure. Once a TCP
+connection is in ``ESTABLISHED`` state userspace can enable the TLS Upper
+Layer Protocol (ULP) and install the cryptographic connection state.
+For details regarding the user-facing interface refer to the TLS
+documentation in :ref:`Documentation/networking/tls.rst <kernel_tls>`.
+
+``ktls`` can operate in three modes:
+
+ * Software crypto mode (TLS_SW) - CPU handles the cryptography.
+   In most basic cases only crypto operations synchronous with the CPU
+   can be used, but depending on calling context CPU may utilize
+   asynchronous crypto accelerators. The use of accelerators introduces extra
+   latency on socket reads (decryption only starts when a read syscall
+   is made) and additional I/O load on the system.
+ * Packet-based NIC offload mode (TLS_HW) - the NIC handles crypto
+   on a packet by packet basis, provided the packets arrive in order.
+   This mode integrates best with the kernel stack and is described in detail
+   in the remaining part of this document
+   (``ethtool`` flags ``tls-hw-tx-offload`` and ``tls-hw-rx-offload``).
+ * Full TCP NIC offload mode (TLS_HW_RECORD) - mode of operation where
+   NIC driver and firmware replace the kernel networking stack
+   with its own TCP handling, it is not usable in production environments
+   making use of the Linux networking stack for example any firewalling
+   abilities or QoS and packet scheduling (``ethtool`` flag ``tls-hw-record``).
+
+The operation mode is selected automatically based on device configuration,
+offload opt-in or opt-out on per-connection basis is planned to be added
+in the future.
+
+TX
+--
+
+At a high level user write requests are turned into a scatter list, the TLS ULP
+intercepts them, inserts record framing, if non-offloaded encrypts them
+and then hands the modified scatter list to the TCP layer. From this point on
+the TCP stack proceeds as normal. When packets reach a device driver,
+the driver will mark the packets for crypto offload based on the socket
+the packet is attached to, and send them to the HW for encryption and
+transmission.
+
+RX
+--
+
+On the receive side if the device handled decryption and authentication
+successfully, the driver will set the decrypted bit in the associated
+:c:type:`struct sk_buff <sk_buff>`. The packets reach the TCP stack and
+are handled normally. ``ktls`` is informed when data is queued to the socket
+and the ``strparser`` mechanism is used to delineate the records. Upon read
+request, records are retrieved from the socket and passed to decryption routine.
+If device decrypted all the segments of the record the decryption is skipped,
+otherwise software path handles decryption.
+
+.. kernel-figure::  tls-offload-layers.svg
+   :alt:	TLS offload layers
+   :align:	center
+   :figwidth:	28em
+
+   Layers of Kernel TLS stack
+
+Device configuration
+====================
+
+During driver initialization device sets the ``NETIF_F_HW_TLS_RX`` and
+``NETIF_F_HW_TLS_TX`` features and installs its
+:c:type:`struct tlsdev_ops <tlsdev_ops>`
+pointer in the :c:member:`tlsdev_ops` member of the
+:c:type:`struct net_device <net_device>`.
+
+When TLS cryptographic connection state is installed on a ``ktls`` socket
+(note that it is done twice, once for RX and once for TX direction,
+and the two are completely independent), the kernel checks if the underlying
+network device is offload-capable and attempts the offload. In case offload
+fails the connection is handled entirely in software using the same mechanism
+as if the offload was never tried.
+
+Offload request is performed via the :c:member:`tls_dev_add` callback of
+:c:type:`struct tlsdev_ops <tlsdev_ops>`:
+
+.. code-block:: c
+
+	int (*tls_dev_add)(struct net_device *netdev, struct sock *sk,
+			   enum tls_offload_ctx_dir direction,
+			   struct tls_crypto_info *crypto_info,
+			   u32 start_offload_tcp_sn);
+
+``direction`` indicates whether the cryptographic information is for
+the received or transmitted packets. Driver uses the ``sk`` parameter
+to retrieve the connection 5-tuple and socket family (IPv4 vs IPv6).
+Cryptographic information in ``crypto_info`` includes the key, iv, salt
+as well as TLS record sequence number. ``start_offload_tcp_sn`` indicates
+which TCP sequence number corresponds to the beginning of the record with
+sequence number from ``crypto_info``. The driver can add its state
+at the end of kernel structures (see :c:member:`driver_state` members
+in ``include/net/tls.h``) to avoid additional allocations and pointer
+dereferences.
+
+TX
+--
+
+After TX state is installed, the stack guarantees that the first segment
+of the stream will start exactly at the ``start_offload_tcp_sn`` sequence
+number, simplifying TCP sequence number matching.
+
+TX offload being fully initialized does not imply that all segments passing
+through the driver and which belong to the offloaded socket will be after
+the expected sequence number and will have kernel record information.
+In particular, already encrypted data may have been queued to the socket
+before installing the connection state in the kernel.
+
+RX
+--
+
+In RX direction local networking stack has little control over the segmentation,
+so the initial records' TCP sequence number may be anywhere inside the segment.
+
+Normal operation
+================
+
+At the minimum the device maintains the following state for each connection, in
+each direction:
+
+ * crypto secrets (key, iv, salt)
+ * crypto processing state (partial blocks, partial authentication tag, etc.)
+ * record metadata (sequence number, processing offset and length)
+ * expected TCP sequence number
+
+There are no guarantees on record length or record segmentation. In particular
+segments may start at any point of a record and contain any number of records.
+Assuming segments are received in order, the device should be able to perform
+crypto operations and authentication regardless of segmentation. For this
+to be possible device has to keep small amount of segment-to-segment state.
+This includes at least:
+
+ * partial headers (if a segment carried only a part of the TLS header)
+ * partial data block
+ * partial authentication tag (all data had been seen but part of the
+   authentication tag has to be written or read from the subsequent segment)
+
+Record reassembly is not necessary for TLS offload. If the packets arrive
+in order the device should be able to handle them separately and make
+forward progress.
+
+TX
+--
+
+The kernel stack performs record framing and reserves space for the
+authentication tag to be filled in by the device. Both the device and the
+driver maintain expected TCP sequence numbers due to the possibility of
+retransmissions and the lack of software fallback once the packet reaches
+the device. For packets passed in order, the driver marks the packets with
+a connection identifier (note that a 5-tuple lookup is insufficient to identify
+packets requiring HW offload, see the :ref:`5tuple_problems` section)
+and hands them to the device. The device identifies the packet as requiring
+TLS handling and confirms the sequence number matches its expectation.
+If packets got out of order due to a bug in the stack or the device,
+reached the device and can't be encrypted such packet must be dropped.
+
+RX
+--
+
+Before a packet is DMAed to the host (but after NIC's embedded switching
+and packet transformation functions) the device performs a 5-tuple lookup
+to find any TLS connection the packet may belong to (technically a 4-tuple
+lookup is sufficient - IP addresses and TCP port numbers, as the protocol
+is always TCP). If connection is matched device confirms if the TCP sequence
+number is the expected one and proceeds to TLS handling (record delineation,
+decryption, authentication for each record in the packet).
+
+If decryption or authentication fails for any record in the packet, the packet
+must be passed to the host as it was received on the wire. This means packets
+should not be modified "in place". Splitting segments to handle partial
+decryption is not advised. In other words either all records in the packet
+had been handled successfully and authenticated or the packet has to be passed
+to the host as it was on the wire. The device communicates whether the packet
+was successfully decrypted in the per-packet context (descriptor) passed
+to the host.
+
+The device leaves the record framing unmodified, the stack takes care of
+record decapsulation.
+
+Upon reception of a TLS offloaded packet, the driver sets
+the :c:member:`decrypted` mark in :c:type:`struct sk_buff <sk_buff>`
+corresponding to the segment. Networking stack makes sure decrypted
+and non-decrypted segments do not get coalesced and takes care of partial
+decryption.
+
+Resync handling
+===============
+
+In presence of packet drops or network packet reordering, the device may lose
+synchronization with the TLS stream, and require a resync with the kernel's
+TCP stack.
+
+Note that resync is only attempted for connections which were successfully
+added to the device table and are in TLS_HW mode. For example,
+if the table was full when cryptographic state was installed in the kernel,
+such connection will never get offloaded. Therefore the resync request
+does not carry any cryptographic connection state.
+
+TX
+--
+
+Segments transmitted from an offloaded socket can get out of sync
+in similar ways to the receive side-retransmissions - local drops
+are possible, though network reorders are not.
+
+Whenever an out of order segment is transmitted the driver provides
+the device with enough information to perform cryptographic operations.
+This means most likely that the part of the record preceding the current
+segment has to be passed to the device as part of the packet context,
+together with its TCP sequence number and TLS record number. The device
+can then initialize its crypto state, process and discard the preceding
+data (to be able to insert the authentication tag) and move onto handling
+the actual packet.
+
+In this mode depending on the implementation the driver can either ask
+for a continuation with the crypto state and the new sequence number
+(next expected segment is the one after the out of order one), or continue
+with the previous stream state - assuming that the out of order segment
+was just a retransmission. The former is simpler, and does not require
+retransmission detection therefore it is the recommended method until
+such time it is proven inefficient.
+
+RX
+--
+
+A small amount of RX reorder events may not require a full resynchronization.
+In particular the device should not lose synchronization
+when record boundary can be recovered:
+
+.. kernel-figure::  tls-offload-reorder-good.svg
+   :alt:	reorder of non-header segment
+   :align:	center
+
+   Reorder of non-header segment
+
+Green segments are successfully decrypted, blue ones are passed
+as received on wire, red stripes mark start of new records.
+
+In above case segment 1 is received and decrypted successfully.
+Segment 2 was dropped so 3 arrives out of order. The device knows
+the next record starts inside 3, based on record length in segment 1.
+Segment 3 is passed untouched, because due to lack of data from segment 2
+the remainder of the previous record inside segment 3 cannot be handled.
+The device can, however, collect the authentication algorithm's state
+and partial block from the new record in segment 3 and when 4 and 5
+arrive continue decryption. Finally when 2 arrives it's completely outside
+of expected window of the device so it's passed as is without special
+handling. ``ktls`` software fallback handles the decryption of record
+spanning segments 1, 2 and 3. The device did not get out of sync,
+even though two segments did not get decrypted.
+
+Kernel synchronization may be necessary if the lost segment contained
+a record header and arrived after the next record header has already passed:
+
+.. kernel-figure::  tls-offload-reorder-bad.svg
+   :alt:	reorder of header segment
+   :align:	center
+
+   Reorder of segment with a TLS header
+
+In this example segment 2 gets dropped, and it contains a record header.
+Device can only detect that segment 4 also contains a TLS header
+if it knows the length of the previous record from segment 2. In this case
+the device will lose synchronization with the stream.
+
+When the device gets out of sync and the stream reaches TCP sequence
+numbers more than a max size record past the expected TCP sequence number,
+the device starts scanning for a known header pattern. For example
+for TLS 1.2 and TLS 1.3 subsequent bytes of value ``0x03 0x03`` occur
+in the SSL/TLS version field of the header. Once pattern is matched
+the device continues attempting parsing headers at expected locations
+(based on the length fields at guessed locations).
+Whenever the expected location does not contain a valid header the scan
+is restarted.
+
+When the header is matched the device sends a confirmation request
+to the kernel, asking if the guessed location is correct (if a TLS record
+really starts there), and which record sequence number the given header had.
+The kernel confirms the guessed location was correct and tells the device
+the record sequence number. Meanwhile, the device had been parsing
+and counting all records since the just-confirmed one, it adds the number
+of records it had seen to the record number provided by the kernel.
+At this point the device is in sync and can resume decryption at next
+segment boundary.
+
+In a pathological case the device may latch onto a sequence of matching
+headers and never hear back from the kernel (there is no negative
+confirmation from the kernel). The implementation may choose to periodically
+restart scan. Given how unlikely falsely-matching stream is, however,
+periodic restart is not deemed necessary.
+
+Special care has to be taken if the confirmation request is passed
+asynchronously to the packet stream and record may get processed
+by the kernel before the confirmation request.
+
+Performance metrics
+===================
+
+TLS offload can be characterized by the following basic metrics:
+
+ * max connection count
+ * connection installation rate
+ * connection installation latency
+ * total cryptographic performance
+
+Note that each TCP connection requires a TLS session in both directions,
+the performance may be reported treating each direction separately.
+
+Max connection count
+--------------------
+
+The number of connections device can support can be exposed via
+``devlink resource`` API.
+
+Total cryptographic performance
+-------------------------------
+
+Offload performance may depend on segment and record size.
+
+Overload of the cryptographic subsystem of the device should not have
+significant performance impact on non-offloaded streams.
+
+Statistics
+==========
+
+Following minimum set of TLS-related statistics should be reported
+by the driver:
+
+ * ``rx_tls_decrypted`` - number of succesfully decrypted TLS segments
+ * ``tx_tls_encrypted`` - number of in-order TLS segments passed to device
+   for encryption
+ * ``tx_tls_ooo`` - number of TX packets which were part of a TLS stream
+   but did not arrive in the expected order
+ * ``tx_tls_drop_no_sync_data`` - number of TX packets dropped because
+   they arrived out of order and associated record could not be found
+   (see also :ref:`pre_tls_data`)
+
+Notable corner cases, exceptions and additional requirements
+============================================================
+
+.. _5tuple_problems:
+
+5-tuple matching limitations
+----------------------------
+
+The device can only recognize received packets based on the 5-tuple
+of the socket. Current ``ktls`` implementation will not offload sockets
+routed through software interfaces such as those used for tunneling
+or virtual networking. However, many packet transformations performed
+by the networking stack (most notably any BPF logic) do not require
+any intermediate software device, therefore a 5-tuple match may
+consistently miss at the device level. In such cases the device
+should still be able to perform TX offload (encryption) and should
+fallback cleanly to software decryption (RX).
+
+Out of order
+------------
+
+Introducing extra processing in NICs should not cause packets to be
+transmitted or received out of order, for example pure ACK packets
+should not be reordered with respect to data segments.
+
+Ingress reorder
+---------------
+
+A device is permitted to perform packet reordering for consecutive
+TCP segments (i.e. placing packets in the correct order) but any form
+of additional buffering is disallowed.
+
+Coexistence with standard networking offload features
+-----------------------------------------------------
+
+Offloaded ``ktls`` sockets should support standard TCP stack features
+transparently. Enabling device TLS offload should not cause any difference
+in packets as seen on the wire.
+
+Transport layer transparency
+----------------------------
+
+The device should not modify any packet headers for the purpose
+of the simplifying TLS offload.
+
+The device should not depend on any packet headers beyond what is strictly
+necessary for TLS offload.
+
+Segment drops
+-------------
+
+Dropping packets is acceptable only in the event of catastrophic
+system errors and should never be used as an error handling mechanism
+in cases arising from normal operation. In other words, reliance
+on TCP retransmissions to handle corner cases is not acceptable.
+
+Known bugs
+==========
+
+skb_orphan() leaks clear text
+-----------------------------
+
+Currently drivers depend on the :c:member:`sk` member of
+:c:type:`struct sk_buff <sk_buff>` to identify segments requiring
+encryption. Any operation which removes or does not preserve the socket
+association such as :c:func:`skb_orphan` or :c:func:`skb_clone`
+will cause the driver to miss the packets and lead to clear text leaks.
+
+Redirects leak clear text
+-------------------------
+
+In the RX direction, if segment has already been decrypted by the device
+and it gets redirected or mirrored - clear text will be transmitted out.
+
+.. _pre_tls_data:
+
+Transmission of pre-TLS data
+----------------------------
+
+User can enqueue some already encrypted and framed records before enabling
+``ktls`` on the socket. Those records have to get sent as they are. This is
+perfectly easy to handle in the software case - such data will be waiting
+in the TCP layer, TLS ULP won't see it. In the offloaded case when pre-queued
+segment reaches transmission point it appears to be out of order (before the
+expected TCP sequence number) and the stack does not have a record information
+associated.
+
+All segments without record information cannot, however, be assumed to be
+pre-queued data, because a race condition exists between TCP stack queuing
+a retransmission, the driver seeing the retransmission and TCP ACK arriving
+for the retransmitted data.
diff --git a/Documentation/networking/tls.rst b/Documentation/networking/tls.rst
index 482bd73f18a2..5bcbf75e2025 100644
--- a/Documentation/networking/tls.rst
+++ b/Documentation/networking/tls.rst
@@ -1,3 +1,5 @@
+.. _kernel_tls:
+
 ==========
 Kernel TLS
 ==========
-- 
2.21.0

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Boris Pismenny]

Hi Jakub,

Thanks for submitting this.

On 5/15/2019 11:41 PM, Jakub Kicinski wrote:
> Describe existing kernel TLS offload (added back in Linux 4.19) -
> the mechanism, the expected behavior and the notable corner cases.
> 
> This documentation is mostly targeting hardware vendors who want
> to implement offload, to ensure consistency between implementations.
> 
> Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com>
> Acked-by: Dave Watson <davejwatson@fb.com>
> Acked-by: Alexei Starovoitov <ast@kernel.org>
> ---
>   Documentation/networking/index.rst            |   1 +
>   .../networking/tls-offload-layers.svg         |   1 +
>   .../networking/tls-offload-reorder-bad.svg    |   1 +
>   .../networking/tls-offload-reorder-good.svg   |   1 +
>   Documentation/networking/tls-offload.rst      | 438 ++++++++++++++++++
>   Documentation/networking/tls.rst              |   2 +
>   6 files changed, 444 insertions(+)
>   create mode 100644 Documentation/networking/tls-offload-layers.svg
>   create mode 100644 Documentation/networking/tls-offload-reorder-bad.svg
>   create mode 100644 Documentation/networking/tls-offload-reorder-good.svg
>   create mode 100644 Documentation/networking/tls-offload.rst
> 

[...]

> diff --git a/Documentation/networking/tls-offload.rst b/Documentation/networking/tls-offload.rst
> new file mode 100644
> index 000000000000..32fecb3fbc4c
> --- /dev/null
> +++ b/Documentation/networking/tls-offload.rst
> @@ -0,0 +1,438 @@
> +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +
> +==================
> +Kernel TLS offload
> +==================
> +
> +Kernel TLS operation
> +====================
> +
> +Linux kernel provides TLS connection offload infrastructure. Once a TCP
> +connection is in ``ESTABLISHED`` state userspace can enable the TLS Upper
> +Layer Protocol (ULP) and install the cryptographic connection state.
> +For details regarding the user-facing interface refer to the TLS
> +documentation in :ref:`Documentation/networking/tls.rst <kernel_tls>`.
> +
> +``ktls`` can operate in three modes:
> +
> + * Software crypto mode (TLS_SW) - CPU handles the cryptography.
> +   In most basic cases only crypto operations synchronous with the CPU
> +   can be used, but depending on calling context CPU may utilize
> +   asynchronous crypto accelerators. The use of accelerators introduces extra
> +   latency on socket reads (decryption only starts when a read syscall
> +   is made) and additional I/O load on the system.
> + * Packet-based NIC offload mode (TLS_HW) - the NIC handles crypto
> +   on a packet by packet basis, provided the packets arrive in order.
> +   This mode integrates best with the kernel stack and is described in detail
> +   in the remaining part of this document
> +   (``ethtool`` flags ``tls-hw-tx-offload`` and ``tls-hw-rx-offload``).
> + * Full TCP NIC offload mode (TLS_HW_RECORD) - mode of operation where
> +   NIC driver and firmware replace the kernel networking stack
> +   with its own TCP handling, it is not usable in production environments
> +   making use of the Linux networking stack for example any firewalling
> +   abilities or QoS and packet scheduling (``ethtool`` flag ``tls-hw-record``).
> +
> +The operation mode is selected automatically based on device configuration,
> +offload opt-in or opt-out on per-connection basis is planned to be added
> +in the future.

I see no reason to document future intentions here in docs. Unless you 
want to have a full blown list scattered over this document, please 
remove it.

> +
> +TX
> +--
> +
> +At a high level user write requests are turned into a scatter list, the TLS ULP
> +intercepts them, inserts record framing, if non-offloaded encrypts them

Maybe it would be best to describe how this is done in each mode?
In particular mentioning non-offloaded, and following with what happens 
on offloaded mode is confusing.

You should also note what fields of the frame are filled with actual 
meaningful data, and what is just a buffer to be filled by hardware.
Being as explicit as possible will prevent problems in the future.

> +and then hands the modified scatter list to the TCP layer. From this point on
> +the TCP stack proceeds as normal. When packets reach a device driver,
> +the driver will mark the packets for crypto offload based on the socket
> +the packet is attached to, and send them to the HW for encryption and
> +transmission.

Maybe we should mention something about software fallback here?

> +
> +RX
> +--
> +
> +On the receive side if the device handled decryption and authentication
> +successfully, the driver will set the decrypted bit in the associated
> +:c:type:`struct sk_buff <sk_buff>`. The packets reach the TCP stack and
> +are handled normally. ``ktls`` is informed when data is queued to the socket
> +and the ``strparser`` mechanism is used to delineate the records. Upon read
> +request, records are retrieved from the socket and passed to decryption routine.
> +If device decrypted all the segments of the record the decryption is skipped,
> +otherwise software path handles decryption.

Maybe we should mention that decryption is per packet, as an skb can 
represent a GRO skb as well.
Also, we should mention that the GRO layer doesn't coalesce plaintext 
with ciphertext.

> +
> +.. kernel-figure::  tls-offload-layers.svg
> +   :alt:	TLS offload layers
> +   :align:	center
> +   :figwidth:	28em
> +
> +   Layers of Kernel TLS stack
> +
> +Device configuration
> +====================
> +
> +During driver initialization device sets the ``NETIF_F_HW_TLS_RX`` and
> +``NETIF_F_HW_TLS_TX`` features and installs its
> +:c:type:`struct tlsdev_ops <tlsdev_ops>`
> +pointer in the :c:member:`tlsdev_ops` member of the
> +:c:type:`struct net_device <net_device>`.
> +
> +When TLS cryptographic connection state is installed on a ``ktls`` socket
> +(note that it is done twice, once for RX and once for TX direction,
> +and the two are completely independent), the kernel checks if the underlying
> +network device is offload-capable and attempts the offload. In case offload
> +fails the connection is handled entirely in software using the same mechanism
> +as if the offload was never tried.
> +
> +Offload request is performed via the :c:member:`tls_dev_add` callback of
> +:c:type:`struct tlsdev_ops <tlsdev_ops>`:
> +
> +.. code-block:: c
> +
> +	int (*tls_dev_add)(struct net_device *netdev, struct sock *sk,
> +			   enum tls_offload_ctx_dir direction,
> +			   struct tls_crypto_info *crypto_info,
> +			   u32 start_offload_tcp_sn);
> +
> +``direction`` indicates whether the cryptographic information is for
> +the received or transmitted packets. Driver uses the ``sk`` parameter
> +to retrieve the connection 5-tuple and socket family (IPv4 vs IPv6).
> +Cryptographic information in ``crypto_info`` includes the key, iv, salt
> +as well as TLS record sequence number. ``start_offload_tcp_sn`` indicates
> +which TCP sequence number corresponds to the beginning of the record with
> +sequence number from ``crypto_info``. The driver can add its state
> +at the end of kernel structures (see :c:member:`driver_state` members
> +in ``include/net/tls.h``) to avoid additional allocations and pointer
> +dereferences.
> +
> +TX
> +--
> +
> +After TX state is installed, the stack guarantees that the first segment
> +of the stream will start exactly at the ``start_offload_tcp_sn`` sequence
> +number, simplifying TCP sequence number matching.
> +
> +TX offload being fully initialized does not imply that all segments passing
> +through the driver and which belong to the offloaded socket will be after
> +the expected sequence number and will have kernel record information.
> +In particular, already encrypted data may have been queued to the socket
> +before installing the connection state in the kernel. > +
> +RX
> +--
> +
> +In RX direction local networking stack has little control over the segmentation,
> +so the initial records' TCP sequence number may be anywhere inside the segment.
> +
> +Normal operation
> +================
> +
> +At the minimum the device maintains the following state for each connection, in
> +each direction:
> +
> + * crypto secrets (key, iv, salt)
> + * crypto processing state (partial blocks, partial authentication tag, etc.)
> + * record metadata (sequence number, processing offset and length)
> + * expected TCP sequence number
> +
> +There are no guarantees on record length or record segmentation. In particular
> +segments may start at any point of a record and contain any number of records.
> +Assuming segments are received in order, the device should be able to perform
> +crypto operations and authentication regardless of segmentation. For this
> +to be possible device has to keep small amount of segment-to-segment state.
> +This includes at least:
> +
> + * partial headers (if a segment carried only a part of the TLS header)
> + * partial data block
> + * partial authentication tag (all data had been seen but part of the
> +   authentication tag has to be written or read from the subsequent segment)
> +
> +Record reassembly is not necessary for TLS offload. If the packets arrive
> +in order the device should be able to handle them separately and make
> +forward progress.
> +
> +TX
> +--
> +
> +The kernel stack performs record framing and reserves space for the
> +authentication tag to be filled in by the device. Both the device and the
> +driver maintain expected TCP sequence numbers due to the possibility of
> +retransmissions and the lack of software fallback once the packet reaches
> +the device. For packets passed in order, the driver marks the packets with
> +a connection identifier (note that a 5-tuple lookup is insufficient to identify
> +packets requiring HW offload, see the :ref:`5tuple_problems` section)
> +and hands them to the device. The device identifies the packet as requiring
> +TLS handling and confirms the sequence number matches its expectation.
> +If packets got out of order due to a bug in the stack or the device,
> +reached the device and can't be encrypted such packet must be dropped.
> +
> +RX
> +--
> +
> +Before a packet is DMAed to the host (but after NIC's embedded switching
> +and packet transformation functions) the device performs a 5-tuple lookup
> +to find any TLS connection the packet may belong to (technically a 4-tuple
> +lookup is sufficient - IP addresses and TCP port numbers, as the protocol
> +is always TCP). If connection is matched device confirms if the TCP sequence
> +number is the expected one and proceeds to TLS handling (record delineation,
> +decryption, authentication for each record in the packet).
> +
> +If decryption or authentication fails for any record in the packet, the packet
> +must be passed to the host as it was received on the wire. This means packets

This is not normal mode of operation, but rather an error handling 
description. Please try to describe only the good flow here, and leave 
the errors for a separate section.

> +should not be modified "in place". Splitting segments to handle partial
> +decryption is not advised. In other words either all records in the packet
> +had been handled successfully and authenticated or the packet has to be passed
> +to the host as it was on the wire. The device communicates whether the packet
> +was successfully decrypted in the per-packet context (descriptor) passed
> +to the host.
> +
> +The device leaves the record framing unmodified, the stack takes care of
> +record decapsulation.
> +
> +Upon reception of a TLS offloaded packet, the driver sets
> +the :c:member:`decrypted` mark in :c:type:`struct sk_buff <sk_buff>`
> +corresponding to the segment. Networking stack makes sure decrypted
> +and non-decrypted segments do not get coalesced and takes care of partial
> +decryption.

Please mention checksum handling as well. It would not make any sense to 
use CHECKSUM_COMPLETE here. Instead, CHECKSUM_UNNECESSARY should be 
expected.

> +
> +Resync handling
> +===============
> +
> +In presence of packet drops or network packet reordering, the device may lose
> +synchronization with the TLS stream, and require a resync with the kernel's
> +TCP stack.
> +
> +Note that resync is only attempted for connections which were successfully
> +added to the device table and are in TLS_HW mode. For example,
> +if the table was full when cryptographic state was installed in the kernel,
> +such connection will never get offloaded. Therefore the resync request
> +does not carry any cryptographic connection state.
> +
> +TX
> +--
> +
> +Segments transmitted from an offloaded socket can get out of sync
> +in similar ways to the receive side-retransmissions - local drops
> +are possible, though network reorders are not.
> +
> +Whenever an out of order segment is transmitted the driver provides
> +the device with enough information to perform cryptographic operations.
> +This means most likely that the part of the record preceding the current
> +segment has to be passed to the device as part of the packet context,
> +together with its TCP sequence number and TLS record number. The device
> +can then initialize its crypto state, process and discard the preceding
> +data (to be able to insert the authentication tag) and move onto handling
> +the actual packet.
> +
> +In this mode depending on the implementation the driver can either ask
> +for a continuation with the crypto state and the new sequence number
> +(next expected segment is the one after the out of order one), or continue
> +with the previous stream state - assuming that the out of order segment
> +was just a retransmission. The former is simpler, and does not require
> +retransmission detection therefore it is the recommended method until
> +such time it is proven inefficient.
> +
> +RX
> +--
> +
> +A small amount of RX reorder events may not require a full resynchronization.
> +In particular the device should not lose synchronization
> +when record boundary can be recovered:
> +
> +.. kernel-figure::  tls-offload-reorder-good.svg
> +   :alt:	reorder of non-header segment
> +   :align:	center
> +
> +   Reorder of non-header segment
> +
> +Green segments are successfully decrypted, blue ones are passed
> +as received on wire, red stripes mark start of new records.
> +
> +In above case segment 1 is received and decrypted successfully.
> +Segment 2 was dropped so 3 arrives out of order. The device knows
> +the next record starts inside 3, based on record length in segment 1.
> +Segment 3 is passed untouched, because due to lack of data from segment 2
> +the remainder of the previous record inside segment 3 cannot be handled.
> +The device can, however, collect the authentication algorithm's state
> +and partial block from the new record in segment 3 and when 4 and 5
> +arrive continue decryption. Finally when 2 arrives it's completely outside
> +of expected window of the device so it's passed as is without special
> +handling. ``ktls`` software fallback handles the decryption of record
> +spanning segments 1, 2 and 3. The device did not get out of sync,
> +even though two segments did not get decrypted.
> +
> +Kernel synchronization may be necessary if the lost segment contained
> +a record header and arrived after the next record header has already passed:
> +
> +.. kernel-figure::  tls-offload-reorder-bad.svg
> +   :alt:	reorder of header segment
> +   :align:	center
> +
> +   Reorder of segment with a TLS header
> +
> +In this example segment 2 gets dropped, and it contains a record header.
> +Device can only detect that segment 4 also contains a TLS header
> +if it knows the length of the previous record from segment 2. In this case
> +the device will lose synchronization with the stream.
> +
> +When the device gets out of sync and the stream reaches TCP sequence
> +numbers more than a max size record past the expected TCP sequence number,
> +the device starts scanning for a known header pattern. For example
> +for TLS 1.2 and TLS 1.3 subsequent bytes of value ``0x03 0x03`` occur
> +in the SSL/TLS version field of the header. Once pattern is matched
> +the device continues attempting parsing headers at expected locations
> +(based on the length fields at guessed locations).
> +Whenever the expected location does not contain a valid header the scan
> +is restarted.
> +
> +When the header is matched the device sends a confirmation request
> +to the kernel, asking if the guessed location is correct (if a TLS record
> +really starts there), and which record sequence number the given header had.
> +The kernel confirms the guessed location was correct and tells the device
> +the record sequence number. Meanwhile, the device had been parsing
> +and counting all records since the just-confirmed one, it adds the number
> +of records it had seen to the record number provided by the kernel.
> +At this point the device is in sync and can resume decryption at next
> +segment boundary.
> +
> +In a pathological case the device may latch onto a sequence of matching
> +headers and never hear back from the kernel (there is no negative
> +confirmation from the kernel). The implementation may choose to periodically
> +restart scan. Given how unlikely falsely-matching stream is, however,
> +periodic restart is not deemed necessary.
> +
> +Special care has to be taken if the confirmation request is passed
> +asynchronously to the packet stream and record may get processed
> +by the kernel before the confirmation request.
> +
> +Performance metrics
> +===================
> +
> +TLS offload can be characterized by the following basic metrics:
> +
> + * max connection count
> + * connection installation rate
> + * connection installation latency
> + * total cryptographic performance
> +
> +Note that each TCP connection requires a TLS session in both directions,
> +the performance may be reported treating each direction separately.
> +
> +Max connection count
> +--------------------
> +
> +The number of connections device can support can be exposed via
> +``devlink resource`` API.
> +
> +Total cryptographic performance
> +-------------------------------
> +
> +Offload performance may depend on segment and record size.
> +
> +Overload of the cryptographic subsystem of the device should not have
> +significant performance impact on non-offloaded streams.
> +
> +Statistics
> +==========
> +
> +Following minimum set of TLS-related statistics should be reported
> +by the driver:
> +
> + * ``rx_tls_decrypted`` - number of succesfully decrypted TLS segments
> + * ``tx_tls_encrypted`` - number of in-order TLS segments passed to device
> +   for encryption
> + * ``tx_tls_ooo`` - number of TX packets which were part of a TLS stream
> +   but did not arrive in the expected order
> + * ``tx_tls_drop_no_sync_data`` - number of TX packets dropped because
> +   they arrived out of order and associated record could not be found
> +   (see also :ref:`pre_tls_data`)
> +
> +Notable corner cases, exceptions and additional requirements
> +============================================================
> +
> +.. _5tuple_problems:
> +
> +5-tuple matching limitations
> +----------------------------
> +
> +The device can only recognize received packets based on the 5-tuple
> +of the socket. Current ``ktls`` implementation will not offload sockets
> +routed through software interfaces such as those used for tunneling
> +or virtual networking. However, many packet transformations performed
> +by the networking stack (most notably any BPF logic) do not require
> +any intermediate software device, therefore a 5-tuple match may
> +consistently miss at the device level. In such cases the device
> +should still be able to perform TX offload (encryption) and should
> +fallback cleanly to software decryption (RX).
> +
> +Out of order
> +------------
> +
> +Introducing extra processing in NICs should not cause packets to be
> +transmitted or received out of order, for example pure ACK packets
> +should not be reordered with respect to data segments.
> +
> +Ingress reorder
> +---------------
> +
> +A device is permitted to perform packet reordering for consecutive
> +TCP segments (i.e. placing packets in the correct order) but any form
> +of additional buffering is disallowed.
> +
> +Coexistence with standard networking offload features
> +-----------------------------------------------------
> +
> +Offloaded ``ktls`` sockets should support standard TCP stack features
> +transparently. Enabling device TLS offload should not cause any difference
> +in packets as seen on the wire.
> +
> +Transport layer transparency
> +----------------------------
> +
> +The device should not modify any packet headers for the purpose
> +of the simplifying TLS offload.
> +
> +The device should not depend on any packet headers beyond what is strictly
> +necessary for TLS offload.
> +
> +Segment drops
> +-------------
> +
> +Dropping packets is acceptable only in the event of catastrophic
> +system errors and should never be used as an error handling mechanism
> +in cases arising from normal operation. In other words, reliance
> +on TCP retransmissions to handle corner cases is not acceptable.
> +
> +Known bugs
> +==========
> +
> +skb_orphan() leaks clear text
> +-----------------------------
> +
> +Currently drivers depend on the :c:member:`sk` member of
> +:c:type:`struct sk_buff <sk_buff>` to identify segments requiring
> +encryption. Any operation which removes or does not preserve the socket
> +association such as :c:func:`skb_orphan` or :c:func:`skb_clone`
> +will cause the driver to miss the packets and lead to clear text leaks.
> +
> +Redirects leak clear text
> +-------------------------
> +
> +In the RX direction, if segment has already been decrypted by the device
> +and it gets redirected or mirrored - clear text will be transmitted out.
> +
> +.. _pre_tls_data:
> +
> +Transmission of pre-TLS data
> +----------------------------
> +
> +User can enqueue some already encrypted and framed records before enabling
> +``ktls`` on the socket. Those records have to get sent as they are. This is
> +perfectly easy to handle in the software case - such data will be waiting
> +in the TCP layer, TLS ULP won't see it. In the offloaded case when pre-queued
> +segment reaches transmission point it appears to be out of order (before the
> +expected TCP sequence number) and the stack does not have a record information
> +associated.
> +
> +All segments without record information cannot, however, be assumed to be
> +pre-queued data, because a race condition exists between TCP stack queuing
> +a retransmission, the driver seeing the retransmission and TCP ACK arriving
> +for the retransmitted data.
> diff --git a/Documentation/networking/tls.rst b/Documentation/networking/tls.rst
> index 482bd73f18a2..5bcbf75e2025 100644
> --- a/Documentation/networking/tls.rst
> +++ b/Documentation/networking/tls.rst
> @@ -1,3 +1,5 @@
> +.. _kernel_tls:
> +
>   ==========
>   Kernel TLS
>   ==========
> 

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Jakub Kicinski]

On Thu, 16 May 2019 09:08:52 +0000, Boris Pismenny wrote:
> > diff --git a/Documentation/networking/tls-offload.rst b/Documentation/networking/tls-offload.rst
> > new file mode 100644
> > index 000000000000..32fecb3fbc4c
> > --- /dev/null
> > +++ b/Documentation/networking/tls-offload.rst
> > @@ -0,0 +1,438 @@
> > +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +
> > +==================
> > +Kernel TLS offload
> > +==================
> > +
> > +Kernel TLS operation
> > +====================
> > +
> > +Linux kernel provides TLS connection offload infrastructure. Once a TCP
> > +connection is in ``ESTABLISHED`` state userspace can enable the TLS Upper
> > +Layer Protocol (ULP) and install the cryptographic connection state.
> > +For details regarding the user-facing interface refer to the TLS
> > +documentation in :ref:`Documentation/networking/tls.rst <kernel_tls>`.
> > +
> > +``ktls`` can operate in three modes:
> > +
> > + * Software crypto mode (TLS_SW) - CPU handles the cryptography.
> > +   In most basic cases only crypto operations synchronous with the CPU
> > +   can be used, but depending on calling context CPU may utilize
> > +   asynchronous crypto accelerators. The use of accelerators introduces extra
> > +   latency on socket reads (decryption only starts when a read syscall
> > +   is made) and additional I/O load on the system.
> > + * Packet-based NIC offload mode (TLS_HW) - the NIC handles crypto
> > +   on a packet by packet basis, provided the packets arrive in order.
> > +   This mode integrates best with the kernel stack and is described in detail
> > +   in the remaining part of this document
> > +   (``ethtool`` flags ``tls-hw-tx-offload`` and ``tls-hw-rx-offload``).
> > + * Full TCP NIC offload mode (TLS_HW_RECORD) - mode of operation where
> > +   NIC driver and firmware replace the kernel networking stack
> > +   with its own TCP handling, it is not usable in production environments
> > +   making use of the Linux networking stack for example any firewalling
> > +   abilities or QoS and packet scheduling (``ethtool`` flag ``tls-hw-record``).
> > +
> > +The operation mode is selected automatically based on device configuration,
> > +offload opt-in or opt-out on per-connection basis is planned to be added
> > +in the future.  
> 
> I see no reason to document future intentions here in docs. Unless you 
> want to have a full blown list scattered over this document, please 
> remove it.

Sure, I will implement it soonish, and I will have to update this
section one way or the other :)

> > +TX
> > +--
> > +
> > +At a high level user write requests are turned into a scatter list, the TLS ULP
> > +intercepts them, inserts record framing, if non-offloaded encrypts them  
> 
> Maybe it would be best to describe how this is done in each mode?
> In particular mentioning non-offloaded, and following with what happens 
> on offloaded mode is confusing.

Ack, will do.  FWIW I think it's clear when you can see the SVG
graphics.

> You should also note what fields of the frame are filled with actual 
> meaningful data, and what is just a buffer to be filled by hardware.
> Being as explicit as possible will prevent problems in the future.

This is an overview section, I will add the details in the section
below.

> > +and then hands the modified scatter list to the TCP layer. From this point on
> > +the TCP stack proceeds as normal. When packets reach a device driver,
> > +the driver will mark the packets for crypto offload based on the socket
> > +the packet is attached to, and send them to the HW for encryption and
> > +transmission.  
> 
> Maybe we should mention something about software fallback here?

I will beef up the information in the detailed sections, but perhaps
not in the overview.

> > +
> > +RX
> > +--
> > +
> > +On the receive side if the device handled decryption and authentication
> > +successfully, the driver will set the decrypted bit in the associated
> > +:c:type:`struct sk_buff <sk_buff>`. The packets reach the TCP stack and
> > +are handled normally. ``ktls`` is informed when data is queued to the socket
> > +and the ``strparser`` mechanism is used to delineate the records. Upon read
> > +request, records are retrieved from the socket and passed to decryption routine.
> > +If device decrypted all the segments of the record the decryption is skipped,
> > +otherwise software path handles decryption.  
> 
> Maybe we should mention that decryption is per packet, as an skb can 
> represent a GRO skb as well.
> Also, we should mention that the GRO layer doesn't coalesce plaintext 
> with ciphertext.

This is stated in the detailed section.

> > +
> > +.. kernel-figure::  tls-offload-layers.svg
> > +   :alt:	TLS offload layers
> > +   :align:	center
> > +   :figwidth:	28em
> > +
> > +   Layers of Kernel TLS stack

> > +Normal operation
> > +================
> > +
> > +At the minimum the device maintains the following state for each connection, in
> > +each direction:
> > +
> > + * crypto secrets (key, iv, salt)
> > + * crypto processing state (partial blocks, partial authentication tag, etc.)
> > + * record metadata (sequence number, processing offset and length)
> > + * expected TCP sequence number
> > +
> > +There are no guarantees on record length or record segmentation. In particular
> > +segments may start at any point of a record and contain any number of records.
> > +Assuming segments are received in order, the device should be able to perform
> > +crypto operations and authentication regardless of segmentation. For this
> > +to be possible device has to keep small amount of segment-to-segment state.
> > +This includes at least:
> > +
> > + * partial headers (if a segment carried only a part of the TLS header)
> > + * partial data block
> > + * partial authentication tag (all data had been seen but part of the
> > +   authentication tag has to be written or read from the subsequent segment)
> > +
> > +Record reassembly is not necessary for TLS offload. If the packets arrive
> > +in order the device should be able to handle them separately and make
> > +forward progress.

> > +RX
> > +--
> > +
> > +Before a packet is DMAed to the host (but after NIC's embedded switching
> > +and packet transformation functions) the device performs a 5-tuple lookup
> > +to find any TLS connection the packet may belong to (technically a 4-tuple
> > +lookup is sufficient - IP addresses and TCP port numbers, as the protocol
> > +is always TCP). If connection is matched device confirms if the TCP sequence
> > +number is the expected one and proceeds to TLS handling (record delineation,
> > +decryption, authentication for each record in the packet).
> > +
> > +If decryption or authentication fails for any record in the packet, the packet
> > +must be passed to the host as it was received on the wire. This means packets  
> 
> This is not normal mode of operation, but rather an error handling 
> description. Please try to describe only the good flow here, and leave 
> the errors for a separate section.

Normal as device is in sync with the stream vs the Resync handling
section.  It is not clear from the name, you're right, I will try
to split further and see how it turns out.

> > +should not be modified "in place". Splitting segments to handle partial
> > +decryption is not advised. In other words either all records in the packet
> > +had been handled successfully and authenticated or the packet has to be passed
> > +to the host as it was on the wire. The device communicates whether the packet
> > +was successfully decrypted in the per-packet context (descriptor) passed
> > +to the host.
> > +
> > +The device leaves the record framing unmodified, the stack takes care of
> > +record decapsulation.
> > +
> > +Upon reception of a TLS offloaded packet, the driver sets
> > +the :c:member:`decrypted` mark in :c:type:`struct sk_buff <sk_buff>`
> > +corresponding to the segment. Networking stack makes sure decrypted
> > +and non-decrypted segments do not get coalesced and takes care of partial
> > +decryption.  
> 
> Please mention checksum handling as well. It would not make any sense to 
> use CHECKSUM_COMPLETE here. Instead, CHECKSUM_UNNECESSARY should be 
> expected.

I was on the fence about adding the checksum info.  I had the feeling
that even for CHECKSUM_UNNECESSARY it's fairly strange to pass mangled
packets.  Looking at skbuff.h the checksum doc states:

 * CHECKSUM_UNNECESSARY:
 *
 *   The hardware you're dealing with doesn't calculate the full checksum
 *   (as in CHECKSUM_COMPLETE), but it does parse headers and verify checksums
 *   for specific protocols. For such packets it will set CHECKSUM_UNNECESSARY
 *   if their checksums are okay. skb->csum is still undefined in this case
 *   though. A driver or device must never modify the checksum field in the
 *   packet even if checksum is verified.

My reading of the last sentence is: the checksum in the packet must
still be correct (based on the context in which this comment was
written, which was in the days of UDP tunnel offload work).  
IOW UNNECESSARY doesn't mean "don't look at the checksum field", 
it means "I've looked at the checksum field and it's correct".

IMHO CHECKSUM_UNNECESSARY without correcting the TCP header csum field
is only slightly less broken than CHECKSUM_COMPLETE with pre-decrypt
csum and without fixing the TCP header.

Not to mention the fact that users may disable RXCSUM offload.

Maybe the least broken option is to fix the TCP header csum and pass
CHECKSUM_COMPLETE of the encrypted data?  But then again clearly the HW
has parsed the packet (voiding the non-ossification gain), and we won't
be doing tunnelling on clear text..

So CHECKSUM_UNNECESSARY "would do".

This is a long winded way of saying - I didn't see the perfect solution
here, so I thought it's better not to codify it in this doc.  But
perhaps I can phrase it tentatively enough.  How about:


  The preferred method of reporting the Layer 4 (TCP) checksum offload
  for packets decrypted by the device is to update the checksum field
  to the correct value for clear text and report CHECKSUM_UNNECESSARY
  or CHECKSUM_COMPLETE computed over clear text. However, the exact
  semantics of RX checksum offload when NIC performs data modification
  are not clear and subject to change.

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Alexei Starovoitov]

On Thu, May 16, 2019 at 10:57 AM Jakub Kicinski
<jakub.kicinski@netronome.com> wrote:
>
>   The preferred method of reporting the Layer 4 (TCP) checksum offload
>   for packets decrypted by the device is to update the checksum field
>   to the correct value for clear text and report CHECKSUM_UNNECESSARY
>   or CHECKSUM_COMPLETE computed over clear text. However, the exact
>   semantics of RX checksum offload when NIC performs data modification
>   are not clear and subject to change.

when host is consuming the tcp stream I don't see the value of
tcp checksum on top tls.
In that sense CHECKSUM_UNNECESSARY is fine and no
need to update checksum field.
Even in case of sockmap and tcp stream redirect it is still fine.
Only the tcp payload being redirected to a different tcp socket
and the headers are gone.
So imo in all cases CHECKSUM_UNNECESSARY is fine
even without adjustment to checksum field.

Obviously the hw/firmware should have checked tcp csum before doing decrypt.

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Jakub Kicinski]

On Thu, 16 May 2019 11:13:47 -0700, Alexei Starovoitov wrote:
> On Thu, May 16, 2019 at 10:57 AM Jakub Kicinski wrote:
> >
> >   The preferred method of reporting the Layer 4 (TCP) checksum offload
> >   for packets decrypted by the device is to update the checksum field
> >   to the correct value for clear text and report CHECKSUM_UNNECESSARY
> >   or CHECKSUM_COMPLETE computed over clear text. However, the exact
> >   semantics of RX checksum offload when NIC performs data modification
> >   are not clear and subject to change.  
> 
> when host is consuming the tcp stream I don't see the value of
> tcp checksum on top tls.
> In that sense CHECKSUM_UNNECESSARY is fine and no
> need to update checksum field.
> Even in case of sockmap and tcp stream redirect it is still fine.
> Only the tcp payload being redirected to a different tcp socket
> and the headers are gone.
> So imo in all cases CHECKSUM_UNNECESSARY is fine
> even without adjustment to checksum field.

No question that CHECKSUM_UNNECESSARY currently works.  
But it's not "entirely" correct without the header fixup?
Device modifies the data - it should fix up the checksum.

I was trying (unsuccessfully) to hint at the fact that it's okay 
today to leave the checksum be, but at the same time if someone 
is designing new HW or has the ability to fix this up in microcode
I think the TCP csum should be fixed..

Maybe like this?

  The preferred method of reporting the Layer 4 (TCP) checksum offload
  for packets decrypted by the device is to update the checksum field
  to the correct value for clear text and report CHECKSUM_UNNECESSARY
  or CHECKSUM_COMPLETE computed over clear text. 

  Some existing devices may report CHECKSUM_UNNECESSARY without fixing
  the checksum field, which currently functions correctly but is not
  in line with the exact semantics of RX checksum offload. Such devices
  must make sure that RXCSUM offload is always enabled for TLS offloaded
  flows.

> Obviously the hw/firmware should have checked tcp csum before doing decrypt.

Ah, that is definitely worth stating, will add!

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Alexei Starovoitov]

On Thu, May 16, 2019 at 11:42:03AM -0700, Jakub Kicinski wrote:
> On Thu, 16 May 2019 11:13:47 -0700, Alexei Starovoitov wrote:
> > On Thu, May 16, 2019 at 10:57 AM Jakub Kicinski wrote:
> > >
> > >   The preferred method of reporting the Layer 4 (TCP) checksum offload
> > >   for packets decrypted by the device is to update the checksum field
> > >   to the correct value for clear text and report CHECKSUM_UNNECESSARY
> > >   or CHECKSUM_COMPLETE computed over clear text. However, the exact
> > >   semantics of RX checksum offload when NIC performs data modification
> > >   are not clear and subject to change.  
> > 
> > when host is consuming the tcp stream I don't see the value of
> > tcp checksum on top tls.
> > In that sense CHECKSUM_UNNECESSARY is fine and no
> > need to update checksum field.
> > Even in case of sockmap and tcp stream redirect it is still fine.
> > Only the tcp payload being redirected to a different tcp socket
> > and the headers are gone.
> > So imo in all cases CHECKSUM_UNNECESSARY is fine
> > even without adjustment to checksum field.
> 
> No question that CHECKSUM_UNNECESSARY currently works.  
> But it's not "entirely" correct without the header fixup?
> Device modifies the data - it should fix up the checksum.

I think it's an interesting angle to discuss.
Though ktls in hw is done per packet many key fields of ip/tcp headers
are fully processed. socket is selected and payload is decrypted.
imo it is better to state that such headers have been 'consumed' by hw.
Where 'consumed' would mean that hw did what network layering suppose to do
and the stack should not look at them (because they can contain garbage).
(in that sense it's fine to keep csum unadjusted. imo it's ok to zero-out IP too)
Such decrypted skb is essentially a wrapper of payload plus
left-over headers passed to the stack.
I think it makes sense to clarify which headers have been consumed/processed.
Like: IP4/6+protocol+port+csum - processed, whereas
tcp bits, dscp, ecn are still valid and have to be processed by the stack.

> I was trying (unsuccessfully) to hint at the fact that it's okay 
> today to leave the checksum be, but at the same time if someone 
> is designing new HW or has the ability to fix this up in microcode
> I think the TCP csum should be fixed..

I don't think so. hw should work together with the stack
instead of being 'inline transparent decryption box'.
If hw decrypts stuff and adjusts csum it would imply that stack
will see completely valid headers. It would also imply that
the stack must check csum.
That doesn't seem right from trust point of view.

> 
> Maybe like this?
> 
>   The preferred method of reporting the Layer 4 (TCP) checksum offload
>   for packets decrypted by the device is to update the checksum field
>   to the correct value for clear text and report CHECKSUM_UNNECESSARY
>   or CHECKSUM_COMPLETE computed over clear text. 
> 
>   Some existing devices may report CHECKSUM_UNNECESSARY without fixing
>   the checksum field, which currently functions correctly but is not
>   in line with the exact semantics of RX checksum offload. Such devices
>   must make sure that RXCSUM offload is always enabled for TLS offloaded
>   flows.

I don't like it for the reasons above.

> > Obviously the hw/firmware should have checked tcp csum before doing decrypt.
> 
> Ah, that is definitely worth stating, will add!

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Jakub Kicinski]

On Thu, 16 May 2019 12:32:59 -0700, Alexei Starovoitov wrote:
> On Thu, May 16, 2019 at 11:42:03AM -0700, Jakub Kicinski wrote:
> > On Thu, 16 May 2019 11:13:47 -0700, Alexei Starovoitov wrote:
> > > On Thu, May 16, 2019 at 10:57 AM Jakub Kicinski wrote:
> > > >
> > > >   The preferred method of reporting the Layer 4 (TCP) checksum offload
> > > >   for packets decrypted by the device is to update the checksum field
> > > >   to the correct value for clear text and report CHECKSUM_UNNECESSARY
> > > >   or CHECKSUM_COMPLETE computed over clear text. However, the exact
> > > >   semantics of RX checksum offload when NIC performs data modification
> > > >   are not clear and subject to change.
> > >
> > > when host is consuming the tcp stream I don't see the value of
> > > tcp checksum on top tls.
> > > In that sense CHECKSUM_UNNECESSARY is fine and no
> > > need to update checksum field.
> > > Even in case of sockmap and tcp stream redirect it is still fine.
> > > Only the tcp payload being redirected to a different tcp socket
> > > and the headers are gone.
> > > So imo in all cases CHECKSUM_UNNECESSARY is fine
> > > even without adjustment to checksum field.
> >
> > No question that CHECKSUM_UNNECESSARY currently works.
> > But it's not "entirely" correct without the header fixup?
> > Device modifies the data - it should fix up the checksum.
>
> I think it's an interesting angle to discuss.
> Though ktls in hw is done per packet many key fields of ip/tcp headers
> are fully processed.

Checksum has been validated, 5-tuple extracted and sequence number
confirmed.  That's not that much, aRFS will do most of it.

> socket is selected and payload is decrypted.

To be clear socket is not assigned to the skb by the offload today.

I only realized it after replying to your other statements but the key
is that the device and the kernel are still tightly coupled by the
decrypted bit set in the descriptor and then the skb.  So there is no
wire-level middlebox going on here.

> imo it is better to state that such headers have been 'consumed' by hw.
> Where 'consumed' would mean that hw did what network layering suppose to do
> and the stack should not look at them (because they can contain garbage).
> (in that sense it's fine to keep csum unadjusted. imo it's ok to zero-out IP too)
> Such decrypted skb is essentially a wrapper of payload plus
> left-over headers passed to the stack.

Expressing that cleanly in terms of sk_buff fields seems hard.  We
could add another checksum bit to denote CHECKSUM_BROKEN_BUT_OKAY,
if we really need it (today as stated for TCP streams UNNECESSARY
works with mangled csums).

> I think it makes sense to clarify which headers have been consumed/processed.
> Like: IP4/6+protocol+port+csum - processed, whereas
> tcp bits, dscp, ecn are still valid and have to be processed by the stack.

Invalidating the 5 tuple on the packet seems like a step backward,
the stack would no longer have the ability to match the packets based
on header fields for firewalling, accounting, whatnot.

> > I was trying (unsuccessfully) to hint at the fact that it's okay
> > today to leave the checksum be, but at the same time if someone
> > is designing new HW or has the ability to fix this up in microcode
> > I think the TCP csum should be fixed..
>
> I don't think so. hw should work together with the stack
> instead of being 'inline transparent decryption box'.

I'd rather not extend socket handling into the firmware.  I'm hoping
that a narrower interface (checksum bit + decrypted bit) will give more
independence to the stack, and I see no negative implications for the
the firmware (negative in the sense we don't have to trust and be bound
by it).

> If hw decrypts stuff and adjusts csum it would imply that stack
> will see completely valid headers. It would also imply that
> the stack must check csum.

What's wrong with the checksum being fixed up after data gets processed?
It's not that the stack _must_ check the checksum, it's that the stack
_may_ reasonably look at that field - CHECKSUM_UNNECESSARY.

> That doesn't seem right from trust point of view.

Please clarify where the trust problem is.  The processed packet still
has to come with a "decrypted" metadata indication (which we'll
translated into skb->decrypted), so it's still necessarily a tightly
coupled interface.


> >
> > Maybe like this?
> >
> >   The preferred method of reporting the Layer 4 (TCP) checksum offload
> >   for packets decrypted by the device is to update the checksum field
> >   to the correct value for clear text and report CHECKSUM_UNNECESSARY
> >   or CHECKSUM_COMPLETE computed over clear text.
> >
> >   Some existing devices may report CHECKSUM_UNNECESSARY without fixing
> >   the checksum field, which currently functions correctly but is not
> >   in line with the exact semantics of RX checksum offload. Such devices
> >   must make sure that RXCSUM offload is always enabled for TLS offloaded
> >   flows.
>
> I don't like it for the reasons above.
>
> > > Obviously the hw/firmware should have checked tcp csum before doing decrypt.
> >
> > Ah, that is definitely worth stating, will add!

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Alexei Starovoitov]

On Thu, May 16, 2019 at 02:39:03PM -0700, Jakub Kicinski wrote:
> On Thu, 16 May 2019 12:32:59 -0700, Alexei Starovoitov wrote:
> > On Thu, May 16, 2019 at 11:42:03AM -0700, Jakub Kicinski wrote:
> > > On Thu, 16 May 2019 11:13:47 -0700, Alexei Starovoitov wrote:
> > > > On Thu, May 16, 2019 at 10:57 AM Jakub Kicinski wrote:
> > > > >
> > > > >   The preferred method of reporting the Layer 4 (TCP) checksum offload
> > > > >   for packets decrypted by the device is to update the checksum field
> > > > >   to the correct value for clear text and report CHECKSUM_UNNECESSARY
> > > > >   or CHECKSUM_COMPLETE computed over clear text. However, the exact
> > > > >   semantics of RX checksum offload when NIC performs data modification
> > > > >   are not clear and subject to change.
> > > >
> > > > when host is consuming the tcp stream I don't see the value of
> > > > tcp checksum on top tls.
> > > > In that sense CHECKSUM_UNNECESSARY is fine and no
> > > > need to update checksum field.
> > > > Even in case of sockmap and tcp stream redirect it is still fine.
> > > > Only the tcp payload being redirected to a different tcp socket
> > > > and the headers are gone.
> > > > So imo in all cases CHECKSUM_UNNECESSARY is fine
> > > > even without adjustment to checksum field.
> > >
> > > No question that CHECKSUM_UNNECESSARY currently works.
> > > But it's not "entirely" correct without the header fixup?
> > > Device modifies the data - it should fix up the checksum.
> >
> > I think it's an interesting angle to discuss.
> > Though ktls in hw is done per packet many key fields of ip/tcp headers
> > are fully processed.
> 
> Checksum has been validated, 5-tuple extracted and sequence number
> confirmed.  That's not that much, aRFS will do most of it.
> 
> > socket is selected and payload is decrypted.
> 
> To be clear socket is not assigned to the skb by the offload today.

but it can cause issues...
if anything after driver tweaks ip header the decrypted payload will go
into wrong socket ?

> I only realized it after replying to your other statements but the key
> is that the device and the kernel are still tightly coupled by the
> decrypted bit set in the descriptor and then the skb.  So there is no
> wire-level middlebox going on here.
> 
> > imo it is better to state that such headers have been 'consumed' by hw.
> > Where 'consumed' would mean that hw did what network layering suppose to do
> > and the stack should not look at them (because they can contain garbage).
> > (in that sense it's fine to keep csum unadjusted. imo it's ok to zero-out IP too)
> > Such decrypted skb is essentially a wrapper of payload plus
> > left-over headers passed to the stack.
> 
> Expressing that cleanly in terms of sk_buff fields seems hard.  We
> could add another checksum bit to denote CHECKSUM_BROKEN_BUT_OKAY,
> if we really need it (today as stated for TCP streams UNNECESSARY
> works with mangled csums).

I'm not proposing any new skb fields.
Only to document what fields were consumed by hw and should not be
touched by the stack before skb reaches the user.
If it helps I'm proposing a pseudo flag on a tcp socket that it's
being ktls offloaded and care should be taken.

> 
> > I think it makes sense to clarify which headers have been consumed/processed.
> > Like: IP4/6+protocol+port+csum - processed, whereas
> > tcp bits, dscp, ecn are still valid and have to be processed by the stack.
> 
> Invalidating the 5 tuple on the packet seems like a step backward,
> the stack would no longer have the ability to match the packets based
> on header fields for firewalling, accounting, whatnot.

good point. IP needs to be preserved for lookup purpose,
but not for rewriting.
The fields that were not 'consumed' during ktls offload
can be mangled by the stack.

> 
> > > I was trying (unsuccessfully) to hint at the fact that it's okay
> > > today to leave the checksum be, but at the same time if someone
> > > is designing new HW or has the ability to fix this up in microcode
> > > I think the TCP csum should be fixed..
> >
> > I don't think so. hw should work together with the stack
> > instead of being 'inline transparent decryption box'.
> 
> I'd rather not extend socket handling into the firmware.  I'm hoping
> that a narrower interface (checksum bit + decrypted bit) will give more
> independence to the stack, and I see no negative implications for the
> the firmware (negative in the sense we don't have to trust and be bound
> by it).
> 
> > If hw decrypts stuff and adjusts csum it would imply that stack
> > will see completely valid headers. It would also imply that
> > the stack must check csum.
> 
> What's wrong with the checksum being fixed up after data gets processed?
> It's not that the stack _must_ check the checksum, it's that the stack
> _may_ reasonably look at that field - CHECKSUM_UNNECESSARY.

because it makes an illusion that the stack sees a valid tcp stream.
But it is not. Arbitrary changes no longer allowed.
The set of decrypted skbs must belong only to the socket that has ktls on
and being offloaded.

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Jakub Kicinski]

On Thu, 16 May 2019 15:52:58 -0700, Alexei Starovoitov wrote:
> On Thu, May 16, 2019 at 02:39:03PM -0700, Jakub Kicinski wrote:
> > On Thu, 16 May 2019 12:32:59 -0700, Alexei Starovoitov wrote:  
> > > On Thu, May 16, 2019 at 11:42:03AM -0700, Jakub Kicinski wrote:  
> > > > On Thu, 16 May 2019 11:13:47 -0700, Alexei Starovoitov wrote:  
> > > > > On Thu, May 16, 2019 at 10:57 AM Jakub Kicinski wrote:  
> > > > > >
> > > > > >   The preferred method of reporting the Layer 4 (TCP) checksum offload
> > > > > >   for packets decrypted by the device is to update the checksum field
> > > > > >   to the correct value for clear text and report CHECKSUM_UNNECESSARY
> > > > > >   or CHECKSUM_COMPLETE computed over clear text. However, the exact
> > > > > >   semantics of RX checksum offload when NIC performs data modification
> > > > > >   are not clear and subject to change.  
> > > > >
> > > > > when host is consuming the tcp stream I don't see the value of
> > > > > tcp checksum on top tls.
> > > > > In that sense CHECKSUM_UNNECESSARY is fine and no
> > > > > need to update checksum field.
> > > > > Even in case of sockmap and tcp stream redirect it is still fine.
> > > > > Only the tcp payload being redirected to a different tcp socket
> > > > > and the headers are gone.
> > > > > So imo in all cases CHECKSUM_UNNECESSARY is fine
> > > > > even without adjustment to checksum field.  
> > > >
> > > > No question that CHECKSUM_UNNECESSARY currently works.
> > > > But it's not "entirely" correct without the header fixup?
> > > > Device modifies the data - it should fix up the checksum.  
> > >
> > > I think it's an interesting angle to discuss.
> > > Though ktls in hw is done per packet many key fields of ip/tcp headers
> > > are fully processed.  
> > 
> > Checksum has been validated, 5-tuple extracted and sequence number
> > confirmed.  That's not that much, aRFS will do most of it.
> >   
> > > socket is selected and payload is decrypted.  
> > 
> > To be clear socket is not assigned to the skb by the offload today.  
> 
> but it can cause issues...
> if anything after driver tweaks ip header the decrypted payload will go
> into wrong socket ?

Yes :(  Going to the wrong socket is king of a less bad version 
of leaving the box due to forwarding or redirect :S

> > I only realized it after replying to your other statements but the key
> > is that the device and the kernel are still tightly coupled by the
> > decrypted bit set in the descriptor and then the skb.  So there is no
> > wire-level middlebox going on here.
> >   
> > > imo it is better to state that such headers have been 'consumed' by hw.
> > > Where 'consumed' would mean that hw did what network layering suppose to do
> > > and the stack should not look at them (because they can contain garbage).
> > > (in that sense it's fine to keep csum unadjusted. imo it's ok to zero-out IP too)
> > > Such decrypted skb is essentially a wrapper of payload plus
> > > left-over headers passed to the stack.  
> > 
> > Expressing that cleanly in terms of sk_buff fields seems hard.  We
> > could add another checksum bit to denote CHECKSUM_BROKEN_BUT_OKAY,
> > if we really need it (today as stated for TCP streams UNNECESSARY
> > works with mangled csums).  
> 
> I'm not proposing any new skb fields.
> Only to document what fields were consumed by hw and should not be
> touched by the stack before skb reaches the user.
> If it helps I'm proposing a pseudo flag on a tcp socket that it's
> being ktls offloaded and care should be taken.

That should be doable.  IIUC we would use skb->sk but we would still
need an skb field to indicate that the sk is assigned on ingress/early
demux rather than for a TX skb (skb_orphan() handling would be
different for RX vs TX).

> > > I think it makes sense to clarify which headers have been consumed/processed.
> > > Like: IP4/6+protocol+port+csum - processed, whereas
> > > tcp bits, dscp, ecn are still valid and have to be processed by the stack.  
> > 
> > Invalidating the 5 tuple on the packet seems like a step backward,
> > the stack would no longer have the ability to match the packets based
> > on header fields for firewalling, accounting, whatnot.  
> 
> good point. IP needs to be preserved for lookup purpose,
> but not for rewriting.
> The fields that were not 'consumed' during ktls offload
> can be mangled by the stack.
> 
> > > > I was trying (unsuccessfully) to hint at the fact that it's okay
> > > > today to leave the checksum be, but at the same time if someone
> > > > is designing new HW or has the ability to fix this up in microcode
> > > > I think the TCP csum should be fixed..  
> > >
> > > I don't think so. hw should work together with the stack
> > > instead of being 'inline transparent decryption box'.  
> > 
> > I'd rather not extend socket handling into the firmware.  I'm hoping
> > that a narrower interface (checksum bit + decrypted bit) will give more
> > independence to the stack, and I see no negative implications for the
> > the firmware (negative in the sense we don't have to trust and be bound
> > by it).
> >   
> > > If hw decrypts stuff and adjusts csum it would imply that stack
> > > will see completely valid headers. It would also imply that
> > > the stack must check csum.  
> > 
> > What's wrong with the checksum being fixed up after data gets processed?
> > It's not that the stack _must_ check the checksum, it's that the stack
> > _may_ reasonably look at that field - CHECKSUM_UNNECESSARY.  
> 
> because it makes an illusion that the stack sees a valid tcp stream.
> But it is not. Arbitrary changes no longer allowed.
> The set of decrypted skbs must belong only to the socket that has ktls on
> and being offloaded.

Agreed, in valid operation the skb must hit its respective socket,
otherwise things will fall apart.  What remains to be figured out 
is how do we achieve that.  The biggest obstacle is probably getting
orphan_skb() to take appropriate action. void skb_orphan()...

Back to the csum - there is perhaps a slight conflict between offload
semantics here.  IIUC checksum offload mandates that the device passes 
a mere hint, the headers remain valid, and are not overwritten (so the
stack can look at them if it wants).  TLS offload makes csum invalid
so we either have to break the "must remain valid" rule, or the "must
not be overwritten" rule.  I think the first one is more important.

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Boris Pismenny]

On 5/16/2019 8:56 PM, Jakub Kicinski wrote:
> On Thu, 16 May 2019 09:08:52 +0000, Boris Pismenny wrote:
>>> diff --git a/Documentation/networking/tls-offload.rst b/Documentation/networking/tls-offload.rst
>>> new file mode 100644
>>> index 000000000000..32fecb3fbc4c
>>> --- /dev/null
>>> +++ b/Documentation/networking/tls-offload.rst
>>> @@ -0,0 +1,438 @@

>>> +RX
>>> +--
>>> +
>>> +Before a packet is DMAed to the host (but after NIC's embedded switching
>>> +and packet transformation functions) the device performs a 5-tuple lookup
>>> +to find any TLS connection the packet may belong to (technically a 4-tuple
>>> +lookup is sufficient - IP addresses and TCP port numbers, as the protocol
>>> +is always TCP). If connection is matched device confirms if the TCP sequence
>>> +number is the expected one and proceeds to TLS handling (record delineation,
>>> +decryption, authentication for each record in the packet).
>>> +
>>> +If decryption or authentication fails for any record in the packet, the packet
>>> +must be passed to the host as it was received on the wire. This means packets
>>
>> This is not normal mode of operation, but rather an error handling
>> description. Please try to describe only the good flow here, and leave
>> the errors for a separate section.
> 
> Normal as device is in sync with the stream vs the Resync handling
> section.  It is not clear from the name, you're right, I will try
> to split further and see how it turns out.
> 

But it is not normal, as decryption or authentication failure are not 
normal. Such a packet is bound to terminate the TLS connection and 
forcing hardware to re-encrypt it is too strict IMO. Instead, I think 
that as long as the driver can provide the stack with the original 
packet in this case, then it is good enough.

>>> +should not be modified "in place". Splitting segments to handle partial
>>> +decryption is not advised. In other words either all records in the packet
>>> +had been handled successfully and authenticated or the packet has to be passed
>>> +to the host as it was on the wire. The device communicates whether the packet
>>> +was successfully decrypted in the per-packet context (descriptor) passed
>>> +to the host.
>>> +
>>> +The device leaves the record framing unmodified, the stack takes care of
>>> +record decapsulation.
>>> +
>>> +Upon reception of a TLS offloaded packet, the driver sets
>>> +the :c:member:`decrypted` mark in :c:type:`struct sk_buff <sk_buff>`
>>> +corresponding to the segment. Networking stack makes sure decrypted
>>> +and non-decrypted segments do not get coalesced and takes care of partial
>>> +decryption.
>>
>> Please mention checksum handling as well. It would not make any sense to
>> use CHECKSUM_COMPLETE here. Instead, CHECKSUM_UNNECESSARY should be
>> expected.
> 
> I was on the fence about adding the checksum info.  I had the feeling
> that even for CHECKSUM_UNNECESSARY it's fairly strange to pass mangled
> packets.  Looking at skbuff.h the checksum doc states:
> 
>   * CHECKSUM_UNNECESSARY:
>   *
>   *   The hardware you're dealing with doesn't calculate the full checksum
>   *   (as in CHECKSUM_COMPLETE), but it does parse headers and verify checksums
>   *   for specific protocols. For such packets it will set CHECKSUM_UNNECESSARY
>   *   if their checksums are okay. skb->csum is still undefined in this case
>   *   though. A driver or device must never modify the checksum field in the
>   *   packet even if checksum is verified.
> 
> My reading of the last sentence is: the checksum in the packet must
> still be correct (based on the context in which this comment was
> written, which was in the days of UDP tunnel offload work).
> IOW UNNECESSARY doesn't mean "don't look at the checksum field",
> it means "I've looked at the checksum field and it's correct".
> 

This interpretation is far from the text - "A driver or device must 
never modify the checksum field". If it is correct, then it needs to be 
fixed. Moreover, one could consider the checksum field to be correct, 
because the encryption can be reverted by the socket/driver on demand.

AFAIU, CHECKSUM_UNNECESSARY is exactly for cases like this, where the 
hardware might have mangled the known payload/headers. But it verified 
the checksum before doing so. As a result, checksum fields might be 
wrong (but unmodified), and setting CHECKSUM_UNNECESSARY informs the 
network stack that it can trust this packet.

> IMHO CHECKSUM_UNNECESSARY without correcting the TCP header csum field
> is only slightly less broken than CHECKSUM_COMPLETE with pre-decrypt
> csum and without fixing the TCP header.
> 
> Not to mention the fact that users may disable RXCSUM offload.

It does not matter if the user disables RXCSUM, because the HW *must* do 
checksum validation for TLS Rx offload regardless of this setting.

> 
> Maybe the least broken option is to fix the TCP header csum and pass
> CHECKSUM_COMPLETE of the encrypted data?  But then again clearly the HW
> has parsed the packet (voiding the non-ossification gain), and we won't
> be doing tunnelling on clear text..

I don't see the point of doing this. TLS Rx offload is for L4 
*endpoints*, not for L3 routers. As such, the socket will receive the 
packet and process it as part of a TCP stream, thereafter the data can 
be forwarded.
The socket must perform the TCP checksum verification, and 
CHECKSUM_UNNECESSARY makes all of this work without complex changes.

> 
> So CHECKSUM_UNNECESSARY "would do".
> 
> This is a long winded way of saying - I didn't see the perfect solution
> here, so I thought it's better not to codify it in this doc.  But
> perhaps I can phrase it tentatively enough.  How about:
> 
> 
>    The preferred method of reporting the Layer 4 (TCP) checksum offload
>    for packets decrypted by the device is to update the checksum field
>    to the correct value for clear text and report CHECKSUM_UNNECESSARY
>    or CHECKSUM_COMPLETE computed over clear text. However, the exact
>    semantics of RX checksum offload when NIC performs data modification
>    are not clear and subject to change.
> 

I disagree with this. Modifying the original checksum field erases the 
original checksum, which might not be recoverable later.

Re: [PATCH net 3/3] Documentation: add TLS offload documentation

[Jakub Kicinski]

On Sun, 19 May 2019 06:24:36 +0000, Boris Pismenny wrote:
> On 5/16/2019 8:56 PM, Jakub Kicinski wrote:
> > On Thu, 16 May 2019 09:08:52 +0000, Boris Pismenny wrote:  
> >>> diff --git a/Documentation/networking/tls-offload.rst b/Documentation/networking/tls-offload.rst
> >>> new file mode 100644
> >>> index 000000000000..32fecb3fbc4c
> >>> --- /dev/null
> >>> +++ b/Documentation/networking/tls-offload.rst
> >>> @@ -0,0 +1,438 @@  
> 
> >>> +RX
> >>> +--
> >>> +
> >>> +Before a packet is DMAed to the host (but after NIC's embedded switching
> >>> +and packet transformation functions) the device performs a 5-tuple lookup
> >>> +to find any TLS connection the packet may belong to (technically a 4-tuple
> >>> +lookup is sufficient - IP addresses and TCP port numbers, as the protocol
> >>> +is always TCP). If connection is matched device confirms if the TCP sequence
> >>> +number is the expected one and proceeds to TLS handling (record delineation,
> >>> +decryption, authentication for each record in the packet).
> >>> +
> >>> +If decryption or authentication fails for any record in the packet, the packet
> >>> +must be passed to the host as it was received on the wire. This means packets  
> >>
> >> This is not normal mode of operation, but rather an error handling
> >> description. Please try to describe only the good flow here, and leave
> >> the errors for a separate section.  
> > 
> > Normal as device is in sync with the stream vs the Resync handling
> > section.  It is not clear from the name, you're right, I will try
> > to split further and see how it turns out.
> 
> But it is not normal, as decryption or authentication failure are not
> normal. Such a packet is bound to terminate the TLS connection and
> forcing hardware to re-encrypt it is too strict IMO. Instead, I think
> that as long as the driver can provide the stack with the original
> packet in this case, then it is good enough.

Sure, you can try to recover original packet in the driver, if device
provides you with precise enough information (remember there can be
multiple records in a segment).

> >>> +should not be modified "in place". Splitting segments to handle partial
> >>> +decryption is not advised. In other words either all records in the packet
> >>> +had been handled successfully and authenticated or the packet has to be passed
> >>> +to the host as it was on the wire. The device communicates whether the packet
> >>> +was successfully decrypted in the per-packet context (descriptor) passed
> >>> +to the host.
> >>> +
> >>> +The device leaves the record framing unmodified, the stack takes care of
> >>> +record decapsulation.
> >>> +
> >>> +Upon reception of a TLS offloaded packet, the driver sets
> >>> +the :c:member:`decrypted` mark in :c:type:`struct sk_buff <sk_buff>`
> >>> +corresponding to the segment. Networking stack makes sure decrypted
> >>> +and non-decrypted segments do not get coalesced and takes care of partial
> >>> +decryption.  
> >>
> >> Please mention checksum handling as well. It would not make any sense to
> >> use CHECKSUM_COMPLETE here. Instead, CHECKSUM_UNNECESSARY should be
> >> expected.  
> > 
> > I was on the fence about adding the checksum info.  I had the feeling
> > that even for CHECKSUM_UNNECESSARY it's fairly strange to pass mangled
> > packets.  Looking at skbuff.h the checksum doc states:
> > 
> >   * CHECKSUM_UNNECESSARY:
> >   *
> >   *   The hardware you're dealing with doesn't calculate the full checksum
> >   *   (as in CHECKSUM_COMPLETE), but it does parse headers and verify checksums
> >   *   for specific protocols. For such packets it will set CHECKSUM_UNNECESSARY
> >   *   if their checksums are okay. skb->csum is still undefined in this case
> >   *   though. A driver or device must never modify the checksum field in the
> >   *   packet even if checksum is verified.
> > 
> > My reading of the last sentence is: the checksum in the packet must
> > still be correct (based on the context in which this comment was
> > written, which was in the days of UDP tunnel offload work).
> > IOW UNNECESSARY doesn't mean "don't look at the checksum field",
> > it means "I've looked at the checksum field and it's correct".
> >   
> 
> This interpretation is far from the text - "A driver or device must 
> never modify the checksum field". If it is correct, then it needs to be 
> fixed. 

Context in which these words were written matters.

> Moreover, one could consider the checksum field to be correct,
> because the encryption can be reverted by the socket/driver on demand.

Sockets (and ULPs) are above TCP checksums.

> AFAIU, CHECKSUM_UNNECESSARY is exactly for cases like this, where the 
> hardware might have mangled the known payload/headers. But it verified 
> the checksum before doing so. As a result, checksum fields might be 
> wrong (but unmodified), and setting CHECKSUM_UNNECESSARY informs the 
> network stack that it can trust this packet.

If I redirect a packet with CHECKSUM_UNNECESSARY it goes out as is, no
checksum recalculation.  The checksum should be valid.

> > IMHO CHECKSUM_UNNECESSARY without correcting the TCP header csum field
> > is only slightly less broken than CHECKSUM_COMPLETE with pre-decrypt
> > csum and without fixing the TCP header.
> > 
> > Not to mention the fact that users may disable RXCSUM offload.  
> 
> It does not matter if the user disables RXCSUM, because the HW *must* do 
> checksum validation for TLS Rx offload regardless of this setting.

Yes, that's what I'm saying, regardless of RXCSUM setting HW has
to do validation, and in case driver is passing frames with a broken
checksum driver has to feed CHECKSUM_UNNECESSARY to the stack, again,
regardless of RXCSUM.

> > Maybe the least broken option is to fix the TCP header csum and pass
> > CHECKSUM_COMPLETE of the encrypted data?  But then again clearly the HW
> > has parsed the packet (voiding the non-ossification gain), and we won't
> > be doing tunnelling on clear text..  
> 
> I don't see the point of doing this. TLS Rx offload is for L4 
> *endpoints*, not for L3 routers. As such, the socket will receive the 
> packet and process it as part of a TCP stream, thereafter the data can 
> be forwarded.
> The socket must perform the TCP checksum verification, and 
> CHECKSUM_UNNECESSARY makes all of this work without complex changes.

Yes, as I said it works today.  But I'm not documenting stuff that
happens to work today as the way things should be.  There are routable
L4 data modifications which _have to_ fix the checksum (tunnels).
I strongly prefer to have the devices behave the same for all L4 data
modification, instead of trying to define this behaviour on offload by
offload bases.  I only leads to confusion and conflicts when two
offloads are in effect and have different expected behaviour.

> > 
> > So CHECKSUM_UNNECESSARY "would do".
> > 
> > This is a long winded way of saying - I didn't see the perfect solution
> > here, so I thought it's better not to codify it in this doc.  But
> > perhaps I can phrase it tentatively enough.  How about:
> > 
> > 
> >    The preferred method of reporting the Layer 4 (TCP) checksum offload
> >    for packets decrypted by the device is to update the checksum field
> >    to the correct value for clear text and report CHECKSUM_UNNECESSARY
> >    or CHECKSUM_COMPLETE computed over clear text. However, the exact
> >    semantics of RX checksum offload when NIC performs data modification
> >    are not clear and subject to change.
> >   
> 
> I disagree with this. Modifying the original checksum field erases the 
> original checksum, which might not be recoverable later.

Checksum covers the data in the packet, if it was valid on arrival to
the device, and was recalculated to match the modified data - what do
you want to recover and to what end?