UNMS - Security


This article covers important details about UNMS security.

Table of Contents

  1. Introduction
  2. UNMS Server Ports, Certificates and HTTP Headers
  3. Device Discovery and Connection
  4. UNMS Login
  5. Data Storage
  6. Credentials Vault
  7. Related Articles


Back to Top

When developing UNMS the question of user security is paramount. UNMS uses double encryption for critical elements of device communication, and will not store credentials unless strictly needed. The special bounty program was also created to help find any security issues.

UNMS Server Ports, Certificates and HTTP Headers

Back to Top

UNMS will only communicate through encrypted channels (HTTPS and WSS), with one exception: HTTP port 80 is used by UNMS exclusively for generating the built-in LetsEncrypt certificate. There is no easy way around it since LE servers need to access the port 80 in order to validate that the certified domain does really belong to the machine generating the certificate. We do not support the DNS challenge since it is almost impossible to create a simple user-friendly UI to set it up for all DNS hosting. UNMS strictly controls whether the Cipher Suites are enabled or not. If the native LE certificate is used, then UNMS has the A+ mark in the SSL Labs security test.

If users supply their own certificate during UNMS installation then port 80 is not used at all and can be completely closed. However, it is important to mention that there is a significant benefit of using the native LE certificate: the user doesn't need to worry about the certificate's expiration date since UNMS will refresh the certificate automatically.

All other communication going to HTTP (on port 80 or any other custom port you may choose eg. 8080) is automatically redirected to HTTPS 443 port (or a custom port, if specified by the user) in order to utilize security encryption of HTTPS protocol. For this reason the UNMS user interface, API or WebSocket cannot be accessed via HTTP.

It is possible to set up a custom inform port (a port to which devices may connect) in order to separate the UNMS GUI from the communication channel to devices. That way it is possible to have UNMS GUI accessible exclusively through a private network, and yet allow devices to communicate with it.

HTTP headers are important for UNMS security because they manage the browser a configuration that will control details such as where the JavaScript is downloaded from, how it should run, how certificates should be approached and so on. UNMS uses the platform securityheaders.com to evaluate the security efficiency of its HTTP headers and currently holds the A+ mark with a perfect configuration.

Device Discovery and Connection

Back to Top

The most secure way to connect a device with UNMS is to manually insert the generic UNMS key into that device. This key contains the URL address of the UNMS server and a generic AES encryption key. After the device receives this key it connects to UNMS using encrypted WebSocket protocol (WSS). All devices are connecting to the UNMS controller using both WSS and AES encryptions; ensuring a double encrypted connection. All communication occurs through this secured channel including remote shell access, although at the first glance it might seem that UNMS is connecting into the device via SSH.

Another scenario when implementing double encryption is important is when the UNMS server does not have a verified certificate. Such would be the case when UNMS is accessible only through an IP address without a valid generated certificate. UNMS will use another encryption system beside the SSL to ensure a system that is resilient to MITM attacks even if a certificate is untrusted. Specifically, AES 256 GCM encryption is used. More details about this can be found in the The UNMS Key and the Device Registration Process article.

Manually inserting generic UNMS keys into devices one by one is not practical, so the UNMS team added a feature called Discovery, which allows to find many devices in a network and insert the generic UNMS key into them automatically. This is one of only two occasions (the second one is the remote shell) when UNMS will ask for a device's credentials and will use them to connect to the device via SSH or HTTPS (if a device doesn't have the HTTPS enabled, discovery won't allow the connection to happen, for security reasons). The credentials are not saved during this process. After the initial connection is established UNMS inserts the key into the device and a new encrypted WebSocket is established for further communication. So the connection is made by UNMS but the communication is then initiated by the device and UNMS plays the role of WebSocket server. 

UNMS Login

Back to Top

The security of the login process is based on a token that is sent through the x-auth-token header. This token also serves as a protection against CSRF attacks. In the version 0.13.1, it is valid for 24 hours and extended in case of user activity. Since version 0.14.0 the validity is customizable for users (from 30 min up to 30 days). While a user is active the token's validity is extended for one month top, after that it is necessary to log in again. There is a brute force protection build in UNMS. We are using this library with a following set of options:

options: {
          enabled: false,
          checkUnauthorized: true,
          pathLimit: false,
          userPathLimit: true,
          userCache: { expiresIn: config.apiRateLimit.userCacheExpiresIn },

The value of 'userCacheExpiresIn' is set to 2 minutes.

Currently, UNMS supports two different user roles. The 'Admin' role has full access to all features; while the 'Read-only' role cannot make any changes to the network or any device. Significant extensions to this system are planned for the future.

UNMS supports two-factor authentication (2FA). On a mobile device, users can use Google Authenticator (iOS or Android). There are 2FA applications for computers as well, but they are not recommended since for 2FA to be truly useful it must be placed on a completely separated device, hopefully, one which the attacker cannot get a hold of. When 2FA is set up the user will need to log in to UNMS with their credentials and insert a 6 digit security code provided at that moment by the authenticator app on their mobile. Even if somehow the user's UNMS credentials were compromised, the possible intruder would also need access to the associated mobile phone in order to access the UNMS account.

To set up 2FA on UNMS follow these three steps:

1. In the UNMS user interface go to Settings > Users > Enable Two-Factor as shown in the picture below.


2. A screen with a barcode will appear. Scan it with the authenticator mobile application of your choice to receive a six-digit code.


3. UNMS will then ask you to log in again using the newly acquired code. This will create the link. Each time you log in to UNMS you will be required to provide the current six-digit code.


If you run into any issues with 2FA, you may use this article about password recovery to disable it completely.

Data Storage

Back to Top

The login credentials of UNMS users are stored and protected with bcrypt, and plaintext is never used to save users' passwords anywhere in UNMS. There is an option to store devices' credentials as well in the UNMS, but those data cannot be encrypted, because UNMS needs to understand and work with those passwords. For that reason, devices' credentials are stored within the safe Vault. 

Credentials Vault

Starting from UNMS version 0.14.0 the Credentials Vault had been incorporated, allowing to save device passwords safely. Since version 1.1.0 there is even an option to generate credentials for many devices at once through the Vault which makes it a key component in UNMS security. The vault encrypts stored passwords with asymmetric encryption. A public key is used to write data and a private key, protected by a master password, is used to read them. The master password with a safe length is generated automatically during the vault creation process (this is a mandatory part of the installation process since version 0.14.0). For local instances, it is necessary to save the Vault key file somewhere safe, but also handily available because the key file is needed each time the UNMS server is restarted. Specifically for free UNMS Cloud instances, there will be an option to save the Vault key outside the instance (but still within the UNMS Cloud). We will then take care of the Vault key, thus removing the need for users to reapply it with each restart while keeping the high level of security at the same time. The vault can be managed through Settings -> Credentials Vault

Related Articles

Back to Top

UNMS - The UNMS Key and the Device Registration Process

UNMS - Password Recovery

Ubiquiti's Guide to Basic Security

We're sorry to hear that!