gen: Improve header comments, add ability to set Address 3 field for all management frames

26 files changed, 388 insertions, 181 deletions

@@ -46,15 +46,18 @@ void libwifi_free_action_detail(struct libwifi_action_detail *detail) {
     }
 }
 
-int libwifi_create_action(struct libwifi_action *action, const unsigned char receiver[6],
-                          const unsigned char transmitter[6], uint8_t category) {
+int libwifi_create_action(struct libwifi_action *action,
+                          const unsigned char receiver[6],
+                          const unsigned char transmitter[6],
+                          const unsigned char address3[6],
+                          uint8_t category) {
     memset(action, 0, sizeof(struct libwifi_action));
 
     action->frame_header.frame_control.type = TYPE_MANAGEMENT;
     action->frame_header.frame_control.subtype = SUBTYPE_ACTION;
     memcpy(&action->frame_header.addr1, receiver, 6);
     memcpy(&action->frame_header.addr2, transmitter, 6);
-    memcpy(&action->frame_header.addr3, transmitter, 6);
+    memcpy(&action->frame_header.addr3, address3, 6);
 
     action->frame_header.seq_control.sequence_number = (rand() % 4096);
 
@@ -63,15 +66,18 @@ int libwifi_create_action(struct libwifi_action *action, const unsigned char rec
     return 0;
 }
 
-int libwifi_create_action_no_ack(struct libwifi_action *action, const unsigned char receiver[6],
-                                 const unsigned char transmitter[6], uint8_t category) {
+int libwifi_create_action_no_ack(struct libwifi_action *action,
+                                 const unsigned char receiver[6],
+                                 const unsigned char transmitter[6],
+                                 const unsigned char address3[6],
+                                 uint8_t category) {
     memset(action, 0, sizeof(struct libwifi_action));
 
     action->frame_header.frame_control.type = TYPE_MANAGEMENT;
     action->frame_header.frame_control.subtype = SUBTYPE_ACTION_NOACK;
     memcpy(&action->frame_header.addr1, receiver, 6);
     memcpy(&action->frame_header.addr2, transmitter, 6);
-    memcpy(&action->frame_header.addr3, transmitter, 6);
+    memcpy(&action->frame_header.addr3, address3, 6);
 
     action->frame_header.seq_control.sequence_number = (rand() % 4096);
 
@@ -23,12 +23,13 @@
  * Create a detail for an action frame by supplying raw data and it's length.
  * New data can be added to an existing libwifi_action_detail.
  *
- * @param detail  A libwifi_action_detail struct
- * @param data    Raw data to be added to the libwifi_action_detail
+ * @param detail   A libwifi_action_detail struct
+ * @param data     Raw data to be added to the libwifi_action_detail
  * @param data_len Length of the raw data
- * @return Length of the action
+ * @return         Length of the action, or negative error
  */
-size_t libwifi_add_action_detail(struct libwifi_action_detail *detail, const unsigned char *data,
+size_t libwifi_add_action_detail(struct libwifi_action_detail *detail,
+                                 const unsigned char *data,
                                  size_t data_len);
 
 /**
@@ -44,13 +45,20 @@ void libwifi_free_action_detail(struct libwifi_action_detail *detail);
  * @param action      A new libwifi_action struct
  * @param receiver    The receiver MAC address
  * @param transmitter The transmitter MAC address
+ * @param address3    The address 3 frame field value, typically the BSSID
  * @param category    The action frame category
- * @return zero on success
+ * @return            Zero on success, or negative error
  */
-int libwifi_create_action(struct libwifi_action *action, const unsigned char receiver[6],
-                          const unsigned char transmitter[6], uint8_t category);
-int libwifi_create_action_no_ack(struct libwifi_action *action, const unsigned char receiver[6],
-                                 const unsigned char transmitter[6], uint8_t category);
+int libwifi_create_action(struct libwifi_action *action,
+                          const unsigned char receiver[6],
+                          const unsigned char transmitter[6],
+                          const unsigned char address3[6],
+                          uint8_t category);
+int libwifi_create_action_no_ack(struct libwifi_action *action,
+                                 const unsigned char receiver[6],
+                                 const unsigned char transmitter[6],
+                                 const unsigned char address3[6],
+                                 uint8_t category);
 
 /**
  * Get the length of a given libwifi_action
@@ -63,10 +71,10 @@ size_t libwifi_get_action_length(struct libwifi_action *action);
 /**
  * Dump a given libwifi_action to a raw buffer
  *
- * @param  action A used libwifi_action struct
- * @param  buf    A buffer receiver
+ * @param  action  A used libwifi_action struct
+ * @param  buf     A buffer receiver
  * @param  buf_len The length of the given buf
- * @return        Bytes written to the buf
+ * @return         Bytes written to the buf, or negative error
  */
 size_t libwifi_dump_action(struct libwifi_action *action, unsigned char *buf, size_t buf_len);
 
@@ -33,15 +33,18 @@ size_t libwifi_get_assoc_req_length(struct libwifi_assoc_req *assoc_req) {
  * The generated association request frame is made with sane defaults defined in common.h.
  * Two tagged parameters are also added to the association request: SSID and Channel.
  */
-int libwifi_create_assoc_req(struct libwifi_assoc_req *assoc_req, const unsigned char receiver[6],
-                             const unsigned char transmitter[6], const char *ssid, uint8_t channel) {
+int libwifi_create_assoc_req(struct libwifi_assoc_req *assoc_req,
+                             const unsigned char receiver[6],
+                             const unsigned char transmitter[6],
+                             const unsigned char address3[6],
+                             const char *ssid, uint8_t channel) {
     memset(assoc_req, 0, sizeof(struct libwifi_assoc_req));
 
     assoc_req->frame_header.frame_control.type = TYPE_MANAGEMENT;
     assoc_req->frame_header.frame_control.subtype = SUBTYPE_ASSOC_REQ;
     memcpy(&assoc_req->frame_header.addr1, receiver, 6);
     memcpy(&assoc_req->frame_header.addr2, transmitter, 6);
-    memcpy(&assoc_req->frame_header.addr3, receiver, 6);
+    memcpy(&assoc_req->frame_header.addr3, address3, 6);
     assoc_req->frame_header.seq_control.sequence_number = (rand() % 4096);
 
     assoc_req->fixed_parameters.capabilities_information = BYTESWAP16(LIBWIFI_DEFAULT_AP_CAPABS);
@@ -24,16 +24,44 @@
  * Create a new association request
  *
  * @param assoc_req   A new libwifi_assoc_req struct
- * @param receiver The receiver MAC address
+ * @param receiver    The receiver MAC address
  * @param transmitter The transmitter MAC address
+ * @param address3    The address 3 frame field value, typically the BSSID
  * @param ssid        The desired BSS SSID
  * @param channel     The desired channel
- * @param zero on success
+ * @param             Zero on success, or negative error
+ */
+int libwifi_create_assoc_req(struct libwifi_assoc_req *assoc_req,
+                             const unsigned char receiver[6],
+                             const unsigned char transmitter[6],
+                             const unsigned char address3[6],
+                             const char *ssid,
+                             uint8_t channel);
+
+/**
+ * Get the length of a given libwifi_assoc_req
+ *
+ * @param assoc_req A libwifi_assoc_req struct
+ * @return          Length of the given libwifi_assoc_req
  */
-int libwifi_create_assoc_req(struct libwifi_assoc_req *assoc_req, const unsigned char receiver[6],
-                             const unsigned char transmitter[6], const char *ssid, uint8_t channel);
 size_t libwifi_get_assoc_req_length(struct libwifi_assoc_req *assoc_req);
+
+/**
+ * Dump a libwifi_assoc_req into a raw format for packet injection.
+ *
+ * @param assoc_req A libwifi_assoc_req struct
+ * @param buf       The buffer to dump into
+ * @param buf_len   The length of the supplied buffer
+ * @param           The amount of bytes dumped, or negative error
+ */
 size_t libwifi_dump_assoc_req(struct libwifi_assoc_req *assoc_req, unsigned char *buf, size_t buf_len);
+
+
+/**
+ * Free any memory claimed by a libwifi_assoc_req back to the system.
+ *
+ * @param assoc_req A libwifi_assoc_req
+ */
 void libwifi_free_assoc_req(struct libwifi_assoc_req *assoc_req);
 
 #endif /* LIBWIFI_GEN_ASSOCREQUEST_H */
@@ -33,7 +33,8 @@
  */
 size_t libwifi_get_assoc_resp_length(struct libwifi_assoc_resp *assoc_resp) {
     return sizeof(struct libwifi_mgmt_unordered_frame_header) +
-           sizeof(struct libwifi_assoc_resp_fixed_parameters) + assoc_resp->tags.length;
+           sizeof(struct libwifi_assoc_resp_fixed_parameters) +
+           assoc_resp->tags.length;
 }
 
 /**
@@ -61,14 +62,18 @@ int libwifi_set_assoc_resp_channel(struct libwifi_assoc_resp *assoc_resp, uint8_
  * The generated association response frame is made with sane defaults defined in common.h and core/types.h.
  * Two tagged parameters are also added to the association response: Channel and Supported Rates.
  */
-int libwifi_create_assoc_resp(struct libwifi_assoc_resp *assoc_resp, const unsigned char receiver[6],
-                               const unsigned char transmitter[6], uint8_t channel) {
+int libwifi_create_assoc_resp(struct libwifi_assoc_resp *assoc_resp,
+                              const unsigned char receiver[6],
+                              const unsigned char transmitter[6],
+                              const unsigned char address3[6],
+                              uint8_t channel) {
     memset(assoc_resp, 0, sizeof(struct libwifi_assoc_resp));
 
     assoc_resp->frame_header.frame_control.type = TYPE_MANAGEMENT;
     assoc_resp->frame_header.frame_control.subtype = SUBTYPE_ASSOC_RESP;
     memcpy(&assoc_resp->frame_header.addr1, receiver, 6);
     memcpy(&assoc_resp->frame_header.addr2, transmitter, 6);
+    memcpy(&assoc_resp->frame_header.addr3, address3, 6);
 
     assoc_resp->fixed_parameters.capabilities_information = BYTESWAP16(LIBWIFI_DEFAULT_AP_CAPABS);
     assoc_resp->fixed_parameters.status_code = STATUS_SUCCESS;
@@ -22,7 +22,8 @@
  * Set the channel of a libwifi_assoc_resp.
  *
  * @param assoc_resp A libwifi_assoc_resp
- * @param channel The new channel
+ * @param channel    The new channel
+ * @return           Zero on success, or negative error
  */
 int libwifi_set_assoc_resp_channel(struct libwifi_assoc_resp *assoc_resp, uint8_t channel);
 
@@ -30,7 +31,7 @@ int libwifi_set_assoc_resp_channel(struct libwifi_assoc_resp *assoc_resp, uint8_
  * Calculate the length of a given libwifi_assoc_resp
  *
  * @param assoc_resp A libwifi_assoc_resp
- * @return The length of the given assoc_resp
+ * @return           The length of the given assoc_resp, or negative error
  */
 size_t libwifi_get_assoc_resp_length(struct libwifi_assoc_resp *assoc_resp);
 
@@ -40,22 +41,26 @@ size_t libwifi_get_assoc_resp_length(struct libwifi_assoc_resp *assoc_resp);
  * A generated libwifi assoc_resp can be "dumped" into a buffer for packet injection
  * via the libwifi_dump_assoc_resp.
  *
- * @param assoc_resp A libwifi_assoc_resp
- * @param receiver The receiver MAC address, aka address 1
+ * @param assoc_resp  A libwifi_assoc_resp
+ * @param receiver    The receiver MAC address, aka address 1
  * @param transmitter The source MAC address, aka address 2
- * @param channel The desired channel of the assoc_resp
- *
+ * @param address3    The address 3 frame field value, typically the BSSID
+ * @param channel     The desired channel of the assoc_resp
+ * @return            Zero on success, or negative error
  */
-int libwifi_create_assoc_resp(struct libwifi_assoc_resp *assoc_resp, const unsigned char receiver[6],
-                               const unsigned char transmitter[6], uint8_t channel);
+int libwifi_create_assoc_resp(struct libwifi_assoc_resp *assoc_resp,
+                              const unsigned char receiver[6],
+                              const unsigned char transmitter[6],
+                              const unsigned char address3[6],
+                              uint8_t channel);
 
 /**
  * Dump a libwifi_assoc_resp into a raw format for packet injection.
  *
  * @param assoc_resp A libwifi_assoc_resp
- * @param buf The output buffer for the frame data
- * @param buf_len The length of the output buffer
- * @return The length of the dumped assoc_resp
+ * @param buf        The output buffer for the frame data
+ * @param buf_len    The length of the output buffer
+ * @return           The length of the dumped assoc_resp, or negative error
  */
 size_t libwifi_dump_assoc_resp(struct libwifi_assoc_resp *assoc_resp, unsigned char *buf, size_t buf_len);
 
@@ -18,15 +18,17 @@
 #include <stdlib.h>
 #include <string.h>
 
-int libwifi_create_atim(struct libwifi_atim *atim, const unsigned char transmitter[6],
-                        const unsigned char receiver[6], const unsigned char bssid[6]) {
+int libwifi_create_atim(struct libwifi_atim *atim,
+                        const unsigned char transmitter[6],
+                        const unsigned char receiver[6],
+                        const unsigned char address3[6]) {
     memset(atim, 0, sizeof(struct libwifi_atim));
 
     atim->frame_header.frame_control.type = TYPE_MANAGEMENT;
     atim->frame_header.frame_control.subtype = SUBTYPE_ATIM;
     memcpy(&atim->frame_header.addr1, transmitter, 6);
     memcpy(&atim->frame_header.addr2, receiver, 6);
-    memcpy(&atim->frame_header.addr3, bssid, 6);
+    memcpy(&atim->frame_header.addr3, address3, 6);
     atim->frame_header.frame_control.flags.power_mgmt = 1;
     atim->frame_header.duration = (rand() % 4096);
     atim->frame_header.seq_control.sequence_number = (rand() % 4096);
@@ -18,7 +18,18 @@
 
 #include "../../core/frame/management/atim.h"
 
-int libwifi_create_atim(struct libwifi_atim *atim, const unsigned char transmitter[6],
-                        const unsigned char receiver[6], const unsigned char bssid[6]);
+/**
+ * Generate a populated ATIM frame.
+ *
+ * @param atim        A new libwifi_atim struct
+ * @param transmitter The transmitter address, aka address 1
+ * @param receiver    The receiver address, aka address 2
+ * @param address3    The address 3 frame value, typically the BSSID
+ * @return            Zero on success, or negative error
+*/
+int libwifi_create_atim(struct libwifi_atim *atim,
+                        const unsigned char transmitter[6],
+                        const unsigned char receiver[6],
+                        const unsigned char address3[6]);
 
 #endif /* LIBWIFI_GEN_ATIM_H */
@@ -32,16 +32,20 @@ size_t libwifi_get_auth_length(struct libwifi_auth *auth) {
 /**
  * The generated authentication frame is made with sane defaults defined in common.h.
  */
-int libwifi_create_auth(struct libwifi_auth *auth, const unsigned char receiver[6],
-                         const unsigned char transmitter[6], uint16_t algorithm_number,
-                         uint16_t transaction_sequence, uint16_t status_code) {
+int libwifi_create_auth(struct libwifi_auth *auth,
+                        const unsigned char receiver[6],
+                        const unsigned char transmitter[6],
+                        const unsigned char address3[6],
+                        uint16_t algorithm_number,
+                        uint16_t transaction_sequence,
+                        uint16_t status_code) {
     memset(auth, 0, sizeof(struct libwifi_auth));
 
     auth->frame_header.frame_control.type = TYPE_MANAGEMENT;
     auth->frame_header.frame_control.subtype = SUBTYPE_AUTH;
     memcpy(&auth->frame_header.addr1, receiver, 6);
     memcpy(&auth->frame_header.addr2, transmitter, 6);
-    memcpy(&auth->frame_header.addr3, transmitter, 6);
+    memcpy(&auth->frame_header.addr3, address3, 6);
     auth->frame_header.seq_control.sequence_number = (rand() % 4096);
 
     auth->fixed_parameters.algorithm_number = algorithm_number;
@@ -24,7 +24,7 @@
  * Calculate the length of a given libwifi_auth
  *
  * @param auth A libwifi_auth
- * @return The length of the given auth
+ * @return     The length of the given auth
  */
 size_t libwifi_get_auth_length(struct libwifi_auth *auth);
 
@@ -34,23 +34,30 @@ size_t libwifi_get_auth_length(struct libwifi_auth *auth);
  * A generated libwifi auth can be "dumped" into a buffer for packet injection
  * via the libwifi_dump_auth.
  *
- * @param auth A libwifi_auth
- * @param receiver The receiver MAC address, aka address 1
- * @param transmitter The source MAC address, aka address 2
- * @param algorithm_number Algorithm type to use
- *
+ * @param auth                 A libwifi_auth
+ * @param receiver             The receiver MAC address, aka address 1
+ * @param transmitter          The source MAC address, aka address 2
+ * @param address3             The address 3 frame field value, typically the BSSID
+ * @param algorithm_number     Algorithm type to use, as defined in the IEEE802.11 spec
+ * @param transaction_sequence Transaction sequence value to use
+ * @param status_code          Status code to use, as defined in the IEEE802.11 spec
+ * @return                     Zero on success, or negative error
  */
-int libwifi_create_auth(struct libwifi_auth *auth, const unsigned char receiver[6],
-                         const unsigned char transmitter[6], uint16_t algorithm_number,
-                         uint16_t transaction_sequence, uint16_t status_code);
+int libwifi_create_auth(struct libwifi_auth *auth,
+                        const unsigned char receiver[6],
+                        const unsigned char transmitter[6],
+                        const unsigned char address3[6],
+                        uint16_t algorithm_number,
+                        uint16_t transaction_sequence,
+                        uint16_t status_code);
 
 /**
  * Dump a libwifi_auth into a raw format for packet injection.
  *
- * @param auth A libwifi_auth
- * @param buf The output buffer for the frame data
+ * @param auth    A libwifi_auth
+ * @param buf     The output buffer for the frame data
  * @param buf_len The length of the output buffer
- * @return The length of the dumped auth
+ * @return        The length of the dumped auth, or negative error
  */
 size_t libwifi_dump_auth(struct libwifi_auth *auth, unsigned char *buf, size_t buf_len);
 
@@ -32,7 +32,8 @@
  */
 size_t libwifi_get_beacon_length(struct libwifi_beacon *beacon) {
     return sizeof(struct libwifi_mgmt_unordered_frame_header) +
-           sizeof(struct libwifi_beacon_fixed_parameters) + beacon->tags.length;
+           sizeof(struct libwifi_beacon_fixed_parameters) +
+           beacon->tags.length;
 }
 
 /**
@@ -75,12 +76,12 @@ int libwifi_set_beacon_channel(struct libwifi_beacon *beacon, uint8_t channel) {
 
 /**
  * The generated beacon frame is made with sane defaults defined in common.h.
- * Three tagged parameters are also added to the beacon: SSID, Channel and Supported Rates.
+ * Two tagged parameters are also added to the beacon: SSID and Channel.
  */
 int libwifi_create_beacon(struct libwifi_beacon *beacon,
                           const unsigned char receiver[6],
                           const unsigned char transmitter[6],
-                          const unsigned char bssid[6],
+                          const unsigned char address3[6],
                           const char *ssid,
                           uint8_t channel) {
     memset(beacon, 0, sizeof(struct libwifi_beacon));
@@ -89,18 +90,19 @@ int libwifi_create_beacon(struct libwifi_beacon *beacon,
     beacon->frame_header.frame_control.subtype = SUBTYPE_BEACON;
     memcpy(&beacon->frame_header.addr1, receiver, 6);
     memcpy(&beacon->frame_header.addr2, transmitter, 6);
-    memcpy(&beacon->frame_header.addr3, bssid, 6);
+    memcpy(&beacon->frame_header.addr3, address3, 6);
     beacon->frame_header.seq_control.sequence_number = (rand() % 4096);
 
     beacon->fixed_parameters.timestamp = BYTESWAP64(libwifi_get_epoch());
     beacon->fixed_parameters.beacon_interval = BYTESWAP16(LIBWIFI_DEFAULT_BEACON_INTERVAL);
     beacon->fixed_parameters.capabilities_information = BYTESWAP16(LIBWIFI_DEFAULT_AP_CAPABS);
 
-    libwifi_set_beacon_ssid(beacon, ssid);
-    libwifi_set_beacon_channel(beacon, channel);
+    int ret = libwifi_set_beacon_ssid(beacon, ssid);
+    if (ret != 0) {
+        return ret;
+    }
 
-    const unsigned char supported_rates[] = LIBWIFI_DEFAULT_SUPP_RATES;
-    int ret = libwifi_quick_add_tag(&beacon->tags, TAG_SUPP_RATES, supported_rates, sizeof(supported_rates) - 1);
+    ret = libwifi_set_beacon_channel(beacon, channel);
 
     return ret;
 }
@@ -22,23 +22,25 @@
  * Set the SSID of a struct libwifi_beacon.
  *
  * @param beacon A struct libwifi_beacon
- * @param ssid The new SSID
+ * @param ssid   The new SSID
+ * @return       Zero on success, or negative error
  */
 int libwifi_set_beacon_ssid(struct libwifi_beacon *beacon, const char *ssid);
 
 /**
  * Set the channel of a struct libwifi_beacon.
  *
- * @param beacon A struct libwifi_beacon
+ * @param beacon  A struct libwifi_beacon
  * @param channel The new channel
+ * @return        Zero on success, or negative error
  */
 int libwifi_set_beacon_channel(struct libwifi_beacon *beacon, uint8_t channel);
 
 /**
  * Calculate the length of a given struct libwifi_beacon
  *
- * @param beacon A struct libwifi_beacon
- * @return The length of the given beacon
+ * @param beacon A libwifi_beacon struct
+ * @return       The length of the given beacon, or negative error
  */
 size_t libwifi_get_beacon_length(struct libwifi_beacon *beacon);
 
@@ -48,28 +50,28 @@ size_t libwifi_get_beacon_length(struct libwifi_beacon *beacon);
  * A generated libwifi beacon can be "dumped" into a buffer for packet injection
  * via the libwifi_dump_beacon.
  *
- * @param beacon A struct libwifi_beacon
- * @param receiver The receiver MAC address, aka address 1
+ * @param beacon      A struct libwifi_beacon
+ * @param receiver    The receiver MAC address, aka address 1
  * @param transmitter The source MAC address, aka address 2
- * @param bssid The BSSID MAC address, aka address 3
- * @param ssid The SSID of the beacon. Maximum length is 32 characters
- * @param channel The desired channel of the beacon
- *
+ * @param address3    The address 3 frame field value, typically the BSSID
+ * @param ssid        The SSID of the beacon. Maximum length is 32 characters
+ * @param channel     The desired channel of the beacon
+ * @return            Zero on success, or negative error
  */
 int libwifi_create_beacon(struct libwifi_beacon *beacon,
                           const unsigned char receiver[6],
                           const unsigned char transmitter[6],
-                          const unsigned char bssid[6],
+                          const unsigned char address3[6],
                           const char *ssid,
                           uint8_t channel);
 
 /**
  * Dump a struct libwifi_beacon into a raw format for packet injection.
  *
- * @param beacon A struct libwifi_beacon
- * @param buf The output buffer for the frame data
+ * @param beacon  A struct libwifi_beacon
+ * @param buf     The output buffer for the frame data
  * @param buf_len The length of the output buffer
- * @return The length of the dumped beacon
+ * @return        The length of the dumped beacon, or negative error
  */
 size_t libwifi_dump_beacon(struct libwifi_beacon *beacon, unsigned char *buf, size_t buf_len);
 
@@ -33,15 +33,18 @@ size_t libwifi_get_deauth_length(struct libwifi_deauth *deauth) {
  * The generated deauthentication frame contains only the supplied receiver, transmitter and reason_code by
  * default.
  */
-int libwifi_create_deauth(struct libwifi_deauth *deauth, const unsigned char receiver[6],
-                          const unsigned char transmitter[6], uint16_t reason_code) {
+int libwifi_create_deauth(struct libwifi_deauth *deauth,
+                          const unsigned char receiver[6],
+                          const unsigned char transmitter[6],
+                          const unsigned char address3[6],
+                          uint16_t reason_code) {
     memset(deauth, 0, sizeof(struct libwifi_deauth));
 
     deauth->frame_header.frame_control.type = TYPE_MANAGEMENT;
     deauth->frame_header.frame_control.subtype = SUBTYPE_DEAUTH;
     memcpy(&deauth->frame_header.addr1, receiver, 6);
     memcpy(&deauth->frame_header.addr2, transmitter, 6);
-    memcpy(&deauth->frame_header.addr3, transmitter, 6);
+    memcpy(&deauth->frame_header.addr3, address3, 6);
 
     deauth->frame_header.seq_control.sequence_number = (rand() % 4096);
 
@@ -24,7 +24,7 @@
  * Calculate the length of a given libwifi_deauth
  *
  * @param deauth A libwifi_deauth
- * @return The length of the given deauth
+ * @return       The length of the given deauth
  */
 size_t libwifi_get_deauth_length(struct libwifi_deauth *deauth);
 
@@ -34,22 +34,26 @@ size_t libwifi_get_deauth_length(struct libwifi_deauth *deauth);
  * A generated libwifi deauth can be "dumped" into a buffer for packet injection
  * via the libwifi_dump_deauth.
  *
- * @param deauth A libwifi_deauth
- * @param receiver The receiver MAC address, aka address 1
+ * @param deauth      A libwifi_deauth
+ * @param receiver    The receiver MAC address, aka address 1
  * @param transmitter The source MAC address, aka address 2
+ * @param address3    The address 3 frame field value, typically the BSSID
  * @param reason_code The deauth reason code
- *
+ * @return            Zero on success, or negative error
  */
-int libwifi_create_deauth(struct libwifi_deauth *deauth, const unsigned char receiver[6],
-                          const unsigned char transmitter[6], uint16_t reason_code);
+int libwifi_create_deauth(struct libwifi_deauth *deauth,
+                          const unsigned char receiver[6],
+                          const unsigned char transmitter[6],
+                          const unsigned char address3[6],
+                          uint16_t reason_code);
 
 /**
  * Dump a libwifi_deauth into a raw format for packet injection.
  *
- * @param deauth A libwifi_deauth
- * @param buf The output buffer for the frame data
+ * @param deauth  A libwifi_deauth
+ * @param buf     The output buffer for the frame data
  * @param buf_len The length of the output buffer
- * @return The length of the dumped deauth
+ * @return        The length of the dumped deauth, or negative error
  */
 size_t libwifi_dump_deauth(struct libwifi_deauth *deauth, unsigned char *buf, size_t buf_len);
 
@@ -33,15 +33,18 @@ size_t libwifi_get_disassoc_length(struct libwifi_disassoc *disassoc) {
  * The generated disassociation frame contains only the supplied receiver, transmitter and reason_code by
  * default.
  */
-int libwifi_create_disassoc(struct libwifi_disassoc *disassoc, const unsigned char receiver[6],
-                             const unsigned char transmitter[6], uint16_t reason_code) {
+int libwifi_create_disassoc(struct libwifi_disassoc *disassoc,
+                            const unsigned char receiver[6],
+                            const unsigned char transmitter[6],
+                            const unsigned char address3[6],
+                            uint16_t reason_code) {
     memset(disassoc, 0, sizeof(struct libwifi_disassoc));
 
     disassoc->frame_header.frame_control.type = TYPE_MANAGEMENT;
     disassoc->frame_header.frame_control.subtype = SUBTYPE_DISASSOC;
     memcpy(&disassoc->frame_header.addr1, receiver, 6);
     memcpy(&disassoc->frame_header.addr2, transmitter, 6);
-    memcpy(&disassoc->frame_header.addr3, transmitter, 6);
+    memcpy(&disassoc->frame_header.addr3, address3, 6);
 
     disassoc->frame_header.seq_control.sequence_number = (rand() % 4096);
 
@@ -24,7 +24,7 @@
  * Calculate the length of a given libwifi_disassoc
  *
  * @param disassoc A libwifi_disassoc
- * @return The length of the given disassoc
+ * @return         The length of the given disassoc, or negative error
  */
 size_t libwifi_get_disassoc_length(struct libwifi_disassoc *disassoc);
 
@@ -37,19 +37,23 @@ size_t libwifi_get_disassoc_length(struct libwifi_disassoc *disassoc);
  * @param disassoc A libwifi_disassoc
  * @param receiver The receiver MAC address, aka address 1
  * @param transmitter The source MAC address, aka address 2
+ * @param address3 The address 3 frame field value, typically the BSSID
  * @param reason_code The disassoc reason code
- *
+ * @return zero
  */
-int libwifi_create_disassoc(struct libwifi_disassoc *disassoc, const unsigned char receiver[6],
-                             const unsigned char transmitter[6], uint16_t reason_code);
+int libwifi_create_disassoc(struct libwifi_disassoc *disassoc,
+                            const unsigned char receiver[6],
+                            const unsigned char transmitter[6],
+                            const unsigned char address3[6],
+                            uint16_t reason_code);
 
 /**
  * Dump a libwifi_disassoc into a raw format for packet injection.
  *
  * @param disassoc A libwifi_disassoc
- * @param buf The output buffer for the frame data
- * @param buf_len The length of the output buffer
- * @return The length of the dumped disassoc
+ * @param buf      The output buffer for the frame data
+ * @param buf_len  The length of the output buffer
+ * @return         The length of the dumped disassoc, or negative error
  */
 size_t libwifi_dump_disassoc(struct libwifi_disassoc *disassoc, unsigned char *buf, size_t buf_len);
 
@@ -31,16 +31,19 @@ size_t libwifi_get_probe_req_length(struct libwifi_probe_req *probe_req) {
  * The generated probe request frame is made with sane defaults defined in common.h.
  * Two tagged parameters are also added to the beacon: SSID and Channel.
  */
-int libwifi_create_probe_req(struct libwifi_probe_req *probe_req, const unsigned char receiver[6],
-                              const unsigned char transmitter[6], const unsigned char bssid[6],
-                              const char *ssid, uint8_t channel) {
+int libwifi_create_probe_req(struct libwifi_probe_req *probe_req,
+                             const unsigned char receiver[6],
+                             const unsigned char transmitter[6],
+                             const unsigned char address3[6],
+                             const char *ssid,
+                             uint8_t channel) {
     memset(probe_req, 0, sizeof(struct libwifi_probe_req));
 
     probe_req->frame_header.frame_control.type = TYPE_MANAGEMENT;
     probe_req->frame_header.frame_control.subtype = SUBTYPE_PROBE_REQ;
     memcpy(&probe_req->frame_header.addr1, receiver, 6);
     memcpy(&probe_req->frame_header.addr2, transmitter, 6);
-    memcpy(&probe_req->frame_header.addr3, bssid, 6);
+    memcpy(&probe_req->frame_header.addr3, address3, 6);
     probe_req->frame_header.seq_control.sequence_number = (rand() % 4096);
 
     int ret = libwifi_quick_add_tag(&probe_req->tags, TAG_SSID, (const unsigned char *) ssid, strlen(ssid));
@@ -24,7 +24,7 @@
  * Calculate the length of a given libwifi_probe_req
  *
  * @param probe_req A libwifi_probe_req
- * @return The length of the given probe_req
+ * @return          The length of the given probe_req, or negative error
  */
 size_t libwifi_get_probe_req_length(struct libwifi_probe_req *probe_req);
 
@@ -34,23 +34,28 @@ size_t libwifi_get_probe_req_length(struct libwifi_probe_req *probe_req);
  * A generated libwifi probe_req can be "dumped" into a buffer for packet injection
  * via the libwifi_dump_probe_req.
  *
- * @param probe_req A libwifi_probe_req
- * @param receiver The receiver MAC address, aka address 1
+ * @param probe_req   A libwifi_probe_req
+ * @param receiver    The receiver MAC address, aka address 1
  * @param transmitter The source MAC address, aka address 2
- * @param reason_code The probe_req reason code
- *
+ * @param address3    The address 3 frame field value, typically the BSSID
+ * @param ssid        The probe request SSID
+ * @param channel     The probe request channel
+ * @return            Zero on success, or negative error
  */
-int libwifi_create_probe_req(struct libwifi_probe_req *probe_req, const unsigned char receiver[6],
-                              const unsigned char transmitter[6], const unsigned char bssid[6],
-                              const char *ssid, uint8_t channel);
+int libwifi_create_probe_req(struct libwifi_probe_req *probe_req,
+                             const unsigned char receiver[6],
+                             const unsigned char transmitter[6],
+                             const unsigned char address3[6],
+                             const char *ssid,
+                             uint8_t channel);
 
 /**
  * Dump a libwifi_probe_req into a raw format for packet injection.
  *
  * @param probe_req A libwifi_probe_req
- * @param buf The output buffer for the frame data
- * @param buf_len The length of the output buffer
- * @return The length of the dumped probe_req
+ * @param buf       The output buffer for the frame data
+ * @param buf_len   The length of the output buffer
+ * @return          The length of the dumped probe_req, or negative error
  */
 size_t libwifi_dump_probe_req(struct libwifi_probe_req *probe_req, unsigned char *buf, size_t buf_len);
 
@@ -32,7 +32,8 @@
  */
 size_t libwifi_get_probe_resp_length(struct libwifi_probe_resp *probe_resp) {
     return sizeof(struct libwifi_mgmt_unordered_frame_header) +
-           sizeof(struct libwifi_probe_resp_fixed_parameters) + probe_resp->tags.length;
+           sizeof(struct libwifi_probe_resp_fixed_parameters) +
+           probe_resp->tags.length;
 }
 
 /**
@@ -48,7 +49,7 @@ int libwifi_set_probe_resp_ssid(struct libwifi_probe_resp *probe_resp, const cha
         }
     }
 
-    ret = libwifi_quick_add_tag(&probe_resp->tags, TAG_SSID, (void *) ssid, strlen(ssid));
+    ret = libwifi_quick_add_tag(&probe_resp->tags, TAG_SSID, (const unsigned char *) ssid, strlen(ssid));
 
     return ret;
 }
@@ -75,16 +76,21 @@ int libwifi_set_probe_resp_channel(struct libwifi_probe_resp *probe_resp, uint8_
 
 /**
  * The generated probe response frame is made with sane defaults defined in common.h.
- * Three tagged parameters are also added to the probe response: SSID, Channel and Supported Rates.
+ * Two tagged parameters are also added to the probe response: SSID and Channel.
  */
-int libwifi_create_probe_resp(struct libwifi_probe_resp *probe_resp, const unsigned char receiver[6],
-                               const unsigned char transmitter[6], const char *ssid, uint8_t channel) {
+int libwifi_create_probe_resp(struct libwifi_probe_resp *probe_resp,
+                              const unsigned char receiver[6],
+                              const unsigned char transmitter[6],
+                              const unsigned char address3[6],
+                              const char *ssid,
+                              uint8_t channel) {
     memset(probe_resp, 0, sizeof(struct libwifi_probe_resp));
 
     probe_resp->frame_header.frame_control.type = TYPE_MANAGEMENT;
     probe_resp->frame_header.frame_control.subtype = SUBTYPE_PROBE_RESP;
     memcpy(&probe_resp->frame_header.addr1, receiver, 6);
     memcpy(&probe_resp->frame_header.addr2, transmitter, 6);
+    memcpy(&probe_resp->frame_header.addr3, address3, 6);
 
     probe_resp->frame_header.seq_control.sequence_number = (rand() % 4096);
     probe_resp->fixed_parameters.timestamp = BYTESWAP64(libwifi_get_epoch());
@@ -98,12 +104,6 @@ int libwifi_create_probe_resp(struct libwifi_probe_resp *probe_resp, const unsig
     }
 
     ret = libwifi_set_probe_resp_channel(probe_resp, channel);
-    if (ret != 0) {
-        return ret;
-    }
-
-    const unsigned char supported_rates[] = LIBWIFI_DEFAULT_SUPP_RATES;
-    ret = libwifi_quick_add_tag(&probe_resp->tags, TAG_SUPP_RATES, supported_rates, sizeof(supported_rates) - 1);
 
     return ret;
 }
@@ -21,24 +21,26 @@
 /**
  * Set the SSID of a libwifi_probe_resp.
  *
- * @param probe_resp A libwifi_probe_resp
- * @param ssid The new SSID
+ * @param probe_resp A libwifi_probe_resp struct
+ * @param ssid       The new SSID
+ * @return           Zero on success, or negative error
  */
 int libwifi_set_probe_resp_ssid(struct libwifi_probe_resp *probe_resp, const char *ssid);
 
 /**
  * Set the channel of a libwifi_probe_resp.
  *
- * @param probe_resp A libwifi_probe_resp
- * @param channel The new channel
+ * @param probe_resp A libwifi_probe_resp struct
+ * @param channel    The new channel
+ * @return           Zero on success, or negative error
  */
 int libwifi_set_probe_resp_channel(struct libwifi_probe_resp *probe_resp, uint8_t channel);
 
 /**
  * Calculate the length of a given libwifi_probe_resp
  *
- * @param probe_resp A libwifi_probe_resp
- * @return The length of the given probe_resp
+ * @param probe_resp A libwifi_probe_resp struct
+ * @return           The length of the given probe_resp, or negative error
  */
 size_t libwifi_get_probe_resp_length(struct libwifi_probe_resp *probe_resp);
 
@@ -48,23 +50,28 @@ size_t libwifi_get_probe_resp_length(struct libwifi_probe_resp *probe_resp);
  * A generated libwifi probe_resp can be "dumped" into a buffer for packet injection
  * via the libwifi_dump_probe_resp.
  *
- * @param probe_resp A libwifi_probe_resp
- * @param receiver The receiver MAC address, aka address 1
+ * @param probe_resp  A libwifi_probe_resp
+ * @param receiver    The receiver MAC address, aka address 1
  * @param transmitter The source MAC address, aka address 2
- * @param ssid The SSID of the probe_resp. Maximum length is 32 characters
- * @param channel The desired channel of the probe_resp
- *
+ * @param address3    The address 3 frame field value, typically the BSSID
+ * @param ssid        The SSID of the probe_resp. Maximum length is 32 characters
+ * @param channel     The desired channel of the probe_resp
+ * @return            Zero on success, or negative error
  */
-int libwifi_create_probe_resp(struct libwifi_probe_resp *probe_resp, const unsigned char receiver[6],
-                               const unsigned char transmitter[6], const char *ssid, uint8_t channel);
+int libwifi_create_probe_resp(struct libwifi_probe_resp *probe_resp,
+                              const unsigned char receiver[6],
+                              const unsigned char transmitter[6],
+                              const unsigned char address3[6],
+                              const char *ssid,
+                              uint8_t channel);
 
 /**
  * Dump a libwifi_probe_resp into a raw format for packet injection.
  *
  * @param probe_resp A libwifi_probe_resp
- * @param buf The output buffer for the frame data
- * @param buf_len The length of the output buffer
- * @return The length of the dumped probe_resp
+ * @param buf        The output buffer for the frame data
+ * @param buf_len    The length of the output buffer
+ * @return           The length of the dumped probe_resp, or negative error
  */
 size_t libwifi_dump_probe_resp(struct libwifi_probe_resp *probe_resp, unsigned char *buf, size_t buf_len);
 
@@ -26,23 +26,28 @@
  */
 size_t libwifi_get_reassoc_req_length(struct libwifi_reassoc_req *reassoc_req) {
     return sizeof(struct libwifi_mgmt_unordered_frame_header) +
-           sizeof(struct libwifi_reassoc_req_fixed_parameters) + reassoc_req->tags.length;
+           sizeof(struct libwifi_reassoc_req_fixed_parameters) +
+           reassoc_req->tags.length;
 }
 
 /**
  * The generated reassociation request frame is made with sane defaults defined in common.h.
  * Two tagged parameters are also added to the reassociation frame: SSID and Channel
  */
-int libwifi_create_reassoc_req(struct libwifi_reassoc_req *reassoc_req, const unsigned char receiver[6],
-                               const unsigned char transmitter[6], const unsigned char current_ap[6],
-                               const char *ssid, uint8_t channel) {
+int libwifi_create_reassoc_req(struct libwifi_reassoc_req *reassoc_req,
+                               const unsigned char receiver[6],
+                               const unsigned char transmitter[6],
+                               const unsigned char address3[6],
+                               const unsigned char current_ap[6],
+                               const char *ssid,
+                               uint8_t channel) {
     memset(reassoc_req, 0, sizeof(struct libwifi_reassoc_req));
 
     reassoc_req->frame_header.frame_control.type = TYPE_MANAGEMENT;
     reassoc_req->frame_header.frame_control.subtype = SUBTYPE_REASSOC_REQ;
     memcpy(&reassoc_req->frame_header.addr1, receiver, 6);
     memcpy(&reassoc_req->frame_header.addr2, transmitter, 6);
-    memcpy(&reassoc_req->frame_header.addr3, receiver, 6);
+    memcpy(&reassoc_req->frame_header.addr3, address3, 6);
     reassoc_req->frame_header.seq_control.sequence_number = (rand() % 4096);
 
     reassoc_req->fixed_parameters.capabilities_information = BYTESWAP16(LIBWIFI_DEFAULT_AP_CAPABS);
@@ -20,11 +20,48 @@
 #include "../../core/frame/management/common.h"
 #include "../../core/frame/management/reassoc_request.h"
 
-int libwifi_create_reassoc_req(struct libwifi_reassoc_req *reassoc_req, const unsigned char receiver[6],
-                               const unsigned char transmitter[6], const unsigned char current_ap[6],
+/**
+ * Create a new libwifi reassociation request
+ *
+ * @param reassoc_req   A new libwifi_reassoc_req struct
+ * @param receiver      The receiver MAC address
+ * @param transmitter   The transmitter MAC address
+ * @param address3      The address 3 frame field value, typically the BSSID
+ * @param current_ap    The current AP BSSID
+ * @param ssid          The desired BSS SSID
+ * @param channel       The desired channel
+ * @return              Zero on success, or negative error
+ */
+int libwifi_create_reassoc_req(struct libwifi_reassoc_req *reassoc_req,
+                               const unsigned char receiver[6],
+                               const unsigned char transmitter[6],
+                               const unsigned char address3[6],
+                               const unsigned char current_ap[6],
                                const char *ssid, uint8_t channel);
+
+/**
+ * Get the length of a given libwifi_reassoc_req
+ *
+ * @param reassoc_req A libwifi_reassoc_req struct
+ * @return            The length of the given libwifi_reassoc_req, or negative error
+ */
 size_t libwifi_get_reassoc_req_length(struct libwifi_reassoc_req *reassoc_req);
+
+/**
+ * Dump a libwifi_reassoc_req into a raw format for packet injection.
+ *
+ * @param reassoc_req A libwifi_reassoc_req struct
+ * @param buf         The buffer to dump into
+ * @param buf_len     The length of the supplied buffer
+ * @return            The amount of bytes dumped, or negative error
+ */
 size_t libwifi_dump_reassoc_req(struct libwifi_reassoc_req *reassoc_req, unsigned char *buf, size_t buf_len);
+
+/**
+ * Free any memory claimed by a libwifi_reassoc_req back to the system.
+ *
+ * @param reassoc_req A libwifi_reassoc_req
+ */
 void libwifi_free_reassoc_req(struct libwifi_reassoc_req *reassoc_req);
 
 #endif /* LIBWIFI_GEN_REASSOCREQUEST_H */
@@ -33,7 +33,8 @@
  */
 size_t libwifi_get_reassoc_resp_length(struct libwifi_reassoc_resp *reassoc_resp) {
     return sizeof(struct libwifi_mgmt_unordered_frame_header) +
-           sizeof(struct libwifi_reassoc_resp_fixed_parameters) + reassoc_resp->tags.length;
+           sizeof(struct libwifi_reassoc_resp_fixed_parameters) +
+           reassoc_resp->tags.length;
 }
 
 /**
@@ -58,28 +59,26 @@ int libwifi_set_reassoc_resp_channel(struct libwifi_reassoc_resp *reassoc_resp,
 
 /**
  * The generated reassoc_resp frame is made with sane defaults defined in common.h.
- * Three tagged parameters are also added to the reassoc_resp: SSID, Channel and Supported Rates.
+ * One tagged parameters is also added to the reassoc_resp: Channel.
  */
-int libwifi_create_reassoc_resp(struct libwifi_reassoc_resp *reassoc_resp, const unsigned char receiver[6],
-                                 const unsigned char transmitter[6], uint8_t channel) {
+int libwifi_create_reassoc_resp(struct libwifi_reassoc_resp *reassoc_resp,
+                                const unsigned char receiver[6],
+                                const unsigned char transmitter[6],
+                                const unsigned char address3[6],
+                                uint8_t channel) {
     memset(reassoc_resp, 0, sizeof(struct libwifi_reassoc_resp));
 
     reassoc_resp->frame_header.frame_control.type = TYPE_MANAGEMENT;
     reassoc_resp->frame_header.frame_control.subtype = SUBTYPE_REASSOC_RESP;
     memcpy(&reassoc_resp->frame_header.addr1, receiver, 6);
     memcpy(&reassoc_resp->frame_header.addr2, transmitter, 6);
+    memcpy(&reassoc_resp->frame_header.addr3, address3, 6);
 
     reassoc_resp->fixed_parameters.capabilities_information = BYTESWAP16(LIBWIFI_DEFAULT_AP_CAPABS);
     reassoc_resp->fixed_parameters.status_code = STATUS_SUCCESS;
     reassoc_resp->fixed_parameters.association_id = rand() % 4096;
 
     int ret = libwifi_set_reassoc_resp_channel(reassoc_resp, channel);
-    if (ret != 0) {
-        return ret;
-    }
-
-    const unsigned char supported_rates[] = LIBWIFI_DEFAULT_SUPP_RATES;
-    ret = libwifi_quick_add_tag(&reassoc_resp->tags, TAG_SUPP_RATES, supported_rates, sizeof(supported_rates) - 1);
 
     return ret;
 }
@@ -22,7 +22,8 @@
  * Set the channel of a libwifi_reassoc_resp.
  *
  * @param reassoc_resp A libwifi_reassoc_resp
- * @param channel The new channel
+ * @param channel      The desired channel
+ * @return             Zero on success, or negative error
  */
 int libwifi_set_reassoc_resp_channel(struct libwifi_reassoc_resp *reassoc_resp, uint8_t channel);
 
@@ -30,7 +31,7 @@ int libwifi_set_reassoc_resp_channel(struct libwifi_reassoc_resp *reassoc_resp,
  * Calculate the length of a given libwifi_reassoc_resp
  *
  * @param reassoc_resp A libwifi_reassoc_resp
- * @return The length of the given reassoc_resp
+ * @return             The length of the given reassoc_resp, or negative error
  */
 size_t libwifi_get_reassoc_resp_length(struct libwifi_reassoc_resp *reassoc_resp);
 
@@ -41,13 +42,17 @@ size_t libwifi_get_reassoc_resp_length(struct libwifi_reassoc_resp *reassoc_resp
  * via the libwifi_dump_reassoc_resp.
  *
  * @param reassoc_resp A libwifi_reassoc_resp
- * @param receiver The receiver MAC address, aka address 1
- * @param transmitter The source MAC address, aka address 2
- * @param channel The desired channel of the reassoc_resp
- *
+ * @param receiver     The receiver MAC address, aka address 1
+ * @param transmitter  The source MAC address, aka address 2
+ * @param address3     The address 3 frame field value, typically the BSSID
+ * @param channel      The desired channel of the reassoc_resp
+ * @return             Zero on success, or negative error
  */
-int libwifi_create_reassoc_resp(struct libwifi_reassoc_resp *reassoc_resp, const unsigned char receiver[6],
-                                 const unsigned char transmitter[6], uint8_t channel);
+int libwifi_create_reassoc_resp(struct libwifi_reassoc_resp *reassoc_resp,
+                                const unsigned char receiver[6],
+                                const unsigned char transmitter[6],
+                                const unsigned char address3[6],
+                                uint8_t channel);
 
 /**
  * Dump a libwifi_reassoc_resp into a raw format for packet injection.
@@ -55,7 +60,7 @@ int libwifi_create_reassoc_resp(struct libwifi_reassoc_resp *reassoc_resp, const
  * @param reassoc_resp A libwifi_reassoc_resp
  * @param buf The output buffer for the frame data
  * @param buf_len The length of the output buffer
- * @return The length of the dumped reassoc_resp
+ * @return The length of the dumped reassoc_resp, or negative error
  */
 size_t libwifi_dump_reassoc_resp(struct libwifi_reassoc_resp *reassoc_resp, unsigned char *buf,
                                  size_t buf_len);
@@ -63,7 +68,7 @@ size_t libwifi_dump_reassoc_resp(struct libwifi_reassoc_resp *reassoc_resp, unsi
 /**
  * Free any memory claimed by a libwifi_reassoc_resp back to the system.
  *
- * @param reassoc_resp A libwifi_reassoc_resp
+ * @param reassoc_resp A libwifi_reassoc_resp struct
  */
 void libwifi_free_reassoc_resp(struct libwifi_reassoc_resp *reassoc_resp);
 
@@ -23,16 +23,23 @@
 #include <stdlib.h>
 #include <string.h>
 
-int libwifi_create_timing_advert(struct libwifi_timing_advert *adv, const unsigned char destination[6],
-                                  const unsigned char transmitter[6], struct libwifi_timing_advert_fields *adv_fields,
-                                  const char country[3], uint16_t max_reg_power, uint8_t max_tx_power, uint8_t tx_power_used,
-                                  uint8_t noise_floor) {
+int libwifi_create_timing_advert(struct libwifi_timing_advert *adv,
+                                 const unsigned char destination[6],
+                                 const unsigned char transmitter[6],
+                                 const unsigned char address3[6],
+                                 struct libwifi_timing_advert_fields *adv_fields,
+                                 const char country[3],
+                                 uint16_t max_reg_power,
+                                 uint8_t max_tx_power,
+                                 uint8_t tx_power_used,
+                                 uint8_t noise_floor) {
     memset(adv, 0, sizeof(struct libwifi_timing_advert));
 
     adv->frame_header.frame_control.type = TYPE_MANAGEMENT;
     adv->frame_header.frame_control.subtype = SUBTYPE_TIME_ADV;
     memcpy(&adv->frame_header.addr1, destination, 6);
     memcpy(&adv->frame_header.addr2, transmitter, 6);
+    memcpy(&adv->frame_header.addr3, address3, 6);
     adv->frame_header.seq_control.sequence_number = (rand() % 4096);
 
     adv->fixed_parameters.timestamp = BYTESWAP64(libwifi_get_epoch());
@@ -18,15 +18,57 @@
 
 #include "../../core/frame/management/timing_ad.h"
 
-int libwifi_create_timing_advert(struct libwifi_timing_advert *adv, const unsigned char destination[6],
-                                  const unsigned char transmitter[6], struct libwifi_timing_advert_fields *adv_fields,
-                                  const char country[3], uint16_t max_reg_power, uint8_t max_tx_power, uint8_t tx_power_used,
-                                  uint8_t noise_floor);
+/**
+ * Create a populated libwifi_timing_advert struct
+ *
+ * A generated libwifi timing advert can be "dumped" into a buffer for packet injection
+ * via the libwifi_dump_timing_advert function.
+ *
+ * @param adv           A new libwifi_timing_advert struct
+ * @param receiver      The receiver MAC address, aka address 1
+ * @param transmitter   The source MAC address, aka address 2
+ * @param address3      The address 3 frame field value, typically the BSSID
+ * @param adv_fields    A libwifi_timing_advert_fields struct
+ * @param country       The ISO 3166-1 country code field value
+ * @param max_reg_power Maximum Regulatory Power value
+ * @param max_tx_power  Maximum Transmit Power value
+ * @param tx_power_used Transmit Power Used value
+ * @param noise_floor   Noise Floor value
+ * @return              Zero on success, or negative errno
+ */
+int libwifi_create_timing_advert(struct libwifi_timing_advert *adv,
+                                 const unsigned char receiver[6],
+                                 const unsigned char transmitter[6],
+                                 const unsigned char address3[6],
+                                 struct libwifi_timing_advert_fields *adv_fields,
+                                 const char country[3],
+                                 uint16_t max_reg_power,
+                                 uint8_t max_tx_power,
+                                 uint8_t tx_power_used,
+                                 uint8_t noise_floor);
 
+/**
+ * Get the length of the specified libwifi_timing_advert struct
+ *
+ * @return Length of the specified timing advert, or negative error
+ */
 size_t libwifi_get_timing_advert_length(struct libwifi_timing_advert *adv);
 
+/**
+ * Dump a libwifi_timing_advert into a raw format for packet injection.
+ *
+ * @param adv     A libwifi_timing_advert
+ * @param buf     The output buffer for the frame data
+ * @param buf_len The length of the output buffer
+ * @return        The length of the dumped timing advert, or negative error
+ */
 size_t libwifi_dump_timing_advert(struct libwifi_timing_advert *adv, unsigned char *buf, size_t buf_len);
 
+/**
+ * Free any memory claimed by a libwifi_timing_advert back to the system.
+ *
+ * @param adv A libwifi_timing_advert struct
+ */
 void libwifi_free_timing_advert(struct libwifi_timing_advert *adv);
 
 #endif /* LIBWIFI_GEN_TIMINGAD_H */