Certificate Management Service:Install an SSL certificate on a Tomcat server (Linux)

Usage notes

Before you begin, ensure you meet the following requirements:

Step 1: Prepare the certificate files

1. Go to the SSL Certificates page. In the Actions column of the target certificate, click Download Certificate. On the Download tab, download the certificate for the Server Type Tomcat.

2. Extract the downloaded certificate package. The package contains a certificate file (.pfx or .jks) and a password file (.txt).

   Note

   Choose the certificate format based on your requirements, resources, and system compatibility.

   • JKS is a Java-specific keystore format. It is suitable for use primarily in Java environments. If your tools and scripts support JKS, choose JKS.

   • PFX is a universal format widely supported by Java and other platforms. To integrate across different technology stacks or with non-Java systems, choose the PFX format.

3. Upload the extracted certificate file (.pfx or .jks) and password file (.txt) to the server. Store them in a secure external directory, such as the /etc/ssl/cert directory.

   Important

   To ensure key security, set strict file permissions after the upload. Allow only the Tomcat user to read the files.

   You can upload files using the file upload feature of a remote logon tool, such as PuTTY, XShell, or WinSCP. If you use an Alibaba Cloud Elastic Compute Service (ECS) instance, see Transfer files to a Windows instance using Remote Desktop or a Windows app or Upload files to a Linux instance.

Step 2: Configure the system and network environment

Ensure your security group and system firewall allow inbound traffic on the HTTPS port (443).

1. Run the following command in the server terminal to check if port 443 is open:

   RHEL/CentOS

   command -v nc > /dev/null 2>&1 || sudo yum install -y nc
   # Replace <your_server_public_ip> with your server's actual public IP address.
   sudo ss -tlnp | grep -q ':443 ' || sudo nc -l 443 & sleep 1; nc -w 3 -vz <your_server_public_ip> 443

   If the output is Ncat: Connected to <The public IP address of the current server>:443, port 443 is open. Otherwise, open port 443 in the security group and firewall.

   Debian/Ubuntu

   command -v nc > /dev/null 2>&1 || sudo apt-get install -y netcat
   # Replace <your_server_public_ip> with your server's actual public IP address.
   sudo ss -tlnp | grep -q ':443 ' || sudo nc -l -p 443 & sleep 1; nc -w 3 -vz <your_server_public_ip> 443

   If the output is Connection to <public IP address of the current server> port [tcp/https] succeeded! or [<public IP address of the current server>] 443 (https) open, port 443 is open. Otherwise, open port 443 in the security group and firewall.

2. Open port 443 in your security group configuration.

   Important

   If your server is deployed on a cloud platform, ensure its security group allows inbound traffic on TCP port 443. Otherwise, the service will be inaccessible. The following steps use Alibaba Cloud Elastic Compute Service (ECS) as an example. For other cloud platforms, refer to their official documentation.

   Go to the Elastic Compute Service instance page, click the target instance name to go to the instance details page. Refer to Add a security group rule to add a new rule in the Security Group with the Action set to Allow, Protocol Type to Custom TCP, Destination Port Range to HTTPS(443), and Authorization Object to All IPv4 Addresses.

3. Open port 443 in your firewall.

   Run the following command to identify the active firewall service on your system:

   if command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet firewalld; then
       echo "firewalld"
   elif command -v ufw >/dev/null 2>&1 && sudo ufw status | grep -qw active; then
       echo "ufw"
   elif command -v nft >/dev/null 2>&1 && sudo nft list ruleset 2>/dev/null | grep -q 'table'; then
       echo "nftables"
   elif command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet iptables; then
       echo "iptables"
   elif command -v iptables >/dev/null 2>&1 && sudo iptables -L 2>/dev/null | grep -qE 'REJECT|DROP|ACCEPT'; then
       echo "iptables"
   else
       echo "none"
   fi

   If the output is none, no further action is required. Otherwise, run the corresponding command below based on the output (firewalld, ufw, nftables, or iptables) to open port 443:

   firewalld

   sudo firewall-cmd --permanent --add-port=443/tcp && sudo firewall-cmd --reload

   ufw

   sudo ufw allow 443/tcp

   nftables

   sudo nft add table inet filter 2>/dev/null
   sudo nft add chain inet filter input '{ type filter hook input priority 0; }' 2>/dev/null
   sudo nft add rule inet filter input tcp dport 443 counter accept 2>/dev/null

   iptables

   sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

   To ensure the iptables rules persist after a system reboot, run the following commands:

   RHEL/CentOS

   sudo yum install -y iptables-services
   sudo service iptables save

   Debian/Ubuntu

   sudo apt-get install -y iptables-persistent
   sudo iptables-save | sudo tee /etc/iptables/rules.v4 >/dev/null

Step 3: Install the certificate on the Tomcat server

1. Go to the root directory of your Tomcat installation and run the following command to open the server.xml file.

   sudo vim ./conf/server.xml 

2. Configure the server.xml file based on the following examples and comments.

   Important

   To avoid errors when you start Tomcat, delete the comments when you copy the code.

   While the steps for configuring SSL certificates in Tomcat is similar across versions, there are minor differences due to variations in supported Java versions and configuration syntax. This section provides specific instructions for Tomcat 7, 8.5, and 9.

   Tomcat 9

   Follow the configuration process below to configure port forwarding, certificate files, and other settings.

   • Configure the HTTP redirect connector. For example:

     <!-- Change the connector port to 80 and the redirectPort to 443, the default SSL port, to forward HTTP requests to port 443. -->
     <Connector port="80" protocol="HTTP/1.1"
                connectionTimeout="20000"
                redirectPort="443"
                maxParameterCount="1000"
                />

   • Configure the SSL connector. For example:

     PFX format

     <!-- Change the default HTTPS port in Tomcat to 443. Port 8443 cannot be accessed directly through a domain name. You must add the port number after the domain name. -->
     <!-- Port 443 is the default port for HTTPS and can be accessed directly through a domain name without adding a port number. -->
     <!-- The connector port has two operating modes: NIO and APR. Select the NIO mode.-->
     <Connector port="443"
                    protocol="org.apache.coyote.http11.Http11NioProtocol" 
                    maxThreads="150" 
                    SSLEnabled="true"
                    maxParameterCount="1000"
                    >
             <SSLHostConfig>
                     <!-- Replace /etc/ssl/cert/domain_name.pfx with the actual path to your certificate. Replace the certificate password with the content of the pfx-password.txt file. -->
                     <Certificate certificateKeystoreFile="/etc/ssl/cert/domain_name.pfx" 
                                  certificateKeystorePassword="Certificate password" 
                                  type="RSA" />
             </SSLHostConfig>
     </Connector>

     JKS format

     <!-- Change the default HTTPS port in Tomcat to 443. Port 8443 cannot be accessed directly through a domain name. You must add the port number after the domain name. -->
     <!-- Port 443 is the default port for HTTPS and can be accessed directly through a domain name without adding a port number. -->
     <!-- The Connector port has two operating modes: NIO and APR. Select the NIO mode.-->
     <Connector port="443"
                    protocol="org.apache.coyote.http11.Http11NioProtocol" 
                    maxThreads="150" 
                    SSLEnabled="true"
                    maxParameterCount="1000"
                    >
             <SSLHostConfig>
                     <!-- Replace /etc/ssl/cert/domain_name.jks with the actual path to your certificate. Replace the certificate password with the content of the jks-password.txt file. -->
                     <Certificate certificateKeystoreFile="/etc/ssl/cert/domain_name.jks" 
                                  certificateKeystorePassword="Certificate password" 
                                  type="RSA" />
             </SSLHostConfig>
     </Connector>

   • Configuration item 3:

     Configuration example (remove the <!-- and --> comment symbols):

     <!-- Change the redirectPort to 443 to forward HTTPS requests to port 443. -->
     <Connector protocol="AJP/1.3"
                    address="::1"
                    port="8009"
                    redirectPort="443" 
                    maxParameterCount="1000"
                    />

   Tomcat 8.5

   Manually specify the SSL implementation (specify the JSSE implementation).

   Configuration example (Uncomment by removing <!-- and -->):

   PFX format

   <Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
              maxThreads="150" SSLEnabled="true"
              maxParameterCount="1000">
       <SSLHostConfig>
           <!-- Replace /etc/ssl/cert/domain_name.pfx with the actual path to your certificate. Replace the certificate password with the content of the pfx-password.txt file. -->
           <Certificate certificateKeystoreFile="/etc/ssl/cert/domain_name.pfx"
                        certificateKeystorePassword="Certificate password"
                        type="RSA"/>
       </SSLHostConfig>
   </Connector>

   JKS format

   <Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
              maxThreads="150" SSLEnabled="true"
              maxParameterCount="1000">
       <SSLHostConfig>
           <!-- Replace /etc/ssl/cert/domain_name.jks with the actual path to your certificate. Replace the certificate password with the content of the jks-password.txt file. -->
           <Certificate certificateKeystoreFile="/etc/ssl/cert/domain_name.jks"
                        certificateKeystorePassword="Certificate password"
                        type="RSA"/>
       </SSLHostConfig>
   </Connector>

   Tomcat 7

   The Tomcat server automatically selects the SSL implementation. If you cannot complete the configuration using this method, your environment may not support the automatically selected SSL implementation.

   Configuration example:

   PFX format

   <!-- #Modify the port attribute as needed (the default HTTPS port is 443). If you use a different port number, you must access your website using https://domain_name:port. 
   Replace the keystoreFile value with the actual path to your certificate.
   Replace the keystorePass value with the content of the pfx-password.txt file.
   For information about other configuration items, visit the official Tomcat website.-->
   <Connector port="443"
              protocol="HTTP/1.1"
              SSLEnabled="true"
              scheme="https"
              secure="true"
              keystoreFile="/etc/ssl/cert/domain_name.pfx"
              keystoreType="PKCS12"
              keystorePass="Certificate password"
              clientAuth="false"
              SSLProtocol="TLSv1.1+TLSv1.2+TLSv1.3"
              ciphers="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256"/>

   JKS format

   <!-- #Modify the port attribute as needed (the default HTTPS port is 443). If you use a different port number, your website using https://domain_name:port. 
   Replace the keystoreFile value with the actual path to your certificate.
   Replace the keystorePass value with the content of the jks-password.txt file.
   For information about other fields, visit the official Tomcat website.-->
   <Connector port="443"
              protocol="HTTP/1.1"
              connectionTimeout="20000"
              redirectport="8443"
              maxParameterCount="1000"
              SSLEnabled="true"
              scheme="https"
              secure="true"
              keystoreFile="/etc/ssl/cert/domain_name.jks"
              keystoreType="JKS"
              keystorePass="Certificate password"
              clientAuth="false"
              SSLProtocol="TLSv1.1+TLSv1.2+TLSv1.3"
              ciphers="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256"/>    

3. Optional: In the /conf/web.xml file, configure automatic redirection from HTTP to HTTPS.

   1. Go to the root directory of your Tomcat installation and run the following command to open the web.xml file.

      sudo vim ./conf/web.xml 

   2. Add the following configuration at the bottom of the web.xml file.

      <security-constraint>
          <web-resource-collection>
              <web-resource-name>SSL</web-resource-name>
              <url-pattern>/*</url-pattern>
          </web-resource-collection>
          <user-data-constraint>
              <transport-guarantee>CONFIDENTIAL</transport-guarantee>
          </user-data-constraint>
      </security-constraint>

4. Go to the bin directory of your Tomcat installation and run the following command to validate the configuration file. If the output is Configuration file test successful, the validation is passed. Otherwise, modify the configuration based on the prompts until the test passes.

   ./configtest.sh

5. Go to the bin directory of your Tomcat installation and run the following commands to stop and restart Tomcat.

   • Stop command:

     sudo ./shutdown.sh

   • Restart command:

     sudo ./startup.sh

Step 4: Verify the deployment

Why is my certificate not working or HTTPS inaccessible after installation or update?

This issue is often caused by one of the following configuration problems. Check them in order:

• Port 443 is blocked: The server's security group or firewall does not have port 443 open. See Configure the system and network environment.

• Domain mismatch: The domain you are accessing is not listed in the certificate's Bound Domains. See Domain name match.

• Tomcat not restarted: The Tomcat service was not restarted after the configuration file was modified. For instructions, see Stop and restart the Tomcat service.

• Incorrect certificate configuration: The certificate file was not replaced correctly, or the certificate path is not correctly specified in the Tomcat configuration. Check the Tomcat configuration file and the certificate file are up-to-date and valid.

• Missing certificate on other services: If your domain uses services such as a Content Delivery Network (CDN), Server Load Balancer (SLB), or Web Application Firewall (WAF), the certificate must also be installed on those services. See Certificate deployment locations when traffic passes through multiple Alibaba Cloud services to complete the setup.

• Incomplete deployment on multiple servers: If your domain's DNS resolves to multiple servers, the certificate must be installed on all of them.

What is the correct way to update or replace an SSL certificate in Tomcat?

1. Back up old files: Back up the existing certificate files (.pfx or .jks, and the .txt file) on the server.

2. Get new files: Download the new certificate and private key files from your Certificate Management Service Console.

3. Replace files: Upload the new files to your server, overwriting the old ones. Ensure the new files have the exact same path and filename as the ones specified in your Tomcat configuration.

4. Restart Tomcat: Restart the Tomcat service to apply the new certificate.

Tomcat fails to start, and the log shows the "Keystore was tampered with, or password was incorrect" error

This is a common issue. See the Install the certificate on the Tomcat server section and troubleshoot with the following steps:

1. Verify that the certificate password configured in server.xml is identical to the password of the keystore file itself. Ensure there are no trailing spaces or newline characters.

2. Verify that the file path for certificateKeystoreFile (or keystoreFile) is correct.

3. Verify that the Tomcat user has read permissions for the certificate file.

Error: "Connection was reset" or "Connection Refused" when accessing the server

This is typically a network connectivity issue. See the Configure the system and network environment section and troubleshoot with the following steps:

1. Verify that both the server's security group and the system firewall allow traffic on the HTTPS port (443 or another configured port).

2. Verify that the Tomcat service is running. You can check this using the ps -ef | grep tomcat command.

3. Verify that the port configured in server.xml matches the port being accessed.