KNOX-3359 - Support Single-Purpose EKU Certificates by moresandeep · Pull Request #1291 · apache/knox

moresandeep · 2026-07-01T19:27:51Z

(It is very important that you created an Apache Knox JIRA for this change and that the PR title/commit message includes the Apache Knox JIRA ID!)

KNOX-3359 - Support Single-Purpose EKU Certificates

Public CAs are retiring dual purpose certificates that carry both serverAuth and clientAuth Extended Key Usages. This change allows Knox to use two separate keystores, one for its inbound TLS server identity (serverAuth only) and one for its outbound mTLS client identity (clientAuth only).

What changes were proposed in this pull request?

gateway.tls.single.eku.enabled — new toggle that activates single-EKU mode. Off by default all existing behavior is unchanged when it is off.
GatewayConfigImpl / GatewayConfig — new config accessors for the HTTP client keystore path, type, alias, and truststore, startup validation (validateSingleEkuConfig) that fails fast if any prerequisite is missing or misconfigured (wrong alias type, wrong EKU, missing truststore). Knox refuses to start rather than silently falling back to the server identity.
DefaultKeystoreService.getKeystoreForHttpClient() / DefaultAliasService.getHttpClientKeyPassphrase() — load the dedicated client-identity keystore using the configured path, type, and alias.
DefaultHttpClientFactory.createSSLContext() — when single-EKU is on and two-way SSL is active, loads the client keystore instead of the gateway server keystore.
JettySSLService - enforce that the server keystore alias carries only serverAuth in single-EKU mode.
gateway.httpclient.twoWaySsl.enabled — new global flag to activate outbound mTLS across all dispatches without requiring use-two-way-ssl="true" on every service definition. Automatically defaults to true when gateway.tls.single.eku.enabled=true, so enabling single-EKU mode is a single config change with sane defaults.

Notes

Note that this feature is independent of mTLS. mTLS can be configured using the existing properties

gateway.client.auth.needed | default false | comments: INBOUND mTLS
gateway.httpclient.twoWaySsl.enabled | default false | comments: OUTBOUND mTLS

How was this patch tested?

Unit Tests

Unit tests added for GatewayConfigImpl, DefaultKeystoreService, DefaultAliasService, JettySSLService, and DefaultHttpClientFactory covering the single-EKU happy path, wrong-passphrase fail-closed, one-way SSL guard (no client cert presented), and the global flag OR-ing with the per-dispatch parameter.

Manual Tests

Tested the following scenarios

Happy path: clientAuth cert + basic auth → 200, backend sees knox-client

curl -sk --cert curl-client.crt --key curl-client.key -u guest:guest-password https://localhost:8443/gateway/sandbox/testmtls/hello

{"service":"test-https-backend","path":"/hello?user.name=guest","authenticated_client_cn":"knox-client","message":"mTLS OK -- backend saw your client certificate"}

No client cert → inbound TLS handshake rejected (client.auth.needed=true)

curl -iku guest:guest-password https://localhost:8443/gateway/sandbox/testmtls/hello-

curl: (56) LibreSSL SSL_read: LibreSSL/3.3.6: error:1404C412:SSL 
routines:ST_OK:sslv3 alert bad certificate, errno 0

serverAuth-ONLY cert presented as inbound client cert → rejected (EKU check)

curl -ik --cert knox-server.crt --key knox-server.key -u guest:guest-password https://localhost:8443/gateway/sandbox/testmtls/hello

curl: (55) Send failure: Broken pipe

Valid client cert but NO credentials → TLS ok, HTTP 401 from Knox'

curl -ik --cert curl-client.crt --key curl-client.key https://localhost:8443/gateway/sandbox/testmtls/hello

HTTP/1.1 401 Unauthorized
Date: Wed, 01 Jul 2026 18:56:23 GMT
WWW-Authenticate: BASIC realm="application"
Content-Length: 0

Integration Tests

Added new integration tests

UI changes

NA

Design for separate client/server keystores and truststores to support single-purpose (single-EKU) certificates, gated behind an explicit gateway.tls.single.eku.enabled toggle with fail-fast startup validation. # Conflicts: # gateway-server/src/test/java/org/apache/knox/gateway/services/token/impl/AliasBasedTokenStateServiceTest.java

…ulting to true when single-EKU is on wire gateway.httpclient.twoWaySsl.enabled into DefaultHttpClientFactory; update log message

github-actions · 2026-07-06T11:30:35Z

Test Results

36 tests 36 ✅ 5s ⏱️
3 suites 0 💤
3 files 0 ❌

Results for commit 6945815.

♻️ This comment has been updated with latest results.

pzampino · 2026-07-07T17:44:37Z

+  public boolean isHttpClientTwoWaySslEnabled() {
+    String configured = get(HTTP_CLIENT_TWO_WAY_SSL_ENABLED);
+    if (configured != null) {
+      return Boolean.parseBoolean(configured);


I believe parseBoolean returns false for null, so I think you could eliminate the null check unless this method intends to fall back to isSingleEkuEnabled() IFF two-way SSL is NOT explicitly configured. Is that the intent here? If so, this only applies to HTTP clients employed by Knox?

Yeah, this method intends to fall back to isSingleEkuEnabled() this is because, for single EKU feature to work two-way-ssl is required as a result if two-way-ssl is not configured we default it to isSingleEkuEnabled().
So, if someone turned on isSingleEkuEnabled() then they not need to specifically turn on two-way-ssl as those go hand in hand.

pzampino · 2026-07-07T17:55:35Z

+    // 1. Outbound client-identity keystore must be configured and contain the configured key entry.
+    String clientKeystorePath = config.getHttpClientKeystorePath();
+    if (clientKeystorePath == null || clientKeystorePath.isEmpty()) {
+      throw new ServiceLifecycleException("Single-EKU mode is enabled (" + GatewayConfig.TLS_SINGLE_EKU_ENABLED


Is it not valid to have single-purpose certs enabled WITHOUT two-way SSL, thus not requiring the client identity keystore?

single-purpose certs need to have two-way SSL, this was pointed out by @smolnar82 in his offline review

This means Knox in "single-EKU mode" will start happily with a client keystore holding a serverAuth-only or dual-purpose cert — exactly the misconfiguration this feature exists to catch. The validation gives a false sense of assurance, and the tests reflect the gap (JettySSLServiceTest covers path-missing, truststore-missing, client-auth-disabled, and cert-not-a-key, but there is no EKU test).

pzampino · 2026-07-07T17:56:53Z

+
+    // 2. Inbound client authentication must be enforced (server truststore + client-auth).
+    if (config.getTruststorePath() == null) {
+      throw new ServiceLifecycleException("Single-EKU mode is enabled but the server truststore ("


Again, is it not permissible to have single-purpose certs enabled for Knox without assuming/requireing two-way SSL?

Correct, two-way-SSL is required for this feature. But this change specifically ensures that we have truststore configured for clients who will talk to us over mTLS.

pzampino · 2026-07-07T17:57:35Z

+      throw new ServiceLifecycleException("Single-EKU mode is enabled but the server truststore ("
+          + GatewayConfig.GATEWAY_TRUSTSTORE_PATH + ") is not configured. Server will not start.");
+    }
+    if (!config.isClientAuthNeeded() && !config.isClientAuthWanted()) {


Here too it seems two-way SSL is required just because single-purpose certs are enabled.

I don't think support for single-purpose certs necessitates mTLS; I think they are orthogonal concerns, but I may be wrong.

You might be right, let me check.

…uses

…eystore fallback

…ootstrap

moresandeep requested review from hanicz and smolnar82 and removed request for smolnar82 July 1, 2026 19:27

moresandeep self-assigned this Jul 1, 2026

smolnar82 self-requested a review July 2, 2026 07:30

smolnar82 added the certificate label Jul 2, 2026

moresandeep added 3 commits July 6, 2026 07:23

KNOX-3359: Add gateway.httpclient.twoWaySsl.enabled global flag, defa…

8513f4c

…ulting to true when single-EKU is on wire gateway.httpclient.twoWaySsl.enabled into DefaultHttpClientFactory; update log message

Fix build

53ceb43

moresandeep force-pushed the KNOX-3359 branch from cd682a0 to 53ceb43 Compare July 6, 2026 11:24

moresandeep added 3 commits July 6, 2026 10:42

Added proper client and server identity validation + some minor changes

e535b31

Update knox credentials

29993ee

Minor changes

5582728

moresandeep requested a review from pzampino July 7, 2026 14:52

pzampino reviewed Jul 7, 2026

View reviewed changes

moresandeep added 10 commits July 7, 2026 14:23

Wire up e2e tests for single EKU feature

69a38ee

FIx broken e2e tests

6ca6ee2

KNOX-3359: Decouple outbound two-way SSL default from single-EKU

c6ea763

KNOX-3359: Re-scope single-EKU validation to validate only what mTLS …

875a162

…uses

KNOX-3359: Add single-EKU-without-mTLS integration scenario

ff19db3

KNOX-3359: Document single-EKU / mTLS independence and config scenarios

bf4c4e2

KNOX-3359: Make X509CertificateUtil.generateCertificate EKU-aware

e722097

KNOX-3359: EKU-aware self-signed generation + single-EKU httpclient k…

81cd047

…eystore fallback

KNOX-3359: Self-bootstrap single-EKU identities at startup with logging

69b41b7

KNOX-3359: Simplify single-EKU no-mTLS integration scenario to self-b…

6945815

…ootstrap

moresandeep requested a review from pzampino July 8, 2026 18:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

KNOX-3359 - Support Single-Purpose EKU Certificates#1291

KNOX-3359 - Support Single-Purpose EKU Certificates#1291
moresandeep wants to merge 16 commits into
apache:masterfrom
moresandeep:KNOX-3359

moresandeep commented Jul 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 6, 2026 •

edited

Loading

Uh oh!

pzampino Jul 7, 2026

Uh oh!

moresandeep Jul 7, 2026

Uh oh!

pzampino Jul 7, 2026

Uh oh!

moresandeep Jul 7, 2026

Uh oh!

pzampino Jul 7, 2026

Uh oh!

moresandeep Jul 7, 2026 •

edited

Loading

Uh oh!

pzampino Jul 7, 2026

Uh oh!

moresandeep Jul 7, 2026

Uh oh!

pzampino Jul 7, 2026

Uh oh!

moresandeep Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

moresandeep commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes were proposed in this pull request?

Notes

How was this patch tested?

Unit Tests

Manual Tests

Happy path: clientAuth cert + basic auth → 200, backend sees knox-client

No client cert → inbound TLS handshake rejected (client.auth.needed=true)

serverAuth-ONLY cert presented as inbound client cert → rejected (EKU check)

Valid client cert but NO credentials → TLS ok, HTTP 401 from Knox'

Integration Tests

UI changes

Uh oh!

github-actions Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

moresandeep Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

moresandeep commented Jul 1, 2026 •

edited

Loading

github-actions Bot commented Jul 6, 2026 •

edited

Loading

moresandeep Jul 7, 2026 •

edited

Loading