Terminal Pairing: Terminal & CAS Trust
Why Pair?
The Terminal and CAS need to trust each other’s identities. The server needs to be sure that the information about the inserted banknotes is coming from an authorized Terminal and not from an attacker. Similarly, the Terminal must ensure that it is communicating with only your CAS and that the addresses for the customer cryptocurrency deposits belong only to you - and not to an attacker.
How is the Terminal’s identity established?
When the Terminal starts for the first time, it generates its own private key, public key, and SSL client certificate. The private key never leaves the device. The Terminal uses the client certificate, which contains the public key, when communicating with the server via HTTPS. We call the hash of the client certificate the “Terminal Certificate Fingerprint”. Each Terminal has its own unique private key, and therefore a unique Terminal Certificate Fingerprint. The Terminal backs up the key pair and certificate when it creates a restore point.
How is the server’s identity established?
Your server (CAS) uses the SSL server certificate and keys provided to the Operator with the license key. We call the hash of the server's SSL certificate used by the master service the “Server Certificate Fingerprint”. Servers that use the same license key use the same keys, and therefore have the same 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. The Server Certificate Fingerprint is “pinned” to the Terminal. A BATM factory reset or changing the server IP on the Terminal will cause the Terminal to forget the Server Certificate Fingerprint, essentially “unpinning” it.
CAS remembers the Terminal Certificate Fingerprint for each Terminal and maintains this information in it's database. The Terminal Certificate Fingerprint is thus “pinned”/”paired”. Please note that even when an attacker happens to obtain the Terminal Certificate Fingerprint value, that 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 BATM itself.
The server checks every Terminal request to ensure that it is coming from the expected 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 it. Generate a VPN configuration for the Terminal if you expect it to use the integrated OpenVPN client (Deployment Scenario A).
The Terminal with serial number XYZ sends a request for pairing to the Gate service along with its client certificate (Terminal Certificate Fingerprint). The Gate service is accessible only if you temporarily expose TCP port 7741. See: Configuring Server Firewalls
The Gate service checks whether that Terminal with that particular fingerprint is already trusted. When already trusted it sends the Terminal VPN configuration and the IP of the Master service.
In the cases where the Terminal is not yet trusted, the pairing code is displayed on the Terminal screen (see illustration 1) and the pairing request is added to the list of Pairing Requests (see illustration 2).
The Operator is expected to review the pairing request in CAS, and call the Location contact person to confirm the pairing code (or at least key pieces of it). This step is needed to ensure that it is really the Location’s genuine machine connecting to your server - and not an attacker. It should also be the Operator’s staff calling the Location contact - to prevent other scam vectors (when an attacker calls the Operator to add his illegitimate machine to CAS).
If the onscreen pairing code matches that in CAS, the 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.
Pairing Process: Illustrated
1. The BATM shows the Pairing Code.
Note that the Pairing Code shown on the BATM matches the Pairing Code shown in Step 3.
2. CAS > Terminals > Pairing Request
3. Approve the Pairing Request.
Note that the Pairing Code shown in CAS matches the Pairing Code shown in Step 1.
How to break trust?
In CAS, unpair the Terminal to forget the Terminal Certificate Fingerprint, or
factory reset the Terminal, see: Reset to Factory Defaults
Unpairing requires active 2FA and your confirmation: