Skip to main content

HS-PKI File Naming convention

This article describes a convention for storing PKI credentials as files: X.509v3 certificates, certificate trust chains and private keys.

This convention was developed for consistency. It allows the same conventions to used consistently for both Nginx and the Apache Web Server, which uses two different representations for the intermediate certificates and it can be confusing to refer to them both certificate chains. It chooses a single set of file name extensions, which is consistent and unambiguously represents the contents of the files.

Identifier

This convention can be referred to as the “HS-PKI File Naming v1.0” convention.

Credential files

cert.crt

The cert.crt file shall contain exactly one X.509v3 certificate.

This is the certificate of the site or server.

chain.crts

The chain.crts file shall contain one or more X.509v3 certificate, representing the trust chain for the certificate in cert.crt.

It does not contain the site/server certificate itself.

It does not contain the self-signed root certificate, since the root certificate normally needs to already exist on the client.

These certificates are sometimes referred to as the “intermediary certificates”.

If there are multiple certificates in chain.crts, they shall be in the order from the the server/site certificate towards the root certificate. That is, the first certificate in chain.crts must be the one that signs the site/server certificate in cert.crt, and any subsequent certificates sign the previous certificate in the file.

If there are no intermediate certificates, the chain.crts file shall not exist.

Most certificate issuers only use one intermediate certificate, so typically the chain.crts file contains only one certificate. But the file name extension is still .crts.

fullchain.crts

The fullchain.crts file shall contain the site/server certificate followed by one or more certificates representing the trust chain for it in signing order.

It does not contain the self-signed root certificate, since the root certificate normally needs to already exist on the client.

Therefore, this file always contains the concatenation of cert.crt followed by chain.crts. It always exists (even when there is no chain.crts file).

privkey.private

The privkey.private file shall contain the private key.

root.crt

The root.crt file should not be needed, since it is not served up by Web servers using HTTPS. The client should already have been configured with it.

If needed, the root certificate shall be stored in root.crt. The root certificate is always a self-signed certificate.

Using the convention

Configuring Nginx

Store the PKI credentials under /etc/nginx/pki, in a directory named after the fully qualified host name.

For example, if the site is www.example.com, store the files in /etc/nginx/pki/www.example.com.

In the configuration of the HTTPS server (e.g. in /etc/nginx/conf.d/https.conf), use those files like this:

server {
  ...

  ssl_certificate /etc/nginx/pki/www.example.com/fullchain.crts;
  ssl_certificate_key /etc/nginx/pki/www.example.com/privkey.private;

  ...
}

Configuring Apache Web Server

Store the PKI credentials under /etc/httpd/pki, in a directory named after the fully qualified host name.

For example, if the site is www.example.com, store the files in /etc/httpd/pki/www.example.com.

In the configuration of the HTTPS server (e.g. in /etc/httpd/conf.d/ssl.conf), use those files like this:

<VirtualHost _default_:443>
  ...

  SSLCertificateKeyFile "/etc/httpd/pki/www.example.com/privkey.private"
  SSLCertificateFile "/etc/httpd/pki/www.example.com/cert.crt"
  SSLCertificateChainFile "/etc/httpd/pki/www.example.com/chain.crts"

  ...
</VirtualHost

Design principles