This is an automated email from the ASF dual-hosted git repository. dsoumis pushed a commit to branch 9.0.x in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit bea56b287bdae0d6920e57f58f716cfcc0f2f913 Author: Dimitris Soumis <[email protected]> AuthorDate: Thu Oct 22 11:41:56 2026 +0300 Document Windows keystores and TLS certificate reloading --- webapps/docs/changelog.xml | 4 +++ webapps/docs/config/http.xml | 10 +++++-- webapps/docs/ssl-howto.xml | 70 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 81 insertions(+), 3 deletions(-) diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml index 55d8af1c26..0052acd639 100644 --- a/webapps/docs/changelog.xml +++ b/webapps/docs/changelog.xml @@ -681,6 +681,10 @@ <code>maxHttpRequestHeaderSize</code> attribute for the HTTP connector. (markt) </fix> + <update> + Documentation: Describe how to configure the Windows certificate store + and reload externally renewed TLS certificates. (dsoumis) + </update> </changelog> </subsection> <subsection name="Tribes"> diff --git a/webapps/docs/config/http.xml b/webapps/docs/config/http.xml index 6e64b7f8f4..b2b96a573f 100644 --- a/webapps/docs/config/http.xml +++ b/webapps/docs/config/http.xml @@ -2097,9 +2097,13 @@ <subsection name="Key store types"> <p>In addition to the standard key store types (JKS and PKCS12), most Java - runtimes support additional key store types such as Windows-ROOT, - Windows-My, DKS as well as hardware security modules. Generally, to use - these additional keystore types with a TLS Connector in Tomcat:</p> + runtimes support additional key store types such as Windows-MY, Windows-ROOT, + DKS as well as hardware security modules. On Windows, Windows-MY and + Windows-ROOT access the current user's certificate store, while + Windows-MY-LOCALMACHINE and Windows-ROOT-LOCALMACHINE access the local machine + store (reading the local machine store from a non-elevated process requires + Java 17.0.17, 21.0.9, 24 or later). Generally, to use these additional key + store types with a TLS Connector in Tomcat:</p> <ul> <li>Set the certificateKeystoreType and/or truststoreType Connector diff --git a/webapps/docs/ssl-howto.xml b/webapps/docs/ssl-howto.xml index 4d85e3ab31..79da61cb65 100644 --- a/webapps/docs/ssl-howto.xml +++ b/webapps/docs/ssl-howto.xml @@ -455,6 +455,76 @@ mailing list</a>.</p> </subsection> </section> +<section name="Reloading certificates before they expire"> + +<p>When certificates are renewed by an external process the +TLS certificate reload listener can load the renewed certificate without +restarting Tomcat. Add it to the <strong>Server</strong> element:</p> + +<source><![CDATA[<Server ...> + <Listener className="org.apache.catalina.security.TLSCertificateReloadListener" /> + ... +</Server>]]></source> + +<p>The listener periodically checks each certificate and, when one is within +<code>daysBefore</code> days of expiry (14 by default), reloads the associated +<code>SSLHostConfig</code> so that the renewed certificate is picked up. The +certificate must be renewed by another process; the listener does not renew it +or re-read <code>server.xml</code>. See the +<a href="config/listeners.html">listener documentation</a> for the available +attributes.</p> + +</section> + +<section name="Using the Windows certificate store"> + +<p>On Windows, Tomcat can read certificates directly from the Windows certificate +store. Set <strong>certificateKeystoreType</strong> to +<code>Windows-MY-LOCALMACHINE</code> for the local machine store, or to +<code>Windows-MY</code> for the current user's store. Reading the local machine +store from a Tomcat service that is not running with elevated privileges requires +Java 17.0.17, 21.0.9, 24, or a later release; on earlier releases the service must +run with elevated privileges. See +<a href="https://bugs.openjdk.org/browse/JDK-8313367";>JDK-8313367</a>. +AD CS autoenrollment can issue and renew the machine's certificates +automatically.</p> + +<p>A Windows certificate store may contain several certificates for the same +machine. Configure <strong>certificateKeyAlias</strong> with the alias exposed +by Java for the intended certificate. If no alias is configured, Tomcat uses the +first key read from the store, in an implementation-dependent order. The +following example uses the alias <code>tomcat</code>; replace it with the alias +of the certificate to use:</p> + +<source><![CDATA[<Connector port="8443" protocol="HTTP/1.1" + SSLEnabled="true" scheme="https" secure="true"> + <SSLHostConfig protocols="TLSv1.2,TLSv1.3"> + <Certificate certificateKeystoreType="Windows-MY-LOCALMACHINE" + certificateKeystoreFile="" + certificateKeystorePassword="" + certificateKeyAlias="tomcat" /> + </SSLHostConfig> +</Connector>]]></source> + +<p>When using the +<a href="#Reloading_certificates_before_they_expire">reload listener</a> +with a configured alias, ensure that the +renewed certificate is available under that alias. Reloading does not select a +different alias or prefer a certificate with a later expiry date.</p> + +<p>Two points to note:</p> + +<ul> + <li>The account running Tomcat must have read access to the certificate's private + key. A renewed certificate may use a new key that does not inherit this + access, so grant it as part of the enrollment or renewal process.</li> + <li>Setting a unique friendly name on the intended certificate can help identify + it for use as the <strong>certificateKeyAlias</strong>. Verify the alias + exposed by Java, especially when several certificates share a name.</li> +</ul> + +</section> + <section name="Using OCSP Certificates"> <p>Tomcat supports the Online Certificate Status Protocol (OCSP) to verify the status of client provided certificates for a sub-set of connector --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
