This is an automated email from the ASF dual-hosted git repository.
markt-asf pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push:
new b5ffcf6775 Improve docs for certificate reloading listener
b5ffcf6775 is described below
commit b5ffcf6775108c77966ef9508ded13f8ebd0c459
Author: Mark Thomas <[email protected]>
AuthorDate: Thu Nov 5 15:12:41 2026 +0000
Improve docs for certificate reloading listener
---
java/org/apache/tomcat/util/net/SSLContext.java | 6 ++++++
webapps/docs/ssl-howto.xml | 8 ++++++++
2 files changed, 14 insertions(+)
diff --git a/java/org/apache/tomcat/util/net/SSLContext.java
b/java/org/apache/tomcat/util/net/SSLContext.java
index 7adf3cbfdb..fdc72c1603 100644
--- a/java/org/apache/tomcat/util/net/SSLContext.java
+++ b/java/org/apache/tomcat/util/net/SSLContext.java
@@ -131,6 +131,12 @@ public interface SSLContext {
* alias, or the synthetic alias generated by the {@code NewSunX509}
key manager.</li>
* </ul>
* If no key manager names an alias, the configured (or default) alias is
returned.
+ * <p>
+ * For a key manager that Tomcat does not wrap, such as one from a FIPS
key manager factory, the result is the
+ * configured alias when that key manager holds it. A JSSE handshake may
nevertheless be served a different entry,
+ * as the key manager chooses per handshake, for example by key type or
server name, and this cannot be predicted.
+ * Certificate monitoring based on the result is therefore only reliable
if the configured alias identifies the
+ * certificate that is served.
*
* @param certificate The certificate configuration
*
diff --git a/webapps/docs/ssl-howto.xml b/webapps/docs/ssl-howto.xml
index d947388873..2157c10fc9 100644
--- a/webapps/docs/ssl-howto.xml
+++ b/webapps/docs/ssl-howto.xml
@@ -508,6 +508,14 @@ or re-read <code>server.xml</code>. See the
<a href="config/listeners.html">listener documentation</a> for the available
attributes.</p>
+<p>The listener checks the certificate Tomcat expects to be served: the one at
+the configured <strong>certificateKeyAlias</strong>, or the Windows-MY numbered
+duplicate that replaced it. When the key manager is not wrapped by Tomcat, for
+example one supplied by a FIPS provider, the key manager chooses the
certificate
+for each handshake and this can differ from the configured alias if the key
store
+holds several entries. The listener cannot detect that, so ensure that
+<strong>certificateKeyAlias</strong> identifies the certificate that is
served.</p>
+
</section>
<section name="Using the Windows certificate store">
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
