Readers will learn more about the various UISP security features such as certificates, encryption, and credential management.
Table of Contents
- UISP Server Ports, Certificates, and HTTP Headers
- Device Discovery and Connection
- UISP Login
- Data Storage
- Credentials Vault
- Related Articles
The security of the UISP console (server) and its users is one of the main design principles during the UISP development process. UISP uses double encryption for critical elements such as device communication, and will not store credentials unless strictly needed. A special bounty program was also created to help find any security issues in order to patch them as soon as possible.
UISP Server Ports, Certificates, and HTTP Headers
UISP Server Ports and Certificates
UISP will only communicate through encrypted channels (HTTPS and WSS), with one exception: HTTP port 80 is used by UISP exclusively for generating the built-in Let's Encrypt certificate. There is no easy way around it since Let's Encrypt servers need to access TCP port 80 in order to validate that the certified domain really belongs to the machine generating the certificate. UISP strictly controls whether the cipher suites are enabled or not. We do not support the DNS challenge since it is almost impossible to create a simple user-friendly user interface and set it up for all DNS hosting.
If users supply their own certificate during UISP 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 Let's Encrypt certificate. With this setup, the user does not need to worry about the certificate's expiration date as UISP will refresh the certificate automatically.
All other communication for HTTP (80) is automatically redirected to HTTPS (443) in order to utilize security encryption of the HTTPS protocol. This applies to any custom HTTP(S) ports set as well. Due to the redirection, the UISP user interface, API, and WebSocket cannot be accessed via HTTP.
It is also possible to set up a custom inform port in order to separate the UISP GUI from the communication channel to devices. The inform port is used by the devices to connect to the UISP server and is set to TCP port 443 by default. Separating the inform port from the GUI port will allow you to access the UISP GUI exclusively through a private network, while still allowing devices to communicate with it.
UISP HTTP Headers
Device Discovery and Connection
Generic UISP Key
The most secure way to connect a device to UISP is to manually add the generic UISP Key to the device. This key contains the URL address of the UISP console (server) and a generic AES encryption key. The device will use the key to connect to the UISP server using the encrypted WebSocket protocol (WSS). All devices connecting to UISP will use both WSS and AES encryption, ensuring a double encrypted connection. All communication occurs through this secured channel, including the UISP Terminal that provides remote shell access, but does not use SSH to accomplish this.
UISP Untrusted Certificates
Another scenario where double encryption is important is when the UISP console (server) does not have a verified (valid) certificate and is accessible only through an IP address. Besides SSL, UISP will use another encryption system (AES 256 GCM) to ensure a system that is resilient to MITM attacks even when the certificate is not trusted.
Manually inserting generic UISP keys into devices one by one is not practical, so UISP also allows you to add devices using the (remote) Discovery feature. This feature will automatically discover devices in a (remote) network and can automatically insert the generic UISP key after providing the device credentials.
This is one of only two occasions (the other one being the UISP Terminal) when UISP will ask for the credentials of a device that uses them to connect via SSH or HTTPS. For security reasons, UISP discovery will not allow a device to connect if HTTPS is not enabled. The credentials are not saved during this process. After the initial connection is established UISP inserts the key into the device and a new encrypted WebSocket is established for further communication. In summary, the initial connection is made by UISP, but the communication is then initiated by the device and UISP assumes the role of the WebSocket server.
UISP Login Token
The security of the UISP user login process is based on a token that is sent through the A-Auth-Token header. This token also serves as a protection against CSRF attacks. On older UISP releases, the user session timeout was fixed at 24 hours and extended in case of user activity. On newer versions, the timeout is can be customized (from 30 min up to 30 days) in the Settings > Users > Edit Account section. While a user is active the token's validity is extended for up to one month, after which it is necessary to log in again. There is brute force protection build in UISP.
UISP User Roles
Currently, UISP supports two different user roles. The Admin role has full access to all features, whereas the Read-Only role cannot make any changes to the network or devices. You can specify a user as Read-Only in the Settings > Users section.
UISP Two-Factor Authentication
UISP supports Two-Factor Authentication (2FA) using the Google Authenticator app. There are 2FA applications for desktop computers available as well, but they are not recommended as 2FA is most useful if it is placed on a completely separate device. When 2FA is set up, the user will need to log in to UISP with their credentials and insert a 6 digit security code provided by the Authenticator app. Even if somehow the user's UISP credentials were compromised, the possible intruder would also need access to the associated mobile phone in order to access the UISP account.
Follow the steps below to enable Two-Factor Authentication (2FA) for a UISP user account:
2. Navigate to the Settings > Users > Edit Account section and select Enable Two Factor.
3. From the app, select Add Account (+) and scan the provided QR code.
The login credentials of UISP users are stored and protected with bcrypt. The plaintext is never used to save user passwords anywhere in UISP. UISP can also store device credentials in the Credentials Vault, see the section below.
The UISP Credentials Vault feature can securely store device credentials. There is also an option to generate credentials for many devices at once through the Vault which makes it a key component of the UISP 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 is generated automatically during the vault creation process.
It is currently necessary to store the Vault key file somewhere safe, but also readily available in order to unlock the Vault. The Vault key needs to be re-inserted every time the UISP server is restarted. The UISP Vault can be managed through the Settings > Credentials Vault section.