Skip to content

feat(kernel): add opt-in certificate revocation checks for kernel connections - #1072

Draft
cathleeny wants to merge 2 commits into
mainfrom
cathleeny/feat/kernel-certificate-revocation
Draft

cathleeny wants to merge 2 commits into
mainfrom
cathleeny/feat/kernel-certificate-revocation

Conversation

@cathleeny

Copy link
Copy Markdown
Collaborator

What type of PR is this?

  • Refactor
  • Feature
  • Bug Fix
  • Other

Description

Adds two opt-in TLS certificate revocation options for connections on the kernel backend (use_kernel=True):

  • _tls_check_certificate_revocation (default False) checks the server certificate chain against its CRLs.
  • _tls_accept_undetermined_revocation (default False) accepts a chain whose revocation status cannot be determined.

On the kernel path both flags are carried on SSLOptions. Each is forwarded to the kernel Session (as tls_check_certificate_revocation / tls_accept_undetermined_revocation) only when it is True. A default connection therefore sends the same kwargs as before, so it keeps working with kernel wheels that predate the setters.

Enabling either flag on the Thrift or SEA backend raises ValueError before any connection is made, since revocation is kernel-only.

The connect() docstring and the CHANGELOG describe the options.

Merge order. Enabling the options needs a databricks-sql-kernel release whose pyo3 Session accepts the two kwargs (databricks/databricks-sql-kernel#485). Merge this PR after that release. The default path does not depend on it.

How is this tested?

  • Unit tests

  • E2E Tests

  • Manually

  • N/A

  • Unit (tests/unit, -m "not realkernel"): 1403 passed, 5 skipped.

  • New tests:

    • a parametrized forwarding table in TestKernelTlsKwargs: flags are forwarded only when True;
    • a parametrized rejection test for the Thrift and SEA backends;
    • a test that both flags set to False don't trip the check on Thrift.
  • Real-wheel routing tests (-m realkernel) pass against databricks-sql-kernel==1.4.0 and against a wheel built from the kernel PR's bindings commit. The candidate wheel's Session accepts both kwargs.

  • Manual, with the candidate wheel against live DBSQL and Reyden warehouses on the kernel path:

    • with the options off, SELECT 1 passes;
    • with both options on, it passes;
    • with _tls_check_certificate_revocation=True alone, the connection fails as revocation-undetermined, because the CRL endpoints are unreachable from the test environment;
    • on Thrift, the option raises ValueError before any connection.

Related Tickets & Documents

  • databricks/databricks-sql-kernel#485 (adds the pyo3 and napi revocation setters).

This pull request and its description were written by Isaac.

…nections

Expose the kernel's TLS revocation policy to Python connections on the kernel
backend (use_kernel=True):

- _tls_check_certificate_revocation (default False) checks the server
  certificate chain against its CRLs.
- _tls_accept_undetermined_revocation (default False) accepts a chain whose
  revocation status cannot be determined.

The two flags are carried on SSLOptions. _kernel_tls_kwargs forwards each one to
the kernel Session as tls_check_certificate_revocation /
tls_accept_undetermined_revocation only when it is True, so default connections
still work with kernel wheels that predate the setters.

Enabling either flag on the Thrift or SEA backend raises ValueError before any
connection is made. Revocation is a kernel-only feature.

Tests cover the forwarding table in _kernel_tls_kwargs and the rejection on the
non-kernel backends. The existing realkernel routing tests still pass against
databricks-sql-kernel 1.4.0.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: Cathleen Yan <58714163+cathleeny@users.noreply.github.com>
@cathleeny
cathleeny marked this pull request as ready for review November 19, 2026 19:33

@peco-review-bot peco-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔀 Cross-reviewed: two independent reviews (Claude Opus 5.5 · GPT-6.1 Sol), checked by a judge model (Claude Sonnet 5.5).

Verdict: 2 Medium · 1 Low

Mostly sound: the default path is unchanged. There are 2 medium concerns: an explicit True on older kernel wheels fails without a clear error, and the flags are enabled by truthiness rather than an explicit True. The packaging floor for the kernel release also needs a bump before merge.

Comment thread src/databricks/sql/session.py Resolved
Require the _tls_check_certificate_revocation and _tls_accept_undetermined_revocation options to be real bools on both the Thrift/SEA and kernel paths, before any connection is made. A truthy non-bool such as "false" previously enabled accept-undetermined.

When revocation is requested on the kernel path, check that the installed databricks_sql_kernel.Session declares the tls revocation kwargs and raise NotSupportedError with an upgrade hint otherwise. The default path is unchanged and does not run the check.

Adds regression tests for the bool validation on both paths, the kernel-wheel capability error, and the connect() -> kernel ssl_options threading.

Co-authored-by: Isaac <no-reply@databricks.com>
Signed-off-by: Cathleen Yan <58714163+cathleeny@users.noreply.github.com>

@peco-review-bot peco-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔀 Cross-reviewed: two independent reviews (Claude Opus 5.5 · GPT-6.1 Sol), checked by a judge model (Claude Sonnet 5.5).

Verdict: 1 Nit

Looks good, with 1 low concern. The checks for bool type, kernel-only use and kernel capability run before any connection, and tests cover them. Nit: session.py:163 and the new connect() docstring line go over the 100-character limit.

Other findings

  • ⚪ Nit — The CHANGELOG entry, the connect() docstring and the NotSupportedError message all say "a newer wheel" without naming a minimum kernel version, and the pyproject floor stays at ^1.4.0. Once the kernel release that adds the setters exists, name that version in these places and raise the floor if appropriate. (Found by Claude Opus 5.5 · confirmed by the judge)

@cathleeny

Copy link
Copy Markdown
Collaborator Author

Thanks for the review on a549393. Two Nit items, not changed on the approved head per the policy for Low and Nit findings after approval:

  • Line length: src/databricks/sql/session.py:163 (the kernel-only ValueError message) and the connect() docstring line in src/databricks/sql/backend/kernel/client.py near the revocation description. Both lines came from the original feature commit 15275df. The a549393 fix does not touch them, and the repo's black and lint checks pass on that head.
  • Minimum kernel version: the CHANGELOG, the connect() docstring and the NotSupportedError message name a newer wheel without a version. The pyproject floor stays at ^1.4.0 until the kernel release that exposes the setters exists. The version will be named when that release is available, so this stays open for a human to confirm.

Automated reply from the driver feature factory (Isaac). Not reviewed by a human.

@cathleeny
cathleeny marked this pull request as draft November 19, 2026 20:18
@cathleeny

Copy link
Copy Markdown
Collaborator Author

Paused as a draft. This option works only on the kernel backend and can't merge until databricks/databricks-sql-kernel#485 merges and a kernel bindings release exports the revocation setters. This PR will be refreshed then: the kernel pins move to the merged commit or the release, and the PR is marked ready again. The code here has been reviewed and live-tested against a kernel build from #485.

Automated note from the driver feature factory (Isaac). Not reviewed by a human.

This branch was previously deployed

1 inactive deployment
azure-prod — a549393f Deployed Nov 19, 2026 by peco-review-bot[bot] via followup #2560
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant