Java 6173 CSFLE/QE Support for HTTP Proxies

[strogiyotec]

Java 6173 CSFLE/QE Support for HTTP Proxies

The first iteration - #2042 I completely missed the scope doc that suggests that implementing http proxy + http proxy connect in the driver side in discouraged

This iteration implements the callback , specifically it adds kmsConnectCallback: the application supplies the connection, and the driver negotiates TLS with the KMS host over it.

API

KmsConnectCallback viaProxy = context -> {
    Socket socket = new Socket();
    int timeout = (int) context.getTimeoutMillis();
    socket.connect(new InetSocketAddress("proxy.example.com", 8080), timeout);
    socket.setSoTimeout(timeout);

    String target = context.getServerAddress().getHost() + ":" + context.getServerAddress().getPort();
    socket.getOutputStream().write(
            ("CONNECT " + target + " HTTP/1.1\r\nHost: " + target + "\r\n\r\n").getBytes(US_ASCII));
    readAndCheckProxyResponse(socket.getInputStream());   // application's code

    return socket;   // the driver adds TLS
};

ClientEncryptionSettings.builder()
        .keyVaultNamespace("keyvault.datakeys")
        .kmsProviders(kmsProviders)
        .kmsConnectCallback(viaProxy)
        .build();

This implementation does not support reactive driver because the ProxySetting does not support reactive driver either see jira.mongodb.org/browse/JAVA-5205

AI Policy

Claude helped me to implement KmsSocketConnector.java and write test cases

[evergreen-ci-prod]

There is an existing patch(es) for this commit SHA:

• Evergreen patch with PR

Please note that the status that is posted is not in the context of this PR but rather the (latest) existing patch and that may affect some tests that may depend on the particular PR. If your tests do not rely on any PR-specific values (like base or head branch name) then your tests will report the same status. If you would like a patch to run in the context of this PR and abort the other(s), comment 'evergreen retry'.

[codeowners-service-app]

Assigned vbabanin for team dbx-java because stIncMale is out of office.

[Copilot]

Pull request overview

Adds kmsConnectCallback support for routing synchronous CSFLE/QE KMS connections through application-managed sockets such as HTTP proxy tunnels.

Changes:

• Adds the public callback/context APIs and encryption settings.
• Implements synchronous TLS negotiation over callback-provided sockets.
• Rejects callbacks in reactive clients and adds unit/functional coverage.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
driver-core/src/main/com/mongodb/KmsConnectCallback.java	Defines the callback API.
driver-core/src/main/com/mongodb/KmsConnectContext.java	Provides KMS target and timeout context.
driver-core/src/main/com/mongodb/AutoEncryptionSettings.java	Adds callback configuration for automatic encryption.
driver-core/src/main/com/mongodb/ClientEncryptionSettings.java	Adds callback configuration for explicit encryption.
driver-core/src/test/unit/com/mongodb/KmsConnectCallbackSettingsTest.java	Tests callback settings propagation.
driver-sync/src/main/com/mongodb/client/internal/KmsSocketConnector.java	Establishes direct or callback-backed TLS sockets.
driver-sync/src/main/com/mongodb/client/internal/KeyManagementService.java	Integrates callbacks and operation timeouts.
driver-sync/src/main/com/mongodb/client/internal/Crypts.java	Propagates callbacks into KMS handling.
driver-sync/src/test/unit/com/mongodb/client/internal/KeyManagementServiceTest.java	Tests KMS timeout calculation.
driver-sync/src/test/functional/com/mongodb/client/AbstractClientSideEncryptionKmsConnectCallbackProseTest.java	Adds HTTP/HTTPS proxy prose tests.
driver-sync/src/test/functional/com/mongodb/client/ClientSideEncryptionKmsConnectCallbackProseTest.java	Supplies the synchronous test implementation.
driver-sync/src/test/functional/com/mongodb/client/AbstractClientSideEncryptionKmsTlsTest.java	Tests hostname verification through callbacks.
driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/crypt/Crypts.java	Rejects unsupported reactive callbacks.
driver-reactive-streams/src/test/unit/com/mongodb/reactivestreams/client/internal/crypt/CryptsKmsConnectCallbackNotSupportedTest.java	Tests reactive rejection behavior.
driver-scala/src/main/scala/org/mongodb/scala/package.scala	Mirrors the new public types in Scala.
config/spotbugs/exclude.xml	Updates the moved SSL null-check exclusion.

Suppressed comments (1)

driver-sync/src/test/functional/com/mongodb/client/AbstractClientSideEncryptionKmsConnectCallbackProseTest.java:218

• This does not implement prose Case 5: passing null means the callback never records its timeout, and the test only checks that the request succeeds. A regression that passes an incorrect timeout would therefore go undetected. Capture the value and assert that it is non-zero as the prose test requires.

        try (ClientEncryption clientEncryption = createClientEncryption(clientEncryptionSettingsBuilder(1000L)
                .kmsConnectCallback(proxyConnectCallback(false, null))
                .build())) {

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jyemin]

LGTM!