Network Security

Introduced in version 3.8.13

SpecMan4EPR is controlled over TCP/IP (see Client-Server Architecture). This page explains what is exposed on the network, what protects it, and how to set up a spectrometer computer so that only the people and programs you intend can reach it.

What the Server exposes

Both listening ports exist only in Server mode. In No network mode no port is opened. The port numbers are fixed – 3128 for the Client-Server port and 8023 for the console port – and cannot be changed, so firewall rules and this page always match the installation. The Client-Server port is always encrypted; the console port is encrypted unless you allow plain connections (see Encryption).

What protects it – and what does not

A client that is allowed to connect has full control of the spectrometer. While Python, MATLAB and programs are allowed (see below), it also controls the computer: it can run Python and MATLAB code and start programs. Treat every entry in the list of allowed hosts as a person or machine you would give an administrator account to.

The protections are:

• List of allowed hosts – connections from any other address are closed immediately. An empty list admits nobody.
• Listen address – decides which network cards the ports are open on at all. By default a server that admits only its own computer is not reachable from the network.
• Server .ini – the Server's settings file (allowed hosts, password hash) can be viewed only in the SpecMan4EPR window of the Server computer. Other GUI clients and the console are refused it.
• List of allowed folders – file names received from any client, console command or script can point only into the SpecMan folders and the folders you list.
• Encryption – the traffic between GUI and Server, and on the console port, cannot be read or changed on the way, and the client checks that it talks to the right Server.
• Login – with a connection password set, a client admitted by the list of allowed hosts must also know the password.

Set a connection password (see Login) whenever other computers connect: without it, any computer admitted by the list of allowed hosts can connect. The data server Data header is sent as plain text and is not a password. If the connection has to cross a network you do not control, use a tunnel or VPN as well (see below).

Encryption

TLS (Transport Layer Security) is the standard way to encrypt a network connection – the same protocol that protects https:// web pages. When a client connects, the two sides first run a short handshake: the Server presents its certificate, the client checks that it belongs to the right Server, and both agree on a secret key used only for this connection. From then on everything sent in either direction is encrypted and protected against changes. TLS does not decide who may connect; that is what the list of allowed hosts and the connection password are for.

Client-Server port. Every connection between a GUI and the Server is encrypted (TLS 1.2 or 1.3), the GUI on the Server computer included. There is no option to switch it off. As a consequence a GUI older than 3.8.13 cannot connect to a 3.8.13 Server, and a 3.8.13 GUI cannot connect to an older Server: update the Server and its clients together. A refused old client shows Server Key was not received; the Server log shows TLS handshake failed with its address.

Server certificate. On its first start in Server mode, SpecMan4EPR creates its own certificate, SpecMan4EPR_server.crt with the key SpecMan4EPR_server.key, in the folder of SpecMan4EPR.ini (a protected folder). Its fingerprint (SHA-256) identifies the Server. It is written to the log at every start

Server certificate SHA-256 fingerprint: 3F:A2:...:9C

and returned by the console command .s.fingerprint. Keep the key file private: anyone who copies it can pretend to be this Server. To create a new certificate, close SpecMan4EPR, delete both files and start it again; every client will then ask to confirm the new fingerprint.

Trusting a Server. The first time a GUI in Client mode connects to a Server, it shows the Server's fingerprint and asks whether to trust it. Compare it with the fingerprint in the Server log before you answer Yes. The GUI remembers it (file SpecMan4EPR_trusted.ini next to its SpecMan4EPR.ini) and connects without asking from then on. If the fingerprint ever changes, the GUI warns and does not connect until you accept the new one: this happens after the certificate was renewed or SpecMan4EPR was reinstalled on the Server, but it can also mean that someone is intercepting the connection. The GUI on the Server computer trusts its own Server without asking.

Console port. Network → Console encryption:

The Server tells the two apart by the first bytes the client sends, so both use the same port. A refused plain client receives sm>.server.error='encrypted connection required'. Set Allowed while older scripts that cannot encrypt still connect from other computers. A changed setting applies to the next connection. How a script connects encrypted is shown in Remote control.

OpenSSL. The encryption uses OpenSSL 3, two files next to SpecMan4EPR.exe: libcrypto-3-x64.dll and libssl-3-x64.dll (with LICENSE-OpenSSL.txt). They are part of every installation. Without them Server and Client mode cannot start (the log says so); No network mode works without them. SpecMan4EPR loads them only from its own folder.

Login

Options → Network → Connection password: type the password and accept the options. SpecMan4EPR stores only a salted hash of it (the field then shows that hash, starting with pbkdf2-sha256:); the password itself is not kept on the Server. Type a new password to change it, clear the field to remove it.

• GUI clients ask for the password when they connect (it travels only inside the encrypted connection) and offer to remember it. A remembered password is stored encrypted for the Windows user, in SpecMan4EPR_trusted.ini; if it stops working, it is forgotten and the GUI asks again. The GUI on the Server computer is never asked.
• After five wrong passwords from one address that address is blocked for one minute: its connection is closed and, until the minute is over, every login from it is refused, even with the right password. The Server log names the address.
• Console: Options → Network → Console login. When it is on, a console connection must first send .s.login='password'; every other command is answered sm>.server.error='login required' until then. The login line is never written to the log. Over a plain connection the login is accepted only from the Server computer itself, so the password never crosses the network in plain text. When Console login is off, console scripts connect without a password.

Set a password before you add other computers to the list of allowed hosts. A new or changed password applies to the next connection.

Setting up a single computer

The GUI and the Server run on the same PC and nothing else needs access. A new installation starts in Client mode with 127.0.0.1 already in the list of allowed hosts, so only the operational mode needs to be changed.

Options → Network:
Operational mode = Server (or No network)
List of allowed hosts = 127.0.0.1 (or localhost)
Listen address = empty

The log shows Server is listening on 127.0.0.1, port 3128 (encrypted): the ports cannot be reached from other computers. Scripts and the Remote control on the same PC still work.

Allowing clients on the lab network

Options → Network:
List of allowed hosts – add 127.0.0.1 for the local GUI and each remote computer: a single IP (192.168.1.20) or a whole subnet (192.168.1.0/24). Prefer single IPs to subnets.
Listen address – the IP of the network card that faces the lab network (for example 192.168.1.10), so the ports are not open on other networks the PC is connected to. Leave it empty to listen on all network cards.

Once the list names another computer and the listen address is empty, the Server listens on all network cards; the log says all network interfaces. Changes of the listen address and switching the console port on or off take effect after SpecMan4EPR is restarted.

In addition, limit the ports in the Windows firewall: allow inbound TCP 3128 (and TCP 8023, if the console port is on) only from the lab computers or subnet. The firewall and the list of allowed hosts are independent; use both.

List of allowed folders

Every file name that reaches the Server from outside – file dialogs of the GUI, the file browser, queue files, console commands such as .s.open and .s.exec, and the automatic data saving – must point inside an allowed folder. The rule applies to all clients, including the GUI on the Server computer.

Always allowed, taken from Options → Directories and files:

• Data directory (the data root)
• Templates, configurations, patterns, calibrations
• Data buffer directory

To add a folder: Options → Network → List of allowed folders, add the full path, for example D:\EPRdata\2026. Sub-folders are included. Changes apply when the options are accepted.

The server file dialogs for templates, queues and data have a Root list: the dialog's own folder first, then the added folders. Pick a root to browse, load from, save into or create sub-folders in it. The Server remembers the root last picked for each kind of dialog (templates, queues, data) and opens the next dialog there, for every client, until SpecMan4EPR is restarted. A dialog opened for a known file starts in the root that holds that file. The configuration, pattern and calibration dialogs, and the dialog that picks the automatic-saving sub-folder, offer only their own folder.

The console command .s.folders returns the complete list, SpecMan folders included:

.s.folders .server.folders=D:\EPRdata; D:\SpecMan\tpl; D:\SpecMan\cfg; ...; E:\EPRdata

A refused request is reported in the log with the name that was asked for and the full list of allowed folders, for example

Writing 'E:\export\run1.exp' is refused: it is outside the allowed folders (D:\EPRdata; D:\SpecMan\tpl; ...).

If the automatic data saving would write outside the allowed folders (because the data root or sub-folder was changed), the data are saved in the dated folder under the data root instead, and an error is posted. The console command .s.fileget accepts only bare file names from the data buffer directory.

Folders set on the Server only

These folders come from the options of the Server computer, and no client can change them:

• Data directory (the data root) and Data buffer directory. A client can still choose the sub-folder and the file name template for automatic saving; the result must stay inside the allowed folders.
• Debug export directory (default C:\Temp). Driver and engine debug exports (AWG patterns, raw acquisitions) go to its AWG and AVG sub-folders, and old exports there are deleted when a driver starts.

The file GUID set with .d.fguid becomes a file name in the data buffer directory, so it must be a plain name without folders, .. or :.

Protected folders

Nothing can be saved, from any client, console command or script, into:

• the program folder (where SpecMan4EPR.exe and its DLLs are),
• the folder of SpecMan4EPR.ini (the program folder, or %LOCALAPPDATA%\SpecMan4EPR),
• the folders in Directories and files → DLL paths and the Python directory,
• the processing scripts directory.

A serial interface whose resource (in the device configuration) is not a COM or LPT port opens a file for writing; that file must lie in an allowed folder that is not protected. A COM or LPT resource always opens the port itself (\\.\COM3, \\.\LPT1), never a file whose path merely contains the port name.

Folders are compared by their real location: short names (PROGRA~1), junctions and symbolic links are resolved first, so they cannot make a protected folder look like another one. File names with an alternate data stream (file:stream) are refused.

The protection holds even when an allowed folder contains a protected one. The one exception is a SpecMan folder or allowed folder that was set up below a protected folder (for example templates in <program folder>\tpl): saving inside that sub-folder stays possible, the protected folder itself is not.

Python, MATLAB and programs

Options → Network → Allow MATLAB, Allow Python, Allow programs. All on by default.

Each switch stops the Server from running one kind of code it does not contain itself:

• Allow MATLAB off: no .matlab.* console commands, no MATLAB scripts of the automatic saving, no MATLAB calls in experiment scripts, no .MATLAB pulse shapes and no MATLAB data streams,
• Allow Python off: no .python.* console commands, no Python calls in experiment scripts and no .PYTHON pulse shapes,
• Allow programs off: no experiment processing programs and no helper programs started by drivers (CG6000, Mini-Circuits SSG command-line control); these devices do not work while it is off.

Each refused call is reported in the log. The switches apply to the Server computer for every client, the GUI on the Server computer included; a GUI in Client mode on another computer keeps its own MATLAB and Python. Switch off every one that the spectrometer does not need: with all three off, a client can control the spectrometer but not the computer.

Processing programs

An experiment can run a program when it completes (Setup → Processing). Because any client can set this field, the program is run only when:

• Options → Directories and files → Processing scripts directory is set. When it is empty, no processing program is run.
• The field holds a file name inside that directory, for example fit_echo.bat or T1\fit.exe. A full path is accepted only if it points into the directory. Programs on the system path (for example cmd) are not found.
• The directory is not one of, and does not lie inside, the folders clients can save to.

The program runs with the scripts directory as its working folder. A refused program is reported in the log with the reason. Make the directory writable for administrators only (Windows folder permissions), so that only the people who manage the spectrometer can add programs.

Access from outside the lab

Do not open port 3128 or port 8023 to the internet or to an untrusted network, even with encryption and a connection password. Connect through a tunnel or VPN and keep the Server listening on 127.0.0.1 only:

• SSH tunnel. Enable the OpenSSH Server that ships with Windows 10/11 (Settings → Optional features) on the spectrometer PC. On the remote computer run
  ssh -L 3128:127.0.0.1:3128 user@spectrometer-pc
  and start SpecMan4EPR in Client mode with TCPIP address localhost. The Server sees the connection as coming from 127.0.0.1, so the single-computer setup above needs no change. Add -L 8023:127.0.0.1:8023 for the console port.
• VPN (for example WireGuard or the institutional VPN). Add the VPN address of the remote computer to the list of allowed hosts and set the listen address to the VPN interface.

Instruments and the data server

Most instruments accept commands from anyone on their network and do not support encryption. Put them on a separate network card or switch that only the spectrometer PC uses, and keep that network off the lab and building networks. Run the data server on the same PC or on that isolated network.

Example

Server PC 192.168.1.10, one analysis computer, extra data disk. The [Network] section of the server .ini (normally written by the Options dialog):

Configuration file example:

[Network] ConsolePort=1 ListenAddress=192.168.1.10 ClientList_0=127.0.0.1 ClientList_1=192.168.1.25 AllowedFolder_0=E:\EPRdata ConsoleEncryption=2 ConsoleLogin=1 PasswordHash=pbkdf2-sha256:200000:...

Checklist

• List of allowed hosts contains only the computers that need control; no broad subnets.
• The log line Server is listening on ... shows the address you expect.
• Windows firewall limits the ports to the lab computers.
• Console port is off unless automation needs it; Console encryption stays on Required unless old scripts on other computers need Allowed.
• Every client accepted the Server fingerprint only after comparing it with the Server log.
• A connection password is set as soon as other computers may connect; Console login is on if console scripts connect from other computers.
• SpecMan4EPR_server.key is readable only by the people who manage the spectrometer.
• Remote access goes through SSH or a VPN, never a forwarded port.
• The list of allowed folders contains only data and template locations.
• Processing scripts directory is empty, or an administrator-only folder outside every allowed folder.
• Allow MATLAB, Allow Python and Allow programs are off unless these features are used.
• Instruments sit on their own network.
• The latest security update of your version is installed.

Security updates and reporting vulnerabilities

Each version of SpecMan4EPR (the first three numbers, for example 3.8.14) receives security updates for five years from its first release. A security update keeps the version and changes the fourth number (3.8.14.1, 3.8.14.2, ...). With active technical support, fixes arrive in the current version; after support has ended, security updates are provided for the last version you are licensed for. The end date of your version is shown in Help → About and in the log at start; after it the log warns that the version no longer receives security updates. SpecMan4EPR does not update itself: download and install the update.

Report a suspected security vulnerability in SpecMan4EPR to security@specman4epr.com, not to the general contact address, and do not publish it before it is fixed. How reports are handled is described in the vulnerability disclosure policy. Security advisories are published on the same page.

See also

Client-Server Architecture, Network Settings, Remote control, Directories