File-Based Authentication for SSL Certificates

File-based authentication is one of the Domain Control Validation (DCV) methods supported for SSL Certificate issuance and reissue. The process works by placing a small text file at a specific location on your web server, where the Certificate Authority (CA) can retrieve it over Hypertext Transfer Protocol (HTTP) to confirm that you control the domain.

This page covers how to set up file-based authentication, important requirements when your SSL Certificate covers both the root domain and the www subdomain, server configuration for common platforms, and troubleshooting steps when validation fails. Learn About The Trustico® Validation Procedure 🔗

File Placement Requirements

After you place your order, the Trustico® system will generate a unique verification file containing specific content. You will need to upload this file to your web server inside the following directory :

/.well-known/pki-validation/

This directory path is an industry standard location for domain validation files, defined by the Internet Engineering Task Force (IETF). Most web servers serve files from this location by default, which makes it the appropriate place for validation files.

Implementation Steps

The following steps assume you have shell access to your web server. The example commands use example.com as a placeholder for your actual domain. Substitute your domain name where required.

First, create the required directory structure on your web server :

mkdir -p /var/www/example.com/.well-known/pki-validation/

The -p flag ensures that all necessary parent directories are created if they do not already exist. The command creates the full directory path in a single step.

Next, create the verification file. The Trustico® tracking system provides the exact filename, which is derived from the MD5 hash of your Certificate Signing Request (CSR), along with the three lines of content that the file must contain.

The contents of the file must include the SHA-256 hash of your Certificate Signing Request (CSR) on the first line, the text "sectigo.com" on the second line, and optionally a unique value on the third line. The exact values are provided in your order confirmation.

cat > /var/www/example.com/.well-known/pki-validation/MD5HASH.txt << EOF
SHA256_HASH_OF_CSR
sectigo.com
EOF

The content must match exactly what was provided in your order confirmation. A single character difference will cause validation to fail. The MD5HASH.txt portion of the path must be replaced with the actual MD5 hash filename provided through the tracking system.

Set the correct file permissions :

chmod 644 /var/www/example.com/.well-known/pki-validation/MD5HASH.txt

The permission setting 644 allows the file to be read by everyone but only written by the owner. This is the standard permission for web-accessible files, allowing the web server to serve the file while preventing unintended modification.

Server Configuration

Some web servers require additional configuration to serve files from the /.well-known/ directory. The configuration block depends on the web server software in use.

For Apache, add the following directive to the appropriate virtual host configuration file :

<Directory "/var/www/example.com/.well-known">
    Allow from all
</Directory>

This Apache directive specifically allows access to the .well-known folder while leaving the rest of the security configuration in place.

For Nginx, add the following location block to the appropriate server block :

location /.well-known {
    allow all;
}

This Nginx block permits access to the .well-known directory. After making changes to either Apache or Nginx configuration, the web server must be reloaded for the changes to take effect.

Troubleshooting

If validation is failing, several commands can help diagnose the cause. The first check confirms that the verification file exists and has the correct permissions :

ls -la /var/www/example.com/.well-known/pki-validation/

The command displays a detailed list of files in the validation directory, showing permissions, ownership, and file sizes. The verification file should have permissions of 644 and be readable by the web server user.

The next check tests whether the file is actually reachable over Hypertext Transfer Protocol (HTTP) from outside the server :

curl -v http://example.com/.well-known/pki-validation/MD5HASH.txt

The curl command shows exactly what the Certificate Authority (CA) sees when retrieving the verification file. A successful response shows HTTP/1.1 200 OK followed by the file contents. If the response is a redirect, error code, or different content, the validation will fail.

If the SSL Certificate covers both the root domain and the www subdomain, the same check should be repeated against the www location :

curl -v http://www.example.com/.well-known/pki-validation/MD5HASH.txt

Both responses must return HTTP/1.1 200 OK with the correct file contents for the SSL Certificate to include both names.

Web server logs can also reveal validation issues. For Apache, log entries appear in the error log :

tail -f /var/log/apache2/error.log

For Nginx, the equivalent log location is :

tail -f /var/log/nginx/error.log

These commands display real-time log entries as the validation system attempts to retrieve the file, which can help identify permission or configuration issues that block successful validation.

Security Practices

After your domain has been validated and your SSL Certificate has been issued, the verification file can be removed :

rm /var/www/example.com/.well-known/pki-validation/MD5HASH.txt

The verification file content is not sensitive, but maintaining a clean server environment is recommended. The file will only be needed again at the next reissue, when a new verification file will be generated.

Alternative Domain Control Validation (DCV) Methods

File-based authentication is one of several Domain Control Validation (DCV) methods that Trustico® supports. Other methods include Canonical Name (CNAME) based validation through your Domain Name System (DNS) records, and e-mail based validation through pre-defined administrative addresses at your domain. Each method has its own requirements and limitations, and the appropriate choice depends on the access you have to your web server, your Domain Name System (DNS) records, and your e-mail infrastructure. Learn About The Trustico® Validation Procedure 🔗