└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # unifi-inform-protocol 2 | 3 | Information about the reverse engineered inform protocol used in Ubiquiti's UniFi access points 4 | Keeping this really simple, everything is in this file (README.md) so you can read it easilly on github. 5 | 6 | # Discovery 7 | 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: 8 | 9 | * As a broadcast packet (`255.255.255.255`) 10 | * As a multicast packet to `233.89.188.1` 11 | 12 | The same announcement packet is sent to both these addresses. This packet is an UDP packet sent to port 10001 13 | 14 | This packet is in the TLV format (type, length, value) 15 | 16 | The following packet types are available: 17 | 18 | * `0x01`: Hardware address 19 | * `0x02`: IP Info 20 | * `0x03`: Firmware version 21 | * `0x06`: Username 22 | * `0x07`: Salt 23 | * `0x08`: Random Challenge 24 | * `0x09`: Challenge 25 | * `0x0A`: Uptime 26 | * `0x0B`: Hostname (Always `UBNT` for an unadopted AP) 27 | * `0x0C`: Platform 28 | * `0x0D`: ESSID 29 | * `0x0E`: WMode ?? 30 | * `0x0F`: Webui ?? 31 | * `0x14`: Model 32 | 33 | Note that not all these options may be available at all times 34 | 35 | ### Full packet format 36 | Note: all data is in network byte format (Big endian). 37 | 38 | * 2 bytes: Packet length 39 | * Repeated `n` times: 40 | * 1 byte: Value type (see above) 41 | * 2 bytes: Value length `l` 42 | * `l` bytes: Value 43 | 44 | # Adoption process 45 | 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 46 | 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. 47 | 48 | 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: 49 | `/usr/bin/syswrapper.sh set-adopt http://ip-of-controller:port/inform ` 50 | 51 | Now the UAP knows the encryption key and will use it to connect to the controller 52 | 53 | # Inform protocol spec 54 | An inform packet is an http POST request to the `/inform` url. It is a binary packet. The format is as follows: 55 | * 4 bytes: Magic header. Always `TNBU` (`UBNT` reversed) 56 | * 4 bytes: Packet version (Currently always 0) 57 | * 6 bytes: AP mac address 58 | * 2 bytes: Flags 59 | * 0x01: Encrypted 60 | * 0x02: Compressed (ZLIB) 61 | * 0x04: Use snappy compression instead of zlib (only valid when 0x02 is set as well) 62 | * 0x08: Use AES-GCM encryption instead of AES-CBC (only valid when 0x01 is set as well) 63 | * 16 bytes: Initialization Vector (IV) for encryption 64 | * 4 bytes: Data Version 65 | * 4 bytes: Payload length `l` 66 | * `l` bytes: Payload 67 | 68 | The encryption of the payload is unpadded AES-128-CBC, or AES-GCM in newer firmwares (see flags above). 69 | The encryption key is the key sent to the UAP while adopting it (see Adoption Process section). 70 | 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. 71 | 72 | When decrypted, you see some json data. What all these values mean should be pretty clear. 73 | 74 | Snappy compression is not used in modern firmwares. Nowadays the compression algorithm is zlib. 75 | 76 | # Configuring an UAP 77 | Coming soon 78 | --------------------------------------------------------------------------------