ContentsInstallation and setup

Renew the TLS certificate

Applies to ISPICIO_E 2.1.1.0 Last reviewed

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.xml contains 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).

  1. 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 || true

    Windows (change to the folder conf first; you only need the second copy line 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
  2. Build a PKCS#12 file from the private key, the certificate and the chain. Set a password when prompted. You enter it in server.xml in the next step.

    Linux:

    openssl pkcs12 -export \
      -inkey privkey.pem \
      -in cert.pem \
      -certfile chain.pem \
      -name tomcat \
      -out /path/to/tomcat/conf/tomcat.p12

    Windows (in the folder conf; in the example, the three PEM files are in C:\certs):

    openssl pkcs12 -export -inkey C:\certs\privkey.pem -in C:\certs\cert.pem -certfile C:\certs\chain.pem -name tomcat -out tomcat.p12
  3. Edit server.xml so 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" />
  4. Restrict access to the file.

    Linux:

    sudo chown tomcat:tomcat /path/to/tomcat/conf/tomcat.p12
    sudo chmod 600 /path/to/tomcat/conf/tomcat.p12

    Windows: open the properties of the file tomcat.p12 and, 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.

  5. Restart Tomcat.

    Linux:

    sudo systemctl restart tomcat
    # or: catalina.sh stop && catalina.sh start

    Windows:

    net stop Tomcat11
    net start Tomcat11
  6. Check the validity dates and the issuer of the certificate. Replace your.domain.com and 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 -subject

    Windows:

    openssl s_client -connect your.domain.com:8443 -servername your.domain.com < NUL | openssl x509 -noout -dates -issuer -subject

    Without 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".

  1. If needed, import the certificates of the intermediate CA first:

    keytool -importcert -alias intermediate -file intermediate.crt -keystore /path/to/keystore.jks
  2. Import the server certificate:

    keytool -importcert -alias tomcat -file server.crt -keystore /path/to/keystore.jks

    The value of -alias must match the alias of the original key pair. You can check it with keytool -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 tomcat

    In the Windows Command Prompt, enter this command on one line, without the \ characters at the line ends.

  3. Leave server.xml unchanged. It still points to the keystore, which now contains the new certificate.

  4. 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" />
  1. Back up server.xml and the existing PEM files.

  2. Replace the files that the connector refers to with your new certificate, key and chain. If you keep the file names, server.xml stays unchanged. Otherwise, enter the new paths in the attributes.

  3. Restrict access to the files as in step 4 of the first section.

  4. Restart Tomcat and test the connection as in steps 5 and 6 of the first section.