Custom SSL

Every custom domain gets a free automatic certificate. Custom SSL lets you install a certificate you supply instead, for example one you bought from a certificate authority. It is an add-on for one site, $500 a year, billed once a year.

Which layer carries your certificate

Read this first, because it decides what your visitors see.

Visitors reach your site through Cloudflare. Cloudflare answers the visitor with its own certificate for your domain, and then connects to your server and checks the certificate the server shows.

• On the server. Avaloi installs your certificate on the server. Cloudflare checks it on every connection, and it must chain to a public certificate authority. Visitors see Cloudflare's own certificate, not yours. This is how it works today.
• On the server and on Cloudflare. Cloudflare only lets a certificate you supply reach visitors on its Enterprise plan. If Avaloi's Cloudflare plan allows it and Avaloi has turned it on, your certificate also goes to Cloudflare and visitors see it.

Each domain row on the Domains tab says which of the two applies, and the dialog says it before you install.

A certificate with your organization's name in it (OV or EV) is therefore not shown to visitors unless the second case applies. Ask support if you need that.

Turn it on

1. Open the site and choose Add-ons.
2. On the Custom SSL card, choose Enable, check the price, and confirm. You need a saved card.

The whole year, $500, is charged to your saved card now, and it renews every year on the same day. There is no free first month and no proration: the year starts today. If the card is declined, nothing is bought and you can try another card. You can turn the add-on off at any time (see below).

The Install custom SSL option appears on the Domains tab only while the add-on is on.

Install a certificate

1. Open Domains and find the domain. It must be active.
2. Open the row menu and choose Install custom SSL.
3. Paste the certificate with its intermediate certificates, your own certificate first. Paste the private key in the second box. The key must not have a password.
4. The dialog checks both and shows the end date. Choose Install certificate.

Avaloi checks the text again on the server. It refuses a certificate that:

• is not PEM, or has a private key in the certificate box;
• does not cover the domain (a wildcard such as *.example.com covers one label);
• has expired, is not valid yet, or has 7 days or fewer left;
• is self-signed, or does not chain to a publicly trusted authority (Cloudflare would refuse it and the site would show an error);
• does not match the key, or has an encrypted key, or a weak key (RSA under 2048 bits, or a curve other than P-256 and P-384).

The key is sealed when it arrives. Avaloi never shows it again, and it never appears in logs, jobs, or the activity log.

You renew it

Avaloi cannot renew a certificate you supply. While yours is installed, the automatic certificate for that domain stops renewing. The bell warns you 30, 14, and 7 days before the end, and once more if it ends, and the Domains tab shows a banner.

To renew, choose Replace custom SSL and paste the new certificate and key.

If it ends before you replace it, the domain goes back to the automatic certificate on its own, so visitors never see an error. Avaloi deletes the ended certificate and its key and orders the automatic one, and the bell tells you. The add-on stays on, so you can install a new certificate whenever you are ready.

Remove it

Choose Remove custom SSL on the domain. Avaloi deletes your certificate and key and orders the automatic certificate again. Visitors keep a valid certificate throughout.

Turn the add-on off

On the Add-ons tab, choose Disable on the Custom SSL card. The add-on ends now, every certificate of the site is deleted with its key, and the domains return to the automatic certificate. The unused days of your year are credited to your account balance and pay down your next invoice. Nothing is refunded to the card.

The add-on also ends, with the same result, when you delete the site, or when Stripe cancels the yearly subscription because a renewal could not be paid. A certificate left installed in that case keeps its state on the Domains tab with a Remove custom SSL option, so you are never stuck.

API and assistants

• PUT /v1/domains/{id}/custom-certificate installs a certificate (certificate_pem and private_key_pem). It needs the permission to edit domains.
• GET /v1/domains/{id}/custom-certificate and GET /v1/environments/{id}/custom-certificates answer metadata only: subject, issuer, names, dates, fingerprint, status, and the layer. The key is never returned.
• DELETE /v1/domains/{id}/custom-certificate?confirm=true removes it.
• Assistants have get_custom_certificate and remove_custom_certificate. There is no install tool on purpose: a private key must never be pasted into a chat.