christophvw commented on code in PR #1089: URL: https://github.com/apache/tomcat/pull/1089#discussion_r4322402160
########## webapps/docs/ssl-howto.xml: ########## @@ -446,6 +446,99 @@ mailing list</a>.</p> </subsection> </section> +<section name="Automatic certificate selection and reloading"> + +<p>When a key store contains more than one certificate, Tomcat must choose which +one to present to clients, and certificates must be replaced before they expire. +Two features help to automate this so that a single configuration can be deployed +to many hosts without per-host customization: selection of a certificate by key +usage, and automatic reloading of renewed certificates.</p> + +<subsection name="Selecting a certificate by key usage"> + +<p>When a key store holds several certificates - for example one intended for TLS +server authentication alongside one intended for another purpose, which may share +the same Subject - Tomcat selects a certificate that is valid for TLS server +authentication. A certificate qualifies if its Extended Key Usage includes +<code>serverAuth</code> or <code>anyExtendedKeyUsage</code>, or if it has no +Extended Key Usage extension at all. Certificates that declare a different purpose, +such as client authentication, are ignored.</p> + +<p>Because of this, it is usually not necessary to set +<strong>certificateKeyAlias</strong>: Tomcat picks a usable server certificate +automatically. When <strong>certificateKeyAlias</strong> is set, only certificates +that share the Subject of that alias are considered.</p> + +<p>If no certificate valid for server authentication is found, the configured +alias (or, when none is configured, the first key in the store) is used unchanged, +so existing configurations are not affected.</p> + +</subsection> + +<subsection 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. See the +<a href="config/listeners.html">listener documentation</a> for the available +attributes.</p> + +</subsection> + +<subsection name="Example: 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 (this store type +requires Java 17.0.5, 19, or a later release; earlier releases only provide Review Comment: please change to Java 17.0.17, 21.0.9 or later. https://bugs.openjdk.org/browse/JDK-8340661 https://github.com/openjdk/jdk/pull/16687 -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
