Fix | Login TLS handshake hangs on Android (Conscrypt): read up to maxBytes during SSL handshake

[David Engel (David-Engel)]

Problem description

On Android (which uses Conscrypt as its default TLS provider), establishing a JDBC connection hangs during the login-phase TLS handshake and eventually fails. SQL Server performs a TLS handshake during login even when encrypt=false, so both encrypt=false and encrypt=true are affected. In a shipped (assertions-off) build the connect blocks until loginTimeout and throws SQLServerException: ... could not establish a secure connection ... Read timed out. In a debuggable build (where the Android Gradle Plugin / d8 force-enables Java assertions) it fails earlier with AssertionError: numMsgsRcvd:1 should be less than numMsgsSent:1 from TDSReader.readPacket — the same root cause, surfaced earlier by an assertion.

Root cause: TDSChannel.SSLHandshakeInputStream.readInternal(byte[], int, int) read exactly maxBytes (blocking across TDS packets) and always returned maxBytes, instead of reading up to maxBytes and returning the actual number of bytes read as the InputStream.read contract requires. SunJSSE reads the TLS handshake in small, exact record-sized chunks and never requests more than is available, so the defect is masked. Conscrypt issues a single large read (its buffer size, e.g. 16709 bytes); the driver then blocks trying to fill 16709 bytes while the server has already sent its complete handshake flight (~1.5 KB in one TDS packet) and is waiting for the client's next flight — a deadlock.

Fixes existing GitHub issue

Fixes #2979

Fix Description

In SSLHandshakeInputStream.readInternal, after ensureSSLPayload() guarantees at least one buffered TDS packet, read Math.min(maxBytes, tdsReader.available()) bytes and return the actual count instead of blocking for the full maxBytes. TDSReader.available() reports only non-blocking buffered bytes, so the handshake input stream now honors the read-up-to contract and hands each buffered chunk to the SSL engine, which can then advance the handshake. A FINEST log records when a short read occurs. There is no behavior change for SunJSSE, which already read within a single packet.

New Public APIs

None.

Testing

• Reproduced and fixed with the Android instrumented-test reproducer attached to Connection hangs during login TLS handshake on Android (Conscrypt) #2979 (Android 14 / API 34 emulator, Conscrypt). With the fix, both encrypt=false and encrypt=true connect successfully on both the release (assertions-off) and debug (assertions-on) variants.
• Desktop regression matrix (OpenJDK / SunJSSE) against the same SQL Server: encrypt=false and encrypt=true, with and without -ea, all continue to connect successfully — no change in the common path.
• Justification for the automated-test gap: the defect is TLS-provider-specific. The JVM-based test suite runs on SunJSSE, which reads the handshake in record-sized chunks and therefore cannot reproduce Conscrypt's single-large-read behavior, so a JVM unit/integration test cannot exercise the failing path. The existing encryption/connection integration tests continue to guard the SunJSSE path against regressions. Happy to add a targeted test if maintainers can suggest a supported way to inject a large-read SSL engine into the suite.
• ADO test runs:
  • https://sqlclientdrivers.visualstudio.com/mssql-jdbc/_build/results?buildId=160194&view=results
  • https://sqlclientdrivers.visualstudio.com/mssql-jdbc/_build/results?buildId=161468&view=results

[codecov]

Codecov Report

❌ Patch coverage is 77.77778% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.15%. Comparing base (76ac158) to head (8bf1850).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
...in/java/com/microsoft/sqlserver/jdbc/IOBuffer.java	77.77%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #2980      +/-   ##
============================================
- Coverage     59.25%   59.15%   -0.10%     
+ Complexity     5058     5023      -35     
============================================
  Files           153      153              
  Lines         36339    36343       +4     
  Branches       6645     6647       +2     
============================================
- Hits          21531    21499      -32     
+ Misses        11091    11088       -3     
- Partials       3717     3756      +39     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Fixes a TLS login-handshake deadlock affecting Android/Conscrypt by making the driver’s SSL handshake InputStream honor the InputStream.read(..) “read up to N bytes” contract, preventing the driver from blocking while trying to fill an oversized TLS-provider buffer.

Changes:

• Update SSLHandshakeInputStream.readInternal(..) to read up to maxBytes based on currently buffered TDS payload, returning the actual count instead of always blocking for/returning maxBytes.
• Relax SSLHandshakeOutputStream.endMessage() to no-op when no handshake output message is currently started (avoids assertion failures during multi-packet handshake responses).

[Mahendra Chavan (machavan)]

Hopefully there are no side effects on the existing mechanism/behavior for SunJSSE path.

[David Engel (David-Engel)]

Oracle and IBM runtime runs showed no regressions. Should be pretty safe.

ADO test runs:
https://sqlclientdrivers.visualstudio.com/mssql-jdbc/_build/results?buildId=160194&view=results
https://sqlclientdrivers.visualstudio.com/mssql-jdbc/_build/results?buildId=161468&view=results