Documentation/networking/tcp_ao.rst

4 TCP Authentication Option Linux implementation (RFC5925)
7 TCP Authentication Option (TCP-AO) provides a TCP extension aimed at verifying
8 segments between trusted peers. It adds a new TCP header option with
10 of a TCP segment using a hashing function with a password known to both peers.
11 The intent of TCP-AO is to deprecate TCP-MD5 providing better security,
17 .. table:: Short and Limited Comparison of TCP-AO and TCP-MD5
20  |                      |       TCP-MD5          |         TCP-AO        |
31  |                      |                        |TCP header permitted.  |
34  |TCP connection        |                        |                       |
45  |traffic-crossing      |                        |includes TCP ports.    |
49  |replayed TCP segments |                        |Extension (SNE) and    |
68    >> The IDs of MKTs MUST NOT overlap where their TCP connection
93    to be removed. TCP-AO provides no mechanism to coordinate their removal,
101 Linux TCP-AO will try its best to prevent you from removing a key that's
109 may yet not have the new key - the TCP connection may just break.
120    socket pair and its TCP-AO KeyID, matched against the MKT's TCP connection
123       i. If there is no matching MKT, remove TCP-AO from the segment.
124          Proceed with further TCP handling of the segment.
130    >> A TCP-AO implementation MUST allow for configuration of the behavior
131    of segments with TCP-AO but that do not match an MKT. The initial default
134    connections, or the connection can indicate that TCP-AO is required.
140    Connections not matching any MKT do not require TCP-AO. Further, incoming
141    segments with TCP-AO are not discarded solely because they include
144 Note that Linux TCP-AO implementation differs in this aspect. Currently, TCP-AO
153    >> All TCP segments MUST be checked against the set of MKTs for matching
154    TCP connection identifiers.
174    protocol operation. It is not manipulated by TCP-AO. Current_key is updated
175    by TCP-AO when processing received TCP segments as discussed in the segment
179    segments are received out of order, and is considered a feature of TCP-AO,
199    >> An outgoing TCP segment MUST match at most one desired MKT, indicated
203    match; such information MUST NOT include values in any TCP option fields.
205 Q: Can TCP-MD5 connection migrate to TCP-AO (and vice-versa):
209    TCP MD5-protected connections cannot be migrated to TCP-AO because TCP MD5
213 Q: If all MKTs are removed on a connection, can it become a non-TCP-AO signed
218 While switching to non-TCP-AO connection is not prohibited directly, it seems
219 what the RFC means. Also, there's a requirement for TCP-AO connections to
222    TCP-AO requires that every protected TCP segment match exactly one MKT.
226    >> An incoming TCP segment including TCP-AO MUST match exactly one MKT,
227    indicated solely by the segment’s socket pair and its TCP-AO KeyID.
234 Q: Can a non-TCP-AO connection become a TCP-AO-enabled one?
236 A: No: for an already established non-TCP-AO connection it would be impossible
237 to switch to using TCP-AO, as the traffic key generation requires the initial
238 sequence numbers. Paraphrasing, starting using TCP-AO would require
239 re-establishing the TCP connection.
244 Linux TCP-AO support is implemented using ``setsockopt()s``, in a similar way
245 to TCP-MD5. It means that a userspace application that wants to use TCP-AO
246 should perform ``setsockopt()`` on a TCP socket when it wants to add,
255 ``setsockopt()s`` for TCP-MD5 support.
267  | changes              | that wants TCP-AO needs| as tunnels, providing |
294 userspace manage TCP-AO on a per-socket basis. In order to add/delete MKTs
295 ``TCP_AO_ADD_KEY`` and ``TCP_AO_DEL_KEY`` TCP socket options must be used.
296 It is not allowed to add a key on an established non-TCP-AO connection
297 as well as to remove the last key from TCP-AO connection.
306 the TCP-AO connection.
309 It also provides a uAPI to change per-socket TCP-AO settings, such as
310 ignoring ICMPs, as well as clear per-socket TCP-AO packet counters.
312 per-socket TCP-AO settings.
315 to list all MKTs on a TCP socket or use a filter to get keys for a specific
318 To repair TCP-AO connections ``setsockopt(TCP_AO_REPAIR)`` is available,
322 A tip here for scaled TCP_LISTEN sockets, that may have some thousands TCP-AO
326 Linux TCP-AO also provides a bunch of segment counters that can be helpful
329 Each TCP-AO socket has the following counters:
331 - for bad segments (failed TCP-AO verification)
336 TCP-AO per-socket counters are also duplicated with per-netns counters,
340 For monitoring purposes, there are following TCP-AO trace events:
345 one can filter them by net-namespace, 4-tuple, family, L3 index, and TCP header
346 flags. If a segment has a TCP-AO header, the filters may also include
349 RFC 5925 very permissively specifies how TCP port matching can be done for
352    TCP connection identifier. A TCP socket pair, i.e., a local IP
353    address, a remote IP address, a TCP local port, and a TCP remote port.
357 Currently Linux TCP-AO implementation doesn't provide any TCP port matching.
364 In contrast with an established TCP-MD5 connection which has just one key,
365 TCP-AO connections may have many keys, which means that accepted connections
371 The result is that when userspace removes TCP-AO keys, that may break
387 This is a similar "do-nothing" approach to TCP-MD5 from the kernel side and
391 Note that this race is rare for it needs TCP-AO key rotation to happen
392 during the 3-way handshake for the new TCP connection.
394 5. Interaction with TCP-MD5
397 A TCP connection can not migrate between TCP-AO and TCP-MD5 options. The
402 both TCP-AO and (deprecated) TCP-MD5 clients. As a result, both types of keys
409 RFC 5925 [6.2] describes the algorithm of how to extend TCP sequence numbers
410 with SNE.  In short: TCP has to track the previous sequence numbers and set
425 tcp_ao_compute_sne() is called for each TCP-AO segment. It compares SEQ numbers
428 requires SNE numbers to be stored on every TCP-AO socket.
432 a rollover. It allows more TCP segment replays, but yet all regular
433 TCP checks in tcp_sequence() are applied on the verified segment.
436 for large TCP windows.
441 RFC 5925 The TCP Authentication Option
444 RFC 5926 Cryptographic Algorithms for the TCP Authentication Option (TCP-AO)
447 Draft "SHA-2 Algorithm for the TCP Authentication Option (TCP-AO)"
448    https://datatracker.ietf.org/doc/html/draft-nayak-tcp-sha2-03
450 RFC 2385 Protection of BGP Sessions via the TCP MD5 Signature Option