On Tue, 8 Feb 2022 20:18:20 GMT, Sean Mullan <mul...@openjdk.org> wrote:
>>> Are you maybe saying that this method returns the value of the system
>>> properties if they are set?
>>
>> The return value of this method depends on the following specs:
>>
>> * If the {@link #setSignatureSchemes} method has not been called, this
>> * method should return the default signature schemes for connection
>> * populated objects, or {@code null} for pre-populated objects.
>> ```
>>
>> If the setSignatureSchemes() method has been called, the get method will
>> return the set values. I may miss this spec. But I think it is a common
>> sense that the getter method returns the values set with setter method. Let
>> me know if you would like to have an explicit clarification in the spec.
>
> 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.
-------------
PR: https://git.openjdk.java.net/jdk/pull/7252
