540 lines · plain
1.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)2 3==================4Kernel TLS offload5==================6 7Kernel TLS operation8====================9 10Linux kernel provides TLS connection offload infrastructure. Once a TCP11connection is in ``ESTABLISHED`` state user space can enable the TLS Upper12Layer Protocol (ULP) and install the cryptographic connection state.13For details regarding the user-facing interface refer to the TLS14documentation in :ref:`Documentation/networking/tls.rst <kernel_tls>`.15 16``ktls`` can operate in three modes:17 18 * Software crypto mode (``TLS_SW``) - CPU handles the cryptography.19 In most basic cases only crypto operations synchronous with the CPU20 can be used, but depending on calling context CPU may utilize21 asynchronous crypto accelerators. The use of accelerators introduces extra22 latency on socket reads (decryption only starts when a read syscall23 is made) and additional I/O load on the system.24 * Packet-based NIC offload mode (``TLS_HW``) - the NIC handles crypto25 on a packet by packet basis, provided the packets arrive in order.26 This mode integrates best with the kernel stack and is described in detail27 in the remaining part of this document28 (``ethtool`` flags ``tls-hw-tx-offload`` and ``tls-hw-rx-offload``).29 * Full TCP NIC offload mode (``TLS_HW_RECORD``) - mode of operation where30 NIC driver and firmware replace the kernel networking stack31 with its own TCP handling, it is not usable in production environments32 making use of the Linux networking stack for example any firewalling33 abilities or QoS and packet scheduling (``ethtool`` flag ``tls-hw-record``).34 35The operation mode is selected automatically based on device configuration,36offload opt-in or opt-out on per-connection basis is not currently supported.37 38TX39--40 41At a high level user write requests are turned into a scatter list, the TLS ULP42intercepts them, inserts record framing, performs encryption (in ``TLS_SW``43mode) and then hands the modified scatter list to the TCP layer. From this44point on the TCP stack proceeds as normal.45 46In ``TLS_HW`` mode the encryption is not performed in the TLS ULP.47Instead packets reach a device driver, the driver will mark the packets48for crypto offload based on the socket the packet is attached to,49and send them to the device for encryption and transmission.50 51RX52--53 54On the receive side if the device handled decryption and authentication55successfully, the driver will set the decrypted bit in the associated56:c:type:`struct sk_buff <sk_buff>`. The packets reach the TCP stack and57are handled normally. ``ktls`` is informed when data is queued to the socket58and the ``strparser`` mechanism is used to delineate the records. Upon read59request, records are retrieved from the socket and passed to decryption routine.60If device decrypted all the segments of the record the decryption is skipped,61otherwise software path handles decryption.62 63.. kernel-figure:: tls-offload-layers.svg64 :alt: TLS offload layers65 :align: center66 :figwidth: 28em67 68 Layers of Kernel TLS stack69 70Device configuration71====================72 73During driver initialization device sets the ``NETIF_F_HW_TLS_RX`` and74``NETIF_F_HW_TLS_TX`` features and installs its75:c:type:`struct tlsdev_ops <tlsdev_ops>`76pointer in the :c:member:`tlsdev_ops` member of the77:c:type:`struct net_device <net_device>`.78 79When TLS cryptographic connection state is installed on a ``ktls`` socket80(note that it is done twice, once for RX and once for TX direction,81and the two are completely independent), the kernel checks if the underlying82network device is offload-capable and attempts the offload. In case offload83fails the connection is handled entirely in software using the same mechanism84as if the offload was never tried.85 86Offload request is performed via the :c:member:`tls_dev_add` callback of87:c:type:`struct tlsdev_ops <tlsdev_ops>`:88 89.. code-block:: c90 91 int (*tls_dev_add)(struct net_device *netdev, struct sock *sk,92 enum tls_offload_ctx_dir direction,93 struct tls_crypto_info *crypto_info,94 u32 start_offload_tcp_sn);95 96``direction`` indicates whether the cryptographic information is for97the received or transmitted packets. Driver uses the ``sk`` parameter98to retrieve the connection 5-tuple and socket family (IPv4 vs IPv6).99Cryptographic information in ``crypto_info`` includes the key, iv, salt100as well as TLS record sequence number. ``start_offload_tcp_sn`` indicates101which TCP sequence number corresponds to the beginning of the record with102sequence number from ``crypto_info``. The driver can add its state103at the end of kernel structures (see :c:member:`driver_state` members104in ``include/net/tls.h``) to avoid additional allocations and pointer105dereferences.106 107TX108--109 110After TX state is installed, the stack guarantees that the first segment111of the stream will start exactly at the ``start_offload_tcp_sn`` sequence112number, simplifying TCP sequence number matching.113 114TX offload being fully initialized does not imply that all segments passing115through the driver and which belong to the offloaded socket will be after116the expected sequence number and will have kernel record information.117In particular, already encrypted data may have been queued to the socket118before installing the connection state in the kernel.119 120RX121--122 123In RX direction local networking stack has little control over the segmentation,124so the initial records' TCP sequence number may be anywhere inside the segment.125 126Normal operation127================128 129At the minimum the device maintains the following state for each connection, in130each direction:131 132 * crypto secrets (key, iv, salt)133 * crypto processing state (partial blocks, partial authentication tag, etc.)134 * record metadata (sequence number, processing offset and length)135 * expected TCP sequence number136 137There are no guarantees on record length or record segmentation. In particular138segments may start at any point of a record and contain any number of records.139Assuming segments are received in order, the device should be able to perform140crypto operations and authentication regardless of segmentation. For this141to be possible device has to keep small amount of segment-to-segment state.142This includes at least:143 144 * partial headers (if a segment carried only a part of the TLS header)145 * partial data block146 * partial authentication tag (all data had been seen but part of the147 authentication tag has to be written or read from the subsequent segment)148 149Record reassembly is not necessary for TLS offload. If the packets arrive150in order the device should be able to handle them separately and make151forward progress.152 153TX154--155 156The kernel stack performs record framing reserving space for the authentication157tag and populating all other TLS header and tailer fields.158 159Both the device and the driver maintain expected TCP sequence numbers160due to the possibility of retransmissions and the lack of software fallback161once the packet reaches the device.162For segments passed in order, the driver marks the packets with163a connection identifier (note that a 5-tuple lookup is insufficient to identify164packets requiring HW offload, see the :ref:`5tuple_problems` section)165and hands them to the device. The device identifies the packet as requiring166TLS handling and confirms the sequence number matches its expectation.167The device performs encryption and authentication of the record data.168It replaces the authentication tag and TCP checksum with correct values.169 170RX171--172 173Before a packet is DMAed to the host (but after NIC's embedded switching174and packet transformation functions) the device validates the Layer 4175checksum and performs a 5-tuple lookup to find any TLS connection the packet176may belong to (technically a 4-tuple177lookup is sufficient - IP addresses and TCP port numbers, as the protocol178is always TCP). If connection is matched device confirms if the TCP sequence179number is the expected one and proceeds to TLS handling (record delineation,180decryption, authentication for each record in the packet). The device leaves181the record framing unmodified, the stack takes care of record decapsulation.182Device indicates successful handling of TLS offload in the per-packet context183(descriptor) passed to the host.184 185Upon reception of a TLS offloaded packet, the driver sets186the :c:member:`decrypted` mark in :c:type:`struct sk_buff <sk_buff>`187corresponding to the segment. Networking stack makes sure decrypted188and non-decrypted segments do not get coalesced (e.g. by GRO or socket layer)189and takes care of partial decryption.190 191Resync handling192===============193 194In presence of packet drops or network packet reordering, the device may lose195synchronization with the TLS stream, and require a resync with the kernel's196TCP stack.197 198Note that resync is only attempted for connections which were successfully199added to the device table and are in TLS_HW mode. For example,200if the table was full when cryptographic state was installed in the kernel,201such connection will never get offloaded. Therefore the resync request202does not carry any cryptographic connection state.203 204TX205--206 207Segments transmitted from an offloaded socket can get out of sync208in similar ways to the receive side-retransmissions - local drops209are possible, though network reorders are not. There are currently210two mechanisms for dealing with out of order segments.211 212Crypto state rebuilding213~~~~~~~~~~~~~~~~~~~~~~~214 215Whenever an out of order segment is transmitted the driver provides216the device with enough information to perform cryptographic operations.217This means most likely that the part of the record preceding the current218segment has to be passed to the device as part of the packet context,219together with its TCP sequence number and TLS record number. The device220can then initialize its crypto state, process and discard the preceding221data (to be able to insert the authentication tag) and move onto handling222the actual packet.223 224In this mode depending on the implementation the driver can either ask225for a continuation with the crypto state and the new sequence number226(next expected segment is the one after the out of order one), or continue227with the previous stream state - assuming that the out of order segment228was just a retransmission. The former is simpler, and does not require229retransmission detection therefore it is the recommended method until230such time it is proven inefficient.231 232Next record sync233~~~~~~~~~~~~~~~~234 235Whenever an out of order segment is detected the driver requests236that the ``ktls`` software fallback code encrypt it. If the segment's237sequence number is lower than expected the driver assumes retransmission238and doesn't change device state. If the segment is in the future, it239may imply a local drop, the driver asks the stack to sync the device240to the next record state and falls back to software.241 242Resync request is indicated with:243 244.. code-block:: c245 246 void tls_offload_tx_resync_request(struct sock *sk, u32 got_seq, u32 exp_seq)247 248Until resync is complete driver should not access its expected TCP249sequence number (as it will be updated from a different context).250Following helper should be used to test if resync is complete:251 252.. code-block:: c253 254 bool tls_offload_tx_resync_pending(struct sock *sk)255 256Next time ``ktls`` pushes a record it will first send its TCP sequence number257and TLS record number to the driver. Stack will also make sure that258the new record will start on a segment boundary (like it does when259the connection is initially added).260 261RX262--263 264A small amount of RX reorder events may not require a full resynchronization.265In particular the device should not lose synchronization266when record boundary can be recovered:267 268.. kernel-figure:: tls-offload-reorder-good.svg269 :alt: reorder of non-header segment270 :align: center271 272 Reorder of non-header segment273 274Green segments are successfully decrypted, blue ones are passed275as received on wire, red stripes mark start of new records.276 277In above case segment 1 is received and decrypted successfully.278Segment 2 was dropped so 3 arrives out of order. The device knows279the next record starts inside 3, based on record length in segment 1.280Segment 3 is passed untouched, because due to lack of data from segment 2281the remainder of the previous record inside segment 3 cannot be handled.282The device can, however, collect the authentication algorithm's state283and partial block from the new record in segment 3 and when 4 and 5284arrive continue decryption. Finally when 2 arrives it's completely outside285of expected window of the device so it's passed as is without special286handling. ``ktls`` software fallback handles the decryption of record287spanning segments 1, 2 and 3. The device did not get out of sync,288even though two segments did not get decrypted.289 290Kernel synchronization may be necessary if the lost segment contained291a record header and arrived after the next record header has already passed:292 293.. kernel-figure:: tls-offload-reorder-bad.svg294 :alt: reorder of header segment295 :align: center296 297 Reorder of segment with a TLS header298 299In this example segment 2 gets dropped, and it contains a record header.300Device can only detect that segment 4 also contains a TLS header301if it knows the length of the previous record from segment 2. In this case302the device will lose synchronization with the stream.303 304Stream scan resynchronization305~~~~~~~~~~~~~~~~~~~~~~~~~~~~~306 307When the device gets out of sync and the stream reaches TCP sequence308numbers more than a max size record past the expected TCP sequence number,309the device starts scanning for a known header pattern. For example310for TLS 1.2 and TLS 1.3 subsequent bytes of value ``0x03 0x03`` occur311in the SSL/TLS version field of the header. Once pattern is matched312the device continues attempting parsing headers at expected locations313(based on the length fields at guessed locations).314Whenever the expected location does not contain a valid header the scan315is restarted.316 317When the header is matched the device sends a confirmation request318to the kernel, asking if the guessed location is correct (if a TLS record319really starts there), and which record sequence number the given header had.320The kernel confirms the guessed location was correct and tells the device321the record sequence number. Meanwhile, the device had been parsing322and counting all records since the just-confirmed one, it adds the number323of records it had seen to the record number provided by the kernel.324At this point the device is in sync and can resume decryption at next325segment boundary.326 327In a pathological case the device may latch onto a sequence of matching328headers and never hear back from the kernel (there is no negative329confirmation from the kernel). The implementation may choose to periodically330restart scan. Given how unlikely falsely-matching stream is, however,331periodic restart is not deemed necessary.332 333Special care has to be taken if the confirmation request is passed334asynchronously to the packet stream and record may get processed335by the kernel before the confirmation request.336 337Stack-driven resynchronization338~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~339 340The driver may also request the stack to perform resynchronization341whenever it sees the records are no longer getting decrypted.342If the connection is configured in this mode the stack automatically343schedules resynchronization after it has received two completely encrypted344records.345 346The stack waits for the socket to drain and informs the device about347the next expected record number and its TCP sequence number. If the348records continue to be received fully encrypted stack retries the349synchronization with an exponential back off (first after 2 encrypted350records, then after 4 records, after 8, after 16... up until every351128 records).352 353Error handling354==============355 356TX357--358 359Packets may be redirected or rerouted by the stack to a different360device than the selected TLS offload device. The stack will handle361such condition using the :c:func:`sk_validate_xmit_skb` helper362(TLS offload code installs :c:func:`tls_validate_xmit_skb` at this hook).363Offload maintains information about all records until the data is364fully acknowledged, so if skbs reach the wrong device they can be handled365by software fallback.366 367Any device TLS offload handling error on the transmission side must result368in the packet being dropped. For example if a packet got out of order369due to a bug in the stack or the device, reached the device and can't370be encrypted such packet must be dropped.371 372RX373--374 375If the device encounters any problems with TLS offload on the receive376side it should pass the packet to the host's networking stack as it was377received on the wire.378 379For example authentication failure for any record in the segment should380result in passing the unmodified packet to the software fallback. This means381packets should not be modified "in place". Splitting segments to handle partial382decryption is not advised. In other words either all records in the packet383had been handled successfully and authenticated or the packet has to be passed384to the host's stack as it was on the wire (recovering original packet in the385driver if device provides precise error is sufficient).386 387The Linux networking stack does not provide a way of reporting per-packet388decryption and authentication errors, packets with errors must simply not389have the :c:member:`decrypted` mark set.390 391A packet should also not be handled by the TLS offload if it contains392incorrect checksums.393 394Performance metrics395===================396 397TLS offload can be characterized by the following basic metrics:398 399 * max connection count400 * connection installation rate401 * connection installation latency402 * total cryptographic performance403 404Note that each TCP connection requires a TLS session in both directions,405the performance may be reported treating each direction separately.406 407Max connection count408--------------------409 410The number of connections device can support can be exposed via411``devlink resource`` API.412 413Total cryptographic performance414-------------------------------415 416Offload performance may depend on segment and record size.417 418Overload of the cryptographic subsystem of the device should not have419significant performance impact on non-offloaded streams.420 421Statistics422==========423 424Following minimum set of TLS-related statistics should be reported425by the driver:426 427 * ``rx_tls_decrypted_packets`` - number of successfully decrypted RX packets428 which were part of a TLS stream.429 * ``rx_tls_decrypted_bytes`` - number of TLS payload bytes in RX packets430 which were successfully decrypted.431 * ``rx_tls_ctx`` - number of TLS RX HW offload contexts added to device for432 decryption.433 * ``rx_tls_del`` - number of TLS RX HW offload contexts deleted from device434 (connection has finished).435 * ``rx_tls_resync_req_pkt`` - number of received TLS packets with a resync436 request.437 * ``rx_tls_resync_req_start`` - number of times the TLS async resync request438 was started.439 * ``rx_tls_resync_req_end`` - number of times the TLS async resync request440 properly ended with providing the HW tracked tcp-seq.441 * ``rx_tls_resync_req_skip`` - number of times the TLS async resync request442 procedure was started by not properly ended.443 * ``rx_tls_resync_res_ok`` - number of times the TLS resync response call to444 the driver was successfully handled.445 * ``rx_tls_resync_res_skip`` - number of times the TLS resync response call to446 the driver was terminated unsuccessfully.447 * ``rx_tls_err`` - number of RX packets which were part of a TLS stream448 but were not decrypted due to unexpected error in the state machine.449 * ``tx_tls_encrypted_packets`` - number of TX packets passed to the device450 for encryption of their TLS payload.451 * ``tx_tls_encrypted_bytes`` - number of TLS payload bytes in TX packets452 passed to the device for encryption.453 * ``tx_tls_ctx`` - number of TLS TX HW offload contexts added to device for454 encryption.455 * ``tx_tls_ooo`` - number of TX packets which were part of a TLS stream456 but did not arrive in the expected order.457 * ``tx_tls_skip_no_sync_data`` - number of TX packets which were part of458 a TLS stream and arrived out-of-order, but skipped the HW offload routine459 and went to the regular transmit flow as they were retransmissions of the460 connection handshake.461 * ``tx_tls_drop_no_sync_data`` - number of TX packets which were part of462 a TLS stream dropped, because they arrived out of order and associated463 record could not be found.464 * ``tx_tls_drop_bypass_req`` - number of TX packets which were part of a TLS465 stream dropped, because they contain both data that has been encrypted by466 software and data that expects hardware crypto offload.467 468Notable corner cases, exceptions and additional requirements469============================================================470 471.. _5tuple_problems:472 4735-tuple matching limitations474----------------------------475 476The device can only recognize received packets based on the 5-tuple477of the socket. Current ``ktls`` implementation will not offload sockets478routed through software interfaces such as those used for tunneling479or virtual networking. However, many packet transformations performed480by the networking stack (most notably any BPF logic) do not require481any intermediate software device, therefore a 5-tuple match may482consistently miss at the device level. In such cases the device483should still be able to perform TX offload (encryption) and should484fallback cleanly to software decryption (RX).485 486Out of order487------------488 489Introducing extra processing in NICs should not cause packets to be490transmitted or received out of order, for example pure ACK packets491should not be reordered with respect to data segments.492 493Ingress reorder494---------------495 496A device is permitted to perform packet reordering for consecutive497TCP segments (i.e. placing packets in the correct order) but any form498of additional buffering is disallowed.499 500Coexistence with standard networking offload features501-----------------------------------------------------502 503Offloaded ``ktls`` sockets should support standard TCP stack features504transparently. Enabling device TLS offload should not cause any difference505in packets as seen on the wire.506 507Transport layer transparency508----------------------------509 510The device should not modify any packet headers for the purpose511of the simplifying TLS offload.512 513The device should not depend on any packet headers beyond what is strictly514necessary for TLS offload.515 516Segment drops517-------------518 519Dropping packets is acceptable only in the event of catastrophic520system errors and should never be used as an error handling mechanism521in cases arising from normal operation. In other words, reliance522on TCP retransmissions to handle corner cases is not acceptable.523 524TLS device features525-------------------526 527Drivers should ignore the changes to the TLS device feature flags.528These flags will be acted upon accordingly by the core ``ktls`` code.529TLS device feature flags only control adding of new TLS connection530offloads, old connections will remain active after flags are cleared.531 532TLS encryption cannot be offloaded to devices without checksum calculation533offload. Hence, TLS TX device feature flag requires TX csum offload being set.534Disabling the latter implies clearing the former. Disabling TX checksum offload535should not affect old connections, and drivers should make sure checksum536calculation does not break for them.537Similarly, device-offloaded TLS decryption implies doing RXCSUM. If the user538does not want to enable RX csum offload, TLS RX device feature is disabled539as well.540