RFR: 8280494: (D)TLS signature schemes [v13]
Xue-Lei Andrew Fan
xuelei at openjdk.java.net
Wed Feb 9 18:33:15 UTC 2022
On Wed, 9 Feb 2022 14:33:11 GMT, Sean Mullan <mullan at openjdk.org> wrote:
>> 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."
Thank you for the word-smithing.
The use of signature schemes in the TLS implementation depends on the getSignatureSchemes() method. In the getSignatureSchemes() methods, there are more cases described such as the signature schemes for populated objects and pre-populated objects. So I have the text in the getSignatureSchemes(), and use the See-link in the setSignatureSchemes() instead.
Both the PR and CSR were updated.
-------------
PR: https://git.openjdk.java.net/jdk/pull/7252
More information about the security-dev
mailing list