Skip to main content

Your own certificate authority

A server that the public internet can't reach, a lab, or an internal deployment can't get certificates from Let's Encrypt, whose validation connects to the hostname or reads its public DNS. Two ways around it: point the panel at a certificate authority of your own that speaks ACME, so that issuance and renewal stay automatic, or import certificates you obtained elsewhere.

A private ACME certificate authority​

The panel talks to any CA over ACME, through an ACME client account whose endpoint is that CA's directory URL (ACME Client Accounts). An ACME server such as step-ca works.

At install time:

curl -fsSL https://repo.rekalogika.com/install.sh | sudo bash -s -- \
  --acme https://<ca host>/acme/<provisioner>/directory ...

--acme (or the environment variable ELPAN_ACME_URL) reaches server:init --acme, which creates a Custom ACME Account at that URL and makes it the active account, beside the two Let's Encrypt accounts it always creates (Install a server).

On a server that is already installed, add the account on System › ACME Client Accounts with the directory URL as its Endpoint, and the CA's External Account Binding credentials if it issues them, then Set as active. Or on the command line:

elpanctl certificate:acme:create "<description>" https://<ca host>/acme/<provisioner>/directory
elpanctl certificate:acme:set-active <id>

What the server must trust​

The CA's root certificate has to be in the server's own trust store before the first order: the directory is reached over HTTPS, and the panel's trust check, Trusted on a certificate's page and certificate:test-trust, validates a chain against that store. On Enterprise Linux:

install -m 0644 <root certificate>.pem /etc/pki/ca-trust/source/anchors/<name>.pem
update-ca-trust
Every client needs the root too

A certificate from a private CA is trusted only where its root is installed. Each browser, mail client and machine that connects to the server needs the root in the store it reads: the operating system's, and separately the NSS database of Firefox and of Chromium on Linux, and a Java keystore for Java clients. Without it, visitors see the same warning a self-signed certificate gives.

What differs from a public CA​

  • Short lifetimes. A private CA may issue certificates that live a day. The panel renews at two-thirds of the lifetime (half of it under 10 days), in its hourly round, and never reorders an identical set within six hours, so a 24-hour certificate is renewed about every 16 hours. A CA that offers no ACME Renewal Information keeps that rule; one that does is followed.
  • IP addresses. A public CA certifies public addresses only, so the default setting of an address, Automatic, asks for nothing on a private one. A private CA that issues for IP identifiers over HTTP validation can certify any address: set the address to On, under Shared IP Address Groups, or with certificate:ip:set <address> on (Certificates). The CA is sent no profile when its directory lists none.
  • Validation still has to work. The CA validates a hostname by connecting to it on port 80, or by reading a DNS record from the zone the panel hosts. It needs to reach the server's addresses and resolve its names the way visitors do.

Import a certificate​

certificate:import puts a certificate you obtained anywhere, with its private key, straight into service:

cat <key>.pem <certificate>.pem <chain>.pem | elpanctl certificate:import

The PEM blocks can come in any order; the certificate whose public key matches the private key is the leaf, every other certificate is its chain. Your shell reads the files, not the panel: it runs as its own user and never reads a path you name, because reading as root would let anything that runs as that user read any key on the machine.

The owner follows the names in the certificate: the account that owns every host it names, or the server when the names span owners or belong to the server. The imported certificate is Issued at once and applied to the hosts it covers, where the panel's chooser puts the best one into service: the highest validation tier (EV, OV, DV), then the longest remaining validity.

What the import refuses:

  • A server certificate that names an account's host. A certificate that names any IP address is the server's, so one naming an address and an account's hosts is refused for the same reason.
  • A certificate that names IP addresses only. The server's address certificates are the panel's own to order and pin.
Nothing renews an imported certificate

The panel renews what it ordered. An imported certificate expires on its date; the panel announces it at 30 and 7 days left, and a host on automatic provisioning orders its own certificate from the active ACME account when the imported one reaches its renewal point. Import again before expiry, or let the automatic certificate take over.

An account holder can do the same for their own domains, with a key the panel generates and a CSR the panel builds, on Account Certificates.