Lines Matching +full:software +full:- +full:driver
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
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
30 NIC driver and firmware replace the kernel networking stack
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 --
47 Instead packets reach a device driver, the driver will mark the packets
52 --
55 successfully, the driver will set the decrypted bit in the associated
61 otherwise software path handles decryption.
63 .. kernel-figure:: tls-offload-layers.svg
73 During driver initialization device sets the ``NETIF_F_HW_TLS_RX`` and
82 network device is offload-capable and attempts the offload. In case offload
83 fails the connection is handled entirely in software using the same mechanism
89 .. code-block:: c
97 the received or transmitted packets. Driver uses the ``sk`` parameter
98 to retrieve the connection 5-tuple and socket family (IPv4 vs IPv6).
102 sequence number from ``crypto_info``. The driver can add its state
108 --
115 through the driver and which belong to the offloaded socket will be after
121 --
142 to be possible, the device has to keep a small amount of segment-to-segment
155 --
160 Both the device and the driver maintain expected TCP sequence numbers
161 due to the possibility of retransmissions and the lack of software fallback
163 For segments passed in order, the driver marks the packets with
164 a connection identifier (note that a 5-tuple lookup is insufficient to identify
172 --
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
184 per-packet context (descriptor) passed to the host.
186 Upon reception of a TLS offloaded packet, the driver sets
189 and non-decrypted segments do not get coalesced (e.g. by GRO or socket layer)
206 --
209 in similar ways to the receive side-retransmissions - local drops
216 Whenever an out of order segment is transmitted the driver provides
225 In this mode depending on the implementation the driver can either ask
228 with the previous stream state - assuming that the out of order segment
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
238 sequence number is lower than expected the driver assumes retransmission
240 may imply a local drop, the driver asks the stack to sync the device
241 to the next record state and falls back to software.
245 .. code-block:: c
249 Until resync is complete driver should not access its expected TCP
253 .. code-block:: c
258 and TLS record number to the driver. Stack will also make sure that
263 --
269 .. kernel-figure:: tls-offload-reorder-good.svg
270 :alt: reorder of non-header segment
273 Reorder of non-header segment
287 handling. ``ktls`` software fallback handles the decryption of record
294 .. kernel-figure:: tls-offload-reorder-bad.svg
323 and counting all records since the just-confirmed one, it adds the number
331 restart scan. Given how unlikely falsely-matching stream is, however,
338 Stack-driven resynchronization
341 The driver may also request the stack to perform resynchronization
358 --
366 by software fallback.
374 --
381 result in passing the unmodified packet to the software fallback. This means
386 driver if device provides precise error is sufficient).
388 The Linux networking stack does not provide a way of reporting per-packet
409 --------------------
415 -------------------------------
420 significant performance impact on non-offloaded streams.
425 Following minimum set of TLS-related statistics should be reported
426 by the driver:
428 * ``rx_tls_decrypted_packets`` - number of successfully decrypted RX packets
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
445 the driver was successfully handled.
446 * ``rx_tls_resync_res_skip`` - number of times the TLS resync response call to
447 the driver was terminated unsuccessfully.
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
465 * ``tx_tls_drop_bypass_req`` - number of TX packets which were part of a TLS
467 software and data that expects hardware crypto offload.
474 5-tuple matching limitations
475 ----------------------------
477 The device can only recognize received packets based on the 5-tuple
479 routed through software interfaces such as those used for tunneling
482 any intermediate software device, therefore a 5-tuple match may
485 fallback cleanly to software decryption (RX).
488 ------------
495 ---------------
502 -----------------------------------------------------
509 ----------------------------
518 -------------
526 -------------------
538 Similarly, device-offloaded TLS decryption implies doing RXCSUM. If the user