On Wed, Dec 30, 2020 at 07:05:47AM +0000, Jason McIntyre wrote: > On Wed, Dec 30, 2020 at 02:02:44AM +0100, Klemens Nanni wrote: > > Manuals like httpd.conf(5) refer to tls_config_parse_protocols(3) the > > list of supported protocols. > > > > Sentences with inlined elements are generally harder to read, especially > > in such pages and/or when they contain comments. > > > > Convert to a proper list that looks like this when rendered: > > > > The tls_config_parse_protocols() utility function parses a protocol > > string and returns the corresponding value via the protocols argument. > > This value can then be passed to the tls_config_set_protocols() > > function. > > The protocol string is a comma or colon separated list of keywords. > > Valid keywords are: > > > > all (all supported protocols) > > tlsv1.0 > > tlsv1.1 > > tlsv1.2 > > tlsv1.3 > > secure (currently TLSv1.2 and TLSv1.3) > > default (alias for "secure") > > legacy (alias for "all") > > > > This is also reordered such that aliases are mentioned *after* the > > string they alias. > > > > Another benefit is that those items are now tagged, e.g. ":tall" in > > less(1) brings you right to the first item in the list. > > > > Available ciphers for tls_config_set_ciphers() further down are already > > in a list and use similar comments for aliases, but I've slightly > > adjusted those for consistency as well. > > > > Feedback? OK? > > > > morning. > > the trade off is the extra space taken up, i guess. i agree it reads > better though, and am ok with it.
While I have no objection to doing something along these lines, I dislike how "all" is singled out in this new list. It's really not recommended. I would just keep the order as it was (I see no issue with mentioning aliases first) or use strict alphabetical order of all keywords. The newly introduced order is not obvious. > > jmc > > > > > Index: ./lib/libtls/man/tls_config_set_protocols.3 > > =================================================================== > > RCS file: /cvs/src/lib/libtls/man/tls_config_set_protocols.3,v > > retrieving revision 1.8 > > diff -u -p -r1.8 tls_config_set_protocols.3 > > --- ./lib/libtls/man/tls_config_set_protocols.3 22 Jan 2020 06:46:34 > > -0000 1.8 > > +++ ./lib/libtls/man/tls_config_set_protocols.3 30 Dec 2020 00:48:07 > > -0000 > > @@ -99,9 +99,19 @@ This value can then be passed to the > > .Fn tls_config_set_protocols > > function. > > The protocol string is a comma or colon separated list of keywords. > > -Valid keywords are tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.3, all (all supported > > -protocols), default (an alias for secure), legacy (an alias for all) and > > -secure (currently TLSv1.2 and TLSv1.3). > > +Valid keywords are: > > +.Pp > > +.Bl -tag -width "tlsv1.3" -offset indent -compact > > +.It Dv all Pq all supported protocols > > +.It Dv tlsv1.0 > > +.It Dv tlsv1.1 > > +.It Dv tlsv1.2 > > +.It Dv tlsv1.3 > > +.It Dv secure Pq currently TLSv1.2 and TLSv1.3 > > +.It Dv default Pq alias for secure > > +.It Dv legacy Pq alias for all > > +.El > > +.Pp > > If a value has a negative prefix (in the form of a leading exclamation > > mark) > > then it is removed from the list of available protocols, rather than being > > added to it. > > @@ -116,10 +126,12 @@ Lists of ciphers are specified by name, > > permitted names are: > > .Pp > > .Bl -tag -width "insecure" -offset indent -compact > > -.It Dv "secure" (or alias "default") > > -.It Dv "compat" > > -.It Dv "legacy" > > -.It Dv "insecure" (or alias "all") > > +.It Dv all Pq all supported ciphers > > +.It Dv secure > > +.It Dv default Pq alias for secure > > +.It Dv compat > > +.It Dv legacy > > +.It Dv insecure Pq alias for all > > .El > > .Pp > > Alternatively, libssl cipher strings can be specified. > > >
