GEODE-10561: Add Documentation for Public CA Client Authentication EKU Migration

[JinwooHwang]

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

• New documentation follows Apache Geode documentation standards
• All technical examples validated for correctness
• Navigation updated to include new pages
• Cross-references between related documentation pages added
• Security considerations documented
• Troubleshooting guidance included
• Both client/server and P2P topologies covered

For all changes, please confirm:

• Is there a JIRA ticket associated with this PR? Is it referenced in the commit message?
• Has your PR been rebased against the latest commit within the target branch (typically develop)?
• Is your initial contribution a single, squashed commit?
• 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?