Overview
This article provides details about the UISP generic key and how it works, as well as describing the fundamentals of the device registration process.
Also please note that UISP doesn't support older airMAX devices with firmware versions 4.x, 5.x, or 7.x.
Table of Contents
- Introduction
- UISP Generic Key Details
- Behind the Scenes: How Does the UISP Key Work?
- How to Manually Register a Device via Device UI
- How to Register a Device via SSH
- Related Articles
Introduction
The purpose of the UISP key is to provide secure communication using AES encryption while telling a device where to look for a UISP console (server). The process of device registration using the generic UISP key and the device-specific UISP key ensures secure communication between the user's devices and UISP.
UISP Generic Key Details
Here is an example of the UISP key:
wss:// your.domain.com :443 + n9yU137QSwTzBXnF...9Sk0pC7sDKGnpbxiHRI9W +
The UISP key consists of several parts (shown in different colors above), each with its own purpose. In the table below, the UISP key is split apart, and each part's purpose is described:
| Key Part | Purpose |
| wss:// | WebSocket Secure connection protocol |
| your.domain.com | Hostname or IP of the console (server) where UISP server is running |
| :443 | Port for devices to access UISP server |
| n9yU137QSwTzBXnF...9Sk0pC7sDKGnpbxiHRI9W | Advanced Encryption Standard key (AES key) |
Behind the Scenes: How Does the UISP Key Work?
When a new instance of UISP is installed, it creates its own UISP key which is called The Generic UISP Key. This key represents a pointer for any device being added to the system for the first time. When the generic UISP key is entered into a device's settings, that device will try to connect to UISP using the hostname / IP and the port part of that key (see the third row of the table above).
If the connection is successful, the AES key part of the UISP key is used for secure communication between the device and UISP. When the connection is established for the first time then a new AES key is generated for the device. This new AES key replaces the original AES key in the generic UISP key, creating The Device Specific UISP Key. Then the device-specific UISP key rewrites the generic UISP key on the device and UISP stores the device’s MAC address and AES key in the PostgreSQL database.
From that point forward, each time the device wants to communicate with UISP, the AES key part of the device-specific UISP key is used and UISP uses the AES key from the PostgreSQL database for decryption/encryption.
How to Manually Register a Device via Device UI
This is only necessary for devices that cannot be found via the UISP Remote Discovery tool.
1. Open UISP and go to the Settings -> Devices section.
2. Expand the Devices Adoption section and click on the Copy UISP key to clipboard link to copy the key, which will be used again in step 5. The generic key is the same for all devices.
3. In your browser type in the IP address of the device, which should open the device's login screen. Insert the correct credentials and you will get to the Device administration screen.
4. Go to the System or Services section.
5. Paste the UISP key.
6. Enable the UISP connection.
7. Save the device configuration.
8. Now you can go back to the UISP and check the 'devices' table. You should see the newly added device there. Authorize the device in the UISP devices list and assign it to a Site or Subscriber
How to Register a Device via SSH
EdgeMAX
admin@ER-X:~$ configure
admin@ER-X# delete service unms disable
admin@ER-X# set service unms connection generic UNMS key
admin@ER-X# commit
admin@ER-X# save
Saving configuration to '/config/config.boot'... Done
airMAX
1. Edit device configuration in file /tmp/system.cfg
unms.uri=wss://XX.YY.ZZ.XX:XX+XYZYXZYXYZYXZYXYZXZYXZ+allowSelfSignedCertificate
unms.uri.changed=wss://XX.YY.ZZ.XX:XX+XYZYXZYXYZYXZYXYZXZYXZ+allowSelfSignedCertificate
unms.status=enabled
2. To apply the configuration use command /usr/etc/rc.d/rc.softrestart save