AiPBX
Features Install Videos Mobile Docs Live demo Contact Sponsor on GitHub UpCloud ($250 Free Credit) YouTube GitHub
ODOO Connect AiPBX with Odoo CRM & ERP — manage calls & customers in one place. Try Odoo Free →
Home / Documentation / Certificates

Certificates

AiPBX uses one TLS certificate for everything that speaks TLS:

ServiceUses it for
Apache (behind the 443 edge)the portal, the mobile API, WebRTC signalling (/ws), chat
coturnTURNS, the encrypted media relay for WebRTC clients on restricted networks
AsteriskSIP-TLS (5061) and its WSS transport, also reached on 443 by phone regions with SIP over TLS on port 443

A phone region with its own SIP server name for SIP on 443 (sip1.example.com, even in another domain) adds that name to the Let's Encrypt certificate: one certificate carries every name. Each name must point to this server in DNS, and port 80 must reach it (or, with Cloudflare DNS validation, the token must cover that domain too). After adding a name, press Renew now on this page: a renewal that finds a region name the certificate lacks makes the certificate again with it, the same way it was made (Apache, webroot or Cloudflare DNS). The automatic renewal keeps the names the certificate has.

A name joins only once it points to the same address as the portal's name (loopback lines in /etc/hosts do not count); until then it is left out, so one wrong DNS record cannot fail the request for the portal's own name. The command line says which names were left out: sudo aipbx-cert renew --dry-run. At most 98 region names fit in one certificate.

The active certificate lives in /etc/ssl/aipbx/active.{crt,key}. coturn and Asterisk run as their own users, so they get copies (/etc/coturn/aipbx.*, /etc/asterisk/keys/); /etc/ssl/aipbx/mode records where the certificate came from (letsencrypt, custom or selfsigned).

The Certificates page

Security → Certificates (admin only) shows the active certificate — name, the names it is valid for, issuer, validity, chain and SHA-256 fingerprint — and checks whether coturn and Asterisk really use the same one. It flags the problems that break calls without an obvious error:

  • self-signed — browsers show a warning for the portal and refuse TURNS entirely, so remote WebRTC calls have no audio;
  • domain mismatch — the certificate does not cover PORTAL_DOMAIN;
  • incomplete chain — the intermediate certificate is missing; some browsers and TURNS clients cannot verify it;
  • expired / expiring soon / not yet valid;
  • a service's copy differs from the active certificate — apply it again.

From the page an admin can:

  1. Get a Let's Encrypt certificate. Supports two validation challenge methods: Test runs against Let's Encrypt's staging server first, so a misconfiguration does not use up the production rate limit. Renewal is automatic (checked twice a day, renewed when less than 30 days are left); Test renewal and Renew now are on the page.
    • HTTP-01 (Standard): Requires port 80 to be open and reachable from the public internet to validate domain ownership.
    • DNS-01 (Cloudflare API): Validates domain ownership via Cloudflare DNS TXT records. Port 80 does NOT need to be exposed to the internet, and Wildcard certificates (*.domain.com) are supported. Requires a Cloudflare API Token with Zone:DNS:Edit permission.
  2. Upload a certificate — PEM files (certificate, optional intermediate chain, private key) or a single PFX/P12 file with its password. The key, validity, domain and chain are checked before anything changes; a certificate that does not cover the portal's domain is only accepted when you tick the override.
  3. Go back to a self-signed certificate.

Switching the certificate reloads Apache, restarts coturn (TURNS connections drop for a few seconds) and reloads Asterisk's PJSIP module.

From the command line

The page runs aipbx-cert through the root helper; you can run it directly:

sudo aipbx-cert letsencrypt --dry-run --email [email protected]                   # HTTP-01 test against staging
sudo aipbx-cert letsencrypt --email [email protected]                             # HTTP-01 issue and apply
sudo aipbx-cert letsencrypt --dns-cloudflare --wildcard --email [email protected]  # DNS-01 Cloudflare wildcard issue
sudo aipbx-cert renew --dry-run
sudo aipbx-cert selfsigned

The result of the last operation is in /var/lib/aipbx-system/cert-status.json and on the page.

Renewals

certbot's deploy hook (/etc/letsencrypt/renewal-hooks/deploy/aipbx.sh) calls aipbx-cert renewal-hook. It only acts while Let's Encrypt is the active source, and copies the renewed certificate with its full chain to coturn and Asterisk, so TURNS keeps working after a renewal.

Self-signed and internal domains

Let's Encrypt only issues certificates for names that resolve on the internet. For an internal name (e.g. pbx.company.local) upload a certificate from your own CA and install that CA on the clients. With a self-signed certificate the portal works after accepting the warning, but WebRTC TURNS does not: calls from browsers or the apps outside the server's network will have no audio. See WebRTC, NAT and TURN.

View or edit this page on GitHub

On This Page