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
27    in the remaining part of this document
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``).
36 offload opt-in or opt-out on per-connection basis is not currently supported.
39 --
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).
100 as well as TLS record sequence number. ``start_offload_tcp_sn`` indicates
101 which TCP sequence number corresponds to the beginning of the record with
102 sequence number from ``crypto_info``. The driver can add its state
108 --
112 number, simplifying TCP sequence number matching.
116 the expected sequence number and will have kernel record information.
121 --
124 so the initial records' TCP sequence number may be anywhere inside the segment.
134  * record metadata (sequence number, processing offset and length)
135  * expected TCP sequence number
138 segments may start at any point of a record and contain any number of records.
141 to be possible device has to keep small amount of segment-to-segment state.
144  * partial headers (if a segment carried only a part of the TLS header)
146  * partial authentication tag (all data had been seen but part of the
154 --
163 a connection identifier (note that a 5-tuple lookup is insufficient to identify
166 TLS handling and confirms the sequence number matches its expectation.
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
179 number is the expected one and proceeds to TLS handling (record delineation,
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)
205 --
208 in similar ways to the receive side-retransmissions - local drops
217 This means most likely that the part of the record preceding the current
218 segment has to be passed to the device as part of the packet context,
219 together with its TCP sequence number and TLS record number. The device
225 for a continuation with the crypto state and the new sequence number
227 with the previous stream state - assuming that the out of order segment
237 sequence number is lower than expected the driver assumes retransmission
244 .. code-block:: c
249 sequence number (as it will be updated from a different context).
252 .. code-block:: c
256 Next time ``ktls`` pushes a record it will first send its TCP sequence number
257 and TLS record number to the driver. Stack will also make sure that
262 --
268 .. kernel-figure::  tls-offload-reorder-good.svg
269    :alt:	reorder of non-header segment
272    Reorder of non-header segment
293 .. kernel-figure::  tls-offload-reorder-bad.svg
308 numbers more than a max size record past the expected TCP sequence number,
319 really starts there), and which record sequence number the given header had.
321 the record sequence number. Meanwhile, the device had been parsing
322 and counting all records since the just-confirmed one, it adds the number
323 of records it had seen to the record number provided by the kernel.
330 restart scan. Given how unlikely falsely-matching stream is, however,
337 Stack-driven resynchronization
347 the next expected record number and its TCP sequence number. If the
357 --
373 --
387 The Linux networking stack does not provide a way of reporting per-packet
408 --------------------
410 The number of connections device can support can be exposed via
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
428    which were part of a TLS stream.
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
481 any intermediate software device, therefore a 5-tuple match may
487 ------------
494 ---------------
501 -----------------------------------------------------
508 ----------------------------
517 -------------
525 -------------------
537 Similarly, device-offloaded TLS decryption implies doing RXCSUM. If the user