Deployment of XQ's Zero Trust Secure Gateway on Ubiquiti UniFi UDM Pro
How to configure your Ubiquiti Router for Zero Trust
Introduction
This walkthrough offers a comprehensive guide on deploying XQ’s Secure Gateway on the UniFi UDM Pro Gateway. The process encompasses setting up and configuring UniFi SSH access, creating and configuring a custom Debian container on UniFiOS 3.0+, and deploying and utilizing XQ’s Secure Gateway within that container. This guide is designed to seamlessly integrate XQ's revolutionary Zero-Trust Gateway into your network infrastructure, enhancing your security without replacing existing setups. Whether you’re aiming to secure file transfers, enable secure media streaming, host URLs securely, or bridge intranets securely across networks, this walkthrough equips you with the knowledge to implement a robust security solution that's both versatile and scalable.
Overview
XQ's Zero-Trust Gateway revolutionizes secure data transmission without replacing your existing infrastructure or software. This innovative solution layers on top of your current setup, seamlessly encrypting data streams and facilitating their encrypted transfer over established data links and public networks. Designed for versatility, it supports a range of applications, including file transfers, media streaming, URL hosting, and intranet bridging, with flexible deployment options that run on devices as compact as a Raspberry Pi across most modern operating systems.
The gateway empowers users to easily configure trusted devices for automatic encryption and decryption of data before it reaches its intended destination, ensuring secure transmission. It is adept at managing multiple TCP/UDP connections, devices, and team settings with a single unit. Moreover, each gateway works in synchronization with at least one XQ backend, maintaining the integrity and traceability of operations just as if interfaced directly with the XQ API, with comprehensive logging accessible via the management portal.
A key feature of the Zero-Trust Gateway is its complete neutrality to the data it processes. Beyond recognizing and utilizing specific known data elements like tokens, it does not inspect or analyze your data, ensuring no recognition or categorization based on content. This ensures that data requiring different handling or categorization can be routed accordingly without compromising privacy or security.
Main Use Cases
Secure File Transfer Services
The Zero-Trust Gateway introduces a revolutionary approach to secure file transfers, enabling a zero-trust file transfer pipeline between one or multiple hosts. Users can continue using their preferred file transfer utilities (such as FTP, FTPS, RDP, etc.), while the integration of XQ's Zero-Trust Gateway guarantees that every data transmitted between the client and server is encrypted. This encryption is not just robust; it's dynamic, employing continuously changing and time-limited keys to ensure unmatched security for your data at every step of the transfer process.
Secure Media Streaming
XQ's Zero-Trust Gateway elevates the security of media streaming, facilitating real-time audio and video streaming between hosts with unparalleled protection. Whether it's video or audio content, packets are transmitted directly from the capture device to the Zero-Trust Gateway. Here, each video frame undergoes encryption with a unique key before being dispatched to its intended destination. This ensures that every moment of your streamed content is protected by robust encryption, making it ideal for secure, real-time media transmission.
Secure URL Hosting
The Zero-Trust Gateway is a formidable, secure web proxy compatible with HTTPS and standard HTTP protocols. It receives HTTP/S requests (TCP) from the client's browser and encrypts them within the gateway. This encrypted traffic is relayed to the web server, where the request is processed. The server's response is securely transmitted back to the client's browser. This seamless process ensures that every web request and response is safeguarded, providing a robust layer of security for web browsing activities.
Secure Intranet Bridging
XQ's Zero-Trust Gateway offers a cutting-edge solution for bridging the communications between two or more Local Area Networks (LANs) across a Wide Area Network (WAN). This configuration enables secure data transfers in various scenarios, including site-to-site, site-to-cloud, and cloud-to-cloud communications. By encrypting data during transmission, the gateway ensures the highest level of security, safeguarding your data across any distance and network architecture. This approach guarantees that your sensitive information remains protected, whether it's moving between physical locations or navigating the complexities of cloud environments.
UniFi configuration & setup for Zero Trust
UniFi configuration & setup
Enabling SSH Access UDM PRO
To get started, we must enable SSH access to the UDM Pro Router.
Open the web browser of your choice, navigate to your Unifi Router's IP Address (by default, 192.168.0.1), and log in.
If you see the “Your Connection is not private” web page simply click the advanced button followed by the proceed to
In the left-hand navigation menu, click the settings cog followed by clicking System in the follow-up menu.
Scroll down to Console Controls and SSH under console controls.
Ensure this is Enabled and click the “Change SSH Password” link.
Input your desired ssh password followed by clicking “Enable”
To ensure this is working as intended, open your terminal window and input “ssh root@192.168.0.1.” If you aren’t using the default IP, replace it with the input and press enter.
Depending on the ssh client you are currently using you may have to specify the HostKeyAlgorithms and PubkeyAcceptedAlgorithms to +ssh-rsa
ssh root@192.168.0.1 -o HostKeyAlgorithms=+ssh-rsa -o PubkeyAcceptedAlgorithms=+ssh-rsa
Input the previously input password followed by pressing enter, and you should now be SSH’d into the UDM PRO Terminal.
How to Create a Custom Container on UnifiOS 3.x+
Due to a kernel update, UnifiOS 3.0 has transitioned away from Podman/Docker support. Nevertheless, the capability to construct a container persists through the use of systemd-nspawn. We'll leverage this feature to establish an XQ Secure Gateway Container effectively.
Installation & Setup
We first need to install systemd-container and debootstrap. We will use debootstrap to create a directory with a base debian system, and then use systemd-nspawn to boot the container.
apt -y install systemd-container debootstrap
2. Next, we use debootstrap to create a directory called debian-custom with a base debian system in /data/custom/machines
mkdir -p /data/custom/machines cd /data/custom/machines debootstrap --include=systemd,dbus unstable debian-custom
(debootstrap --include=systemd,dbus unstable debian-custom)
Finally, let’s bring up a shell on this container, set the root password, and enable the networking service. Run each command one-by-one.
systemd-nspawn -M debian-custom -D /data/custom/machines/debian-custom passwd root systemctl enable systemd-networkd echo "nameserver 1.1.1.1" > /etc/resolve.conf echo "debian-custom" > /etc/hostname exit
{systemd-nspawn -M debian-custom -D /data/custom/machines/debian-custom}
First, we will link the container to /var/lib/machines so we can control it with machinectl.
mkdir -p /var/lib/machines ln -s /data/custom/machines/debian-custom /var/lib/machines/
(ln -s /data/custom/machines/debian-custom /var/lib/machines/)
Make sure you are back on the host OS and not in the container and link the container to /var/lib/machines so we can control it with machinectl
mkdir -p /etc/systemd/nspawn vim /etc/systemd/nspawn/debian-custom.nspawn
For a container that has access to all the host network interfaces and full capabilities to do anything to the system, here is an example nspawn configuration file. Note it is important to set Boot=on so systemd boots up inside the container.
[Exec] Boot=on Capability=all ResolvConf=off
[Network] Private=off VirtualEthernet=off
[Files] Bind=/data:/data
After you've configured your nspawn file, let's boot up the container and see if it works.
machinectl start debian-custom machinectl enable debian-custom
Now that the container is running, we should be able to open a shell or login to it.
Typing machinectl shell debian-custom should open a shell to the machine and bypass login. Typing exit in this shell will exit back to the host Unifi OS.
Make sure you run machinectl enable debian-custom so the container starts on boot.
Configure Persistence Across Firmware Updates
Download the 0-setup-system.sh script into /data/on_bood.d.
mkdir -p /data/on_boot.d && cd /data/on_boot.d curl -LO https://raw.githubusercontent.com/peacey/unifios-utilities/nspawn/nspawn-container/scripts/0-setup-system.sh chmod +x /data/on_boot.d/0-setup-system.sh
(curl -LO https://raw.githubusercontent.com/peacey/unifios-utilities/nspawn/nspawn-container/scripts/0-setup-system.sh)
Download the backup dpkg package files for systemd-container and dependencies into /data/custom/dpkg. These packages will only be used as a backup install in case the Internet is down after the first boot after an update.
mkdir -p /data/custom/dpkg && cd /data/custom/dpkg apt download systemd-container libnss-mymachines debootstrap arch-test
(apt download systemd-container libnss-mymachines debootstrap arch-test)
The script 0-setup-system.sh in /data/on_boot.d must be started on boot.
vi /etc/systemd/system/setup-system.service [Unit] Description=Setup custom container service Wants=network-online.target After=network-online.target StartLimitBurst=5
[Service] Type=oneshot ExecStart=/data/on_boot.d/0-setup-system.sh RemainAfterExit=yes
Enable the setup-system script on startup.
systemctl enable setup-system
XQ Secure Gateway Installation & Setup
Configuring Routing & Mappings for XQSG
Each gateway is set up using two configuration files:
routing.json: describes all the devices, configurations, and routes this gateway will be responsible for processing. xq.conf: Contains the URLs for the XQ backends that this gateway will be connecting to and the associated api keys.
Both of these are generated through the steps outlined below:
Sign into https://gateway.xqmsg.com (you must have super user permissions)
Go to the gateways section.
Click on the "Create Gateway" button in order to configure your gateway.
Provide a name for the gateway you are creating followed by clicking the "Create Gateway" button.
Input the necessary values in the following fields:
Name: The user-specified name for the gateway you are creating.
Connection IP: The publicly accessible IP address of the hardware that the gateway will be deployed on.
Create an Inbound Route for your gateway by inputting the necessary values in the following fields:
Name: The user-specified name for the inbound route.
Routing Type: Specifies whether this route is for encryption (enc) or decryption (dec) or untouched (pass). The last type is for passing unprocessed data through the gateway (mainly for testing purposes).
Transport: Specifies whether this route uses standard (standard) or raw (sockets).
Protocol: The network protocol to use. This can be udp, tcp or inherit. The last option is only valid for raw transports, and allows all packets to go through regardless of protocol (these can be filtered further down the validation chain).
Algorithm: The encryption algorithm to use. This is only valid for encryption routes. Must be either AES or OTP. Using AES is not currently recommended for audio/video streams due to its CPU usage.
Listen IP: The local IP or domain name that this route will be bound to in order to listen for incoming data. For tcp transports, 0.0.0.0 or all may be used to listen on all incoming interfaces. For raw transports (which must have an interface specified), omitting this value will listen to all the traffic on an interface.
Listen Port: The network port that this route will listen on.
Listen Interface: The network interface this route will listen on.
Key Recycling: The number of times a key is reused before it is discarded and a new one obtained. A higher number reduces the number of requests to the XQ server and thus latency. A zero value means the key server will be hit with every data frame.
Key Lifetime: The time based on the lifetime units that an encryption key will remain valid in the database.
Lifetime Unit: The unit of measurement utilized in the Key Lifetime.
Concurrency: For raw transports, this refers to the maximum number of concurrent connections that this route should expect to process at any given time. For tcp transports, it is the maximum number of pending connections allowed.
VLAN Filter: The VLAN tag to filter on. For standard transports, this will cause a new virtual interface to get created on the system and used in place of the provided interface.
Recipients: The recipients that will be able to decrypt outgoing messages from this route. To allow encryption by all clients, this can be set to xq.public. Valid only for encryption routes. In general, the email address for a trusted device will be in the form of Device_Name-Local_IP@TEAM_ID.trusted.local. The entire field should be 1024 characters at most.
Create an Outbound Mapping for the Inbound Route for your gateway by inputting the necessary values in the following fields:
Title: The user-specified name for the mapping.
Transport: Specifies whether this mapping uses standard (standard) or raw (sockets).
Protocol: The network protocol to use for mappings. This can be udp, tcp or inherit. The last option is only valid for raw transports, and allows all packets to go through regardless of protocol
Source Device: The name of the device that this particular mapping is for. Must either match the name of a defined device (in the "devices" block), or omitted to indicate a default route.
Target IP: The outgoing destination IP or domain name. Data that has been processed by this route will be transmitted to this IP. This value may also be set to inherit, which causes the mapping interface to use the IP of the parent route.
Target MAC: The target interface MAC Address that data will be sent through.
Source VLAN: Specifies the incoming VLAN tag that should be filtered through to this mapping. If this is non-zero raw transmissions are automatically enabled
Target VLAN: Specifies the VLAN tag that will be applied to data transmitted with this mapping be filtered. If this is non-zero raw transmissions are automatically enabled
Outgoing Port: The outgoing destination port.
Raw Types: This field is for raw transport only, and acts as an additional ethertype / protocol filter. By setting the filter on the mapping level, we can support multiple protocols on a single raw route. Possible options are ip, ip.udp, ip.tcp, ip.icmp, ip.icmp.request, ip.icmp.reply, arp, arp.request and arp.reply.
Downloading XQSG Binaries
Sign into https://gateway.xqmsg.com (you must have super user permissions).
Go to the Download section.
In the Binary Platform dropdown select the UnifiOS Operating System of the device the gateway will be running on.
In the Gateway Config dropdown select the name of the gateway configuration previously created.
Click "Download Now" to download the binary and the necessary configuration files.
Transferring & Running the Necessary XQSG Executable Files
Use Secure Copy Protocol or other tools such as putty to transmit the necessary container files to the UDM Pro.
scp -i ~/.ssh/id_rsa -o HostKeyAlgorithms=+ssh-rsa -O xqsg.zip root@192.168.0.1:/data
Open the systemd.nspawn container and install the necessary OpenSSL and Curl dependencies utilizing the following command.
machinectl shell debian-custom apt install openssl curl unzip
Extract and ensure the binaries are executable
cd /data && unzip xqsg.zip chmod +x xqsg xqmon
Running XQ Monitor & XQ Secure Gateway
Once that is complete you should now be able to run your gateway as well as the monitor tool.
./xqmon -c /path/to/xq.conf -r /path/to/routing.json -g /path/to/xqsg
(./xqmon -c /path/to/xq.conf -r /path/to/routing.json -g /path/to/xqsg)
You can now configure your gateway remotely using the gateway.xqmsg.com portal.
For additional configuration documentation please visit the following link: https://xq.stoplight.io/docs/xq-gateway/p7j204yrj6dxr-xq-zero-trust-gateway
Further routing.json properties can be identified at the following link: https://xq.stoplight.io/docs/xq-gateway/rztp2jijytg1t-routing-json-properties
