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. 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. >
