Certificates#

System → Certificates lists the router's certificate authorities and certificates: what each one is, when it expires, and what in the configuration uses it. From here you import one, generate one, or have the router request a certificate from an ACME server such as Let's Encrypt and renew it itself. The page's subtitle: "Certificate authorities and certificates on the router, including those it requests from an ACME server."

Like every editor, the ones on this page add to the pending changes; nothing reaches the router until the changes are applied from the bar at the bottom of the page. The bar marks certificate changes as able to cut off your connection, since a service you reach the router through may use the certificate, so Apply with auto-revert is the safer way to apply them.

Anyone can open an entry and read it. Adding, replacing, deleting and changing entries need the operator role.

The certificate the web interface itself is served with is not one of these entries: it belongs to the agent, and a backup carries it. Nothing on this page changes it; serving the web interface with another certificate is a start-up option of the agent, set at the console, as The web interface's certificate describes.

The tiles#

Tile	Shows
Certificates	How many certificates the router holds.
Expiring within 30 days	Certificates and certificate authorities that expire within 30 days or have expired, in warning colour when there are any.
Requested by ACME	How many certificates the router requests from an ACME server.
Certificate authorities	How many certificate authorities the router holds.

The two tables#

Certificates and Certificate authorities, each with its count:

Column	Shows
Name	The name other settings refer to it by. ACME marks a certificate the router requests; Unreadable, one whose stored certificate cannot be read.
Names	For a certificate: the host names and addresses it is valid for, or its subject when it names none.
Subject	For a certificate authority: its subject.
Issued by	The certificate authority on this router that signed it, Self-signed, or the issuer's name when the issuer is not on this router.
Expires	The date; "12 days left" in warning colour within 30 days; Expired; or Not issued yet for an ACME certificate the router does not have yet.
Used by	What in the configuration refers to it, by the name of its page and the interface where there is one, such as OpenVPN vtun0 or HTTPS API; or Nothing.

With no entries: "No certificates" — "Import one, generate one, or have the router request one from an ACME server such as Let’s Encrypt." — and "No certificate authorities" — "A certificate authority on the router can sign certificates for VPN clients and servers."

If Nginx Proxy Manager is installed from the catalogue, a card above the tiles notes that the certificates it issues are kept in its own store and do not appear on this page (integration offers).

Adding an entry#

Add certificate and Add certificate authority, in the page header, each offer a choice:

Choice	What it does
Import	"Paste a certificate and its private key." For a certificate authority: "Paste a certificate authority’s certificate, and its key to sign with it."
Generate	"Create a certificate signed by a certificate authority on the router, or by itself." For a certificate authority: "Create a new certificate authority on the router."
Request from an ACME server	Certificates only: "The router requests the certificate, from Let’s Encrypt for example, and renews it."

The check before anything is added#

An import or a generated entry is not added straight away. The form first goes to the agent — Check certificate for an import, Generate for a new entry — which reads it, checks it against what the router holds, and answers with what the entry will be: Subject, Names, Issued by, Expires, Key, and Private key (Stored on the router or None), with any warnings beneath. Only then does the button become Add certificate (or Add certificate authority), which adds the entry to the pending changes.

Changing any field after the check discards its result, and the check has to be run again. When the agent refuses the entry, the panel says "The certificate cannot be added", with the reason.

Import#

Field	Accepts
Name	"Other settings refer to it by this name." Up to 64 letters, digits, dots, hyphens and underscores, not a name already in use.
Description	Any text, up to 255 characters.
Certificate	"PEM, beginning -----BEGIN CERTIFICATE-----."
Private key	"PEM. It is stored on the router and not shown again."

The check refuses:

a private key that does not belong to the certificate;
a private key protected by a passphrase: "Remove the passphrase and paste it again";
for a certificate authority, a certificate that is not a certificate authority's: "Import it as a certificate".

It warns, and still lets you add the entry, when:

more than one certificate was pasted: only the first is imported, and the others can be imported as certificate authorities;
a certificate authority's certificate is imported as a certificate, which cannot sign others;
a certificate comes without its private key: "The router can present this certificate only with its private key.";
the certificate has expired, expires within 30 days, or is not valid yet.

Generate#

Field	Accepts
Name, Description	As for Import.
Common name	Required; up to 64 characters.
Organisation	Up to 64 characters.
Names	Certificates only. The host names, wildcards such as `.example.com`, and IP addresses the certificate is valid for. "The common name when empty."*
Identifies	Certificates only: A server, A client, or A server and a client.
Valid for	Days: a certificate from 1 to 3650 (365 unless changed), a certificate authority from 1 to 9125 (3650 unless changed).
Key	EC P-256 (the default), EC P-384, RSA 2048 or RSA 4096.
Signed by	Itself — "Itself (self-signed)", or for a certificate authority "Itself (a root certificate authority)" — or a certificate authority on the router whose private key the router holds.

Generate creates the key and the certificate and shows the result; the key is stored with the entry when it is added. Signed by a certificate authority on the router, an entry is valid no longer than that authority ("Valid until 2031-05-01, when home-ca expires."), and a certificate authority that has expired cannot sign. A certificate authority signed by another becomes an intermediate, which can sign certificates but not further certificate authorities. A server certificate that names no host name or address, and whose common name is not one, comes with a warning that browsers will not accept it for any site.

Request from an ACME server#

"The ACME server checks each name on port 80, so every name must resolve to this router and port 80 must reach it."

Field	Accepts
Name	As for Import.
Domain names	One or more host names.
Contact email	"The ACME server sends expiry notices here."
ACME server	Let’s Encrypt; Let’s Encrypt staging, for testing; or Another server, with its Directory URL, beginning `https://`.
Answer on	Every address, or one of the router's addresses: where the router answers the server's check on port 80.
RSA key size	2048 (the default), 3072 or 4096.

Request certificate adds the request to the pending changes. The router requests the certificate when the changes are applied, and renews it itself. If the ACME server refuses, applying the changes fails with its reason. Until the router has the certificate, the table shows Not issued yet.

The whole procedure is in Request a certificate from an ACME server.

An entry's panel#

Selecting an entry opens it, under its name and what it is: Certificate authority, Certificate requested by ACME, or Certificate.

Fact	Shows
Problem	Why the stored certificate cannot be read, when it cannot.
Subject	Who the certificate is for.
Names	The host names and addresses it is valid for.
Issued by	As in the table.
Valid from, Expires	Its validity.
Key	The key's type and size, such as EC P-256 or RSA 2048.
Identifies	A server, A client, or both.
Private key	Held by the router or Not held.
SHA-256 fingerprint	The certificate's fingerprint, in pairs of hex digits.

ACME request, for a certificate the router requests: Domain names, Contact email, ACME server, Answers on ("Every address, port 80" or an address with port 80) and RSA key size.

Used by lists what in the configuration uses the entry, or says "Nothing in the configuration uses this certificate." For a certificate authority it also names the entries on the router it issued.

Trust, for a certificate authority: Trusted by the router — "The router accepts certificates this authority issued, for its own connections." Switching it adds the change to the pending changes: "Trust certificate authority “home-ca” on the router".

Description, with Save, adds a changed description to the pending changes.

At the foot of the panel:

Replace certificate, or Edit request for a certificate the router requests;
Delete certificate or Delete certificate authority, which asks "Delete home-ca?" before it adds the removal to the pending changes.

Delete is disabled while anything in the configuration uses the entry. Its tooltip names the users: "Used by OpenVPN vtun0. Remove it from there first." A setting that names a certificate needs it to exist, so the setting is changed first, on its own page; then the entry can be deleted.

Replace certificate#

Replace certificate opens Replace the certificate of web (for an entry named web): the Import form without Name and Description. Paste the new certificate. When the router holds the entry's private key, the key field says "Leave empty to keep the key the router holds.": a renewal issued for the same key needs no key pasted. A certificate issued for a different key is refused unless its private key is pasted too: "The certificate was not issued for the private key the router holds for web. Paste the private key that belongs to it." After the check, Replace certificate adds the new certificate to the pending changes.

A certificate the router requests from an ACME server is replaced by the router itself; Edit request changes the request instead: its names, contact, server, address and key size, with Save changes.

What the pending changes say#

The bar describes certificate changes without the certificate or the key:

"Add certificate authority “home-ca”", with "With its private key" beneath it;
"Replace the certificate “web”";
"Request certificate “router” from an ACME server", with the names it covers;
"Trust certificate authority “home-ca” on the router";
"Remove certificate “web”".

In Advanced mode#

With Advanced mode turned on (Account → Preferences), the page header shows the part of the configuration the page edits, pki, and the pending changes are also listed as the router's commands.

For automation#

GET /api/pki/certificates (viewer) answers what the page shows: every entry, parsed, with the settings that use it and whether the router holds its key; the key itself never. POST /api/pki/plan (operator) is the check: it takes an import or a generate request and answers with the entry, any warnings, and the changes that would store it. It stores nothing; the changes are added and applied the same way as any others.