This article covers important details about UNMS security.
Table of Contents
- UNMS Server Ports, Certificates and HTTP Headers
- Device Discovery and Connection
- UNMS Login
- Data Storage
- Related Articles
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
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.
Device Discovery and Connection
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.
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 XSS and CSRF attacks. It is valid either for 30 minutes or during the time UNMS is being actively used, in which case the validity is extended automatically.
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 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.
UNMS is minimizing the number of stored credentials. When login details are required during the device discovery process the data is not stored in a database. UNMS retains it for a short period, but once the connection to the device is established, the data is deleted. The login credentials of UNMS users are stored and protected with bcrypt, and plaintext is never used to save passwords anywhere in UNMS.
Starting from UNMS version 0.13.0 the Password vault feature will be incorporated, which will allow saving device passwords safely. The vault will be encrypted with asymmetric encryption. There will be a public key used to write data and a private key, protected by a master password, used to read them. The master password with a safe length will be generated automatically during the vault creation process.