Update the crypto(4) and crypto(9) manpages.

[jhb]

Summary

There are probably bits that are still wrong, but this fixes some
things at least:

• Add named arguments to the functions in crypto(9).
• Add missing algorithms.
• Don't mention arguments that don't exist in crypto_register.
• Add CIOGSESSION2.
• Remove CIOCNFSESSION.
• Clarify some stale language that assumed an fd had only one sesson.
• Note that you have to use CRIOGET and add a note in BUGS lamenting that one has to use CRIOGET.
• Various other cleanups.

[cem]

Thanks, this page is a mess and this is a good improvement. I've got some quibbles and nits below; some is subjective, feel free to reject proposals. Hopefully someone from manpages has some time to review this as well.

share/man/man4/crypto.4

96

nice.

115–118

I have two alternative suggestions.

1. .Xr open 2 \n the \n .Pa ... \n device. (just make .Xr open 2 the verb and remove the redundancy) or
2. Open ... device with \n .Xr open 2 . (s/via/with/)

120–131

It's a little unclear what the relationship between session fds and sessions is, and I think the similar naming implies a relationship that doesn't exist. But I'm struggling to come up with a better name for the fd, and the ioctl name is already tied firmly to SESSION.

130

Also things like hashes and MACs, I think (which aren't symmetric crypto).

The clearest description might be "if the cryptop ioctl of what you want to do includes a session identifier, create a session for it" but that isn't a great logical explanation.

147–149

It might be worth pointing out that this is unnecessary if you're closing the fd anyway. I'm not sure there's any real utility to end users of closing sessions at all (aside from preventing kernel memory leak until the process exits). Do we have a user resource limit on sessions?

207–208

Something slightly less obsolete for both examples while here? Also technically there should be a comma after e.g..

215

C99 uint32_t while you're here?

264

session2_op

273

Ditto remarks re: earlier session_op

281

I think s/via/with/ here as well.

282

I think we usually just say .Fa crid ..

I'd also suggest documenting that pad must be zero. Otherwise it doesn't serve a lot of purpose as a future expansion option.

457–460

This sentence is a bit awkward. Maybe just "CRIOGET should not exist."?

share/man/man9/crypto.9

166

by -> be

249–250

Maybe: "For variable-size key algorithms, the length of the key, in bits."

251–252

Maybe "If non-zero, truncate the calculated hash to this many bytes."

254

s/ with the algorithm//

256

I'd drop "(IV)" given the field has "iv" in the name and if someone doesn't know that initialization vector and IV are synonymous, they're unlikely to be reading this manual page at all.

266–267

suggest: s/multi-algorithm/dual-algorithm/, since that's all drivers support in practice and we're trying to ditch the arbitrary linked list model soon.

Also, comma before "such as."

267

Maybe just "a MAC."

272–279

Maybe "... will not be modified or referenced by the framework ...". (I'd keep the clarifying 2nd sentence even with that change, though.

305

wat

367–371

In general, sized buffers are expected to be contiguous (in the virtual memory context that this use means) in C. So I'd just drop that qualifying word.

I tend to prefer leading with the conditionals, so I'd suggest "Unless ... IMBUF or ... IOV is specified in crp_flags, a pointer to the data."

373–375

Missing a word ("... is normally set crp_ilen bytes"), and missing a period at the end of the sentence.

464–465

The parentheses bit is awkward. I'd pull it out as its own sentence and rephrase a bit:

"Two examples of this use are ipsec, in some configurations, and encrypted swap."

If the latter means GELI, I'd just replace it with GELI. If it doesn't mean GELI, what does it mean?

[jhb]

share/man/man4/crypto.4

120–131

So you can have multiple sessions on a single fd, but it has to be an fd created via CRIOGET. I wanted to have some way to differentiate a /dev/crypto fd from a CRIOGET fd. Long term I'd like to kill CRIOGET, but until then, I was trying to use "session fd" to mean "fd returned from CRIOGET" vs /dev/crypto fd. Not sure of a better way to name these. Perhaps "cryptography fd". That's kind of what procstat(8) calls these.

130

I tried to borrow from the language in the para at line 105, but added digests explicitly.

147–149

We do not.

207–208

The comment is straight from cryptodev.h. I think in my old trees I need to rebase that remove these algorithms I do change them to something else, so I can do that here when I do it to the header.

215

So, I might do a pass over the crypto header to do that at some point, but for now I think it's best to match what the header uses.

281

With also reads a bit odd, so I've reworked the sentence.

282

I chose to the 'sesp->crid' to match the rest of the manpage which uses that style.

Documenting pad is a good idea.

share/man/man9/crypto.9

305

*sigh*

367–371

For a definition list I like to start with the root definition first and then append qualifiers. I do think "unless" is a better wording than "when neither" though.

464–465

I think this sentence predates geli? I'm not sure, I might just axe it. I plan to rewrite this entire section for the refactor anyway.

[jhb]

• Various nits.