Certificates

SBN Media uses TLS certificates to secure its encrypted connections - the secure SIP ports, secure WebSocket, and HTTPS. It can obtain and renew these certificates automatically from Let's Encrypt.

Overview

The encrypted endpoints across SBN Media use TLS certificates: the secure SIP ports (sips and wss) on the SIP Server, and HTTPS on the API Proxy. SBN Media manages these certificates for you - it obtains a free certificate from Let's Encrypt for a domain you control, stores it, and renews it before it expires.

Certificates are stored as files - a certificate and a matching key per domain - in SBN Media's certificate directory, and the encrypted endpoints load them from there.

1. Applies to: Every encrypted endpoint - secure SIP (sips / wss) and HTTPS (the API Proxy).
2. Required: Only when you use encrypted connections. Plain, unencrypted endpoints do not need a certificate.
3. Depends on: A domain you control that Let's Encrypt is able to verify.

Managing certificates

Certificates are obtained and renewed with the certificate commands:

1. create obtains a certificate from Let's Encrypt for the domain. Let's Encrypt verifies that you control the domain, so the domain must be set up to point at this host. Add -s (--staging) to test against Let's Encrypt's staging service first - this avoids using up the limited number of real certificates while you get the setup right.
2. list shows the installed certificates and their expiry dates.
3. renew renews any certificate that is due to expire within 30 days; passing a domain forces that one to renew. Run it regularly - for example as a daily scheduled task - so certificates never lapse. Certificates that are still well within their validity are left untouched.

Turning on TLS

TLS is enabled per endpoint, not on this page. Once a certificate exists for the relevant domain, the endpoint uses it:

1. API Proxy - set apiproxy.protocol to https.
2. SIP Server - use the sips (5061) and wss (5081) ports.

FAQ

Do I need certificates?

Only if you use encrypted connections - secure SIP or HTTPS. Plain endpoints work without them. If you offer encrypted connections, you need a certificate for the domain clients use to reach SBN Media.

How do I stop certificates from expiring?

Run ./sbn-media certificate renew regularly, for example as a daily scheduled task. It renews anything within 30 days of expiry and leaves valid certificates alone, so it is safe to run often.

Can I test without using up my Let's Encrypt allowance?

Yes. Add -s (--staging) to certificate create to use Let's Encrypt's staging service while you get the setup working, then run it again without -s to obtain the real certificate.

Where are certificates stored?

As files - a certificate and a key per domain - in SBN Media's certificate directory. The encrypted endpoints load them from there automatically.

Can I use certificates other than Let's Encrypt?

Yes - follow the domain file name convention and it will be used by the services.

Related pages

1. SBN Media Overview (SBN-Media/overview)
2. Installing and Configuring SBN Media (SBN-Media/installation)
3. SIP Server (SBN-Media/Telephony/sip-server)
4. API Proxy (SBN-Media/Platform/api-proxy)