— Kiaasa Dhanori Pune

Generating an SSL certificate request for Tomcat means creating a keystore, generating a key pair and a Certificate Signing Request (CSR), submitting that CSR to your Certificate Authority (CA), and importing the signed chain back into the keystore so Tomcat can serve HTTPS. This guide walks through the whole lifecycle using KeyStore Explorer, a free GUI tool that lets you build the request on your desktop instead of typing keytool commands on a production server.

Working in a GUI removes most of the syntax mistakes that break a renewal at 2 a.m., but the underlying concepts are identical whether you use KeyStore Explorer, keytool, or openssl. Get the keystore, the key pair, the Subject Alternative Names, and the import order right, and the Tomcat SSL certificate will install cleanly the first time.

Before You Start: Information You Must Collect

A failed SSL certificate renewal is almost always a missing-information problem, not a tooling problem. Before you touch a keystore, confirm the following with the application owner. Skipping any one of these is the most common cause of an outage during a Tomcat SSL certificate swap.

• Location of the keystore file on the server (for example /opt/tomcat/conf/keystore.jks or a path referenced in server.xml).
• Keystore and key password currently in use. Tomcat needs these to read the private key at startup.
• Every hostname the certificate must cover, including all Subject Alternative Names (SANs). Modern browsers ignore the Common Name entirely and validate only against the SAN list, so every URL clients use must appear here.
• How the application is restarted and an approved maintenance window, because the new certificate only takes effect after Tomcat reloads.

Also confirm the keystore type. Older Tomcat deployments use JKS, but Java 9+ defaults to PKCS12, which is the cross-platform, non-proprietary standard. If you are building a new keystore today, prefer PKCS12; only stick with JKS when you must match an existing file that Tomcat already references.

Why Build the CSR on Your Desktop

Running keytool directly on a production host works, but it has real downsides: a typo can corrupt a live keystore, the private key is generated on a shared server, and you need shell access during the change window. KeyStore Explorer lets you do all the sensitive work locally and copy only the finished keystore to the server.

• No live-server commands until the very last step, when you replace the file.
• Visual validation of the Distinguished Name, key algorithm, and SANs before you submit anything.
• Repeatable across renewals, so the next administrator follows the same clicks.

Install KeyStore Explorer from the official project site (keystore-explorer.org) and verify the download against the published checksum. Use a recent release rather than an old internal copy, because newer versions default to stronger algorithms and modern keystore formats.

Step 1: Create the Keystore and Key Pair

The keystore is the encrypted container that holds your private key and, eventually, the signed certificate chain. The key pair is the math that proves your server owns the certificate. Create them in order.

1. Launch KeyStore Explorer and choose Create a new KeyStore.
2. Select the keystore type. Pick PKCS12 for a new deployment, or JKS only if you are replacing an existing JKS file, then click OK.
3. Click Generate Key Pair (the toolbar icon, or right-click in the empty keystore).
4. Set the algorithm to RSA with a 2048-bit key (or RSA 3072/4096, or ECDSA with the P-256 curve for a smaller, faster key). Set a validity period that exceeds your CA's issuance window, then click OK.

Why this matters: 1024-bit keys are obsolete and rejected by every public CA. RSA 2048 is the minimum acceptable strength today; ECDSA P-256 is a modern, efficient alternative if your clients support it.

Step 2: Enter the Distinguished Name

The Distinguished Name (DN) identifies the certificate subject. Click Edit Name and fill in the fields carefully, because the CA validates them against your domain ownership.

Enter the CN exactly as users will type it in the browser. Click OK, review the assembled DN string, and confirm. If the certificate needs to cover more than one hostname, add the SANs now using the steps in the SAN section below before you finish.

Step 3: Add Subject Alternative Names (SANs)

This step is mandatory if the server answers on more than one name, such as a short hostname plus its FQDN, a load-balancer alias, or multiple domains. A certificate without the right SANs throws NET::ERR_CERT_COMMON_NAME_INVALID in the browser even when the CN looks correct.

1. In the key-pair generation dialog, click Add Extensions.
2. Click the green plus sign to add an extension, choose Subject Alternative Name from the list, and click OK.
3. Click the green plus sign again, select DNS Name, and type the hostname (for example app.example.com). Click OK.
4. Repeat for every additional name the certificate must cover, then click OK until you exit the dialogs.

Best practice: include your primary CN as a SAN entry too. Browsers validate against SANs only, so the CN must be duplicated in the SAN list to be trusted. Use DNS Name entries for hostnames and IP Address entries only when a public CA explicitly allows them.

Step 4: Set the Alias and Key Password

After confirming the DN and SANs, KeyStore Explorer asks for an alias and a password for this key entry.

1. Accept the default alias or rename it to something meaningful like tomcat. Record this value, because server.xml may reference it as the keyAlias.
2. Set the key password. The safest choice is to use the same password as the keystore; Tomcat assumes this by default unless you explicitly configure a separate keyPass.
3. Click OK to create the key pair inside the keystore.

Step 5: Generate the CSR

The CSR is the public half of your key pair plus your DN and SANs, packaged for the CA to sign. The private key never leaves the keystore.

1. Right-click the key-pair entry and choose Generate CSR.
2. Keep the default signature algorithm (for example SHA-256 with RSA). Never use SHA-1, which CAs reject.
3. Tick Add Certificate Extensions to Request so your SANs are carried into the CSR. Skipping this is the number-one reason a reissued certificate comes back without the SANs you specified.
4. Click OK and save the .csr file.

Now save the keystore itself: choose File > Save, set a strong keystore password (reuse the password of the keystore you are replacing if this is a renewal), and keep the file name handy. Submit the CSR through your CA or internal certificate-management process and wait for the signed certificate.

Step 6: Import the Signed Certificate Chain

When the CA returns your certificate, you typically receive three files: the Root CA certificate, one or more Intermediate (issuing) CA certificates, and your server certificate. Import order matters: trust the CA certificates first, then apply the signed reply to your key pair.

1. Open your keystore in KeyStore Explorer and enter the keystore password.
2. Click Import Trusted Certificate, select the Root CA certificate, and import it. Accept or set a clear alias.
3. Repeat Import Trusted Certificate for each Intermediate CA certificate.
4. Right-click your key-pair entry and choose Import CA Reply > From File, then select your server certificate and import it. This links the signed certificate to the private key you generated in Step 1.

Why the order matters: Tomcat must present the full chain (server, intermediate, root) so clients can build a path to a trusted anchor. If the intermediate is missing, many browsers and API clients fail with an incomplete-chain error even though the server certificate is valid.

Step 7: Verify the Chain and SANs

Confirm the keystore is complete before you go anywhere near the server. Right-click the key pair and choose View Details > Certificate Chain Details. You should see your server certificate at the top, then the intermediate, then the root.

1. Check the chain has all expected links and that the issuer of each certificate matches the subject of the next one up.
2. Click Extensions, then Subject Alternative Name, and confirm every hostname you requested is present.
3. Verify the validity dates and the key algorithm match what you generated.
4. Choose File > Save to persist the completed keystore.

Step 8: Deploy the Keystore to the Tomcat Server

This is the only step that touches production. Treat it as a controlled change with a rollback ready.

1. Back up the current keystore on the server first: cp keystore.jks keystore.jks.bak-$(date +%F). This is your instant rollback.
2. Copy your new keystore to the server and replace the old file. The new file name must be exactly the same as the one Tomcat references in server.xml (including no extension if the original had none).
3. Confirm the connector in conf/server.xml points at the right file, alias, and password. A modern Tomcat connector looks like this:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true" maxThreads="200" scheme="https" secure="true"> <SSLHostConfig> <Certificate certificateKeystoreFile="conf/keystore.jks" certificateKeystorePassword="yourpassword" certificateKeystoreType="JKS" certificateKeyAlias="tomcat" /> </SSLHostConfig> </Connector>

Set certificateKeystoreType to PKCS12 if you built a PKCS12 keystore. Then restart Tomcat using the approved method and test immediately.

Verification: Confirm HTTPS Actually Works

Do not declare success from the keystore alone. Verify what Tomcat is presenting on the wire after the restart.

• Browser check: open https://app.example.com:8443, confirm the padlock, and inspect the certificate's validity dates and SAN list.
• Command line: run openssl s_client -connect app.example.com:8443 -servername app.example.com and read the certificate chain it returns. Confirm the server, intermediate, and root all appear.
• SAN check: run openssl s_client -connect app.example.com:8443 2>/dev/null | openssl x509 -noout -text | grep -A1 "Subject Alternative Name" to list the names actually served.
• Logs: tail catalina.out for SSL or keystore errors during startup, such as a wrong password or a key that cannot be found under the configured alias.

Common Pitfalls (and How to Avoid Them)

• Mismatched passwords. If the key password differs from the keystore password and server.xml does not declare it, Tomcat fails to read the key. Keep them the same unless you have a reason not to.
• Missing intermediate certificate. The most frequent post-deploy failure. Always import the full chain, not just the server certificate.
• SANs dropped from the CSR. If you forget Add Certificate Extensions to Request, the reissued certificate loses its SANs and browsers reject it. Verify SANs in the CSR and again in the final certificate.
• Wrong file name or path. Renaming the keystore breaks the server.xml reference. Match the original name and location exactly.
• Importing the CA reply before the trusted roots. KeyStore Explorer needs the trust anchors present to build the chain when you apply the CA reply. Import root and intermediate first.
• Editing a live keystore directly. Always work on a copy and keep the timestamped backup so a rollback is one command away.
• Forgetting to restart. Tomcat loads the keystore at startup, so the new certificate is invisible until the service reloads.

Doing It on the Command Line (the keytool Equivalent)

If you cannot use a GUI, the same workflow maps directly to keytool, which ships with the JDK. This is useful for scripting or air-gapped servers.

1. Generate the key pair with SANs: keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -keystore keystore.jks -storetype JKS -dname "CN=app.example.com, O=Example Corp, C=US" -ext "SAN=dns:app.example.com,dns:app2.example.com"
2. Create the CSR carrying the SANs: keytool -certreq -alias tomcat -keystore keystore.jks -ext "SAN=dns:app.example.com,dns:app2.example.com" -file app.csr
3. Import the root, then intermediate: keytool -import -trustcacerts -alias root -file root.cer -keystore keystore.jks
4. Apply the CA reply to your alias: keytool -import -trustcacerts -alias tomcat -file server.cer -keystore keystore.jks
5. List and verify the result: keytool -list -v -keystore keystore.jks

To modernize an older JKS file to PKCS12, convert it once with keytool -importkeystore -srckeystore keystore.jks -srcstoretype JKS -destkeystore keystore.p12 -deststoretype PKCS12 and update server.xml accordingly.

Key Takeaways

• Collect the keystore path, password, full SAN list, and restart procedure before you start any Tomcat SSL certificate renewal.
• Build the keystore, key pair, and CSR on your desktop with KeyStore Explorer to avoid risky commands on a live server, then deploy only the finished file.
• Always tick Add Certificate Extensions to Request so SANs survive into the CSR; browsers validate against SANs, not the Common Name.
• Import the root and intermediate CA certificates first, then apply the CA reply to the key pair, so Tomcat serves a complete trust chain.
• Back up the existing keystore, match the file name exactly, restart Tomcat, and verify with openssl s_client and a browser before closing the change.

Frequently Asked Questions

What is the difference between a JKS and a PKCS12 keystore for Tomcat?

JKS is Java's older, proprietary keystore format, while PKCS12 (.p12 or .pfx) is the open, cross-platform standard and the default since Java 9. Both work with Tomcat, but PKCS12 is recommended for new keystores because it is portable across tools and platforms. Convert an existing JKS with keytool -importkeystore when you are ready.

Why is my Tomcat certificate untrusted even though it is valid?

The most common cause is a missing intermediate certificate. Browsers need the full chain from your server certificate up to a trusted root, so import the root and intermediate CA certificates into the keystore and apply the CA reply to the key pair. Confirm the served chain with openssl s_client -connect host:8443.

Do I need to add Subject Alternative Names if I only have one hostname?

Yes. Modern browsers ignore the Common Name and validate only the SAN list, so even a single-hostname certificate must list that hostname as a DNS SAN. Add the SAN extension during key-pair generation and ensure it is carried into the CSR.

How do I roll back if the new certificate breaks Tomcat?

Restore the timestamped backup you made before the swap (for example cp keystore.jks.bak-2026-06-28 keystore.jks), confirm server.xml still points at it, and restart Tomcat. Because you only replaced one file, rollback is a single copy plus a restart.

For more hands-on system administration and DevOps walkthroughs, subscribe to @explorenystream on YouTube.