Sangoma Phones and OpenVPN

Defaults

By default, the phone does not attempt to connect using OpenVPN.  These options must be enabled.

Recommended Firmware

Firmware 2_7_0 (D6x) is recommended and D80 (1_9_0).  Versions between 2_2_1_1 and 2_6_6 support a series of deprecated OpenVPN configuration parameters that are not supported going forward and will be removed in a future firmware release.

Compatibility

OpenVPN connectivity is supported by models D60, D62, D65, and D80.  Models D40, D45, D50, and D70 do not support OpenVPN connectivity.

Important Notes

Phones require an in-line OpenVPN configuration file bundling the OpenVPN configuration, the root CA, the client cert, and the client key in order to be able to use VPN connectivity.

OpenVPN server configuration must not require manual password entry in order to connect.  The phone does not provide the user a means of inputting user and/or password credentials as a part of VPN connection.

Certificates have been tested in CRT format only.

Requirements and Overview

In order to connect to an OpenVPN server, the phone utilizes an OpenVPN configuration file with an in-line / bundled Root (CA) certificate and, optionally, client key and CRT files.  The phone will, when directed by its configuration, attempt to cURL the files in from a defined http(s) server.  The phone can retrieve the files using no authentication, basic auth, or digest auth.  Once the file  is retrieved, the phone will store it locally. 

Retrieval of an updated OpenVPN configuration is dictated by the mandatory md5 parameter.  Where the value of the openvpn_inline_config md5 parameter in the phone configuration file changes, the phone will download a new file from the specified URL.  The phone will calculate the md5sum of the downloaded file and compare it to the specified md5 parameter value.  Where a match is found, the phone will apply the new file.  Where a match is not found, the phone will reject the downloaded new file and continue to use the current file.  If an md5 parameter is not found, on a factory defaulted phone, the OpenVPN configuration file will not be downloaded.

It is important to note that the phone must be able to retrieve the OpenVPN configuration file without actually being connected to the VPN.  This presents a chicken-and-egg scenario that is most often solved by connecting the phone to an already-secure network, feeding it a configuration file that points to an OpenVPN configuration that can be retrieved, and then, once successfully loaded, moving the phone to the insecure network.

A built-in vpn web element is provided by the phone, through which configurations may be uploaded and applied.  For many scenarios, this capability offers an excellent fall-back in the case of expired certificates or the lack of server-supplied certificates.

Configuration Elements

The phone maintains three (3) VPN configuration elements that are defined like:

<setting id="network_default_enable_openvpn" value="1" />

<setting id="openvpn_inline_config" url="https://user:pass@server.example.com/client.ovpn" value="1" md5="abc123" />

<setting id="openvpn_logging" value="0" />

The network_default_enable_openvpn element is disabled by default.  When enabled, the phone will, on boot, attempt to load its already-stored VPN configuration file and connect to the VPN.  When disabled, the phone will not attempt to connect to the VPN.

The phone will retrieve from the defined URL using cURL.  Basic and Digest Authorization are supported.  If the phone does not have the file, it will cURL it in, regardless of the disposition of the network_default_enable_openvpn option.

The openvpn_inline_config element defines an in-line OpenVPN configuration file.  This element provides updated functionality over the older elements.  Use of this element requires a value parameter of 1 and and an md5 parameter.

The openvpn_logging element turns on or off logging that can be used by Sangoma Support to troubleshoot issues.  Note: this option should not be enabled unless you are so directed by Digium's Support department.

When the VPN is Enabled

When the network_default_enable_openvpn option is enabled on the phone, the phone will display an additional setup item in its BootConfig Settings page, e.g.:

Open

Within this menu, the phone will show the load status of the VPN configuration files as well as its VPN address.

If the configuration file was retrieved okay, the menu will display a green checkmark.  If the configuration file is not found or the VPN is not connected, the phone will display an red x icon.  The phone will also display the VPN IP Address and the connection status.  When connected, you may Disconnect using the Disconnect soft key.  When disconnected, you may connect using the Connect soft key:

Open

When the phone is booted, OpenVPN is enabled, and the connection is successfully brought up, the phone will show a blue VPN shield icon in the status bar, e.g.:

If the OpenVPN connection cannot be brought up, a red VPN shield icon will show in the status bar, e.g.:

The OpenVPN web configuration page

D6x phones beginning with firmware 2.7.0 have a built-in web handler for locally configuring the OpenVPN client.  This handler is accessible at:

http://[ip of phone/vpn

Logging into the page is done using the username admin and the phone's admin password - defaults to 789.

This page looks like:

From this page, you can see the current VPN address of the phone, enable or disable the local VPN configuration, upload an in-line OpenVPN configuration file, delete the file, submit your settings, or revert to any server-supplied settings.

The OpenVPN configuration file

OpenVPN has myriad configuration options, and not all can be or have been tested with Digium's phones.  The phone can operate OpenVPN in either UDP or TCP protocols.  The comp-lzo option has been tested to work but adds additional processing overhead.

A tested, sample configuration file, with placeholders for the in-line Root CA, Client Cert and Client Key is provided here:

Ciphers

Sangoma D6x phones support the following Control Channel TLS Ciphers:

Digium Phone Control Channel TLS Ciphers

Model D80 phones may support a different set of Control Channel TLS Ciphers.

Versions of firmware prior to 2.3.9 also supported the following, additional ciphers:

Digium Phone Control Channel TLS Ciphers

Sangoma D6x phones support the following Data Channel Ciphers:

Digium Phone Data Channel Ciphers

Model D80 phones may support a different set of Data Channel Ciphers.

PJSIP Configuration Considerations

When configuring an endpoint in PJSIP that will be behind a VPN, the endpoint should be configured with the rewrite_contact parameter set to yes.  

Debugging

In the event that OpenVPN login fails, and you cannot resolve the issue by inspecting the OpenVPN server-side logging, first, only if directed by Digium's Support department, enable OpenVPN logging by turning it on:

Setting this will cause the phone to restart and capture extra OpenVPN logging.  Do not leave this option enabled while normally using the phone.

Then, after the phone has booted and has attempted to connect to the OpenVPN server, capture a phone debug by taking a web browser to:

http://[ip address of phone]/cgi-bin/ptsr

the debug file should be provided to Digium's Support department.

Replacing Configuration when using openvpn_inline_config

When a phone is factory defaulted, any stored configurations and certificates are deleted.

If you need to cause a phone to switch to a different configuration file, then the value of the md5 parameter of the openvpn_inline_config element must be changed.  When the phone retrieves a new configuration file and the md5 value differs from the previous configuration file, the phone will download a new configuration file.  After download, the phone will perform an md5sum calculation on the newly-retrieved file.  If the result of the calculation is the same as the value of the md5 parameter specified in the phone's configuration file, the phone will install and use the new configuration file.

If the result of the calculation differs, the phone will not utilize the newly-downloaded file, instead discarding it, and continuing the utilize the in-place OpenVPN configuration file.

Disabling OpenVPN

By default, a phone will not perform OpenVPN login.  The phone disables OpenVPN when the following parameter is configured as zero, the default:

Even if this setting is disabled, the phone will continue to retrieve new certificates if so directed by the phone's configuration file.