Install a custom certificate

Most sites are happy with a free Let's Encrypt certificate. Sometimes you need something else: an extended validation certificate your company requires, a certificate from an internal authority, a wildcard bought from a commercial provider, or one that a client supplied. SrvYard installs these too, and serves them with the same Nginx setup as a free one.

The difference is renewal. SrvYard cannot ask your authority for a new certificate, so a custom certificate is never renewed automatically. This article shows the three ways to get one onto a site, what SrvYard checks before it touches the server, and how to replace it before it expires.

Before you begin#

• A site in the Ready state and the permission to manage its SSL.
• A certificate that covers a name of the site. SrvYard refuses a certificate that does not include any hostname of the site, for example one issued for another domain.
• The matching private key, in PEM format and without a passphrase. If your key is encrypted, remove the passphrase first with openssl pkey -in encrypted.key -out server.key.
• The intermediate certificates your authority gave you, if they were not already part of the certificate file. Browsers need the whole chain.

1. Choose how to get the certificate#

The SSL tab of a site offers three routes for a custom certificate. The one you use depends on who holds the private key.

1. Install your own opens the panel where you paste a certificate and its key. Use it when you already have both.
2. The menu button next to it (three dots) holds Create a signing request, for when the authority has not signed anything yet, and Copy from another site, for a certificate that is already on the server.
3. Certificate in use. A custom certificate shows A certificate you installed and, in the Renewal line, Manual: we email you before it expires. Validation says Installed by you, and Issuer shows the authority that signed it.

2. Paste a certificate and its key#

Press Install your own. A panel opens from the right.

1. Certificate. Paste the certificate for your domain, including the BEGIN CERTIFICATE and END CERTIFICATE lines. Put your certificate first, then the intermediates if they are in the same file.
2. Private key. Paste the key without a passphrase, starting with a BEGIN PRIVATE KEY line (or the RSA or EC variant). It is stored encrypted in SrvYard and never shown again.
3. Intermediate certificates (optional). The CA bundle from your provider, when it was not in the certificate above. Duplicates are ignored.
4. Install certificate. Checks everything and installs it.

Before anything reaches the server, SrvYard checks the material with OpenSSL. The request is refused, with a message beside the field, when:

• the certificate field holds a private key, or has no certificate in it;
• the key cannot be read, or is protected by a passphrase;
• the key does not belong to the first certificate you pasted (the first certificate pasted must be the one for your domain, followed by the intermediates);
• the certificate has expired, or is not valid yet (the message gives the date);
• the certificate is for names that do not include any hostname of the site;
• the chain is longer than 10 certificates, or the pasted text is far larger than a normal certificate (60,000 characters for the chain, 16,000 for the key).

When the check passes, SrvYard writes the files under /etc/srvyard/ssl, makes the new certificate the one in use and reloads Nginx. If Nginx does not accept the new files, SrvYard puts the old setup back and the site keeps serving what it served before.

3. Let SrvYard keep the key: a signing request#

Some authorities want a certificate signing request (CSR) from you, and some security policies say a private key must never travel by email. With a signing request SrvYard creates the key, keeps it encrypted, and only the request leaves. Open the menu next to Install your own and choose Create a signing request.

1. Hostnames. Tick the names the certificate must cover. The wildcard name (for example *.acme-studio.example) is offered here too, because a wildcard bought from an authority does not need DNS validation by SrvYard.
2. Key type. ECDSA (secp384r1) is the default. Choose RSA only if your authority or a very old client needs it.
3. The subject fields. Country (2 letters), State or province, City, Organization, Department and Contact email, all optional. Fill in what your authority asks for.
4. Create request. Creates the key and the request.

A new row appears in the certificate list with the status Awaiting certificate. Open its menu and choose View signing request, then Copy request and paste it into your authority's order form. The panel reminds you that the private key stays in SrvYard, encrypted.

When the authority returns the signed certificate, open the same row's menu, choose Install signed certificate, paste the certificate (and the intermediates, if you got them separately) and confirm. SrvYard checks that the stored key matches, installs it and makes it the certificate in use.

4. Copy a certificate from another site#

If a wildcard or multi-name certificate is already installed for another site on the same server, you can reuse it.

1. Copy certificate. The panel lists installed certificates of other sites on this server that cover a name of this site. When there is none, it says No other site on this server has an installed certificate yet and the button stays disabled. Pick one and press Copy certificate.

The copy is its own certificate, with its own files. It is not renewed by SrvYard: when the original is replaced, copy it again. The expiry dates are the same, so one renewal alert per copy will arrive.

5. Replace it before it expires#

SrvYard emails the owners and admins of the organisation when an active certificate has 14 days or less left, and again every day while it stays that way, and when it has expired. Do not wait for the email.

1. Get the new certificate from your authority, with the same names.
2. Install it with Install your own (or Install signed certificate on the signing request row). The new certificate becomes the one in use; the old one stays in the list, so you can switch back with Use this certificate.
3. Check that the new Expires date is what you expected and, if you use it, that Force HTTPS is still on. See Force HTTPS and HSTS.
4. Delete the old certificate when you no longer need it. An expired certificate cannot be activated again: SrvYard says This certificate has expired. Renew it or install a new one.

A Deactivate puts the site back on HTTP only (and switches Force HTTPS off with it). It is the way out when a certificate turns out to be wrong.

Troubleshooting#

• "The private key does not belong to this certificate." You pasted a different certificate than the key was made for, or the intermediates came first. Put the certificate for your domain first.
• "The private key is protected by a passphrase." Remove the passphrase with openssl pkey -in encrypted.key -out server.key and paste the new file.
• "No certificate found. Paste a PEM certificate". The text is not PEM, for example a .p12 or .pfx bundle or a certificate in binary DER form. Convert it with openssl.
• "The certificate is for … which does not include any hostname of this site". The certificate was issued for other names. Ask the authority to reissue it, or add the missing name.
• The browser warns about an incomplete chain. The intermediates are missing. Install the certificate again with the authority's CA bundle in Intermediate certificates.
• The row stays on Awaiting certificate. A signing request is only a request. Send it to your authority and install the answer with Install signed certificate. Delete the row if you changed your mind.

Related#

• Get a free Let's Encrypt certificate: the automatic alternative.
• Force HTTPS and HSTS: redirect visitors once the certificate is in place.
• How renewals work and what to do when one fails: the alerts SrvYard sends for a certificate that is about to expire.
• Wildcard certificates with DNS validation: a free wildcard instead of a bought one.