TLS Certificates

This page covers the operator's side of managing the TLS certificate that the appliance presents on its web interface. The screen described here is TLS Certificates in the operator TUI.

The screen has two parts.

• The status panel at the top shows the subject, issuer, validity window (with an in-line warning when the certificate is within 30 days of expiry), the IP and DNS SANs the certificate covers, the SHA256 fingerprint, and a Type: line that says whether the active certificate is self-signed or customer-supplied.
• The actions list at the bottom offers Generate CSR, Upload Certificate, and Restore Self-Signed — plus Cancel CSR when a request is awaiting signature.

If the SFTP exchange directory already contains staged certificate files when the operator opens the screen, a hint such as 1 cert ready in SFTP — Upload to apply appears under the status panel as a reminder that there is work to do.

Press r at any time on the main view to reload the panel — useful after a customer has just uploaded files over SFTP and you want the hint to appear without leaving the screen.

What ships out of the box

A freshly installed appliance generates a self-signed certificate on first boot and serves it on the web interface. There is no public CA signature involved, so browsers will warn on the first visit — that is expected.

For headless or LAN-only deployments the self-signed certificate is often sufficient: the mobile app does not rely on a public CA at all. It verifies the appliance by fingerprint instead, which makes pairing safe even when the certificate is self-signed. See Fingerprint and mobile pairing below for the verification flow.

If you do want browsers to trust the certificate without a warning — or you have policy reasons to install a customer-supplied certificate — use Upload Certificate as described next. To go back to the appliance-generated certificate at any time, use Restore Self-Signed.

Requesting a CA-signed certificate

If your CA signs certificates from a certificate signing request (CSR), the appliance can generate the request and the matching private key for you — the private key never leaves the appliance.

1. From the TLS Certificates screen, choose Generate CSR and confirm. The active certificate keeps serving traffic; only a new pending key is created. The request reuses the appliance's IP and DNS names, so the signed certificate covers the same addresses.
2. Connect over SFTP and download pulse-csr.pem from the downloads/ folder, then submit it to your CA. SFTP access is set up on the SFTP Access screen.
3. While the request is awaiting signature, the status panel shows a CSR pending CA signature reminder and a Cancel CSR action appears.
4. When the CA returns the signed certificate, install it with Upload Certificate (see below). Because a request is pending, the appliance matches the certificate against the pending key automatically — you do not upload a key.

If a request already exists and you generate another, the pending key is replaced and any CSR you already submitted becomes invalid. To abandon a request without installing anything, choose Cancel CSR — it removes the pending key and request and leaves the active certificate untouched.

Uploading your own certificate

The Upload Certificate action accepts a PEM-encoded certificate and, optionally, a PEM-encoded private key. Two delivery paths are supported: a USB drive plugged into the appliance, or files staged into the SFTP exchange directory. The validation, install, and reload steps are identical in both cases — only the source picker differs.

Both paths accept only PEM-encoded inputs. If a file is not parseable as PEM, or if the certificate and key do not match, the TUI reports the error inline and does not install anything; the previously active certificate continues to serve traffic.

The key prompt also adapts to whether a CSR was generated earlier:

• If there is a pending key in tls-key-pending.pem (the operator generated a CSR and is now installing the signed certificate that came back from the CA), uploading the certificate alone matches it against the pending key.
• Otherwise the certificate is matched against the currently active key — useful when only the certificate itself is being rotated.
• If the operator picks a key file too, the cert/key pair is validated together before anything is written to disk.

Via USB

Use this path when you are at the appliance with a thumb drive in hand.

1. Copy the PEM certificate (and the private key, if you are rotating it) to a USB drive formatted as FAT32 or ext4. Files must have the .pem extension to be discovered by the picker.
2. Plug the drive into the appliance. The TUI mounts it read-only at /mnt/usb.
3. From the TLS Certificates screen, choose Upload Certificate, then USB as the source.
4. If more than one USB drive is detected, pick the right one. The TUI then scans for .pem files and shows a picker. If no .pem files are found, the screen returns to the source picker with an error — copy the files to the drive's root or a top-level directory and try again.
5. Select the certificate file and press Enter. The TUI parses the PEM. If parsing fails it shows a red error and stays on the picker — fix the file and try again.
6. The TUI then asks whether you also have a new key file to upload. Pick the key from the same drive, or skip if you are reusing the currently active key (or, if a CSR was generated previously, the pending key in tls-key-pending.pem).
7. On success the certificate is installed, nginx is reloaded with the new pair, and the screen returns to the main view with a green confirmation. The drive is unmounted automatically.

If you press Esc partway through the flow — for example after picking the wrong cert file — the TUI walks back through the previous step. From the cert picker, Esc returns to the source picker and unmounts the drive; from the key prompt, Esc returns to the cert picker so you can choose again.

Via SFTP

Use this path when the customer wants to deliver the certificate over the network rather than carry a USB stick. The prerequisite is that the customer can authenticate to the SFTP exchange — by SSH key or the appliance's password; see SFTP Access to set that up.

1. The customer uploads the certificate (and key, if separate) into the exchange directory under uploads/certificates/. From their perspective they SFTP to the appliance as the pulse-transfer user and put the files.
2. The TLS Certificates screen will show a hint such as 1 cert ready in SFTP — Upload to apply when files are waiting. Choose Upload Certificate, then From SFTP exchange as the source.
3. The TUI lists every .pem file staged under uploads/certificates/. Pick the certificate, answer the key prompt, and confirm. Validation rules are the same as the USB path.
4. On success the consumed files are removed from the exchange directory and an audit entry is written so the operator can later show which customer-supplied file was applied and when.

If a file in the exchange directory is not a valid PEM, the TUI reports it and skips installation — the file remains in uploads/certificates/ for the customer to replace. The same applies to certificate/key mismatches: nothing is installed, and the staged files are kept so the customer can correct and re-upload.

If you reach this screen and the SFTP list is empty, the most common cause is that the customer uploaded into the wrong subdirectory. Files for this picker must land specifically under uploads/certificates/; bundles or unrelated PEM files elsewhere in the exchange are ignored by the TLS Certificates screen.

Restoring the self-signed certificate

The Restore Self-Signed action regenerates an appliance-controlled self-signed certificate and switches the web interface back to it. Reach for this when:

• The uploaded customer certificate turns out to be wrong (mismatched subject, expired before installation, signed by the wrong CA).
• The uploaded certificate has expired and no replacement is ready — restoring the self-signed certificate returns the appliance to a working HTTPS state so operators can still reach the web UI.
• You are wiping a customer-specific configuration off the appliance ahead of redeploying it elsewhere.

The confirmation prompt warns that the current certificate will be replaced and that nginx will reload. Any pending CSR is cleaned up as part of the restore — a stale tls-key-pending.pem left over from a half-finished CSR cycle is best-effort removed. If the current certificate is already self-signed, the prompt offers to regenerate it anyway, which produces a fresh fingerprint while keeping the same Type: Self-signed label.

The new self-signed certificate is regenerated using the appliance's current site IP (read from /var/pulse/site.env) as one of the SANs. In DHCP mode the site IP may be empty, in which case the IP SAN is omitted; this is normal and does not affect the mobile pairing flow, which relies on the fingerprint rather than the SAN.

Fingerprint and mobile pairing

The Fingerprint row on the main TLS Certificates panel shows the SHA256 fingerprint of the active certificate, formatted with colon separators (for example, AB:CD:EF:...). This is the value the Pulse mobile app asks the operator to verify during first-run pairing.

Because the appliance often serves a self-signed certificate, the mobile app cannot rely on a public CA to authenticate the server. Instead, the app shows the fingerprint of the certificate it received and asks the operator to compare it with the value displayed on this screen. They must match character-for-character. If they do not match, abort pairing — the connection is being intercepted, or the operator is looking at the wrong appliance.

The fingerprint changes whenever the certificate changes — including every time Restore Self-Signed is used, since that regenerates the key pair. After restoring (or uploading a new certificate) any already-paired mobile devices will surface a fingerprint-mismatch warning the next time they connect; reconfirm the new fingerprint from this screen.

Related screens

• SFTP Access — authorise the customer, by SSH key or the appliance password, for the SFTP upload path described above.
• Mobile Setup & Pairing — how the mobile app uses the fingerprint shown on this screen to verify the appliance.
• TUI Reference — the full operator menu.