Docs / Security

Security

This chapter covers the Security page and what it protects: intrusion prevention, which blocks addresses that keep failing to sign in, the never-block list, sign-in throttling for the console and portal, two-factor sign-in for administrators, and encrypted calls. The Security page is for system administrators. Tenant administrators do not see it.

The Certificate card at the top of the Security page is covered in Names and certificates. Toll fraud (who may call abroad, spending caps) has its own page and chapter: Call limits.

Intrusion prevention

Phone systems on the internet are scanned all day by machines that try SIP usernames and passwords. Onyx Voice counts every failed sign-in per address. When one address fails too often within a short time, the server blocks it at the firewall, before the phone engine or the web server sees another packet from it.

Two kinds of failure count, and they count together:

Failed SIP sign-ins: a phone, softphone or scanner that uses an unknown SIP username, a wrong password, or is turned away for another sign-in reason.
Failed web sign-ins: a wrong e-mail address or password at the sign-in page of the console or the portal, and a wrong two-factor code.

With the default settings, an address that fails 10 times within 10 minutes is blocked for 60 minutes. The block is lifted by itself when the time runs out.

A whole office often reaches the server from one public address. If one desk phone has an old password and keeps retrying, or one person mistypes their portal password ten times, that address is blocked and every phone in that office goes offline with it. Put your offices on the never-block list (see below).

When to block

To change when addresses are blocked:

Open Security in the console.
In the When to block card, set:
- Failed sign-ins: how many failures block an address. 0 turns automatic blocking off. Otherwise the value is 3 to 1000. The default is 10.
- Within (minutes): the time window the failures must fall in, 1 to 1440 minutes. The default is 10.
- Block for (minutes): how long a block lasts. 0 means until an administrator lifts it. The default is 60.
- Never block: see the next section.
Select Save.

The new values apply within half a minute. They are stored as the server settings security.ban_after, security.ban_window, security.ban_minutes and security.never_ban, so you can also set them from a shell, for example onyx setting set security.ban_minutes 1440 (see Command line).

The never-block list

Addresses and networks on the never-block list are never blocked, however often they fail. Their failures still appear under Recent failed sign-ins, so you can see a misconfigured phone there.

Put these on the list:

The public addresses of your offices and of the sites where remote phones sit, for example 203.0.113.10.
Your own admin and monitoring addresses.
Internal networks, if you prefer that a misbehaving phone on the LAN never takes itself offline, for example 10.0.0.0/24.

Type addresses and networks separated by commas, in the Never block field: 203.0.113.10, 10.0.0.0/24. A single address without a / means just that address. IPv6 addresses and networks work too. The server always exempts its loopback address, so its own connections to itself are never blocked.

A test tool that sends the server anonymous SIP requests many times a second counts as failing too, and gets its address blocked. Put such a machine on the list.

Blocking and unblocking by hand

To block an address yourself, for example one you see trying usernames under Recent failed sign-ins:

In the Block an address card, type the address in Address.
In For (minutes), type how long. 0 means until lifted.
Select Block.

An address on the never-block list cannot be blocked. The console says so.

The Blocked now table lists every active block:

Column	What it shows
Address	The blocked IPv4 or IPv6 address.
Why	The reason, for example "10 failed sign-ins in 10 min" with the last failure, and whether it was Automatic or By an administrator, with how long ago.
Until	When the block ends, or Lifted by hand for a block without an end.

To lift a block, select Unblock on its row and confirm. The address can reach the server again at once.

From a shell, onyx security bans lists the blocks and onyx security unban 203.0.113.9 lifts one. The running service takes the address out of the firewall within a minute.

Recent failed sign-ins

The Recent failed sign-ins table shows the latest 200 failures since the service last started:

When: how long ago.
From: the address the attempt came from.
Where: SIP (a phone or a scanner) or web (the console or portal sign-in).
What: for SIP, the kind of failure and the username tried. For the web, the sign-in name tried, or "two-factor code for" an account.

Use it to find a phone with a wrong password before it gets its office blocked: the SIP username in What tells you which device it is. Correct the phone (on the extension's page, Show settings shows the right username and password), then unblock the address if it was blocked.

The list lives in memory. It is empty again after the service restarts. The block list itself is kept in the database.

How blocks work on the firewall

Blocks are kept in the database and put into a firewall table of Onyx Voice's own (the nftables table inet onyx, sets banned and banned6). That table drops packets from blocked addresses before anything else on the server sees them. It is separate from the firewall rules on Server › Network: turning that firewall off, or using Reset to phone system ports, does not lift any block. The Firewall card there shows how many addresses intrusion prevention is blocking.

After a restart of the server, the service puts the active blocks back into the firewall when it starts. In a cluster, both servers block the same addresses: each server's firewall follows the shared list within a minute. See High availability.

If the Security page shows Blocks are recorded but the firewall cannot be changed (nft missing or no permission): they are not enforced, the service could not change the firewall. Blocks are saved but have no effect. On a server installed from the Onyx Voice ISO, VM image or package the service has the permission it needs, so this points to a damaged installation or a missing nft command. Check the Control plane log under Server › Logs & diagnostics for the reason.

To see blocking activity over time, choose the log Security (failed sign-ins, blocked addresses) under Server › Logs & diagnostics.

Separately from the firewall blocks, the sign-in page itself slows down password guessing. Onyx Voice refuses further sign-in attempts for 15 minutes when, within the last 15 minutes, there were:

10 failed attempts for the same sign-in name, from anywhere, or
30 failed attempts from the same address, for any names.

The person sees Too many failed sign-in attempts. Try again in 15 minutes. Wrong two-factor codes count the same as wrong passwords. Throttling applies to the admin console and the user portal alike, because both use the same sign-in.

There is nothing to reset: the counter clears itself as the failures age past 15 minutes. If the person has forgotten their password, an administrator sets a new one under Sign-in accounts, or with onyx user password [email protected] from a shell. Passwords need at least 10 characters.

With two-factor sign-in, a person signs in with their password and then a 6-digit code from an authenticator app on their phone (Microsoft Authenticator, Google Authenticator, 1Password, Authy and other time-based apps). A stolen password alone is then not enough. Every sign-in account can turn it on for itself: administrators on Your account (select your name in the console), portal users under Sign-in and security in the portal. The steps are in The web console and sign-in accounts.

When someone signs in with two-factor sign-in on:

After the correct password they have 5 minutes and 5 tries to type a code. After that they start again with the password.
Each code works once. If a code is refused, the phone's clock is often wrong.
Instead of a code they can type one of their 10 recovery codes. Each recovery code works once. When fewer than 3 are left, their account page asks them to make new ones.

The authenticator secrets are stored encrypted with a key file on the server, /etc/onyx-voice/secret.key, so a copy of the database alone does not reveal them. Backups include this key and a restore puts it back (see Backup and restore).

Requiring it for administrators

To make every administrator use two-factor sign-in:

Open Security.
In the Two-factor sign-in card, tick Require it for administrators.
Select Save.

Within half a minute it takes effect. An administrator who has not set it up yet is asked to at their next sign-in: the console shows only the set-up card (and Sign out) until they have scanned the code and typed a code from the app. Administrators also cannot turn their own two-factor sign-in off while it is required; they can only move it to a new phone. The requirement applies to system and tenant administrators, not to portal users.

The setting is security.require_2fa: admins to require it, off (the default) not to.

A lost phone

If someone has lost their phone and has no recovery codes left:

An administrator opens Sign-in accounts.
On the person's row (the 2FA column says On), select Reset 2FA and confirm.

Two-factor sign-in is then off for that account and the person can set it up again. If administrators are required to use it, they are asked to at their next sign-in. You cannot reset your own two-factor sign-in this way: use your account page.

If no administrator can sign in any more, reset it from a shell on the server: sudo onyx user 2fa-reset [email protected].

Encrypted calls

By default, calls between phones and the server use plain SIP and plain audio (RTP) on your network. Onyx Voice can encrypt both:

TLS encrypts the signalling: phones register and set up calls over SIP TLS on port 5061.
SRTP encrypts the audio. Onyx Voice uses SRTP with keys exchanged inside the TLS signalling.

The server's SIP TLS listener is always on, with the server's certificate. With a self-signed certificate, many desk phones refuse the connection; a Let's Encrypt certificate or your own certificate from a public authority fixes that. See Names and certificates.

Encryption is set per device and per trunk:

Desk phones and other SIP devices: on the extension's page (Extensions & numbers), each device in the Phones card has Encrypt calls, and Plain calls to go back. Provisioned desk phones have the same buttons on Desk phones, and get the matching settings at their next settings fetch (select Push settings to apply it now). Supported makes and details: Desk phones. From a shell: onyx device secure acme <sip username> on.
The browser softphone is always encrypted (DTLS-SRTP). There is nothing to turn on.
Trunks: a trunk whose transport is TLS shows Encrypt audio on the Trunks (carriers) page. The carrier must support SRTP. See Trunks (carriers). From a shell: onyx trunk srtp ExampleTel on.

A device set to encrypted calls must be set the same way. A phone that still sends plain audio cannot complete calls with the server, because the server then accepts only encrypted audio from it.

Good practice

SIP passwords are generated for you. Every device gets a random 24-character password and a generated SIP username that is not the extension number, which defeats the usual guessing. Never replace them with simple ones. If one leaks, select New password on the device; the phone is signed out until it gets the new one.
Keep the firewall on. Server › Network shows the firewall and warns about closed phone ports. If only known carriers and offices need SIP, open SIP for their addresses only (the From field when you open a port). See Network, NAT and firewall.
Turn SSH off when nobody needs it, under Server › System & updates (see Server tools).
Keep phone files on the local network. Phone settings files contain SIP passwords, so by default only the local networks may fetch them. Allow other networks only for remote phones that need it, and use New secret address on Desk phones if the provisioning address has leaked.
Use call limits. A stolen SIP account is most expensive when it can dial abroad. New tenants cannot call abroad until you allow it. See Call limits.
Require two-factor sign-in for administrators, and give every person their own sign-in account.
Keep the server updated: Ubuntu's security fixes and new Onyx Voice versions. See Updates.
Back up, so a broken or compromised server can be rebuilt. See Backup and restore.