Page MenuHomeFreeBSD

setkey(8): Clarify language around AEAD ciphers.
ClosedPublic

Authored by jhb on Apr 18 2022, 6:57 PM.

Details

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

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

jhb requested review of this revision.Apr 18 2022, 6:57 PM
This revision is now accepted and ready to land.Apr 18 2022, 7:09 PM

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.

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 added inline comments.
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.

Expand AEAD on first use.

This revision now requires review to proceed.Apr 27 2022, 4:06 PM
jhb marked an inline comment as done.Apr 27 2022, 4:08 PM
jhb added inline comments.
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.

This revision is now accepted and ready to land.Apr 27 2022, 4:12 PM
This revision was automatically updated to reflect the committed changes.