jeffreykog/unifi-inform-protocol

Information about the reverse engineered inform protocol used in Ubiquiti's UniFi access points

unifi-inform-protocol

Information about the reverse engineered inform protocol used in Ubiquiti's UniFi access points Keeping this really simple, everything is in this file (README.md) so you can read it easilly on github.

Discovery

When an unadopted UAP is connected to the network, it will start announcing itself on the layer 2 network. It will do this in 2 ways:

• As a broadcast packet (255.255.255.255)
• As a multicast packet to 233.89.188.1

The same announcement packet is sent to both these addresses. This packet is an UDP packet sent to port 10001

This packet is in the TLV format (type, length, value)

The following packet types are available:

• 0x01: Hardware address
• 0x02: IP Info
• 0x03: Firmware version
• 0x06: Username
• 0x07: Salt
• 0x08: Random Challenge
• 0x09: Challenge
• 0x0A: Uptime
• 0x0B: Hostname (Always UBNT for an unadopted AP)
• 0x0C: Platform
• 0x0D: ESSID
• 0x0E: WMode ??
• 0x0F: Webui ??
• 0x14: Model

Note that not all these options may be available at all times

Full packet format

Note: all data is in network byte format (Big endian).

• 2 bytes: Packet length
• Repeated n times:
  • 1 byte: Value type (see above)
  • 2 bytes: Value length l
  • l bytes: Value

Adoption process

When the unifi controller is on the same layer 2 network as the UAP, the controller will have discovered the UAP after this announcement packet is received and will list it in the devices list as unadopted If the UAP is not on the same layer 2 network as the controller, and you want to use layer 3 adoption, you have to ssh into the UAP (default username ubnt, default password ubnt), and issue the command set-inform http://ip-of-controller:port/inform. When this is done, the UAP will try to connect to the controller to be adopted. If the UAP was not known yet to the controller, it will be listed in the devices list after this packet is sent, but it is not adopted yet.

If the UAP is on the same L2 network as the controller and you click Adopt in the controller, the controller will connect to the UAP over ssh (using the default ubnt:ubnt credentials) and issue the following command: /usr/bin/syswrapper.sh set-adopt http://ip-of-controller:port/inform <random generated 16 bit hex string (the encryption key)>

Now the UAP knows the encryption key and will use it to connect to the controller

Inform protocol spec

An inform packet is an http POST request to the /inform url. It is a binary packet. The format is as follows:

• 4 bytes: Magic header. Always TNBU (UBNT reversed)
• 4 bytes: Packet version (Currently always 0)
• 6 bytes: AP mac address
• 2 bytes: Flags
  • 0x01: Encrypted
  • 0x02: Compressed (ZLIB)
  • 0x04: Use snappy compression instead of zlib (only valid when 0x02 is set as well)
  • 0x08: Use AES-GCM encryption instead of AES-CBC (only valid when 0x01 is set as well)
• 16 bytes: Initialization Vector (IV) for encryption
• 4 bytes: Data Version
• 4 bytes: Payload length l
• l bytes: Payload

The encryption of the payload is unpadded AES-128-CBC, or AES-GCM in newer firmwares (see flags above). The encryption key is the key sent to the UAP while adopting it (see Adoption Process section). If the UAP is already adopted, you can find the encryption key in the cfg/mgmt file in the default ssh folder on the UAP. See the mgmt.authkey line for the encryption key.

When decrypted, you see some json data. What all these values mean should be pretty clear.

Snappy compression is not used in modern firmwares. Nowadays the compression algorithm is zlib.

Configuring an UAP

Coming soon

unifi-inform-protocol's Issues

Doc update - add information about other devices

Thank you for your work.
I think it would be great to mention that other devices (at least M series) using same protocol for the device discovery. At least valid for the M and AC access points/CPE. I am going to write a small tool to make discovery from Linux w/o using Java, etc.

Layer confusion

When an unadopted UAP is connected to the network, it will start announcing itself on the layer 2 network. It will do this in 2 > ways:

As a broadcast packet (255.255.255.255)
As a multicast packet to 233.89.188.1

Layer 2 (Ethernet) does not have IP Addresses. Also, Ethernet does not distinguish between multicast and broadcast.
There is a range of reserved multicast MAC Addresses for specific purposes. And there is also the special mac address FF:FF:FF:FF:FF:FF. In every case, multicast ethernet frames are spammed to the whole collision domain (hubs) or to every port (switch) that is connected.

Additionally, you have to enable layer 2 adoption specifically in the controller. So I think L3 adoption is the default and does not neccesarily need additional configuration in the devices, prior to adopt them in L3

Actually the UDP communication that you found out on port 10001 would be, strictly speaking, already L4

Snappy

Yes, it was used for snappy for a while, I have captures and a working decoder for flags = 5 ( encryption + snappy ). The compression seems to be depreciated and they are back to zlib and moved on to GCM.