Docs: 20.2: Document Java TLS error

[bdarnell]

Certain older versions of Java may get the error javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request when connecting to CockroachDB 20.2 (the issue is new in that version because we are supporting TLS 1.3 by default). We should document this, saying something like:

CockroachDB 20.2 is incompatible with some releases of Java, including OpenJDK 11 versions older than 11.0.7 and OpenJDK 13 versions older than 13.0.3. The recommended solution is to upgrade to the latest JDK release in a given branch. If that is not possible, as a workaround you can add the flag -Djdk.tls.client.protocols=TLSv1.2 when running the Java client processes.

This issue is the successor to #7258

[rafiss]

If that is not possible, as a workaround you can add the flag -Djdk.tls.client.protocols=TLSv1.2 when running the Java client processes.

I'm a bit confused by this. Shouldn't the setting be -Djdk.tls.client.protocols=TLSv1.3, since CockroachDB 20.2 uses TLS 1.3 by default?

[bdarnell]

CRDB and java both support both TLS 1.2 and 1.3. By default TLS will negotiate the highest version supported by both client and server, i.e. 1.3. But java's TLS 1.3 implementation has a bug (in certain releases) that makes it incompatible with Go's implementation of TLS 1.3, so we use -Djdk.tls.client.protocols=TLSv1.2 to disable TLS 1.3.

[ericharmeling]

@taroface

This PR might fix this issue: #7988

Not sure where else you were planning to document this workaround.

[taroface]

@ericharmeling I think that PR mostly fixes the issue, but we may want to cite the specific error and add this to a troubleshooting document somewhere. I can handle that as part of this issue.

Thank you!

[bdarnell]

A correction to #7988:

CockroachDB versions v20.1 and lower require TLS 1.2. By default, Java 8 uses TLS 1.2, but applications running on Java 9+ must be configured to run TLS 1.2. For example, when starting your app, use: $ java -Djdk.tls.client.protocols=TLSv1.2 appName

This isn't quite right: Newer versions of java must be configured to use TLS 1.2 when the server also supports TLS 1.3. No callout is necessary for CockroachDB 20.1 and older (because they don't support TLS 1.3 at all); everything will just work.

[ericharmeling]

Thanks @bdarnell!

See #8010 for the fix.