Align SSLSocket and SSLEngine Javadocs

[Xuelei Fan]

Hi Simone,

I see your point now.  I filed a bug for the tracking:
     https://bugs.openjdk.java.net/browse/JDK-8209992

Thanks,
Xuelei


On 8/27/2018 7:22 AM, Simone Bordet wrote:
> Xuelei,
> 
> On Mon, Aug 27, 2018 at 4:00 PM Xuelei Fan <xuelei.fan at oracle.com> wrote:
>>
>> H Simone,
>>
>> There is no change for the SSLSocket.startHandshake() and
>> SSLEngine.beginHandshake() specification.  They are can be used for new
>> handshake and key update.
>>
>> We want the specification independent from TLS versions as much as
>> possible.  An application developer only need to know the
>> functionalities, but not necessarily to understand the TLS protocol details.
>>
>> For TLS 1.2 and prior versions, the key update is performed with
>> renegotiation;  for TLS 1.3, it is the KeyUpdate post-handshake.
> 
> Perhaps I was not clear. I'm not talking about the specification (what
> the method does), just about the Javadoc.
> A developer needs to know if calling a method causes a renegotiation or not :)
> 
> Would be great if your paragraph above ("For TLS 1.2 and prior ...")
> would be included in the Javadoc.
> In particular for SSLEngine, the current Javadoc says:
> 
> "Initiates handshaking (initial or renegotiation) on this SSLEngine."
> 
> It does not mention TLS 1.3 and does not mention KeyUpdate, so would
> be great if it does.
> And would be great if beginHandshake() and startHandshake() have a
> very similar Javadoc.
> 
> Thanks!
>