1. cPanel & WHM Documentation
  2. cPanel Knowledge Base
  3. Security
  4. The SSL Installation and Precedence Logic
apache ssl

The SSL Installation and Precedence Logic

Last modified: March 26, 2024

Overview

Warning:
  • We recommend this document for experienced systems administrators only.
  • cPanel users can generate and manage SSL certificates in cPanel’s SSL/TLS interface. For more information about managing SSL certificates on your cPanel account, read our Guide to SSL and Troubleshoot SSL-Related Issues documentation.

This document outlines how cPanel & WHM processes Secure Sockets Layer (SSL) certificate requests and how Apache processes SSL requests.

To purchase and install an SSL certificate, follow the directions in our Purchase and Install an SSL Certificate documentation.

Important:

cPanel & WHM supports Transport Layer Security (TLS) protocol version 1.2 and Transport Layer Security (TLS) protocol version 1.3:

  • Beginning in cPanel and WHM version 86, cPanel & WHM only supports TLSv1.2 or later. The system also enables TLSv1.2 by default.
  • In cPanel and WHM version 84 or earlier, cPanel & WHM strongly recommends that you enable TLSv1.2 on your server.
  • Not all internet browsers or clients will support TLSv1.3, which requires OpenSSL 1.1.1 or higher.
Note:
This document refers to other services’ domain-indexed SSL storage as Domain TLS.

Name-based and virtual host match

Most SSL-enabled services that WebPros International, LLC deploys support simple name-based SSL. When a client requests an SSL certificate for a specific domain, the service performs one of the following actions:

  • If the certificate exists, the service responds with a certificate that matches the requested domain.
  • If no certificate exists, the the system uses the service’s default SSL certificate.

Apache SSL certificates

Apache does not follow this logic. When a client requests an SSL certificate for a specific domain’s SSL certificate, Apache performs the following actions:

  1. It establishes the virtual host that hosts the domain.
  2. It responds with the certificate for that virtual host.
Note:
Apache cannot match a certificate directly with a domain, and offers the virtual host’s certificate even if the certificate does not match the domain. Apache serves the same certificate for any request that matches a given virtual host. Because of this limitation, Apache’s domain-indexed SSL storage differs from that of the other services.

For simplicity, cPanel & WHM only exposes a single set of API functions to install and remove SSL certificates. When a user or administrator installs an SSL certificate, that installation only applies to a specific Apache virtual host. This behavior impacts both Apache and services that support name-based SSL. After the Apache installation finishes, the system copies the certificate to Domain TLS for each domain on the virtual host that matches the certificate.

  • The system only copies the certificate to Domain TLS if the certificate passes OpenSSL’s validity check. This check occurs daily.
  • The system removes certificates from Domain TLS if they fail validation or are set to expire within one day.
  • Certificate removal follows the same pattern. The system removes Domain TLS entries for all domains on the virtual host that match the certificate.
Important:

If your SSL certificate and key did not pair correctly, Apache cannot start with SSL enabled. To check whether they paired correctly, run the following commands, where filename represents the certificate name:

1
2

openssl x509 -noout -in filename.crt
openssl rsa -noout -text -in filename.key
If the modulus number and exponent that each file returns match, the certificate and key paired correctly.

Service-default SSL certificates

Non-Apache services use default SSL certificates that administrators can manage via WHM. These services only serve the default SSL certificate to the client if no certificate in Domain TLS matches the client’s requested domain.

Note:

FTP is the only service that does not support name-based SSL.

When the administrator installs a service-default SSL certificate, the system compares this certificate with the contents of Domain TLS. For each domain on the default certificate, the system installs that new certificate to Domain TLS. The system only performs this action if an SSL certificate with higher-grade identity assurance does not already exist on Domain TLS. This ensures that the system serves the highest-grade SSL certificate for each request for every non-Apache service.

Troubleshooting SSL certificates

If you experience issues with your SSL certificates, use our Troubleshoot SSL-Related Issues document to help solve those issues.

Additional Documentation