Update the TCP-AO documentation to fix some incorrect terminology and claims regarding the MAC algorithms, and document which MAC algorithms and lengths the Linux implementation supports. Signed-off-by: Eric Biggers --- Documentation/networking/tcp_ao.rst | 38 ++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/Documentation/networking/tcp_ao.rst b/Documentation/networking/tcp_ao.rst index d5b6d0df63c3..55304037aa81 100644 --- a/Documentation/networking/tcp_ao.rst +++ b/Documentation/networking/tcp_ao.rst @@ -5,32 +5,34 @@ TCP Authentication Option Linux implementation (RFC5925) ======================================================== TCP Authentication Option (TCP-AO) provides a TCP extension aimed at verifying segments between trusted peers. It adds a new TCP header option with a Message Authentication Code (MAC). MACs are produced from the content -of a TCP segment using a hashing function with a password known to both peers. +of a TCP segment using a key known to both peers. The intent of TCP-AO is to deprecate TCP-MD5 providing better security, -key rotation and support for a variety of hashing algorithms. +key rotation and support for a variety of MAC algorithms. 1. Introduction =============== .. table:: Short and Limited Comparison of TCP-AO and TCP-MD5 +----------------------+------------------------+-----------------------+ | | TCP-MD5 | TCP-AO | +======================+========================+=======================+ - |Supported hashing |MD5 |Must support HMAC-SHA1 | - |algorithms |(cryptographically weak)|(chosen-prefix attacks)| - | | |and CMAC-AES-128 (only | - | | |side-channel attacks). | - | | |May support any hashing| - | | |algorithm. | + |Supported MAC |MD5 of data and key |HMAC-SHA-1-96 and | + |algorithms |(cryptographically weak)|AES-128-CMAC-96. | + | | |Implementations are | + | | |permitted to support | + | | |additional algorithms. | +----------------------+------------------------+-----------------------+ - |Length of MACs (bytes)|16 |Typically 12-16. | - | | |Other variants that fit| - | | |TCP header permitted. | + |Length of MACs (bytes)|16 |12 for HMAC-SHA-1-96 | + | | |and AES-128-CMAC-96. | + | | |Implementations are | + | | |permitted to support | + | | |any MAC length that | + | | |fits in the TCP header.| +----------------------+------------------------+-----------------------+ |Number of keys per |1 |Many | |TCP connection | | | +----------------------+------------------------+-----------------------+ |Possibility to change |Non-practical (both |Supported by protocol | @@ -294,10 +296,24 @@ Linux provides a set of ``setsockopt()s`` and ``getsockopt()s`` that let userspace manage TCP-AO on a per-socket basis. In order to add/delete MKTs ``TCP_AO_ADD_KEY`` and ``TCP_AO_DEL_KEY`` TCP socket options must be used. It is not allowed to add a key on an established non-TCP-AO connection as well as to remove the last key from TCP-AO connection. +``TCP_AO_ADD_KEY`` allows the MAC algorithm and MAC length to be selected. +Linux supports the mandatory-to-implement algorithms HMAC-SHA-1-96 and +AES-128-CMAC-96. In addition, as Linux extensions, it supports: + +- HMAC-SHA256. Linux uses HMAC-SHA256 in the same way as HMAC-SHA1; this + includes omitting an explicit entropy extraction step. To work around the + missing entropy extraction, users should provide keys with full entropy. The + implementation is interoperable with other implementations of HMAC-SHA256 for + TCP-AO only when they have implemented the key derivation the same way (and + also the same MAC length is selected on each side). + +- Any MAC length for any of the supported MAC algorithms, provided it fits in + the TCP header and is at least 4 bytes. + ``setsockopt(TCP_AO_DEL_KEY)`` command may specify ``tcp_ao_del::current_key`` + ``tcp_ao_del::set_current`` and/or ``tcp_ao_del::rnext`` + ``tcp_ao_del::set_rnext`` which makes such delete "forced": it provides userspace a way to delete a key that's being used and atomically set another one instead. This is not intended for normal use and should be used base-commit: 09942ddedcb960f9e78fd817ec33f501d1040c5b -- 2.54.0.545.g6539524ca2-goog