Documentation/networking/tls-offload.rst

1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
13 For details regarding the user-facing interface refer to the TLS
18  * Software crypto mode (``TLS_SW``) - CPU handles the cryptography.
24  * Packet-based NIC offload mode (``TLS_HW``) - the NIC handles crypto
26    This mode integrates best with the kernel stack and is described in detail
28    (``ethtool`` flags ``tls-hw-tx-offload`` and ``tls-hw-rx-offload``).
29  * Full TCP NIC offload mode (``TLS_HW_RECORD``) - mode of operation where
33    abilities or QoS and packet scheduling (``ethtool`` flag ``tls-hw-record``).
35 The operation mode is selected automatically based on device configuration,
36 offload opt-in or opt-out on per-connection basis is not currently supported.
39 --
43 mode) and then hands the modified scatter list to the TCP layer. From this
46 In ``TLS_HW`` mode the encryption is not performed in the TLS ULP.
52 --
63 .. kernel-figure::  tls-offload-layers.svg
82 network device is offload-capable and attempts the offload. In case offload
89 .. code-block:: c
98 to retrieve the connection 5-tuple and socket family (IPv4 vs IPv6).
108 --
121 --
141 to be possible device has to keep small amount of segment-to-segment state.
154 --
163 a connection identifier (note that a 5-tuple lookup is insufficient to identify
171 --
175 checksum and performs a 5-tuple lookup to find any TLS connection the packet
176 may belong to (technically a 4-tuple
177 lookup is sufficient - IP addresses and TCP port numbers, as the protocol
182 Device indicates successful handling of TLS offload in the per-packet context
188 and non-decrypted segments do not get coalesced (e.g. by GRO or socket layer)
199 added to the device table and are in TLS_HW mode. For example,
205 --
208 in similar ways to the receive side-retransmissions - local drops
224 In this mode depending on the implementation the driver can either ask
227 with the previous stream state - assuming that the out of order segment
244 .. code-block:: c
252 .. code-block:: c
262 --
268 .. kernel-figure::  tls-offload-reorder-good.svg
269    :alt:	reorder of non-header segment
272    Reorder of non-header segment
275 as received on wire, red stripes mark start of new records.
293 .. kernel-figure::  tls-offload-reorder-bad.svg
322 and counting all records since the just-confirmed one, it adds the number
330 restart scan. Given how unlikely falsely-matching stream is, however,
337 Stack-driven resynchronization
342 If the connection is configured in this mode the stack automatically
357 --
373 --
377 received on the wire.
384 to the host's stack as it was on the wire (recovering original packet in the
387 The Linux networking stack does not provide a way of reporting per-packet
408 --------------------
414 -------------------------------
419 significant performance impact on non-offloaded streams.
424 Following minimum set of TLS-related statistics should be reported
427  * ``rx_tls_decrypted_packets`` - number of successfully decrypted RX packets
429  * ``rx_tls_decrypted_bytes`` - number of TLS payload bytes in RX packets
431  * ``rx_tls_ctx`` - number of TLS RX HW offload contexts added to device for
433  * ``rx_tls_del`` - number of TLS RX HW offload contexts deleted from device
435  * ``rx_tls_resync_req_pkt`` - number of received TLS packets with a resync
437  * ``rx_tls_resync_req_start`` - number of times the TLS async resync request
439  * ``rx_tls_resync_req_end`` - number of times the TLS async resync request
440     properly ended with providing the HW tracked tcp-seq.
441  * ``rx_tls_resync_req_skip`` - number of times the TLS async resync request
443  * ``rx_tls_resync_res_ok`` - number of times the TLS resync response call to
445  * ``rx_tls_resync_res_skip`` - number of times the TLS resync response call to
447  * ``rx_tls_err`` - number of RX packets which were part of a TLS stream
449  * ``tx_tls_encrypted_packets`` - number of TX packets passed to the device
451  * ``tx_tls_encrypted_bytes`` - number of TLS payload bytes in TX packets
453  * ``tx_tls_ctx`` - number of TLS TX HW offload contexts added to device for
455  * ``tx_tls_ooo`` - number of TX packets which were part of a TLS stream
457  * ``tx_tls_skip_no_sync_data`` - number of TX packets which were part of
458    a TLS stream and arrived out-of-order, but skipped the HW offload routine
461  * ``tx_tls_drop_no_sync_data`` - number of TX packets which were part of
464  * ``tx_tls_drop_bypass_req`` - number of TX packets which were part of a TLS
473 5-tuple matching limitations
474 ----------------------------
476 The device can only recognize received packets based on the 5-tuple
479 or virtual networking. However, many packet transformations performed
481 any intermediate software device, therefore a 5-tuple match may
487 ------------
494 ---------------
501 -----------------------------------------------------
505 in packets as seen on the wire.
508 ----------------------------
517 -------------
525 -------------------
537 Similarly, device-offloaded TLS decryption implies doing RXCSUM. If the user