Network Settings

Change local network settings, and connect to other networks with OpenVPN.

Change network settings

Changes device's network settings. The HTTP method used is the POST.

POST /set_system_network.fcgi

Parameters

• ip (string): Plain text with the new device's IP address. Example: "192.168.0.33".
• netmask (string): Plain text with the new device's netmask. Example: "255.255.255.0".
• gateway (string): Gateway IP address. Example: "192.168.0.1".
• custom_hostname_enabled (bool) : Enables setting to create custom hostname for the device. Values: "true" to enable and "false" to disable.
• device_hostname (string) : When custom_hostname_enabled is enabled, this parameter must receive the hostname customized by the user. Example: "ControlID". When custom_hostname_enabled is disabled the default value will be : "CID-" + device serial. Example: "CID-0M0200-C0FF33".
• web_server_port (int): The port number of the Internet socket address. Example: 80.
• ssl_enabled (bool) : Enables SSL encryption on the web server. Values: "true" to enable e "false" to disable.
• self_signed_certificate (bool) : Enables setting to use self-signed certificate. Values: "true" to enable self-signed certificate and "false" to use SSL with third-party certificate.
• dns_primary (string): Represents the device's primary DNS. Default: "8.8.8.8".
• dns_secondary (string): Represents the device's secondary DNS. Default: "8.8.4.4".

Response

• This request has no response.

Request example

Changes the device's IP address, netmask, gateway, and port:

$.ajax({
    url: "/set_system_network.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        ip: "192.168.0.33",
        netmask: "255.255.255.0",
        gateway: "192.168.0.1",
        custom_hostname_enabled: true,
        device_hostname: "ControlID",
        web_server_port: 80,
        ssl_enabled: false,
        self_signed_certificate: true,
        dns_primary: "1.1.1.1",
        dns_secondary: "1.1.4.4"
    })
});

SSL

SSL (Secure Sockets Layer) is a type of security protocol that establishes an encrypted connection between a web server and a browser, ensuring that the information transmitted over the internet remains private and secure. The following describes the process of generating SSL certificates and adding them to a Control iD access control equipment. Finally, the HTTP POST request that allows this same process to be carried out is presented.

SSL certificate configuration

1. Download the Light version of OpenSSL (option "Win64 OpenSSL v1.1.1t Light" for 64-bit Windows, or "Win32 OpenSSL v1.1.1t Light" for 32-bit Windows) from https://slproweb.com/products/Win32OpenSSL.html;
2. Run the installer, leaving the default directory as the directory of the library;
3. Open "Command Prompt" as "Administrator" and go to the default directory where OpenSSL was installed;
   Example (command line): cd C:\Program Files\OpenSSL-Win64\bin
4. Execute the following command and fill in the requested information, according to the guidelines provided below;
   Example (command line): openssl req -x509 -newkey rsa:1024 -nodes -keyout domain.key -out domain.pem Field entries:
   • Insert a two-letter country code in the "Country Name" field, as presented in the following link: SSL Certificate Country Codes
   • Enter a two-letter state/province code in the "State or Province Name" field;
   • Enter the name of your locality/city in the "Locality name/City" field;
   • Enter the name of your company in the "Organization Name" field;
   • Enter the unique name of your organization in the "Organizational Unit Name" field;
   • Enter the IP of your equipment in the "Common Name" field;
   • Enter an email address in the "Email Address" field.
5. Finally, the two files (a .pem and a .key) generated need to be combined. To do this, execute the following command;
   Example (command line): type domain.key,domain.pem > final.pem (for Linux environments: cat domain.key domain.pem > final.pem)
6. After that, close the "Command Prompt", access the OpenSSL default directory, and open the bin folder (C:\Program Files\OpenSSL-Win64\bin);
7. Collect the file named final.pem;
8. With this, access the Web interface of the equipment by entering its IP in your browser;
9. Once you have accessed it, select the "Settings" option, present in the menu on the left;
10. Look for the "Network" option, select it, and enable the "SSL" option. In the "Certificate" field, select the final.pem file presented in step 7, confirm and save the settings;
11. After performing the previous steps, simply reload the page and access the equipment by entering the "https" protocol in the URL.

POST /ssl_certificate_change.fcgi

Note: encryption by SSL must be enabled by a request to the set_system_network.fcgi endpoint for the certificate to be configured. Moreover, the certificate must be in the PEM and generated according to the instructions above.

Parameters

• Certificate, in binary format, to be added to the server.

Response

• This request has no response.

Example of request:

Add SSL certificate to the equipment's web server:

$.ajax({
    url: "/ssl_certificate_change.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/octet-stream',
    data: [bytes of the .pem certificate]
});

OpenVPN

Changes the network settings for using the OpenVPN utility via the /set_vpn_information endpoint. For proper operation, it is necessary to load a configuration file, on the /set_vpn_file endpoint, in .conf format, containing in it the certificates, keys and/or credentials required for access. The file can also be loaded together with a zip file, containing the certificates (.crt), keys (*.key) and/or credentials in separate files. Examples of parameterization of the configuration file can be obtained via the endpoint /get_vpn_file.fcgi. In addition, for status control and connections there are three endpoints: /get_vpn_information, which returns the connection settings; /get_vpn_status, which checks the state of the connection, and /has_vpn_file, which checks if there is already a configuration file present.

Change OpenVPN settings

Changes the network settings for using the OpenVPN utility. The HTTP method used is POST.

POST /set_vpn_information.fcgi

Parameters

• enabled (bool) : Represents if the OpenVPN is enabled. Default: "false".
• login_enabled (bool) : Represents if OpenVPN is accessed from manual login and passwords. Default: "false".
• login (string) : Represents the login user used if login_enabled is enabled. Example : "Admin".
• password (string) : Represents the password used if login_enabled is enabled. Example : "Admin".

Response

• This request has no response.

Request Example

Enables the utility and allows manual user and password update:

$.ajax({
    url: "/set_vpn_information.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        "enabled": true,
        "login_enabled": true,
        "login": "Admin",
        "password": "Admin"
    })
});

Change the VPN access files.

Change the upload files for the utility. This can be a .conf file format or a .zip file format containing all the necessary data. The HTTP method used is POST.

POST /set_vpn_file.fcgi

Parameters

• file_type (string) : Identifier of the type of file sent. Values: "zip" for .zip files and "config" for .conf configuration files. This parameter is passed in the query string.

Response

• This request has no response.

Request example

This request will define the configuration file used in the VPN.

$.ajax({
    url: "/set_vpn_file.fcgi?file_type=zip&session=" + session,
    type: 'POST',
    contentType: 'application/octet-stream',
    data: [bytes of VPN file]
});

Receive the Example files

Receives the example of parameterization of the configuration file. The HTTP method used is GET.

GET /get_vpn_file.fcgi

Parameters

• This request has no parameters.

Response

• File in zip format.

Request example

This request returns the configuration file used in the VPN.

$.ajax({
    url: "/get_vpn_file.fcgi?&session=" + session,
    type: 'GET',
    contentType: 'application/octet-stream
});

Receive the OpenVPN settings

Receives the network settings for using the OpenVPN utility. The HTTP method used is GET.

GET /get_vpn_information.fcgi

Parameters

• This request has no parameters.

Response

• enabled (bool) : Represents if the OpenVPN is enabled. Default: "false".
• login_enabled (bool) : Represents if OpenVPN is accessed from manual login and passwords. Default: "false".
• login (string) : Represents the login user used if login_enabled is enabled. Example : "Admin".
• password (bool) : Represents whether there is a login configuration password if login_enabled is enabled. Example : "true".

Request example

This request returns the settings used in OpenVPN.

$.ajax({
    url: "/get_vpn_information.fcgi?&session=" + session,
    type: 'GET',
    contentType: 'application/json
});

Response example

{
    "enabled": true,
    "login_enabled": false,
    "login": "Admin",
    "password": true
}

Receive OpenVPN Connection Status

Receives network status from the OpenVPN utility. The HTTP method used is GET.

GET /get_vpn_status.fcgi

Parameters

• This request has no parameters.

Response

• status (int) : Represents one of the OpenVPN status below.

  • 0 (connected) : Represents if that OpenVPN is connected.
  • 1 (auth_failed) : Represents that the OpenVPN server is rejecting the connection during the authentication stage.
  • 2 (ca_missing) : Represents that the certifying unit is missing for the OpenVPN approval.
  • 3 (ca_failed) : Represents that the OpenVPN server was unable to verify the certificate unit.
  • 4 (crt_key_missing) : Represents that the public certificate, private key or both may be missing.
  • 5 (crt_failed) : Represents that the public certificate key was not approved by the OpenVPN server
  • 6 (key_failed) : Represents a failed of authentication by the OpenVPN server using the private key.
  • 7 (tls_failed) : Represents TLS security protocol failure.
  • 8 (disconnected) : Represents if that OpenVPN is disabled.
  • 9 (trying_to_connect) : Represents that OpenVPN is active but has not yet reached any of the mapped statuses.
  • 10 (no connection) : Represents that the network is disconnected.

Request example

This request returns the status of the OpenVPN connection.

$.ajax({
    url: "/get_vpn_status.fcgi?&session=" + session,
    type: 'GET',
    contentType: 'application/json
});

Response example

{
    "status": "0"
}

Confirm if exists a configuration file

Receive confirmation that configuration file exists on device for OpenVPN utility. The HTTP method used is GET.

GET /has_vpn_file.fcgi

Parameters

• This request has no parameters.

Response

• has_file (bool) : Represents if an OpenVPN configuration file already exists on the device.

Request example

This request returns the OpenVPN file status.

$.ajax({
    url: "/has_vpn_file.fcgi?&session=" + session,
    type: 'GET',
    contentType: 'application/json
});

Response example

{
    "has_file": true
}

Enable 802.1X

It is possible to configure the device as a supplicant and enable the 802.1X authentication protocol for its network port. The method used is PEAP.

POST /configure_802_1X.fcgi

Parameters

• enabled (bool): Determines whether 802.1X authentication is enabled or not;
• login (string): Login credential;
• password (string): Password credential;
• inner_auth (int): Internal authentication. 0: MS-CHAPv2. 1: MD5. 2: GTC.

Response

• This request has no response.

Request Example

Enable 802.1X with login credentials "testing" and password "password," and internal authentication using MS-CHAPv2.

$.ajax({
    url: "/configure_802_1X.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        enabled: true,
        login: "testing",
        password: "password",
        inner_auth: 0
    })
});