Renew the TLS certificate
Replace the TLS (SSL) certificate of your ISPICIO_E server: find out where TLS is terminated and renew the certificate in Apache Tomcat.
On this page
Check where TLS is terminated
- Tomcat terminates TLS itself: the file
server.xmlcontains a<Connector ... SSLEnabled="true">on port 443 or 8443 with keystore settings, or the elements<SSLHostConfig>and<Certificate>. Continue with the next section. - A reverse proxy runs in front of Tomcat (Apache HTTPD, Nginx, load balancer): replace the certificate there, not in Tomcat.
Renew the certificate in Tomcat
Which section applies depends on how the key and the certificate are stored. The first two sections cover the standard implementation (JSSE), the third covers APR/Native.
The commands are given for Linux and for Windows. On Windows, enter them in a Command Prompt that you opened as administrator. The examples assume the following values; replace them with the values of your installation:
| Value | Linux | Windows |
|---|---|---|
| Folder of the Tomcat installation | /path/to/tomcat |
C:\Program Files\Apache Software Foundation\Tomcat 11.0 |
| Name of the Tomcat service | tomcat |
Tomcat11 |
| HTTPS port of the connector | 8443 |
8443 |
You have the key and the certificate as PEM files
This is the case if the files come from Let’s Encrypt or from your certificate authority (CA).
-
Back up the configuration and the existing keystore.
Linux:
sudo cp /path/to/tomcat/conf/server.xml /path/to/tomcat/conf/server.xml.bak sudo cp /path/to/keystore.* /path/to/keystore.bak 2>/dev/null || trueWindows (change to the folder
conffirst; you only need the secondcopyline if a keystore already exists there):cd /d "C:\Program Files\Apache Software Foundation\Tomcat 11.0\conf" copy server.xml server.xml.bak copy tomcat.p12 tomcat.p12.bak -
Build a PKCS#12 file from the private key, the certificate and the chain. Set a password when prompted. You enter it in
server.xmlin the next step.Linux:
openssl pkcs12 -export \ -inkey privkey.pem \ -in cert.pem \ -certfile chain.pem \ -name tomcat \ -out /path/to/tomcat/conf/tomcat.p12Windows (in the folder
conf; in the example, the three PEM files are inC:\certs):openssl pkcs12 -export -inkey C:\certs\privkey.pem -in C:\certs\cert.pem -certfile C:\certs\chain.pem -name tomcat -out tomcat.p12 -
Edit
server.xmlso that the connector refers to the new file. On Windows, specify the path relative to the folder of the Tomcat installation:conf/tomcat.p12.Modern syntax (preferred):
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"> <SSLHostConfig> <Certificate certificateKeystoreFile="/path/to/tomcat/conf/tomcat.p12" certificateKeystorePassword="YOUR_P12_PASSWORD" type="RSA" /> </SSLHostConfig> </Connector>Classic syntax:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true" keystoreFile="/path/to/tomcat/conf/tomcat.p12" keystoreType="PKCS12" keystorePass="YOUR_P12_PASSWORD" clientAuth="false" sslProtocol="TLS" /> -
Restrict access to the file.
Linux:
sudo chown tomcat:tomcat /path/to/tomcat/conf/tomcat.p12 sudo chmod 600 /path/to/tomcat/conf/tomcat.p12Windows: open the properties of the file
tomcat.p12and, on the Security tab, allow only administrators and the account that the Tomcat service runs under. You find this account in the Services console (services.msc), in the properties of the service on the Log On tab. -
Restart Tomcat.
Linux:
sudo systemctl restart tomcat # or: catalina.sh stop && catalina.sh startWindows:
net stop Tomcat11 net start Tomcat11 -
Check the validity dates and the issuer of the certificate. Replace
your.domain.comand the port with your values.Linux:
openssl s_client -connect your.domain.com:8443 -servername your.domain.com </dev/null \ | openssl x509 -noout -dates -issuer -subjectWindows:
openssl s_client -connect your.domain.com:8443 -servername your.domain.com < NUL | openssl x509 -noout -dates -issuer -subjectWithout OpenSSL, open ISPICIO_E in the browser and view the certificate there.
You generated the key in a Java keystore
This is the case if you created the certificate signing request (CSR) with keytool. Import the new certificate into the same alias.
The keytool commands are the same on Linux and Windows. On Windows, keytool is in the folder bin of the Java installation; specify the path to the keystore in Windows notation and in quotation marks, for example "C:\Program Files\Apache Software Foundation\Tomcat 11.0\conf\keystore.jks".
-
If needed, import the certificates of the intermediate CA first:
keytool -importcert -alias intermediate -file intermediate.crt -keystore /path/to/keystore.jks -
Import the server certificate:
keytool -importcert -alias tomcat -file server.crt -keystore /path/to/keystore.jksThe value of
-aliasmust match the alias of the original key pair. You can check it withkeytool -list -v -keystore /path/to/keystore.jks.If you received a PKCS#12 file instead of a CRT file, import it like this instead:
keytool -importkeystore \ -srckeystore tomcat.p12 -srcstoretype PKCS12 \ -destkeystore keystore.jks -deststoretype JKS \ -srcalias tomcat -destalias tomcatIn the Windows Command Prompt, enter this command on one line, without the
\characters at the line ends. -
Leave
server.xmlunchanged. It still points to the keystore, which now contains the new certificate. -
Restart Tomcat and test the connection as in steps 5 and 6 of the previous section.
You use APR/Native with OpenSSL
This is the case if the connector in server.xml refers directly to the PEM files of the certificate, the key and the chain instead of a keystore. Such a connector looks like this.
Modern syntax:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11AprProtocol" SSLEnabled="true">
<SSLHostConfig>
<Certificate certificateFile="/path/to/cert.pem"
certificateKeyFile="/path/to/privkey.pem"
certificateChainFile="/path/to/chain.pem"
type="RSA" />
</SSLHostConfig>
</Connector>
Classic syntax:
<Connector port="8443" protocol="org.apache.coyote.http11.Http11AprProtocol"
SSLEnabled="true" scheme="https" secure="true"
SSLCertificateFile="/path/to/cert.pem"
SSLCertificateKeyFile="/path/to/privkey.pem"
SSLCertificateChainFile="/path/to/chain.pem" />
-
Back up
server.xmland the existing PEM files. -
Replace the files that the connector refers to with your new certificate, key and chain. If you keep the file names,
server.xmlstays unchanged. Otherwise, enter the new paths in the attributes. -
Restrict access to the files as in step 4 of the first section.
-
Restart Tomcat and test the connection as in steps 5 and 6 of the first section.