UNMS - The UNMS Key and the Device Registration Process


Overview


This article provides details about UNMS's generic key and how it works, as well as describing the fundamentals of the device registration process.

NOTES & REQUIREMENTS
This article applies to the following firmware versions:
  • EdgeRouter: 1.9.7+ / EdgeSwitch: 1.7.3+ / UFiber OLT: 1.0.0+ / airMAX (AC): 8.4.1+ / airMAX (M): 6.1.3+ / airCube: 1.0.0+
  • Also please note that UNMS doesn't support older airMAX devices with firmware versions 4.x, 5.x or 7.x.
WARNING: For security reasons, never share your UNMS key publicly. If you need to share it for whatever reason, always obscure the hostname and AES string parts of the key.

Table of Contents


  1. Introduction
  2. How to Register a Device via UNMS Discovery
  3. How to Manually Register a Device via Device UI
  4. How to Register a Device via SSH
  5. UNMS Generic Key Details
  6. Behind the Scenes: How Does the UNMS Key Work?
  7. Related Articles

Introduction


Back to Top

The purpose of the UNMS key is to provide a secure communication using AES encryption while telling a device where to look for a UNMS server. The process of device registration using the generic UNMS key and the device specific UNMS key ensures secure communication between the user's devices and UNMS.


How to Register a Device via UNMS Discovery


Back to Top

1. Go to the UNMS Discovery Manager.

2. Fill in the subnet or IP addresses of the devices.

3. Click the START button.

4. Fill in the credentials.

5. Click the CONNECT button.

discovery.png


How to Manually Register a Device via Device UI


Back to Top

This is only necessary if UNMS is not on the same network as the devices being registered and they cannot be found with UNMS Discovery.

1. Open UNMS and go to the Devices section.

2. Click the ADD DEVICE button.

3. Copy the UNMS key (it is the same UNMS key for all devices).

4. Open the device's administration page.

5. Go to the System or Services section.

6. Paste the UNMS key.

7. Enable the UNMS connection.

8. Save the device configuration.

9. Authorize the device in the UNMS devices list.


How to Register a Device via SSH


Back to Top

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

Danger: Be extremely careful when changing airMAX devices' configurations. There is no validation before this manual change applies and a mistake in configuration may lead to losing connectivity to the device.

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


UNMS Generic Key Details


Back to Top

In the following two sections we will discuss what happened in the background as the devices were registered using one of the two processes described above. Here is an example of the UNMS key:

wss:// your.domain.com :443 + n9yU137QSwTzBXnF...9Sk0pC7sDKGnpbxiHRI9W +

The UNMS key consists of several parts (shown in different colors above), each with their own purpose. In the table below the UNMS key appears split in its different parts, and each section's purpose described.

Key Part Purpose
wss:// WebSocket Secure connection protocol
your.domain.com Hostname or IP of the server where UNMS runs
:443 Port for devices to access UNMS server
n9yU137QSwTzBXnF...9Sk0pC7sDKGnpbxiHRI9W Advanced Encryption Standard key (AES key)

 


Behind the Scenes: How Does the UNMS Key Work?


Back to Top

When a new instance of UNMS is installed, it creates its own UNMS key which is called The Generic UNMS Key. This key represents a pointer for any device being added to the system for the first time. When the generic UNMS key is entered into a device's settings, that device will try to connect to UNMS 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 UNMS key is used for secure communication between the device and UNMS. 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 UNMS key, creating The Device Specific UNMS Key. Then the device specific UNMS key rewrites the generic UNMS key on the device and UNMS stores the device’s MAC address and AES key in PostgreSQL database.

From that point forward, each time the device wants to communicate with UNMS, the AES key part of the device specific UNMS key is used and UNMS uses the AES key from the PostgreSQL database for decryption/encryption.


Related Articles


Back to Top

UNMS - Device Discovery


We're sorry to hear that!