Improve docs, links and references #255
Conversation
janbrasna
added
enhancement
| - `form.serverVersion` - desired server version | ||
| - `form.opensslVersion` - desired OpenSSL version |
There was a problem hiding this comment.
"desired"? I am not sure that describes "generate config to work with this version" (if version is recognized)
There was a problem hiding this comment.
Yes please do challenge any awkward language you come across. Thanks!
I wanted to make a clear difference between options read from configs as compared to values entered by the visitor through the UI at the time of every render.
Do you have any idea for a reasonably brief wording? Something equivalent to "… version requested by the user" perhaps?
PS: "config to work with this version" is not exactly achieved yet, as the value entered might be artificially high or unreasonably low… but it's the value passed from the user nonetheless.
There was a problem hiding this comment.
"user's server version"? "your server version"? "input server version"? "user-selected server version"? "user-specified server version"? I lean towards one of the last two.
There was a problem hiding this comment.
I think I'll go with "requested", as we don't know if it's actually "entered", "selected" or "specified" by the user as their version at all, as it may just come from the default value being pre-populated by configs settings on load; guess I'll be as neutral as possible.
| - `{{#each (reverse output.protocols)}}` | ||
| - `sameminorver(version another)` - returns `true` if `version` and `another` are of the same minor version, e.g. `2.4` |
There was a problem hiding this comment.
"anotherVersion"? "versionA" "versionB"?
| - `last(array)` - returns the last item in the array | ||
| - `minpatchver(minimumver, curver)` - `true` if `curver` is greater than or equal to `minimumver`, and both versions are the same patch version, e.g. `2.2` | ||
| - `minpatchver(minimum current)` - only `true` if `current` version is greater than or equal to `minimum`, and both are of the same minor version, e.g. `2.4.x` (won't match any higher `2.5.x` or `3.x`) |
| # Mozilla SSL Configuration Generator | ||
|
|
||
| The Mozilla SSL Configuration Generator is a tool which builds configuration files to help you follow the Mozilla [Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) configuration guidelines. | ||
| The Mozilla SSL Configuration Generator is a tool which builds configuration files to help you follow the Mozilla [Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) recommendations. |
There was a problem hiding this comment.
I'm not quite comfortable with "recommending" anything in the "Old" config. Maybe suggested configuration to support user-selected configuration guideline?
|
|
||
| ## JSON guidelines | ||
|
|
||
| Each revision of the Mozilla Server Side TLS guidelines is published in a machine-readable format from this repository as a [JSON specification](/src/static/guidelines/) that can be found at [`/src/static/guidelines/`](/src/static/guidelines/) 📟 |
There was a problem hiding this comment.
redundant link? I suggest removing hyperlink for "JSON specification" and leaving the rest as-is.
There was a problem hiding this comment.
It was kinda on purpose as I want the link for the specs listed and titled as such in the outline (think a11y), but at the same time have the following path clickable.
I think I will work around this by linking the first occurrence to the actual deployed latest.json symlink to hint what's the public/canonical location of those specs outside of this repo source.
|
|
||
| ## Contributing | ||
|
|
||
| The project is written in JavaScript, uses Webpack for development and production builds, and most of the templating logic to turn the recommendations into the various server configs is done in Handlebars. |
There was a problem hiding this comment.
"..., and uses Handlebars for most of the templating logic ..." and remove "is done in Handlerbars." from the end.
|
Aside: what level of details would you like to include in CHANGELOG.md? User-facing changes are relevant. Version bumps are less important unless related to a user-facing change, such as adding TLSv1.3 support. Internal changes are also less important and can be summarized or omitted, IMO. |
| - `output.cipherSuites` - TLSv1.3+ cipher suites list | ||
| - `output.serverPreferredOrder` - enforce ServerPreference for ordering cipher list (boolean true/false) | ||
| - `output.hstsMaxAge` - max-age (seconds) for Strict-Transport-Security: max-age=... HTTP response header | ||
| - `output.latestVersion` - server latest version | ||
| - `output.usesOpenssl` - server uses openssl (boolean true/false) | ||
| - `output.usesDhe` - server might use Diffie-Hellmann key exchange (boolean true/false) | ||
| - `output.usesDhe` - config includes Diffie-Hellmann key exchange (boolean true/false) |
There was a problem hiding this comment.
should we specify "config includes ciphers employing non-ECDHE Diffie-Hellmann key exchange"?
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
There was a problem hiding this comment.
TBD: this actually only applies to ≤TLS1.2 currently (or, more precisely for Kx=DH specifically and not Kx=Any in general when including FFDHE too) so I'll need to revisit this once we decide on limiting ffdhe* groups in TLS1.3…
There was a problem hiding this comment.
TODO: also document dhParamSize proper that's not mentioned in the docs.
readme:
https://github.com/janbrasna/ssl-config-generator/tree/upd/docs-refs-links#readme
manifest:
header:
footer:
https://develop--mozsslconf-dev.netlify.app/