VPN

1. Overview

This document describes how the WE500 uses the Nethix Portal API for establishing a VPN. The WE500 is a client whilst the Portal is the server. There can be other clients such as PCs, laptops and mobile devices.

Normally, when configuring a VPN client, the user enters manually the data, such as the username and password, required for the connection to take place. When one of these parameters change, the user changes it again manually in the client and so on. This workflow cannot be applied to the WE500 since it’s an unmanned device that must be able to set and update its configuration automatically. This is done with the help of a web server to which the WE500 connects to. Then the web server replies with the data that contains the address of the actual VPN server (that can be different from the web server’s), the access credentials and some other info. Once the WE500 gets this info, it can establish the VPN connection.

Danger

Nethix strongly recommends to use a secure HTTPS connection for exchanging the VPN data configuration.

By using this approach, the user only has to enter the web server address and port in the menu Administration -> Networking -> VPN:

../_images/vpn_config1.png

This documentation can be used for customers that want the WE500 to use their own VPN server.

Note

The VPN server must be compatible with the OpenVPN client.

The web server needs to implement the following couple of resources that are described in the Portal API :

2. Communication flow

This is the communication flow between the WE500 and the Nethix Portal. A customer’s portal (or a simple HTTPS web server) must implement this functionality.

../_images/vpn_communication_flow1.png

1) The device sends a request to the server to get the VPN status

Resource

/api/v1/vpn

Request

GET

Authentication

HTTP Basic
username: the device serial number
password: the MD5 of serial number

2) The server replies with the VPN status, reconnection time and package info

Response

<ntx>
    <vpn>
        <reconnection_time>10</reconnection_time>
        <status>3</status>
        <package_info>
            <auth_type>0</auth_type>
            <md5_ca_cert>422d6be13d96ebbe44a710eca79bbbff</md5_ca_cert>
            <md5_client_conf>d41d8cd98f00b204e9800998ecf8427e</md5_client_conf>
            <md5_ta_key>6d05e5f3bab43672a6189c3e1cf05d17</md5_ta_key>
            <md5_credentials>05t5f69ca672a6189c3e1cf05dab5</md5_credentials>
        </package_info>
    </vpn>
</ntx>

When the status is disable, the reply does not have the package_info tag. See 3.7. VPN for details.

3) The device parses the reply and if the VPN status is “update configuration”, the device requests the VPN files

Resource

/api/v1/vpn/packet

Request

GET

Authentication

HTTP Basic
username: the device serial number
password: the MD5 of serial number

4) The server checks if the device is enabled and returns the client’s VPN files. These files are grouped in a single archive (tar).

See 3.8. VPN Packet

5) The device checks the files integrity and update the VPN status to “enable”

Resource

/api/v1/vpn/packet

Request

PUT

Authentication

HTTP Basic
username: the device serial number
password: the MD5 of serial number

6) The server changes the VPN status if the device is authenticated.

7) The device sends a request to the server to get the VPN status

Resource

/api/v1/vpn/packet

Request

GET

Authentication

HTTP Basic
username: the device serial number
password: the MD5 of serial number

8) The server replies the with VPN status, reconnection time and package info

Response

<ntx>
    <vpn>
        <reconnection_time>900</reconnection_time>
        <status>2</status>
        <package_info>
            <auth_type>0</auth_type>
            <md5_ca_cert>422d6be13d96ebbe44a710eca79bbbff</md5_ca_cert>
            <md5_client_conf>d41d8cd98f00b204e9800998ecf8427e</md5_client_conf>
            <md5_ta_key>6d05e5f3bab43672a6189c3e1cf05d17</md5_ta_key>
           <md5_credentials>05t5f69ca672a6189c3e1cf05dab5</md5_credentials>
        </package_info>
    </vpn>
</ntx>

When the status is disable, the reply does not have the package_info tag. See 3.7. VPN

9) The VPN status is in “enabled”, therefore the device can launch the OpenVPN client and every 900 seconds poll the server with a request to /api/vi/vpn to get its VPN status.