On Tue, 8 Feb 2022 23:36:05 GMT, Xue-Lei Andrew Fan <xue...@openjdk.org> wrote:
>> Ok, I get it now, the API wins if both are set. But I could not discern that
>> from the current text. I think it is ok to be more clear about this. I
>> suggest adding something like the following:
>>
>> "The set of signature schemes that will be used is determined in this order
>> of preference: 1. explicitly set by application; 2. specified by system
>> property; 3. specified by provider defaults. For example, setting the
>> signature schemes in your application overrides settings specified in
>> jdk.tls.client.SignatureSchemes or jdk.tls.server.SignatureSchemes, as well
>> as JDK provider defaults."
>>
>> Does that accurately capture the implementation behavior?
>
> Basically, the suggestion captures the implementation behaviors correctly.
> To make it more accuracy, if we want to use it, we may need to consider more
> cases:
> 1. _explicitly set by application_, with null, empty or 1+ schemes.
> 2. _specified by system property_, with unset, empty or 1+ schemes.
>
> I think the description could be in the following logic:
> A. the system properties are used to customize the provider default schemes.
> B. If the API set it to null, use the the provider default schemes (including
> system properties customized default schemes).
> C. If the API set it to empty, don't use any schemes.
> D. if the API set it to 1+ scheme, use the API set schemes.
>
> With logic A, we don't have to describe both _system properties_ and the
> _provider default schemes_ each time when we talk about the interaction
> behaviors of them. And then we can simplify the 3 interactive factors into 2
> factors.
>
> Here is the general 3 interactive factors:
> 1. the API.
> 2. the System properties.
> 3. the provider default.
>
> Here is set 1 of the 2 interactive factors:
> 1. The System properties;
> 2. the provider default.
>
> Here is set 2 of the 2 interactive factors:
> 1. the API
> 2. the provider default.
>
> Then, we could describe set 1 and set 2 individually. I think it is easier
> to understand.
>
> Then, we could have the sections accordingly.
> For A, we have (for set 1 of the 2 interactive factors):
>
> * @implNote
> * Note that the underlying provider may define the default signature
> * schemes for each SSL/TLS/DTLS connection. Applications may also use
> * the {@systemProperty jdk.tls.client.SignatureSchemes} and/or
> * {@systemProperty jdk.tls.server.SignatureSchemes} system properties to
> * customize the provider-specific default signature schemes.
> ```
>
> For B, we have (for set 2 of the 2 interactive factors):
>
> * If the returned array is {@code null}, then the underlying
> * provider-specific default signature schemes will be used over the
> * SSL/TLS/DTLS connections.
>
>
> For C, we have (for set 2 of the 2 interactive factors):
>
> * If the returned array is empty (zero-length), then the signature scheme
> * negotiation mechanism is turned off for SSL/TLS/DTLS protocols, and
> * the connections may not be able to be established if the negotiation
> * mechanism is required by a certain SSL/TLS/DTLS protocol.
>
>
> For D, we have (for set 2 of the 2 interactive factors):
>
> * <p>
> * If the returned array is not {@code null} or empty (zero-length),
> * then the signature schemes in the returned array will be used over
> * the SSL/TLS/DTLS connections.
>
>
> That's the current description we have. That's, in order to explain behavior
> of the null, empty and 1+ schemes setting, I cut the sentence into 4 sections
> above.
>
> I understand it could be confusing when multiple facts are involved. It may
> be clear if re-org the description. What do you think of the following
> descriptions?
>
> In the get method:
>
> * <p>
> * Note that the underlying provider may define the default signature
> schemes for
> * each SSL/TLS/DTLS connection. Applications may also use the
> {@systemProperty
> * jdk.tls.client.SignatureSchemes} and/or {@systemProperty
> * jdk.tls.server.SignatureSchemes} system properties to customize the
> * provider-specific default signature schemes.
> * <p>
> * The set of signature schemes that will be used over the SSL/TLS/DTLS
> * connections is determined by the returned array of this method and the
> * underlying provider-specific default signature schemes.
> * <p>
> * If the returned array is {@code null}, then the underlying
> * provider-specific default signature schemes will be used over the
> * SSL/TLS/DTLS connections.
> * <p>
> * If the returned array is empty (zero-length), then the signature scheme
> * negotiation mechanism is turned off for SSL/TLS/DTLS protocols, and
> * the connections may not be able to be established if the negotiation
> * mechanism is required by a certain SSL/TLS/DTLS protocol.
> * <p>
> * If the returned array is not {@code null} or empty (zero-length),
> * then the signature schemes in the returned array will be used over
> * the SSL/TLS/DTLS connections.
>
>
> and similarly, in the set method:
>
> * <p>
> * Note that the underlying provider may define the default signature
> * schemes for each SSL/TLS/DTLS connection. Applications may also use
> * the {@systemProperty jdk.tls.client.SignatureSchemes} and/or
> * {@systemProperty jdk.tls.server.SignatureSchemes} system properties to
> * customize the provider-specific default signature schemes.
> * <p>
> * The set of signature schemes that will be used over the SSL/TLS/DTLS
> * connections is determined by the input parameter {@code
> signatureSchemes} array
> * and the underlying provider-specific default signature schemes.
> * <p>
> * If the input parameter {@code signatureSchemes} array is {@code null},
> * then the underlying provider-specific default signature schemes will
> * be used over the SSL/TLS/DTLS connections.
> * <p>
> * If the input parameter {@code signatureSchemes} array is empty
> * (zero-length), then the signature scheme negotiation mechanism is
> * turned off for SSL/TLS/DTLS protocols, and the connections may not be
> * able to be established if the negotiation mechanism is required by a
> * certain SSL/TLS/DTLS protocol.
> * <p>
> * If the input parameter {@code signatureSchemes} array is not {@code
> null}
> * or empty (zero-length), then the signature schemes specified in the
> * {@code signatureSchemes} array will be used over the SSL/TLS/DTLS
> * connections.
I see your points. Were you proposing that this text would all be normative
text? If so, I don't think that is correct, as the system properties are
implementation specific. What might work is if you take the first paragraph and
move it to the end of the text above as an @implNote:
> * @implNote
> * Note that the underlying provider may define the default signature
> * schemes for each SSL/TLS/DTLS connection. Applications may also use
> * the {@systemProperty jdk.tls.client.SignatureSchemes} and/or
> * {@systemProperty jdk.tls.server.SignatureSchemes} system properties to
> * customize the provider-specific default signature schemes.
I would probably use the word "override" instead of "customize". Customize
sounds like you can change some of the defaults and leave others in place.
I think you should also consider adding this sentence to the end of each of the
paragraphs when the input is an empty array or an array of 1+: "This parameter
will override the underlying provider-specific default signature schemes."
Finally, to avoid duplication of text, I would only add this text to the
`setSignatureSchemes` method, and in the `getSignatureSchemes` method, add
something like: "See {@link setSignatureSchemes} for specific details on how
the parameters are used in SSL/TLS/DTLS connections."
-------------
PR: https://git.openjdk.java.net/jdk/pull/7252
