Re: [PATCH v13 net-next 23/23] Documentation/tcp: Add TCP-AO documentation

[Jonathan Corbet <corbet@lwn.net>]

Dmitry Safonov <dima@arista.com> writes:

> It has Frequently Asked Questions (FAQ) on RFC 5925 - I found it very
> useful answering those before writing the actual code. It provides answers
> to common questions that arise on a quick read of the RFC, as well as how
> they were answered. There's also comparison to TCP-MD5 option,
> evaluation of per-socket vs in-kernel-DB approaches and description of
> uAPI provided.
>
> Hopefully, it will be as useful for reviewing the code as it was for writing.

It looks like useful information; I just have one request...

> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: Dmitry Safonov <dima@arista.com>
> Acked-by: David Ahern <dsahern@kernel.org>
> ---
>  Documentation/networking/index.rst  |   1 +
>  Documentation/networking/tcp_ao.rst | 434 ++++++++++++++++++++++++++++
>  2 files changed, 435 insertions(+)
>  create mode 100644 Documentation/networking/tcp_ao.rst
>
> diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
> index 5b75c3f7a137..69c1e53ef88b 100644
> --- a/Documentation/networking/index.rst
> +++ b/Documentation/networking/index.rst
> @@ -107,6 +107,7 @@ Contents:
>     sysfs-tagging
>     tc-actions-env-rules
>     tc-queue-filters
> +   tcp_ao
>     tcp-thin
>     team
>     timestamping
> diff --git a/Documentation/networking/tcp_ao.rst b/Documentation/networking/tcp_ao.rst
> new file mode 100644
> index 000000000000..cfa13a0748a2
> --- /dev/null
> +++ b/Documentation/networking/tcp_ao.rst
> @@ -0,0 +1,434 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +========================================================
> +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.
> +The intent of TCP-AO is to deprecate TCP-MD5 providing better security,
> +key rotation and support for variety of hashing algorithms.
> +
> +1. Introduction
> +===============
> +
> +.. list-table:: Short and Limited Comparison of TCP-AO and TCP-MD5
> +
> +   * -
> +     - TCP-MD5
> +     - TCP-AO
> +   * - Supported hashing algorithms
> +     - MD5 (cryptographically weak).
> +     - Must support HMAC-SHA1 (chosen-prefix attacks) and CMAC-AES-128
> +       (only side-channel attacks). May support any hashing algorithm.

...can you please avoid using list-table if possible?  It makes the
plain-text version nearly impossible to read.

Thanks,

jon