This document describes state valid for software version 2023801 and higher.
If you are having issues pairing the terminal please consult with pairing troubleshooting guide here. Make sure you get familiar with pairing by reading this page before troubleshooting pairing.
Terminal and server need to trust each other’s identity. The server needs to be sure that information about the inserted banknotes is coming from the particular terminal and not from the attacker. Similarly, the terminal must ensure that it is communicating with the correct server and that the addresses for customer coin deposits belong to the operator and not to an attacker.
How is the terminal’s identity established?
When the terminal is started for the first time, it generates its own private key, public key, and SSL client certificate. The private key never leaves the device. The client certificate containing the public key is used when communicating with the server via HTTPS. The hash of the client certificate is called the Terminal Certificate Fingerprint. Each terminal has its own unique private key, and therefore a unique Terminal Certificate Fingerprint. The key pair and certificate are backed up during the creation of a restore point on the terminal.
How is the server’s identity established?
Your server is using SSL server certificate and keys provided to the operator with the license key. The hash of the server's SSL certificate used by the master service is called the Server Certificate Fingerprint. Servers that use the same license key use the same keys therefore they have Server Certificate Fingerprint.
How is the trust maintained?
The terminal remembers the Server Certificate Fingerprint and refuses to communicate with a server that has a different Server Certificate Fingerprint. We can say that the Server Certificate Fingerprint is 'pinned' on the terminal. A factory reset of the terminal or changing the IP address of a server on the terminal will cause the terminal to forget the Server Certificate Fingerprint, essentially 'unpinning' it.
The server remembers the Terminal Certificate Fingerprint for each terminal and maintains such information in its database. We could say that the Terminal Certificate Fingerprint is 'pinned,' or the terminal is 'paired.' Please note that even when an attacker happens to obtain the Terminal Certificate Fingerprint value, such information is useless to them as they cannot emulate terminal calls since they do not have access to the terminal's private key, which is only stored in the terminal itself.
The server checks with every terminal request to ensure that it is coming from a trusted terminal.
How is the initial trust established?
Create a terminal with a known serial number in CAS. CAS will know that the terminal is expected to start talking to him. Generate VPN configuration for the terminal if you expect it to use built-in OpenVPN client (Deployment Scenario A).
Terminal with serial number XYZ sends a request for pairing to the gate service along with its client certificate (Terminal Certificate Fingerprint). Gate service is accessible only if you temporarily open its TCP port 7741 accessible from Internet.
Gate service checks whether such a terminal with a particular fingerprint is already trusted. When already trusted it sends terminal VPN configuration and IP of the master service.
In cases where the terminal is not yet trusted the pairing code is displayed on the terminal screen and the pairing request is added to the list of paring requests in server admin.
The operator is expected to review the pairing request in CAS and call the location contact person to read him the pairing code (or at least pieces of it). This step is needed to be sure that it is really the location’s genuine machine connecting to your server and not the attacker’s. It should be also the operator’s staff that should be calling the location contact to prevent other scam vectors when an attacker is calling the operator to add his machine to CAS.
Once the pairing code matches on screen and in the CAS operator can click on APPROVE. Only users with 2FA can perform such an operation.
Once pairing is approved the Terminal Certificate Fingerprint is stored in the database and the terminal is paired - trusted.
Here are some pictures from the pairing process
Error screen displayed on the terminal showing pairing code. Operator’s action is needed in CAS
Visible pairing request in CAS (first button from right). Operator should review Pairing Requests
Pairing request displayed in CAS showing information about the terminal that is trying to pair. Operator should click on APPROVE button only when is the pairing code matches.
How to break trust?
In CAS you can unpair terminal causing server to forget Terminal Certificate Fingerprint.