Feedback type: bug OS affected: all (documentation) Abstract: SSL_CTX_set_tmp_dh(3ssl) man page feedback
I received a feedback which I don't think I've passed on to you yet
about the SSL_CTX_set_tmp_dh(3ssl) man page (or at least I can't find
any evidence that I did in the rt tracker).
Original feedback follows:
> I believe both commas should be removed from the following passage:
>
> "The server will always generate a new DH key during the
> negotiation, when the DH parameters are supplied via callback and/or
> when the SSL_OP_SINGLE_DH_USE option of SSL_CTX_set_options(3) is
> set. It will immediately create a DH key, when DH parameters are
> supplied via SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not
> set."
My follow-on comments:
There's another grammatical problem in the paragraph that further
hurts readability. The words "when" and "if" are not really
interchangeable. You should only use "when" if you are referring to a
particular point in time, e.g. the loop exits when the count reaches
zero. When referring to things that may or may not actually occur,
you should always use "if" to avoid confusion.
This is compounded by an unfortunate quirk of the English language,
specifically that the final comma in a list (referred to as a serial
comma) may be omitted. Thus....
As written, the first sentence has two possible interpretations:
1. The server generates a key at three points in time:
A. during the negotiation
B. at the moment in time when the DH parameters are supplied
C. at the moment in time when the SSL_OP_SINGLE_SH_USE option
is set.
2. The server generates a key during negotiation, but only if either
the DH parameters
are supplied and/or the option is set.
I'm fairly certain that the intended meaning is #2, but the meaning is
somewhat ambiguous. There's a similar misuse of "when" in the second
sentence, though it is not quite as ambiguous.
Suggested rewording below:
"The server will always generate a new DH key during the negotiation
if either the DH parameters are supplied via callback or the
SSL_OP_SINGLE_DH_USE option of SSL_CTX_set_options(3) is set. It will
immediately create a DH key if DH parameters are supplied via
SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set."
If you really want to be pedantic, you could add "(or both)" to the
end of the first sentence.
David
Feedback type: bug OS affected: all (documentation) Abstract: SSL_CTX_set_tmp_dh(3ssl) man page feedback I received a feedback which I don't think I've passed on to you yet about the SSL_CTX_set_tmp_dh(3ssl) man page (or at least I can't find any evidence that I did in the rt tracker). Original feedback follows:
My follow-on comments: There's another grammatical problem in the paragraph that further hurts readability. The words "when" and "if" are not really interchangeable. You should only use "when" if you are referring to a particular point in time, e.g. the loop exits when the count reaches zero. When referring to things that may or may not actually occur, you should always use "if" to avoid confusion. This is compounded by an unfortunate quirk of the English language, specifically that the final comma in a list (referred to as a serial comma) may be omitted. Thus.... As written, the first sentence has two possible interpretations: 1. The server generates a key at three points in time: A. during the negotiation B. at the moment in time when the DH parameters are supplied C. at the moment in time when the SSL_OP_SINGLE_SH_USE option is set. 2. The server generates a key during negotiation, but only if either the DH parameters are supplied and/or the option is set. I'm fairly certain that the intended meaning is #2, but the meaning is somewhat ambiguous. There's a similar misuse of "when" in the second sentence, though it is not quite as ambiguous. Suggested rewording below: "The server will always generate a new DH key during the negotiation if either the DH parameters are supplied via callback or the SSL_OP_SINGLE_DH_USE option of SSL_CTX_set_options(3) is set. It will immediately create a DH key if DH parameters are supplied via SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set." If you really want to be pedantic, you could add "(or both)" to the end of the first sentence. David |
