Skip to content

Commit ec974dd

Browse files
JinwooHwangJinwooHwang
authored
GEODE-10561: Add Documentation for Public CA Client Authentication EKU Migration (#7989)
* documentation * Sheila's review * GEODE-10561: fix wording in CA topology section
1 parent 932f06c commit ec974dd

6 files changed

Lines changed: 1019 additions & 0 deletions

‎geode-book/master_middleman/source/subnavs/geode-subnav.erb‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,20 @@ limitations under the License.
157157
<li>
158158
<a href="/docs/guide/<%=vars.product_version_nodot%>/security/ssl_example.html">SSL Sample Implementation</a>
159159
</li>
160+
<li class="has_submenu">
161+
<a href="/docs/guide/<%=vars.product_version_nodot%>/security/public_ca_client_auth_eku_mitigations.html">Mitigating Public CA Client Auth EKU Changes</a>
162+
<ul>
163+
<li>
164+
<a href="/docs/guide/<%=vars.product_version_nodot%>/security/ssl_internal_ca_mtls.html">Internal / Enterprise CA for mTLS</a>
165+
</li>
166+
<li>
167+
<a href="/docs/guide/<%=vars.product_version_nodot%>/security/ssl_server_only_tls_alt_auth.html">Server-only TLS + Alternative Client Auth</a>
168+
</li>
169+
<li>
170+
<a href="/docs/guide/<%=vars.product_version_nodot%>/security/ssl_hybrid_public_server_private_client.html">Hybrid: Public-CA Server + Private-CA Client</a>
171+
</li>
172+
</ul>
173+
</li>
160174
</ul>
161175
</li>
162176
<li>

‎geode-docs/security/public_ca_client_auth_eku_mitigations.html.md.erb‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: Mitigating Public CA Client Authentication EKU Changes
3+
---
4+
5+
<!--
6+
Licensed to the Apache Software Foundation (ASF) under one or more
7+
contributor license agreements. See the NOTICE file distributed with
8+
this work for additional information regarding copyright ownership.
9+
The ASF licenses this file to You under the Apache License, Version 2.0
10+
(the "License"); you may not use this file except in compliance with
11+
the License. You may obtain a copy of the License at
12+
13+
http://www.apache.org/licenses/LICENSE-2.0
14+
15+
Unless required by applicable law or agreed to in writing, software
16+
distributed under the License is distributed on an "AS IS" BASIS,
17+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18+
See the License for the specific language governing permissions and
19+
limitations under the License.
20+
-->
21+
22+
Public Certificate Authorities (CAs) are removing or restricting issuance
23+
of the Client Authentication Extended Key Usage (EKU) from publicly-issued
24+
leaf certificates. Deployments that relied on public-CA-signed client
25+
certificates for mutual TLS (mTLS) client authentication must migrate to an
26+
alternative approach.
27+
28+
**This guide does not apply to you if:**
29+
30+
- Your deployment already uses an enterprise or internal CA for mTLS, **or**
31+
- Your deployment uses a public CA chain that includes client CA certificates
32+
and those certificates are unaffected by the EKU policy change.
33+
34+
**This guide applies to you if:**
35+
36+
- Your deployment used public-CA-issued client certificates for mTLS, **and**
37+
- Those certificates no longer contain the `clientAuth` EKU, or the CA will
38+
no longer issue them.
39+
40+
## <a id="eku_background" class="no-quick-link"></a>Background
41+
42+
<%=vars.product_name%> uses JSSE (`SSLContext`, `SSLEngine`, `SSLSocket`,
43+
`TrustManager`, `KeyManager`) for all TLS connections. Per-component SSL
44+
configuration is resolved via `SSLConfig` and `SSLConfigurationFactory`.
45+
Keystores and truststores are watched at runtime by `FileWatchingX509ExtendedKeyManager`
46+
and `FileWatchingX509ExtendedTrustManager`, backed by `PollingFileWatcher`,
47+
which reloads credential material when files change on disk without a server
48+
restart.
49+
50+
When a Java TLS peer presents a certificate in a role that requires client
51+
authentication, the JSSE stack checks that the certificate's Extended Key Usage
52+
extension contains `id-kp-clientAuth` (OID 1.3.6.1.5.5.7.3.2). If that OID is
53+
absent, the TLS handshake fails with an authentication error. Because public CAs
54+
are ceasing to include this OID in publicly-issued leaf certificates,
55+
public-CA-signed client certificates can no longer be used for mTLS.
56+
57+
## <a id="eku_decision_guide" class="no-quick-link"></a>Choosing a Mitigation
58+
59+
Select the option that best fits your operational environment:
60+
61+
| Scenario | Recommended option |
62+
|---|---|
63+
| You can operate or integrate with an enterprise PKI | [Internal / Enterprise CA for mTLS](ssl_internal_ca_mtls.html) |
64+
| Client certificates are impractical; you prefer credential-based auth | [Server-only TLS + alternative client authentication](ssl_server_only_tls_alt_auth.html) |
65+
| Servers must use a public-CA certificate (external trust) but clients need a controllable identity | [Hybrid: public-CA server certificates + private-CA client certificates](ssl_hybrid_public_server_private_client.html) |
66+
67+
You may combine approaches: for example, running the hybrid model in production
68+
while temporarily using server-only TLS + credentials during a phased migration.
69+
70+
## <a id="eku_common_features" class="no-quick-link"></a>Key <%=vars.product_name%> Features Used by All Mitigations
71+
72+
- **Per-component SSL configuration** — `ssl-enabled-components` and associated
73+
`ssl-keystore` / `ssl-truststore` properties allow independent TLS settings for
74+
`cluster`, `server`, `locator`, `gateway`, `jmx`, and `web` components. See
75+
[Configuring SSL](implementing_ssl.html).
76+
- **`ssl-require-authentication`** — controls whether servers require client
77+
certificates during the TLS handshake. Set to `true` for mTLS; `false` for
78+
server-only TLS.
79+
- **File-watching keystore reload** — `FileWatchingX509ExtendedKeyManager` and
80+
`FileWatchingX509ExtendedTrustManager` automatically reload keystore and
81+
truststore files when they are atomically replaced on disk. Configure by
82+
pointing `ssl-keystore` / `ssl-truststore` at the watched path.
83+
- **Pluggable authentication** — `AuthInitialize` (client-side credential
84+
injection) and `SecurityManager` (server-side enforcement) support
85+
username/password, token, and custom authentication without requiring client
86+
certificates.
87+
88+
## <a id="eku_migration_checklist" class="no-quick-link"></a>Migration Checklist
89+
90+
1. **Inventory** — Identify all clients, members, and locators that present a
91+
public-CA-signed client certificate during TLS handshake.
92+
2. **Choose a mitigation** — Use the decision table above to select an approach
93+
(or a phased combination).
94+
3. **Provision credentials** — Issue replacement certificates from an internal/
95+
private CA, or configure application-layer authentication.
96+
4. **Update truststores** — Update server truststores to include the new CA(s)
97+
before rotating client credentials to avoid handshake failures during the
98+
rollout.
99+
5. **Deploy and verify** — Roll out the new configuration component by component.
100+
Use `openssl s_client` and JSSE debug logging (`-Djavax.net.debug=ssl,handshake`)
101+
to verify handshake behavior at each step.
102+
6. **Remove old credentials** — Once all clients have migrated, remove the
103+
public-CA trust anchor from server truststores if it is no longer needed.
104+
105+
## <a id="eku_quick_verify" class="no-quick-link"></a>Quick Verification
106+
107+
Test that the server certificate chain and (if applicable) client certificate
108+
chain are seen and accepted:
109+
110+
```bash
111+
# Server-only TLS verification (no client certificate required)
112+
openssl s_client -connect geode-server.example.com:10334 -showcerts
113+
114+
# mTLS verification (present client cert and key)
115+
openssl s_client -connect geode-server.example.com:10334 \
116+
-cert client.crt -key client.key \
117+
-CAfile server-trust-anchor.pem -showcerts
118+
```
119+
120+
Enable JSSE debug on client JVMs for detailed handshake tracing:
121+
122+
```bash
123+
java -Djavax.net.debug=ssl,handshake -jar my-geode-client.jar
124+
```
125+
126+
## <a id="eku_mitigation_pages" class="no-quick-link"></a>Mitigation Guides
127+
128+
- **[Internal / Enterprise CA for mTLS](ssl_internal_ca_mtls.html)**
129+
130+
Run an internal or enterprise CA (offline root + issuing intermediate, or
131+
enterprise PKI automation such as HashiCorp Vault or Smallstep) to issue
132+
client certificates. The internal CA is the trust anchor for client
133+
authentication; public CA EKU policies are irrelevant.
134+
135+
- **[Server-only TLS + Alternative Client Authentication](ssl_server_only_tls_alt_auth.html)**
136+
137+
Retain TLS encryption for all connections but disable mandatory client
138+
certificate authentication. Authenticate clients at the application layer
139+
using <%=vars.product_name%>'s existing `AuthInitialize` / `SecurityManager`
140+
framework (username/password, tokens, or a custom implementation).
141+
142+
- **[Hybrid: Public-CA Server Certs + Private-CA Client Certs](ssl_hybrid_public_server_private_client.html)**
143+
144+
Keep server certificates signed by a public CA (preserving external trust)
145+
while issuing client certificates from an internal/private CA. Server
146+
truststores include the private CA; client truststores use the public CA
147+
(or the system trust store) for server certificate validation.

0 commit comments

Comments
 (0)