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
— site/server certificatechain.crts
— certificate chain without root (without server certificate)fullchain.crts
— site/server certificate and certificate chain without rootprivkey.private
— private keyroot.crt
— self-signed root certificate (optional: usually not required on the server)
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
The fullchain and chain are given distinct names to clearly indicated which includes, and which excludes, the site/server certificates.
The .crt and .crts file extensions are used to clearly indicate which always contains exactly one certificate, and which one contains one or more certificates.
The .private file extension is used to avoid conflicts with .pvt which is already being used by other programs (e.g. Pivot Stickfigure Animator files, Fidonet Pointlist files and PlayStation RSD Pivot files).
The .pem file extension is not used, because it is ambiguous as to what it contains. The Privacy Ehanced Mail (PEM) format is a text encoding that can be used to encode very different binary data. This extension is not sufficient enough to indicate what the file contains.
Credential files are not stored under /etc/pki, since that directory is used by OpenSSL. It is not intended for Nginx or the Apache Web Server to use.