Cannot Setup TLS
 

Common reasons why a secure browser connection might fail

There are several common reasons why the MailArchiva web console could not be accessed securely (i.e. via TLS) using a web browser. They are:
 

• The keystore password specified in the HTTPS Connector in Tomcat's server.xml may be incorrect.
• The HTTPS connector might not be defined in Tomcat's server.xml, or SSLEnabled might not be set to true in the server.xml file.
• There may be a mismatch between the keystore alias defined in the HTTPS Connector in Tomcat's server.xml and the alias of the server certificate in the keystore itself.
• There may be a missing intermediate certificate. Sometimes intermediate certificates are not provided by the Certificate Authority (CA) and need to be downloaded separately from the CA’s website.
• There may be DNS mismatch. For example, using a certificate issued for mailarchiva.company.com but accessing the console via https://mailarchiva.company.local can result in validation failure.
• The server certificate might have a missing DNS SAN (Subject Alternative Name) extension. Modern browsers require the presence of a DNS SAN field, whose value matches the domain of the accessing URL.
• The server certificate may already be expired.
• Incorrect CA certificates may be installed.
• The HTTPS port may be bound by another process.
• MailArchiva may be running in Multitenant mode and the installed certificate may not have a wild card DNS present.
• The Tomcat TLS connector in Tomcat's server.xml may be in the wrong format (i.e. after upgrading from MailArchiva V8 to V9, the server.xml format in Tomcat changed, which could cause compatibility issues).

Reviewing Tomcat Logs

The Tomcat startup logs provide valuable information for diagnosing TLS issues. These logs can be found in /var/opt/mailarchiva/tomcat/logs on Linux systems and C:\ProgramData\MailArchiva\Tomcat\logs on Windows systems.

When Tomcat starts, any errors related to keystore or certificate access will be recorded in these logs. Ensure that no local firewall is blocking communications on port 443. Also, verify that Tomcat is not attempting to bind to an IPv6 address. If IPv6 binding is an issue, add the following line to the CATALINA_OPTS in /opt/mailarchiva/server/startserver:

MailArchiva V8 to V9 TLS Configuration Changes

MailArchiva V9 uses Tomcat 10, which introduces changes to the server.xml configuration. For example, you may encounter an error in the catalina.out log file that reads:

To resolve this issue, update the HTTPS connector configuration in the server.xml file located at /var/opt/mailarchiva/tomcat/conf/server.xml on Linux or C:\ProgramData\MailArchiva\Tomcat\conf\server.xml on Windows. The configuration must now include the SSLHostConfig child tag, which was introduced in Tomcat 10. Previously, SSL settings were specified as attributes within the connector itself.

Here is an example of a correctly configured HTTPS connector in server.xml:

Certificate Installation and Troubleshooting

If you cannot import a server certificate, ensure that certificates are imported in the correct order. First, import the root CA certificate, then the intermediate certificates, and finally the server certificate and key. If any intermediate certificates are missing, the certificate chain will be incomplete, and validation will fail.

To verify whether a missing intermediate certificate is the cause, trace the chain of trust. Examine the issuer DN of the server certificate and check if there is a corresponding certificate with a matching subject DN. If no such certificate exists, search the issuer DN on Google to locate the missing intermediate certificate. This approach often works if the intermediate certificate is public and published on a CA’s website. If you cannot find the missing certificate, contact the CA to request it.

Certificates that lack a DNS SAN extension are invalid in modern browsers. Ensure that your certificate includes a Subject Alternative Name entry, such as *.yourdomain.local, to cover all necessary subdomains.

If the GUI fails to start after launching the server, verify that the alias specified in server.xml matches the alias in the MailArchiva certificate store. Also, confirm that the keystore password in server.xml matches the keystore's actual password. Examine the Tomcat logs for errors. If needed, switch back to port 80 in server.xml, restart MailArchiva, and review the certificate installation steps.

SMTP Start TLS Troubleshooting

If SMTP communications fail with TLS enabled, isolate the issue by temporarily reverting the SMTP listener to plaintext mode. Verify whether mail is received in this configuration. If mail is received in plaintext, the problem is likely with the TLS setup. Ensure the Exchange server can authenticate the certificates imported into MailArchiva and that all necessary CA certificates are present in Exchange.

Common Certificate Issues

An invalid chain to the trusted ROOT certificate is a frequent issue. To ensure a valid chain, check that all intermediate certificates are present and correctly imported. Match the issuer DN of each certificate with the subject DN of the next in the chain, ending with the root certificate. If intermediate certificates are missing, download them from the CA website or contact the CA directly.

To establish whether an intermediate certificate is missing, inspect the chain of trust. Look for a certificate with an issuer DN that does not correspond to a certificate with a matching subject DN. If you find such a certificate, type the DN of the missing certificate into Google to locate it. This method works if the intermediate certificate is public and available on a CA website. If it cannot be found, contact the CA for assistance.

Insecure connection warnings in browsers may indicate an invalid chain, an expired certificate, a missing DNS SAN extension, or a DNS mismatch. By addressing these issues systematically, TLS and certificate-related problems can be resolved effectively.