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

Usage notes

Before you begin, make sure that you meet the following requirements:

Open port 443 in the security group

If your server runs on Alibaba Cloud ECS, add an inbound rule to allow TCP port 443:

1. Go to Elastic Compute Service (ECS) instances and click the target instance name.

2. In the Security Group Details section, add a security group rule with the following settings and save: For other cloud platforms, refer to their documentation.

   Field	Value
   Action	Allow
   Protocol	Custom TCP
   Destination (Current Instance)	HTTPS (443)
   Source	0.0.0.0/0 (anywhere)

Open port 443 in the OS firewall

First, check whether port 443 is already reachable. Run the following command for your Linux distribution:

RHEL/CentOS

command -v nc > /dev/null 2>&1 || sudo yum install -y nc
# Replace <your_server_public_ip> with your server's 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 contains Ncat: Connected to <your_server_public_ip>:443, port 443 is open and no further action is needed.

Debian/Ubuntu

command -v nc > /dev/null 2>&1 || sudo apt-get install -y netcat
# Replace <your_server_public_ip> with your server's 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 contains Connection to <your_server_public_ip> port [tcp/https] succeeded! or [<your_server_public_ip>] 443 (https) open, port 443 is open and no further action is needed.

If port 443 is not open, identify the active firewall and open the port:

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 firewall is active. Otherwise, run the command for your firewall:

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 persist iptables rules across reboots:

• 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

(Optional) Force HTTP to HTTPS redirection

To redirect all HTTP requests to HTTPS automatically, add the following block at the bottom of conf/web.xml, just before the closing </web-app> tag:

<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>

Validate and restart Tomcat

1. Validate the configuration. From the Tomcat bin directory, run:

   ./configtest.sh

   If the output is Configuration file test successful, the configuration is valid. If errors appear, correct the configuration based on the error messages and re-run the validation.

2. Restart Tomcat to apply the changes:

   sudo ./shutdown.sh
   sudo ./startup.sh

HTTPS is inaccessible after installation or certificate update

Check the following in order:

1. Port 443 blocked. Verify that both the security group and the OS firewall allow inbound TCP traffic on port 443. See Step 2.

2. Domain mismatch. Confirm the domain you are accessing is listed in the certificate's Bound Domains field. See the Prerequisites section for domain-matching rules.

3. Tomcat not restarted. The new configuration takes effect only after Tomcat restarts. See the validate and restart steps in Step 3.

4. Incorrect certificate path or file. Check that certificateKeystoreFile (or keystoreFile) in server.xml points to the correct, up-to-date certificate file.

5. Certificate missing on upstream services. If your domain passes through a Content Delivery Network (CDN), Server Load Balancer (SLB), or Web Application Firewall (WAF), the certificate must be installed on those services as well. See Certificate deployment locations when traffic passes through multiple Alibaba Cloud services.

6. Incomplete multi-server deployment. If the domain's DNS resolves to multiple servers, install the certificate on all of them.

For deeper troubleshooting, see Resolve certificate deployment issues based on browser error messages and the SSL certificate deployment troubleshooting guide.

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

This almost always means the password in server.xml doesn't match the keystore file. To fix it:

1. Open the password file (.txt) from the certificate package and copy its contents exactly, with no trailing spaces or newlines.

2. Update the certificateKeystorePassword (or keystorePass) attribute in server.xml with that value.

3. Confirm that certificateKeystoreFile (or keystoreFile) points to the correct file path.

4. Confirm that the Tomcat user has read permission on the certificate file.

Connection was reset / Connection refused when accessing the server

This is a network connectivity issue, not a certificate problem. Check the following:

1. Confirm that both the security group and the OS firewall allow inbound traffic on port 443 (or whichever port is configured in server.xml). See Step 2.

2. Verify that Tomcat is running: ps -ef | grep tomcat

3. Confirm that the port attribute in the server.xml SSL connector matches the port you are accessing.

How to update or replace an SSL certificate in Tomcat

1. Back up the existing files. Save copies of the current certificate file (.pfx or .jks) and the password file (.txt) from the server.

2. Download the new certificate. Get the new certificate package from the Certificate Management Service console.

3. Replace the files. Upload the new certificate and password files to the same path on the server, overwriting the old ones. The file path and name must match exactly what is configured in server.xml.

4. Restart Tomcat. Run sudo ./shutdown.sh and sudo ./startup.sh from the Tomcat bin directory to apply the new certificate.