Align SSLSocket and SSLEngine Javadocs

[Simone Bordet]

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!

-- 
Simone Bordet
---
Finally, no matter how good the architecture and design are,
to deliver bug-free software with optimal performance and reliability,
the implementation technique must be flawless.   Victoria Livschitz