setkey(8): Clarify language around AEAD ciphers.

[jhb]

Summary

AEAD ciphers for IPsec combine both encryption and authentication. As
such, ESP configurations using an AEAD cipher should not use a
seperate authentication algorithm via -A. However, this was not
apparent from the setkey manpage and 12.x and earlier did not perform
sufficient argument validation permitting users to pair an explicit -A
such as SHA256-HMAC with AES-GCM. (The result was a non-standard
combination of AES-CTR with the specified MAC, but with the wrong
initial block counter (and thus different keystream) compared to using
AES-CTR as the cipher.)

Attempt to clarify this in the manpage by explicitly calling out AEAD
ciphers (currently only AES-GCM) and noting that AEAD ciphers should
not use -A.

While here, explicitly note which authentication algorithms can be
used with esp vs esp-old. Also add subsection headings for the
different algorithm lists and tidy some language.

I did not convert the tables to column lists (Bl -column) though that
would probably be more correct than using literal blocks (Bd
-literal).

PR: 263379

[debdrup]

Ss, like Sh, should be capitalized according to mdoc(7).

I don't know how much the MANUAL STRUCTURE referenced on the Ss macro in mdoc(7) matters for this, since it seems to be what subsections are for.

Please remember to also bump .Dd :)

sbin/setkey/setkey.8

628

Needs a space here.

[jhb]

In D34947#792309, @debdrup wrote:

Ss, like Sh, should be capitalized according to mdoc(7).

All I see in mdoc(7) is that .Sh has pre-defined names that all happened to be all-caps, but in neither .Sh nor .Ss do I see a requirement for all-caps. The majority of existing .Ss uses in the tree today are not all-caps.

mdoc(7) itself seems to not use all-caps (e.g. "Displays and lists" under MACRO OVERVIEW)

The only requirement in mdoc(7) seems to be that subsection names must be unique?

Please remember to also bump .Dd :)

Yes, I bump prior to commit once a change is approved.

[pauamma_gundo.com]

sbin/setkey/setkey.8

331–332

Audience check: would someone reading this be able both to expand this acronym and to understand what the expansion means? If not, it needs clarification.

648

Same here.

[jhb]

Expand AEAD on first use.

[jhb]

sbin/setkey/setkey.8

331–332

They probably should (it's used in the RFC's for IPsec, etc.) such that if you are choosing an algorithm by hand you should be familiar with it. That said we do expand it on first use in some other pages, so I've done that here. I think expanding it on first use here is sufficient to permit using the acronym alone later in the page.

[jhb]

Add missing space.