diff options
Diffstat (limited to 'capture/airpcap.h')
| -rw-r--r-- | capture/airpcap.h | 906 |
1 files changed, 906 insertions, 0 deletions
diff --git a/capture/airpcap.h b/capture/airpcap.h new file mode 100644 index 00000000..f7549d8c --- /dev/null +++ b/capture/airpcap.h @@ -0,0 +1,906 @@ +/** @file + * + * Copyright (c) 2006-2007 CACE Technologies, Davis (California) + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +#if !defined(AIRPCAP_H__EAE405F5_0171_9592_B3C2_C19EC426AD34__INCLUDED_) +#define AIRPCAP_H__EAE405F5_0171_9592_B3C2_C19EC426AD34__INCLUDED_ + +#ifdef _MSC_VER +/* This stops VS2005 ranting against stdio. */ +#pragma warning( disable : 4996) +#endif + +#ifdef _WIN32 +#include <winsock2.h> +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/* + \mainpage AirPcap interface documentation + + \section Introduction + + This document describes the data structures and the functions exported by the CACE Technologies AirPcap library. + The AirPcap library provides low-level access to the AirPcap driver including advanced capabilities such as channel setting, + link type control and WEP configuration.<br> + This manual includes the following sections: + + \note throughout this documentation, \e device refers to a physical USB AirPcap device, while \e adapter is an open API + instance. Most of the AirPcap API operations are adapter-specific but some of them, like setting the channel, are + per-device and will be reflected on all the open adapters. These functions will have "Device" in their name, e.g. + AirpcapSetDeviceChannel(). + + \b Sections: + + - \ref airpcapfuncs + - \ref airpcapdefs + - \ref radiotap +*/ + +/** @defgroup airpcapdefs AirPcap definitions and data structures + * @{ + */ + +/*! + \brief This string is the fixed prefix in the airpcap adapter name. + It can be used to parse the name field in an AirpcapDeviceDescription structure. +*/ +#define AIRPCAP_DEVICE_NAME_PREFIX "\\\\.\\airpcap" + +/*! + \brief This string is the scanf modifier to extract the adapter number from an adapter name. + It can be used to parse the name field in an AirpcapDeviceDescription structure with scanf. +*/ +#define AIRPCAP_DEVICE_NUMBER_EXTRACT_STRING "\\\\.\\airpcap%u" + +#define AIRPCAP_DEVICE_ANY_EXTRACT_STRING "\\\\.\\airpcap_any" + +/*! + \brief Entry in the list returned by \ref AirpcapGetDeviceList(); +*/ +typedef struct _AirpcapDeviceDescription +{ + struct _AirpcapDeviceDescription *next; /* < Next element in the list */ + char * Name; /* < Device name */ + char * Description; /* < Device description */ +} AirpcapDeviceDescription, *PAirpcapDeviceDescription; + +#define MAX_ENCRYPTION_KEYS 64 + +#define WEP_KEY_MAX_SIZE 32 /* < Maximum size of a WEP key, in bytes. This is the size of an entry in the + < AirpcapWepKeysCollection structure. */ + +#ifdef _WIN32 +#ifndef __MINGW32__ +#pragma pack(push) +#pragma pack(1) +#endif +#endif + +#define AIRPCAP_KEYTYPE_WEP 0 /* < Key type: WEP. The key can have an arbitrary length smaller than 32 bytes. */ +#define AIRPCAP_KEYTYPE_TKIP 1 /* < Key type: TKIP (WPA). NOT SUPPORTED YET. */ +#define AIRPCAP_KEYTYPE_CCMP 2 /* < Key type: CCMP (WPA2). NOT SUPPORTED YET. */ + +/*! + \brief WEP key container +*/ +typedef struct _AirpcapKey +{ + unsigned KeyType; /* < Type of key, can be on of: \ref AIRPCAP_KEYTYPE_WEP, \ref AIRPCAP_KEYTYPE_TKIP, \ref AIRPCAP_KEYTYPE_CCMP. Only AIRPCAP_KEYTYPE_WEP is supported by the driver at the moment. */ + unsigned KeyLen; /* < Length of the key, in bytes */ + uint8_t KeyData[WEP_KEY_MAX_SIZE]; /* < Key Data */ +} +#ifdef __MINGW32__ +__attribute__((__packed__)) +#endif +AirpcapKey, *PAirpcapKey; + +/*! + \brief frequency Band. + 802.11 adapters can support different frequency bands, the most important of which are: 2.4GHz (802.11b/g/n) + and 5GHz (802.11a/n). +*/ +typedef enum _AirpcapChannelBand +{ + AIRPCAP_CB_AUTO = 1, /* < Automatically pick the best frequency band */ + AIRPCAP_CB_2_4_GHZ = 2, /* < 2.4 GHz frequency band */ + AIRPCAP_CB_4_GHZ = 4, /* < 4 GHz frequency band */ + AIRPCAP_CB_5_GHZ = 5 /* < 5 GHz frequency band */ +}AirpcapChannelBand, *PAirpcapChannelBand; + +/*! + \brief Type of frame validation the adapter performs. + An adapter can be instructed to accept different kind of frames: correct frames only, frames with wrong Frame Check Sequence (FCS) only, all frames. +*/ +typedef enum _AirpcapValidationType +{ + AIRPCAP_VT_ACCEPT_EVERYTHING = 1, /* < Accept all the frames the device captures */ + AIRPCAP_VT_ACCEPT_CORRECT_FRAMES = 2, /* < Accept correct frames only, i.e. frames with correct Frame Check Sequence (FCS). */ + AIRPCAP_VT_ACCEPT_CORRUPT_FRAMES = 3, /* < Accept corrupt frames only, i.e. frames with wrong Frame Check Sequence (FCS). */ + AIRPCAP_VT_UNKNOWN = 4 /* < Unknown validation type. You should see it only in case of error. */ +}AirpcapValidationType, *PAirpcapValidationType; + +/*! + \brief Type of decryption the adapter performs. + An adapter can be instructed to turn decryption (based on the device-configured keys configured + with \ref AirpcapSetDeviceKeys()) on or off. +*/ +typedef enum _AirpcapDecryptionState +{ + AIRPCAP_DECRYPTION_ON = 1, /* < This adapter performs decryption */ + AIRPCAP_DECRYPTION_OFF = 2 /* < This adapter does not perform decryption */ +}AirpcapDecryptionState, *PAirpcapDecryptionState; + + +/*! + \brief Storage for a MAC address +*/ +typedef struct _AirpcapMacAddress +{ + uint8_t Address[6]; /* < MAC address bytes */ +} +#ifdef __MINGW32__ +__attribute__((__packed__)) +#endif +AirpcapMacAddress, *PAirpcapMacAddress; + +/*! + \brief This structure is used to store a collection of WEP keys. + Note that the definition of the structure has one key in it + (so that this code can be compiled by compilers that don't + support zero-length arrays), so be careful to allocate a buffer + with the size of the set of keys, as per the following example: + + \code + PAirpcapKeysCollection KeysCollection; + unsigned KeysCollectionSize; + + KeysCollectionSize = AirpcapKeysCollectionSize(NumKeys); + + KeysCollection = (PAirpcapKeysCollection)malloc(KeysCollectionSize); + if(!KeysCollection) + { + Error + } + \endcode +*/ +typedef struct _AirpcapKeysCollection +{ + unsigned nKeys; /* < Number of keys in the collection */ + AirpcapKey Keys[1]; /* < Array of nKeys keys. */ +} AirpcapKeysCollection, *PAirpcapKeysCollection; + +#define AirpcapKeysCollectionSize(nKeys) \ + ((sizeof(AirpcapKeysCollection) - sizeof(AirpcapKey)) + ((nKeys) * sizeof(AirpcapKey))) +#define AirpcapKeysCollectionSizeToKeyCount(size) \ + (unsigned)(((size) - AirpcapKeysCollectionSize(0))/sizeof(AirpcapKey)) + +/*! + \brief Packet header. + + This structure defines the BPF that precedes every packet delivered to the application. +*/ +typedef struct _AirpcapBpfHeader +{ + unsigned TsSec; /* < Timestamp associated with the captured packet. SECONDS. */ + unsigned TsUsec; /* < Timestamp associated with the captured packet. MICROSECONDS. */ + unsigned Caplen; /* < Length of captured portion. The captured portion <b>can be different</b> from the original packet, because it is possible (with a proper filter) to instruct the driver to capture only a portion of the packets. */ + unsigned Originallen; /* < Original length of packet */ + uint16_t Hdrlen; /* < Length of bpf header (this struct plus alignment padding). In some cases, a padding could be added between the end of this structure and the packet data for performance reasons. This field can be used to retrieve the actual data of the packet. */ +} +#ifdef __MINGW32__ +__attribute__((__packed__)) +#endif +AirpcapBpfHeader, *PAirpcapBpfHeader; + +/* Helper macros to extract packets coming from the driver. Rounds up to the next even multiple of AIRPCAP_ALIGNMENT. */ +#define AIRPCAP_ALIGNMENT sizeof(int) +#define AIRPCAP_WORDALIGN(x) (((x)+(AIRPCAP_ALIGNMENT-1))&~(AIRPCAP_ALIGNMENT-1)) + +#ifdef _WIN32 +#ifndef __MINGW32__ +#pragma pack(pop) +#endif +#endif + +#define AIRPCAP_ERRBUF_SIZE 512 /* < Size of the error buffer, in bytes */ + +#ifndef __AIRPCAP_DRIVER__ + +/*! + \brief Link type. + AirPcap supports two kind of 802.11 linktypes: plain 802.11 and radiotap. +*/ +#undef _AirpcapLinkType +typedef enum _AirpcapLinkType +{ + AIRPCAP_LT_802_11 = 1, /* < plain 802.11 linktype. Every packet in the buffer contains the raw 802.11 frame, including MAC FCS. */ + AIRPCAP_LT_802_11_PLUS_RADIO = 2, /* < 802.11 plus radiotap linktype. Every packet in the buffer contains a radiotap header followed by the 802.11 frame. MAC FCS is included. */ + AIRPCAP_LT_UNKNOWN = 3, /* < Unknown linktype. You should see it only in case of error. */ + AIRPCAP_LT_802_11_PLUS_PPI = 4 /* < 802.11 plus PPI header linktype. Every packet in the buffer contains a PPI header followed by the 802.11 frame. MAC FCS is included. */ +}AirpcapLinkType, *PAirpcapLinkType; + +#if !defined(AIRPCAP_HANDLE__EAE405F5_0171_9592_B3C2_C19EC426AD34__DEFINED_) +#define AIRPCAP_HANDLE__EAE405F5_0171_9592_B3C2_C19EC426AD34__DEFINED_ +/*! + \brief Adapter handle. +*/ +typedef struct _AirpcapHandle AirpcapHandle, *PAirpcapHandle; +#endif + +/*! + \brief Capture statistics. + Returned by \ref AirpcapGetStats(); +*/ +typedef struct _AirpcapStats +{ + unsigned Recvs; /* < Number of packets that the driver received by the adapter */ + /* < from the beginning of the current capture. This value includes the packets */ + /* < dropped because of buffer full. */ + unsigned Drops; /* < number of packets that the driver dropped from the beginning of a capture. */ + /* < A packet is lost when the driver's buffer is full. */ + unsigned IfDrops; /* < Packets dropped by the card before going to the USB bus. */ + /* < Not supported at the moment. */ + unsigned Capt; /* < number of packets that pass the BPF filter, find place in the kernel buffer and */ + /* < therefore reach the application. */ +}AirpcapStats, *PAirpcapStats; + +/*! + \brief Channel information. + Used by \ref AirpcapSetDeviceChannelEx(), \ref AirpcapGetDeviceChannelEx(), \ref AirpcapGetDeviceSupportedChannels() +*/ +typedef struct _AirpcapChannelInfo +{ + unsigned Frequency; /* < Channel frequency, in MHz. */ + /*! + \brief 802.11n specific. Offset of the extension channel in case of 40MHz channels. + + Possible values are -1, 0 +1: + - -1 means that the extension channel should be below the control channel (e.g. Control = 5 and Extension = 1) + - 0 means that no extension channel should be used (20MHz channels or legacy mode) + - +1 means that the extension channel should be above the control channel (e.g. Control = 1 and Extension = 5) + + In case of 802.11a/b/g channels (802.11n legacy mode), this field should be set to 0. + */ + int8_t ExtChannel; + uint8_t Reserved[3]; /* < Reserved. It should be set to {0,0,0}. */ +} + AirpcapChannelInfo, *PAirpcapChannelInfo; + + +/*@}*/ + +/** @defgroup airpcapfuncs AirPcap functions + * @{ + */ + +/*! + \brief Return a string with the API version + \param VersionMajor Pointer to a variable that will be filled with the major version number. + \param VersionMinor Pointer to a variable that will be filled with the minor version number. + \param VersionRev Pointer to a variable that will be filled with the revision number. + \param VersionBuild Pointer to a variable that will be filled with the build number. +*/ +void AirpcapGetVersion(unsigned * VersionMajor, unsigned * VersionMinor, unsigned * VersionRev, unsigned * VersionBuild); + +/*! + \brief Return the last error related to the specified handle + \param AdapterHandle Handle to an open adapter. + \return The string with the last error. +*/ +char * AirpcapGetLastError(PAirpcapHandle AdapterHandle); + +/*! + \brief Return the list of available devices + \param PPAllDevs Address to a caller allocated pointer. On success this pointer will receive the head of a list of available devices. + \param Ebuf String that will contain error information if false is returned. The size of the string must be AIRPCAP_ERRBUF_SIZE bytes. + \return true on success. false is returned on failure, in which case Ebuf is filled in with an appropriate error message. + + Here's a snippet of code that shows how to use AirpcapGetDeviceList(): + + \code + char Ebuf[AIRPCAP_ERRBUF_SIZE]; + AirpcapDeviceDescription *Desc, *tDesc; + + if(AirpcapGetDeviceList(&Desc, Ebuf) == -1) + { + printf("Unable to get the list of devices: %s\n", Ebuf); + return -1; + } + + for(tDesc = Desc; tDesc; tDesc = tDesc->next) + { + printf("%u) %s (%s)\n", + ++i, + tDesc->Name, + tDesc->Description); + } + + AirpcapFreeDeviceList(Desc); + \endcode +*/ +bool AirpcapGetDeviceList(PAirpcapDeviceDescription *PPAllDevs, char * Ebuf); + +/*! + \brief Free a list of devices returned by AirpcapGetDeviceList() + \param PAllDevs Head of the list of devices returned by \ref AirpcapGetDeviceList(). +*/ +void AirpcapFreeDeviceList(PAirpcapDeviceDescription PAllDevs); + +/*! + \brief Open an adapter + \param DeviceName Name of the device to open. Use \ref AirpcapGetDeviceList() to get the list of devices. + \param Ebuf String that will contain error information in case of failure. The size of the string must be AIRPCAP_ERRBUF_SIZE bytes. + \return A PAirpcapHandle handle on success. NULL is returned on failure, in which case Ebuf is filled in with an appropriate error message. +*/ +PAirpcapHandle AirpcapOpen(char * DeviceName, char * Ebuf); + +/*! + \brief Close an adapter + \param AdapterHandle Handle to the adapter to close. +*/ +void AirpcapClose(PAirpcapHandle AdapterHandle); + +/*! + \brief Sets the monitor mode for the specified adapter + \param AdapterHandle Handle to the adapter. + \param MonitorModeEnabled If true, the adapter will be put in monitor mode. If false, the adapter will be configured + for normal operation. + \return true on success. + + When monitor mode is on, the adapter captures all the packets transmitted on the channel. This includes: + + - unicast packets + - multicast packets + - broadcast packets + - control and management packets + + When monitor mode is off, the adapter has a filter on unicast packets to capture only the packets whose MAC + destination address equals to the adapter's address. This means the following frames will be received: + + - unicast packets with the address of the adapter + - multicast packets + - broadcast packets + - beacons and probe requests + + The main reason to turn monitor mode off is that, when not in monitor mode, the adapter will acknowledge the + data frames sent to its address. This is useful when the adapter needs to interact with other devices on the + 802.11 network, because handling the ACKs in software is too slow. + + \note When an adapter is plugged into the system, it's always configured with monitor mode ON. The monitor mode + configuration is not stored persistently, so if you want to turn monitor mode off, you will need to do it + every time you open the adapter. +*/ +bool AirpcapSetMonitorMode(PAirpcapHandle AdapterHandle, bool MonitorModeEnabled); + +/*! + \brief Returns true if the specified adapter is in monitor mode. + \param AdapterHandle Handle to the adapter. + \param PMonitorModeEnabled User-provided variable that will be set to true if the adapter is in monitor mode. + \return true if the operation is successful. false otherwise. + + \note When an adapter is plugged into the system, it's always configured with monitor mode ON. The monitor mode + configuration is not stored persistently, so if you want to turn monitor mode off, you will need to do it + every time you open the adapter. +*/ +bool AirpcapGetMonitorMode(PAirpcapHandle AdapterHandle, bool * PMonitorModeEnabled); + +/*! + \brief Set the link type of an adapter + \param AdapterHandle Handle to the adapter. + \param NewLinkType the "link type", i.e. the format of the frames that will be received from the adapter. + \return true on success. + + the "link type" determines how the driver will encode the packets captured from the network. + Aircap supports two link types: + - AIRPCAP_LT_802_11, to capture 802.11 frames (including control frames) without any + power information. Look at the Capture_no_radio example application in the developer's pack + for a reference on how to decode 802.11 frames with this link type. + - AIRPCAP_LT_802_11_PLUS_RADIO, to capture 802.11 frames (including control frames) with a radiotap header + that contains power and channel information. More information about the radiotap header can be found in the + radiotap section. Moreover, the "Capture_radio" example application in + the developer's pack can be used as a reference on how to decode 802.11 frames with radiotap headers. + - AIRPCAP_LT_802_11_PLUS_PPI, to capture 802.11 frames (including control frames) with a Per Packet Information (PPI) + header that contains per-packet meta information like channel and power information. More details on the PPI header can + be found in the PPI online documentation (TODO). +*/ +bool AirpcapSetLinkType(PAirpcapHandle AdapterHandle, AirpcapLinkType NewLinkType); + +/*! + \brief Get the link type of the specified adapter + \param AdapterHandle Handle to the adapter. + \param PLinkType Pointer to a caller allocated AirpcapLinkType variable that will contain the link type of the adapter. + \return true on success. + + the "link type" determines how the driver will encode the packets captured from the network. + Aircap supports two link types: + - AIRPCAP_LT_802_11, to capture 802.11 frames (including control frames) without any + power information. Look at the Capture_no_radio example application in the developer's pack + for a reference on how to decode 802.11 frames with this link type. + - AIRPCAP_LT_802_11_PLUS_RADIO, to capture 802.11 frames (including control frames) with a radiotap header + that contains power and channel information. More information about the radiotap header can be found int the + radiotap section. Moreover, the "Capture_radio" example application in + the developer's pack can be used as a reference on how to decode 802.11 frames with radiotap headers. +*/ +bool AirpcapGetLinkType(PAirpcapHandle AdapterHandle, PAirpcapLinkType PLinkType); + +/*! + \brief Configures the adapter on whether to include the MAC Frame Check Sequence in the captured packets. + \param AdapterHandle Handle to the adapter. + \param IsFcsPresent true if the packets should include the FCS. false otherwise + \return true on success. + + In the default configuration, the adapter includes the FCS in the captured packets. The MAC Frame Check Sequence + is 4 bytes and is located at the end of the 802.11 packet, with both AIRPCAP_LT_802_11 and AIRPCAP_LT_802_11_PLUS_RADIO + link types. + When the FCS inclusion is turned on, and if the link type is AIRPCAP_LT_802_11_PLUS_RADIO, the radiotap header + that precedes each frame has two additional fields at the end: Padding and FCS. These two fields are not present + when FCS inclusion is off. +*/ +bool AirpcapSetFcsPresence(PAirpcapHandle AdapterHandle, bool IsFcsPresent); + +/*! + \brief Returns true if the specified adapter includes the MAC Frame Check Sequence in the captured packets + \param AdapterHandle Handle to the adapter. + \param PIsFcsPresent User-provided variable that will be set to true if the adapter is including the FCS. + \return true if the operation is successful. false otherwise. + + In the default configuration, the adapter has FCS inclusion turned on. The MAC Frame Check Sequence is 4 bytes + and is located at the end of the 802.11 packet, with both AIRPCAP_LT_802_11 and AIRPCAP_LT_802_11_PLUS_RADIO + link types. + When the FCS inclusion is turned on, and if the link type is AIRPCAP_LT_802_11_PLUS_RADIO, the radiotap header + that precedes each frame has two additional fields at the end: Padding and FCS. These two fields are not present + when FCS inclusion is off. +*/ +bool AirpcapGetFcsPresence(PAirpcapHandle AdapterHandle, bool * PIsFcsPresent); + +/*! + \brief Configures the adapter to accept or drop frames with an incorrect Frame Check sequence (FCS). + \param AdapterHandle Handle to the adapter. + \param ValidationType The type of validation the driver will perform. See the documentation of \ref AirpcapValidationType for details. + \return true on success. + + \note By default, the driver is configured in AIRPCAP_VT_ACCEPT_EVERYTHING mode. +*/ +bool AirpcapSetFcsValidation(PAirpcapHandle AdapterHandle, AirpcapValidationType ValidationType); + +/*! + \brief Checks if the specified adapter is configured to capture frames with incorrect an incorrect Frame Check Sequence (FCS). + \param AdapterHandle Handle to the adapter. + \param ValidationType Pointer to a user supplied variable that will contain the type of validation the driver will perform. See the documentation of \ref AirpcapValidationType for details. + \return true if the operation is successful. false otherwise. + + \note By default, the driver is configured in AIRPCAP_VT_ACCEPT_EVERYTHING mode. +*/ +bool AirpcapGetFcsValidation(PAirpcapHandle AdapterHandle, PAirpcapValidationType ValidationType); + +/*! + \brief Set the list of decryption keys that the driver is going to use with the specified device. + \param AdapterHandle Handle an open adapter instance. + \param KeysCollection Pointer to a PAirpcapKeysCollection structure that contains the keys to be set in the driver. + \return true if the operation is successful. false otherwise. + + The AirPcap driver is able to use a set of decryption keys to decrypt the traffic transmitted on a specific SSID. If one of the + keys corresponds to the one the frame has been encrypted with, the driver will perform decryption and return the cleartext frames + to the application. + + This function allows to set the <b>adapter-specific</b> set of keys. These keys will be used by the specified adapter only, + and will not be used by other airpcap devices besides the specified one. + + At this time, the only supported decryption method is WEP. + + The keys are applied to the packets in the same order they appear in the KeysCollection structure until the packet is + correctly decrypted, therefore putting frequently used keys at the beginning of the structure improves performance. + + \note: when you change the set of keys from an open capture instance, the change will be + immediately reflected on all the other capture instances. +*/ +bool AirpcapSetDeviceKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection); + +/*! + \brief Returns the list of decryption keys in the driver that are currently associated with the specified device + \param AdapterHandle Handle to an open adapter instance. + \param KeysCollection User-allocated PAirpcapKeysCollection structure that will be filled with the keys. + \param PKeysCollectionSize \b IN: pointer to a user-allocated variable that contains the length of the KeysCollection structure, in bytes. + \b OUT: amount of data moved by the driver in the buffer pointed by KeysBuffer, in bytes. + \return true if the operation is successful. If an error occurs, the return value is false and KeysCollectionSize is zero. + If the provided buffer is too small to contain the keys, the return value is false and KeysCollectionSize contains the + needed KeysCollection length, in bytes. If the device doesn't have any decryption key configured, the return value is true, and + KeysCollectionSize will be zero. + + This function returns the <b>adapter-specific</b> set of keys. These keys are used by the specified adapter only, + and not by other airpcap devices besides the specified one. + + The AirPcap driver is able to use a set of decryption keys to decrypt the traffic transmitted on a specific SSID. If one of the + keys corresponds to the one the frame has been encrypted with, the driver will perform decryption and return the cleartext frames + to the application. + The driver supports, for every device, multiple keys at the same time. + + The configured decryption keys are device-specific, therefore AirpcapGetDeviceKeys() will return a different set of keys + when called on different devices. + + At this time, the only supported decryption method is WEP. +*/ +bool AirpcapGetDeviceKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection, unsigned * PKeysCollectionSize); + +/*! + \brief Set the global list of decryption keys that the driver is going to use with all the devices. + \param AdapterHandle Handle an open adapter instance. + \param KeysCollection Pointer to a PAirpcapKeysCollection structure that contains the keys to be set in the driver. + \return true if the operation is successful. false otherwise. + + The AirPcap driver is able to use a set of decryption keys to decrypt the traffic transmitted on a specific SSID. If one of the + keys corresponds to the one the frame has been encrypted with, the driver will perform decryption and return the cleartext frames + to the application. + + This function allows to set the <b>global driver</b> set of keys. These keys will be used by all the adapters plugged in + the machine. + + At this time, the only supported decryption method is WEP. + + The keys are applied to the packets in the same order they appear in the KeysCollection structure until the packet is + correctly decrypted, therefore putting frequently used keys at the beginning of the structure improves performance. + + \note: when you change the set of keys from an open capture instance, the change will be + immediately reflected on all the other capture instances. +*/ +bool AirpcapSetDriverKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection); + +/*! + \brief Returns the global list of decryption keys in the driver that are associated with all the devices. + \param AdapterHandle Handle to an open adapter instance. + \param KeysCollection User-allocated PAirpcapKeysCollection structure that will be filled with the keys. + \param PKeysCollectionSize \b IN: pointer to a user-allocated variable that contains the length of the KeysCollection structure, in bytes. + \b OUT: amount of data moved by the driver in the buffer pointed by KeysBuffer, in bytes. + \return true if the operation is successful. If an error occurs, the return value is false and KeysCollectionSize is zero. + If the provided buffer is too small to contain the keys, the return value is false and KeysCollectionSize contains the + needed KeysCollection length, in bytes. If the device doesn't have any decryption key configured, the return value is true, and + KeysCollectionSize will be zero. + + This function returns the <b>global driver</b> set of keys. These keys will be used by all the adapters plugged in + the machine. + + The AirPcap driver is able to use a set of decryption keys to decrypt the traffic transmitted on a specific SSID. If one of the + keys corresponds to the one the frame has been encrypted with, the driver will perform decryption and return the cleartext frames + to the application. + + At this time, the only supported decryption method is WEP. +*/ +bool AirpcapGetDriverKeys(PAirpcapHandle AdapterHandle, PAirpcapKeysCollection KeysCollection, unsigned * PKeysCollectionSize); + +/*! + \brief Turns on or off the decryption of the incoming frames with the <b>adapter-specific</b> keys. + \param AdapterHandle Handle to the adapter. + \param Enable Either AIRPCAP_DECRYPTION_ON or AIRPCAP_DECRYPTION_OFF + \return true on success. + + The adapter-specific decryption keys can be configured with the \ref AirpcapSetDeviceKeys() function. + \note By default, the driver is configured with AIRPCAP_DECRYPTION_ON. +*/ +bool AirpcapSetDecryptionState(PAirpcapHandle AdapterHandle, AirpcapDecryptionState Enable); + +/*! + \brief Tells if this open instance is configured to perform the decryption of the incoming frames with the <b>adapter-specific</b> keys. + \param AdapterHandle Handle to the adapter. + \param PEnable Pointer to a user supplied variable that will contain the decryption configuration. See \ref _AirpcapDecryptionState for details. + \return true if the operation is successful. false otherwise. + + The adapter-specific decryption keys can be configured with the \ref AirpcapSetDeviceKeys() function. + \note By default, the driver is configured with AIRPCAP_DECRYPTION_ON. +*/ +bool AirpcapGetDecryptionState(PAirpcapHandle AdapterHandle, PAirpcapDecryptionState PEnable); + +/*! + \brief Turns on or off the decryption of the incoming frames with the <b>global driver</b> set of keys. + \param AdapterHandle Handle to the adapter. + \param Enable Either AIRPCAP_DECRYPTION_ON or AIRPCAP_DECRYPTION_OFF + \return true on success. + + The global decryption keys can be configured with the \ref AirpcapSetDriverKeys() function. + \note By default, the driver is configured with AIRPCAP_DECRYPTION_ON. +*/ +bool AirpcapSetDriverDecryptionState(PAirpcapHandle AdapterHandle, AirpcapDecryptionState Enable); + +/*! + \brief Tells if this open instance is configured to perform the decryption of the incoming frames with the <b>global driver</b> set of keys. + \param AdapterHandle Handle to the adapter. + \param PEnable Pointer to a user supplied variable that will contain the decryption configuration. See \ref _AirpcapDecryptionState for details. + \return true if the operation is successful. false otherwise. + + The global decryption keys can be configured with the \ref AirpcapSetDriverKeys() function. + \note By default, the driver is configured with AIRPCAP_DECRYPTION_ON. +*/ +bool AirpcapGetDriverDecryptionState(PAirpcapHandle AdapterHandle, PAirpcapDecryptionState PEnable); + +/*! + \brief Set the radio channel of a device + \param AdapterHandle Handle to the adapter. + \param Channel the new channel to set. + \return true on success. + + The list of available channels can be retrieved with \ref AirpcapGetDeviceSupportedChannels(). The default channel setting is 6. + + \note this is a device-related function: when you change the channel from an open capture instance, the change will be + immediately reflected on all the other capture instances. +*/ +bool AirpcapSetDeviceChannel(PAirpcapHandle AdapterHandle, unsigned Channel); + +/*! + \brief Get the radio channel of a device + \param AdapterHandle Handle to the adapter. + \param PChannel Pointer to a user-supplied variable into which the function will copy the currently configured radio channel. + \return true on success. + + The list of available channels can be retrieved with \ref AirpcapGetDeviceSupportedChannels(). The default channel setting is 6. + + \note this is a device-related function: when you change the channel from an open capture instance, the change will be + immediately reflected on all the other capture instances. +*/ +bool AirpcapGetDeviceChannel(PAirpcapHandle AdapterHandle, unsigned * PChannel); + +/*! + \brief Set the size of the kernel packet buffer for this adapter + \param AdapterHandle Handle to the adapter. + \param BufferSize New size, in bytes. + \return true on success. + + Every AirPcap open instance has an associated kernel buffer, whose default size is 1 Mbyte. + This function can be used to change the size of this buffer, and can be called at any time. + A bigger kernel buffer size decreases the risk of dropping packets during network bursts or when the + application is busy, at the cost of higher kernel memory usage. + + \note don't use this function unless you know what you are doing. Due to caching issues and bigger non-paged + memory consumption, bigger buffer sizes can decrease the capture performance instead of improving it. +*/ +bool AirpcapSetKernelBuffer(PAirpcapHandle AdapterHandle, unsigned BufferSize); + +/*! + \brief Get the size of the kernel packet buffer for this adapter + \param AdapterHandle Handle to the adapter. + \param PSizeBytes User-allocated variable that will be filled with the size of the kernel buffer. + \return true on success. + + Every AirPcap open instance has an associated kernel buffer, whose default size is 1 Mbyte. + This function can be used to get the size of this buffer. +*/ +bool AirpcapGetKernelBufferSize(PAirpcapHandle AdapterHandle, unsigned * PSizeBytes); + +/*! + \brief Saves the configuration of the specified adapter in the registry, so that it becomes the default for this adapter. + \param AdapterHandle Handle to the adapter. + \return true on success. false on failure. + + Almost all the AirPcap calls that modify the configuration (\ref AirpcapSetLinkType(), \ref AirpcapSetFcsPresence(), + \ref AirpcapSetFcsValidation(), \ref AirpcapSetKernelBuffer(), \ref AirpcapSetMinToCopy()) + affect only the referenced AirPcap open instance. This means that if you do another \ref AirpcapOpen() on the same + adapter, the configuration changes will not be remembered, and the new adapter handle will have default configuration + settings. + + Exceptions to this rule are the \ref AirpcapSetDeviceChannel() and \ref AirpcapSetDeviceKeys() functions: a channel change is + reflected on all the open instances, and remembered until the next call to \ref AirpcapSetDeviceChannel(), until the adapter + is unplugged, or until the machine is powered off. Same thing for the configuration of the WEP keys. + + AirpcapStoreCurConfigAsAdapterDefault() stores the configuration of the give open instance as the default for the adapter: + all the instances opened in the future will have the same configuration that this adapter currently has. + The configuration is stored in the registry, therefore it is remembered even when the adapter is unplugged or the + machine is turned off. However, an adapter doesn't bring its configuration with it from machine to machine. + + the configuration information saved in the registry includes the following parameters: + - channel + - kernel buffer size + - mintocopy + - link type + - CRC presence + - Encryption keys + - Encryption Enabled/Disabled state + + The configuration is adapter-specific. This means that changing the configuration of an adapter + doesn't modify the one of the other adapters that are currently used or that will be used in the future. + + \note AirpcapStoreCurConfigAsAdapterDefault() must have exclusive access to the adapter -- it + will fail if more than one AirPcap handle is opened at the same time for this adapter. + AirpcapStoreCurConfigAsAdapterDefault() needs administrator privileges. It will fail if the calling user + is not a local machine administrator. +*/ +bool AirpcapStoreCurConfigAsAdapterDefault(PAirpcapHandle AdapterHandle); + +/*! + \brief Set the BPF kernel filter for an adapter + \param AdapterHandle Handle to the adapter. + \param Instructions pointer to the first BPF instruction in the array. Corresponds to the bf_insns + in a bpf_program structure (see the WinPcap documentation at https://www.winpcap.org/devel.htm). + \param Len Number of instructions in the array pointed by the previous field. Corresponds to the bf_len in + a bpf_program structure (see the WinPcap documentation at https://www.winpcap.org/devel.htm). + \return true on success. + + The AirPcap driver is able to perform kernel-level filtering using the standard BPF pseudo-machine format. You can read + the WinPcap documentation at https://www.winpcap.org/devel.htm for more details on the BPF filtering mechanism. + + A filter can be automatically created by using the pcap_compile() function of the WinPcap API. This function + converts a human readable text expression with the tcpdump/libpcap syntax into a BPF program. + If your program doesn't link wpcap, but you need to generate the code for a particular filter, you can run WinDump + with the -d or -dd or -ddd flags to obtain the pseudocode. + +*/ +bool AirpcapSetFilter(PAirpcapHandle AdapterHandle, void * Instructions, unsigned Len); + +/*! + \brief Return the MAC address of an adapter. + \param AdapterHandle Handle to the adapter. + \param PMacAddress Pointer to a user allocated MAC address. + The size of this buffer needs to be at least 6 bytes. + \return true on success. +*/ +bool AirpcapGetMacAddress(PAirpcapHandle AdapterHandle, PAirpcapMacAddress PMacAddress); + +/*! + \brief Set the mintocopy parameter for an open adapter + \param AdapterHandle Handle to the adapter. + \param MinToCopy is the mintocopy size in bytes. + \return true on success. + + When the number of bytes in the kernel buffer changes from less than mintocopy bytes to greater than or equal to mintocopy bytes, + the read event is signalled (see \ref AirpcapGetReadEvent()). A high value for mintocopy results in poor responsiveness since the + driver may signal the application "long" after the arrival of the packet. And a high value results in low CPU loading + by minimizing the number of user/kernel context switches. + A low MinToCopy results in good responsiveness since the driver will signal the application close to the arrival time of + the packet. This has higher CPU loading over the first approach. +*/ +bool AirpcapSetMinToCopy(PAirpcapHandle AdapterHandle, unsigned MinToCopy); + +/*! + \brief Gets an event that is signaled when that is signalled when packets are available in the kernel buffer (see \ref AirpcapSetMinToCopy()). + \param AdapterHandle Handle to the adapter. + \param PReadEvent Pointer to a user-supplied handle that in which the read event will be copied. + \return true on success. + + \note the event is signalled when at least mintocopy bytes are present in the kernel buffer (see \ref AirpcapSetMinToCopy()). + This event can be used by WaitForSingleObject() and WaitForMultipleObjects() to create blocking behavior when reading + packets from one or more adapters (see \ref AirpcapRead()). +*/ +bool AirpcapGetReadEvent(PAirpcapHandle AdapterHandle, void *** PReadEvent); + +/*! + \brief Fills a user-provided buffer with zero or more packets that have been captured on the referenced adapter. + \param AdapterHandle Handle to the adapter. + \param Buffer pointer to the buffer that will be filled with captured packets. + \param BufSize size of the input buffer that will contain the packets, in bytes. + \param PReceievedBytes Pointer to a user supplied variable that will receive the number of bytes copied by AirpcapRead. + Can be smaller than BufSize. + \return true on success. + + 802.11 frames are returned by the driver in buffers. Every 802.11 frame in the buffer is preceded by a \ref AirpcapBpfHeader structure. + The suggested way to use an AirPcap adapter is through the pcap API exported by wpcap.dll. If this is not + possible, the Capture_radio and Capture_no_radio examples in the AirPcap developer's pack show how to properly decode the + packets in the read buffer returned by AirpcapRead(). + + \note this function is NOT blocking. Blocking behavior can be obtained using the event returned + by \ref AirpcapGetReadEvent(). See also \ref AirpcapSetMinToCopy(). +*/ +bool AirpcapRead(PAirpcapHandle AdapterHandle, uint8_t * Buffer, unsigned BufSize, unsigned * PReceievedBytes); + +/*! + \brief Transmits a packet. + \param AdapterHandle Handle to the adapter. + \param TxPacket Pointer to a buffer that contains the packet to be transmitted. + \param PacketLen Length of the buffer pointed by the TxPacket argument, in bytes. + \return true on success. + + The packet will be transmitted on the channel the device is currently set. To change the device adapter, use the + \ref AirpcapSetDeviceChannel() function. + + If the linktype of the adapter is AIRPCAP_LT_802_11, the buffer pointed by TxPacket should contain just the 802.11 + packet, without additional information. The packet will be transmitted at 1Mbps. + + If the linktype of the adapter is AIRPCAP_LT_802_11_PLUS_RADIO, the buffer pointed by TxPacket should contain a radiotap + header followed by the 802.11 packet. AirpcapWrite will use the rate information in the radiotap header when + transmitting the packet. +*/ +bool AirpcapWrite(PAirpcapHandle AdapterHandle, char * TxPacket, uint32_t PacketLen); + +/*! + \brief Get per-adapter WinPcap-compatible capture statistics. + \param AdapterHandle Handle to the adapter. + \param PStats pointer to a user-allocated AirpcapStats structure that will be filled with statistical information. + \return true on success. +*/ +bool AirpcapGetStats(PAirpcapHandle AdapterHandle, PAirpcapStats PStats); + +/*! + \brief Get the number of LEDs the referenced adapter has available. + \param AdapterHandle Handle to the adapter. + \param NumberOfLeds Number of LEDs available on this adapter. + \return true on success. +*/ +bool AirpcapGetLedsNumber(PAirpcapHandle AdapterHandle, unsigned * NumberOfLeds); + +/*! + \brief Turn on one of the adapter's LEDs. + \param AdapterHandle Handle to the adapter. + \param LedNumber zero-based identifier of the LED to turn on. + \return true on success. +*/ +bool AirpcapTurnLedOn(PAirpcapHandle AdapterHandle, unsigned LedNumber); + +/*! + \brief Turn off one of the adapter's LEDs. + \param AdapterHandle Handle to the adapter. + \param LedNumber zero-based identifier of the LED to turn off. + \return true on success. +*/ +bool AirpcapTurnLedOff(PAirpcapHandle AdapterHandle, unsigned LedNumber); + +/*! + \brief Set the channel of a device through its radio frequency. In case of 802.11n enabled devices, it sets the extension channel, if used. + \param AdapterHandle Handle to the adapter. + \param ChannelInfo The new channel information to set. + \return true on success. + + \note this is a device-related function: when you change the channel from an open capture instance, the change will be + immediately reflected on all the other capture instances. +*/ +bool AirpcapSetDeviceChannelEx(PAirpcapHandle AdapterHandle, AirpcapChannelInfo ChannelInfo); + +/*! + \brief Get the channel of a device through its radiofrequency. In case of 802.11n enabled devices, it gets the extension channel, if in use. + \param AdapterHandle Handle to the adapter. + \param PChannelInfo Pointer to a user-supplied variable into which the function will copy the currently configured channel information. + \return true on success. + + \note this is a device-related function: when you change the channel from an open capture instance, the change will be + immediately reflected on all the other capture instances. +*/ +bool AirpcapGetDeviceChannelEx(PAirpcapHandle AdapterHandle, PAirpcapChannelInfo PChannelInfo); + +/*! + \brief Get the list of supported channels for a given device. In case of a 802.11n capable device, information related to supported extension channels is also reported. + + Every control channel is listed multiple times, one for each different supported extension channel. For example channel 6 (2437MHz) is usually listed three times: + - <b>Frequency 2437 Extension +1</b>. Control channel is 6, extension channel is 10. + - <b>Frequency 2437 Extension 0</b>. Control channel is 6, no extension channel is used (20MHz channel and legacy mode). + - <b>Frequency 2437 Extension -1</b>. Control channel is 6, extension channel is 2. + \param AdapterHandle Handle to the adapter. + \param ppChannelInfo Pointer to a user-supplied variable that will point to an array of supported channel. Such list must not be freed by the caller + \param pNumChannelInfo Number of channels returned in the array. + \return true on success. + + \note The supported channels are not listed in any specific order. +*/ +bool AirpcapGetDeviceSupportedChannels(PAirpcapHandle AdapterHandle, PAirpcapChannelInfo *ppChannelInfo, unsigned * pNumChannelInfo); + +/*! + \brief Converts a given frequency to the corresponding channel. + + \param Frequency Frequency of the channel, in MHz. + \param PChannel Pointer to a user-supplied variable that will contain the channel number on success. + \param PBand Pointer to a user-supplied variable that will contain the band (a or b/g) of the given channel. + \return true on success, i.e. the frequency corresponds to a valid a or b/g channel. +*/ +bool AirpcapConvertFrequencyToChannel(unsigned Frequency, unsigned * PChannel, PAirpcapChannelBand PBand); + +/*! + \brief Converts a given channel to the corresponding frequency. + + \param Channel Channel number to be converted. + \param PFrequency Pointer to a user-supplied variable that will contain the channel frequency in MHz on success. + \return true on success, i.e. the given channel number exists. +*/ +bool AirpcapConvertChannelToFrequency(unsigned Channel, unsigned * PFrequency); + + +/*@}*/ + +#endif /* __AIRPCAP_DRIVER__ */ + +#ifdef __cplusplus +} +#endif + +#endif /* !defined(AIRPCAP_H__EAE405F5_0171_9592_B3C2_C19EC426AD34__INCLUDED_) */ |