JinwooHwang opened a new pull request, #7989:
URL: https://github.com/apache/geode/pull/7989
## Summary
This PR adds comprehensive documentation to guide Apache Geode users through
the upcoming Public Certificate Authority policy change that removes the
`clientAuth` Extended Key Usage (EKU) from publicly-issued TLS certificates
(effective May 2026).
## Background
Major public Certificate Authorities (Let's Encrypt, DigiCert, etc.) will
stop including the `clientAuth` EKU in public TLS certificates starting May
2026. This change impacts Apache Geode deployments using mutual TLS (mTLS) with
public-CA-issued client certificates, as the Java TLS stack will reject
certificates lacking the required `clientAuth` EKU.
## Changes Included
### New Documentation Pages
1. **Public CA Client Authentication EKU Mitigations**
(`public_ca_client_auth_eku_mitigations.html.md.erb`)
- Overview of the three mitigation approaches
- Decision matrix to help users choose the right strategy
- Links to detailed implementation guides
2. **Internal/Enterprise CA for mTLS** (`ssl_internal_ca_mtls.html.md.erb`)
- Approach 1: Full mTLS using internal/private CA
- Certificate automation with HashiCorp Vault, Smallstep, ACME
- PKI architecture and lifecycle management
3. **Hybrid: Public-CA Server + Private-CA Client**
(`ssl_hybrid_public_server_private_client.html.md.erb`)
- Approach 2: Hybrid model combining public and private CAs
- Split trust architecture for servers and clients
- Configuration for both client/server and P2P topologies
4. **Server-only TLS + Alternative Client Auth**
(`ssl_server_only_tls_alt_auth.html.md.erb`)
- Approach 3: Application-layer authentication
- SecurityManager implementation examples
- Token-based and credential-based authentication
### Updated Documentation
- **SSL Overview** (`ssl_overview.html.md.erb`)
- Added links to new EKU mitigation documentation
- **Navigation** (`geode-subnav.erb`)
- Added menu entries for new documentation pages
## Technical Details
All three mitigation approaches have been:
- Validated in test environments
- Confirmed to work with both client/server and P2P cache topologies
- Tested with FileWatchingX509ExtendedKeyManager for zero-downtime
certificate rotation
- Verified with JSSE debug logging
## Documentation Quality
- Comprehensive step-by-step configuration examples
- Troubleshooting sections with common issues and resolutions
- Security considerations and best practices
- References to relevant source code locations
- Clear decision criteria for choosing between approaches
## Testing
The documentation has been:
- Built and previewed locally using Bookbinder
- Verified for correct rendering and formatting
- Checked for broken links and accurate technical content
- Reviewed against blog post source material for accuracy
## Migration Timeline
Users should begin planning migration well before May 2026 when the public
CA policy change takes effect. This documentation provides multiple migration
paths to accommodate different operational constraints and security
requirements.
## Related Issues
- GEODE-10561: Public CA Client Authentication EKU sunset documentation
## Checklist
- [x] New documentation follows Apache Geode documentation standards
- [x] All technical examples validated for correctness
- [x] Navigation updated to include new pages
- [x] Cross-references between related documentation pages added
- [x] Security considerations documented
- [x] Troubleshooting guidance included
- [x] Both client/server and P2P topologies covered
<!-- Thank you for submitting a contribution to Apache Geode. -->
<!-- In order to streamline review of your contribution we ask that you
ensure you've taken the following steps. -->
### For all changes, please confirm:
- [x] Is there a JIRA ticket associated with this PR? Is it referenced in
the commit message?
- [x] Has your PR been rebased against the latest commit within the target
branch (typically `develop`)?
- [x] Is your initial contribution a single, squashed commit?
- [x] Does `gradlew build` run cleanly?
- [ ] Have you written or updated unit tests to verify your changes?
- [ ] If adding new dependencies to the code, are these dependencies
licensed in a way that is compatible for inclusion under [ASF
2.0](http://www.apache.org/legal/resolved.html#category-a)?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
