Lines Matching +full:segment +full:- +full:1 +full:a
1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
10 Linux kernel provides TLS connection offload infrastructure. Once a TCP
13 For details regarding the user-facing interface refer to the TLS
18 * Software crypto mode (``TLS_SW``) - CPU handles the cryptography.
22 latency on socket reads (decryption only starts when a read syscall
24 * Packet-based NIC offload mode (``TLS_HW``) - the NIC handles crypto
25 on a packet by packet basis, provided the packets arrive in order.
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 --
41 At a high level user write requests are turned into a scatter list, the TLS ULP
47 Instead packets reach a device driver, the driver will mark the packets
52 --
63 .. kernel-figure:: tls-offload-layers.svg
79 When TLS cryptographic connection state is installed on a ``ktls`` socket
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 --
110 After TX state is installed, the stack guarantees that the first segment
121 --
125 inside the segment.
139 segments may start at any point of a record and contain any number of records.
142 to be possible, the device has to keep a small amount of segment-to-segment
145 * partial headers (if a segment carried only a part of the TLS header)
148 authentication tag has to be written or read from the subsequent segment)
155 --
164 a connection identifier (note that a 5-tuple lookup is insufficient to identify
172 --
174 Before a packet is DMAed to the host (but after NIC's embedded switching
176 checksum and performs a 5-tuple lookup to find any TLS connection the packet
177 may belong to (technically a 4-tuple
178 lookup is sufficient - IP addresses and TCP port numbers, as the protocol
179 is always TCP). If the packet is matched to a connection, the device confirms
184 per-packet context (descriptor) passed to the host.
186 Upon reception of a TLS offloaded packet, the driver sets
188 corresponding to the segment. Networking stack makes sure decrypted
189 and non-decrypted segments do not get coalesced (e.g. by GRO or socket layer)
196 synchronization with the TLS stream, and require a resync with the kernel's
206 --
209 in similar ways to the receive side-retransmissions - local drops
216 Whenever an out of order segment is transmitted the driver provides
219 segment has to be passed to the device as part of the packet context,
226 for a continuation with the crypto state and the new sequence number
227 (next expected segment is the one after the out of order one), or continue
228 with the previous stream state - assuming that the out of order segment
229 was just a retransmission. The former is simpler, and does not require
236 Whenever an out of order segment is detected the driver requests
237 that the ``ktls`` software fallback code encrypt it. If the segment's
239 and doesn't change device state. If the segment is in the future, it
240 may imply a local drop, the driver asks the stack to sync the device
245 .. code-block:: c
250 sequence number (as it will be updated from a different context).
253 .. code-block:: c
257 Next time ``ktls`` pushes a record it will first send its TCP sequence number
259 the new record will start on a segment boundary (like it does when
263 --
265 A small amount of RX reorder events may not require a full resynchronization.
269 .. kernel-figure:: tls-offload-reorder-good.svg
270 :alt: reorder of non-header segment
273 Reorder of non-header segment
278 In above case segment 1 is received and decrypted successfully.
279 Segment 2 was dropped so 3 arrives out of order. The device knows
280 the next record starts inside 3, based on record length in segment 1.
281 Segment 3 is passed untouched, because due to lack of data from segment 2
282 the remainder of the previous record inside segment 3 cannot be handled.
284 and partial block from the new record in segment 3 and when 4 and 5
288 spanning segments 1, 2 and 3. The device did not get out of sync,
291 Kernel synchronization may be necessary if the lost segment contained
292 a record header and arrived after the next record header has already passed:
294 .. kernel-figure:: tls-offload-reorder-bad.svg
295 :alt: reorder of header segment
298 Reorder of segment with a TLS header
300 In this example segment 2 gets dropped, and it contains a record header.
301 Device can only detect that segment 4 also contains a TLS header
302 if it knows the length of the previous record from segment 2. In this case
309 numbers more than a max size record past the expected TCP sequence number,
310 the device starts scanning for a known header pattern. For example
315 Whenever the expected location does not contain a valid header the scan
318 When the header is matched the device sends a confirmation request
319 to the kernel, asking if the guessed location is correct (if a TLS record
323 and counting all records since the just-confirmed one, it adds the number
326 segment boundary.
328 In a pathological case the device may latch onto a sequence of matching
331 restart scan. Given how unlikely falsely-matching stream is, however,
338 Stack-driven resynchronization
358 --
360 Packets may be redirected or rerouted by the stack to a different
369 in the packet being dropped. For example if a packet got out of order
370 due to a bug in the stack or the device, reached the device and can't
374 --
380 For example authentication failure for any record in the segment should
388 The Linux networking stack does not provide a way of reporting per-packet
392 A packet should also not be handled by the TLS offload if it contains
405 Note that each TCP connection requires a TLS session in both directions,
409 --------------------
415 -------------------------------
417 Offload performance may depend on segment and record size.
420 significant performance impact on non-offloaded streams.
425 Following minimum set of TLS-related statistics should be reported
428 * ``rx_tls_decrypted_packets`` - number of successfully decrypted RX packets
429 which were part of a TLS stream.
430 * ``rx_tls_decrypted_bytes`` - number of TLS payload bytes in RX packets
432 * ``rx_tls_ctx`` - number of TLS RX HW offload contexts added to device for
434 * ``rx_tls_del`` - number of TLS RX HW offload contexts deleted from device
436 * ``rx_tls_resync_req_pkt`` - number of received TLS packets with a resync
438 * ``rx_tls_resync_req_start`` - number of times the TLS async resync request
440 * ``rx_tls_resync_req_end`` - number of times the TLS async resync request
441 properly ended with providing the HW tracked tcp-seq.
442 * ``rx_tls_resync_req_skip`` - number of times the TLS async resync request
444 * ``rx_tls_resync_res_ok`` - number of times the TLS resync response call to
446 * ``rx_tls_resync_res_skip`` - number of times the TLS resync response call to
448 * ``rx_tls_err`` - number of RX packets which were part of a TLS stream
450 * ``tx_tls_encrypted_packets`` - number of TX packets passed to the device
452 * ``tx_tls_encrypted_bytes`` - number of TLS payload bytes in TX packets
454 * ``tx_tls_ctx`` - number of TLS TX HW offload contexts added to device for
456 * ``tx_tls_ooo`` - number of TX packets which were part of a TLS stream
458 * ``tx_tls_skip_no_sync_data`` - number of TX packets which were part of
459 a TLS stream and arrived out-of-order, but skipped the HW offload routine
462 * ``tx_tls_drop_no_sync_data`` - number of TX packets which were part of
463 a TLS stream dropped, because they arrived out of order and associated
465 * ``tx_tls_drop_bypass_req`` - number of TX packets which were part of a TLS
474 5-tuple matching limitations
475 ----------------------------
477 The device can only recognize received packets based on the 5-tuple
482 any intermediate software device, therefore a 5-tuple match may
488 ------------
495 ---------------
497 A device is permitted to perform packet reordering for consecutive
502 -----------------------------------------------------
509 ----------------------------
517 Segment drops
518 -------------
526 -------------------
538 Similarly, device-offloaded TLS decryption implies doing RXCSUM. If the user