wiremax

Un disector de Wireshark/tshark para los AirMAX (AC + M) de Ubiquiti y los elementos de información de proveedor complementarios de Mikrotik / RouterBoard, escrito en Lua.

Es la contraparte en el cable de pyrmax: la lógica de decodificación refleja ese paquete de Python campo por campo. El formato de paquetes AC se obtuvo mediante ingeniería inversa del binario de firmware AirMAX AC; los diseños de M y RouterBoard provienen de notas publicadas anteriormente sobre el IE de proveedor AirMAX-M más antiguo.

AirMAX viaja dentro de los IE específicos de proveedor de 802.11 (etiqueta 221). Wireshark ya analiza la trama 802.11 y muestra el IE de proveedor como un blob opaco; wiremax toma ese blob, lo descifra (AES-128-ECB, clave derivada de las MAC de la trama) y representa un subárbol analizado y filtrable.

Tag: Vendor Specific: Ubiquiti Inc  (built-in 802.11 dissector)
AirMAX AC (Vendor Specific IE)       ← added by wiremax
    Flags: 0x02 ( .... ..1. = Encrypted: True )
    Message Type: Beacon (1)
    Encrypted Length: 48
    [Decrypted payload (AES-128-ECB)]
        [AES Key …: 1f162a13…  (dst=broadcast)]
        Version: 9
        Source MAC: 24:5a:4c:44:57:fd
        Radio MAC (mac_0c): 24:5a:4c:44:57:fd
        Capability Flags: 0x0000003e
        Mixed Mode: 0
        Radioname: LB1
        SSID: labalUBI2
        TLV: Radioname (1), len 3
        TLV: SSID (2), len 9
        TLV: Padding (0)

El diseño descifrado depende de Message Type: los beacons llevan mac_0c / cap_flags / mixed_mode + TLVs de nombre (arriba); assoc req/resp llevan chainmasks, cap_flags y campos finales controlados por versión (field_9c, rssi, fwname, txpower); probe req es solo cabecera; deauth lleva un nonce de jiffies y un token de autenticación opaco (y su MAC de origen está enmascarada con XOR, que wiremax desenmascara).

Estado

Las regiones de bytes no documentadas se muestran crudas (Unknown [n:len]), nunca inventadas: la misma disciplina que pyrmax y la base de conocimiento ac/.

Cómo funciona

Un postdisector (no reemplaza al disector 802.11 integrado, sino que se ejecuta después de él). Para cada trama:

1. lee todos los wlan.tag.oui más wlan.sa / wlan.da mediante extractores Field;
2. coincide con el OUI de AirMAX AC (00:27:22), M (00:15:6d) o RouterBoard (00:0c:42) — para AC/M también requiere el tipo de OUI FF FF FF, porque 00:15:6d se comparte con Mikrotik y con otro IE de Ubiquiti que aparece en la misma trama;
3. localiza los bytes del IE en la trama y, para AC/M, descifra la carga útil con AES-128-ECB, clave = HMAC-SHA1(dst_mac, src_mac)[:16], probando primero el destino 802.11 capturado y recurriendo a broadcast (las tramas de identidad usan la clave de broadcast incluso cuando son unicast) — el ganador es aquel cuya MAC de origen incrustada en la carga útil descifrada coincide con el origen 802.11;
4. construye el subárbol, exponiendo los bytes descifrados como su propia fuente de datos para que la selección de campos los resalte.

La criptografía (SHA-1, HMAC-SHA1, descifrado AES-128) es Lua puro autocontenido — Wireshark no expone ninguna API criptográfica a Lua. Las cargas útiles son unos pocos bloques de 16 bytes, por lo que el rendimiento es irrelevante. La clave se deriva de MAC públicas, por lo que esto es ofuscación, no seguridad.

Instalación / ejecución

Puntual (sin instalación):

tshark   -X lua_script:airmax.lua -r capture.pcap -V
wireshark -X lua_script:airmax.lua capture.pcap

Persistente (GUI de Wireshark + tshark): coloca toda la carpeta wiremax/ en un directorio de complementos Lua personales. La ruta exacta se muestra en Wireshark en Ayuda ▸ Acerca de Wireshark ▸ Carpetas ▸ Complementos Lua personales; los valores predeterminados son:

Un enlace simbólico es ideal mientras se itera: los cambios se detectan al recargar (Ctrl+Shift+L) sin necesidad de copiar:

ln -s "$PWD" ~/.local/lib/wireshark/plugins/wiremax

Wireshark carga recursivamente todos los .lua dentro de la carpeta de complementos; los submódulos en wsairmax/ son módulos simples (inofensivos si se cargan de forma independiente) y test/selftest.lua no hace nada dentro de Wireshark.

Campos (filtros de visualización)

Ejemplos:

tshark -r cap.pcap -Y 'airmax.ac.ssid'                 -T fields -e wlan.sa -e airmax.ac.ssid
tshark -r cap.pcap -Y 'airmax.m.msg_type == 1'         -T fields -e airmax.m.src_mac
tshark -r cap.pcap -Y 'airmax.rb.device_name'          -T fields -e airmax.rb.device_name

Las capturas deben ser en modo monitor 802.11 (radiotap); las tramas de gestión que transportan los IE (beacon / probe response / assoc) no están cifradas en la capa 802.11 — solo la carga útil de AirMAX dentro del IE está envuelta en AES, y wiremax la desenvuelve.

Pruebas

test/selftest.lua ejecuta la criptografía y los decodificadores bajo el intérprete Lua 5.4 independiente (sin Wireshark), comprobando contra vectores de referencia más los vectores SHA-1 / HMAC estándar de RFC-2202:

lua test/selftest.lua        # from this directory

De extremo a extremo contra una captura real (pyrmax incluye pcaps de muestra en tests/samples/):

tshark -X lua_script:airmax.lua -r airmax_ac_beacon.pcap -V
tshark -X lua_script:airmax.lua -r airmax_m_probe_response.pcap -V

Estructura

wiremax/
├── airmax.lua            # Wireshark entry: ProtoFields + postdissector + tree
├── wsairmax/             # pure-Lua modules (no Wireshark dependency)
│   ├── util.lua          # hex / MAC helpers
│   ├── sha1.lua          # SHA-1 + HMAC-SHA1
│   ├── aes.lua           # AES-128 ECB decrypt
│   ├── crypto.lua        # key derivation + decrypt (mirrors pyrmax/_crypto.py)
│   ├── ac.lua            # AirMAX AC decoder (outer ksy: airmax_ac; payload hand-written per 09b)
│   ├── m.lua             # AirMAX M decoder       (ksy: airmax_m[_payload])
│   └── routerboard.lua   # RouterBoard decoder    (ksy: routerboard)
├── test/selftest.lua     # standalone-Lua test harness
└── README.md

Advertencias

• msg_type de M etiqueta 1 = Beacon según las notas más antiguas de AirMAX-M, pero el valor 1 también se observa en respuestas de sonda (probe responses) — el espacio de tipos de mensaje de M no está completamente mapeado, así que confía en el número crudo.
• La longitud del texto claro AC es enc_len, un u16 big-endian (09b §3); la antigua lectura de 1 byte era accidentalmente correcta solo para cargas útiles < 256.
• Los diseños de assoc-req / assoc-resp / deauth del AC se decodifican directamente de la especificación, pero el corpus de capturas aún no tiene muestras reales de AC de ellos — solo beacon y probe-req están verificados en el cable. Los decodificadores version < 9 tampoco están verificados (TX solo emite 9). Consulta los vectores sintéticos en test/selftest.lua.
• El descifrado depende de que la MAC de origen 802.11 esté presente en la captura. Si una trama no se puede descifrar, la cabecera externa en texto claro aún se muestra con una nota de experto.

Mantenerlo sincronizado con pyrmax

Cuando se añade/renombra un campo en pyrmax (src/pyrmax/ac.py o sus esquemas ksy/*.ksy), reprodúcelo en el decodificador wsairmax/*.lua correspondiente y, si es visible para el usuario, añade un ProtoField en airmax.lua. Los vectores de referencia en test/selftest.lua provienen de los pcaps de muestra de pyrmax, por lo que cualquier divergencia aparecerá allí.