libtins  4.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Pages
Public Types | Public Member Functions | List of all members
Tins::Crypto::WPA2Decrypter Class Reference

Decrypts WPA2-encrypted traffic. More...

#include <crypto.h>

Public Types

typedef HWAddress< 6 > address_type
 
typedef std::pair
< address_type, address_type
addr_pair
 Represents a pair of mac addresses. More...
 
typedef std::map< addr_pair,
WPA2::SessionKeys
keys_map
 Maps an address pair to the session keys. More...
 
typedef std::function< void(const
std::string &, const
address_type &)> 
ap_found_callback_type
 The type used to store the callback type used when a new access point is found. More...
 
typedef std::function< void(const
std::string &, const
address_type &, const
address_type &)> 
handshake_captured_callback_type
 

Public Member Functions

void add_ap_data (const std::string &psk, const std::string &ssid)
 Adds an access points's information. More...
 
void add_ap_data (const std::string &psk, const std::string &ssid, const address_type &addr)
 Adds a access points's information, including its BSSID. More...
 
void add_decryption_keys (const addr_pair &addresses, const WPA2::SessionKeys &session_keys)
 Explicitly add decryption keys. More...
 
bool decrypt (PDU &pdu)
 Decrypts the provided PDU. More...
 
void handshake_captured_callback (const handshake_captured_callback_type &callback)
 Sets the handshake captured callback. More...
 
void ap_found_callback (const ap_found_callback_type &callback)
 Sets the access point found callback. More...
 
const keys_mapget_keys () const
 Getter for the keys on this decrypter. More...
 

Detailed Description

Decrypts WPA2-encrypted traffic.

This class takes valid PSK and SSID tuples, captures client handshakes, and decrypts their traffic afterwards.

Member Typedef Documentation

Represents a pair of mac addresses.

This is used to identify a host and the access point to which it is connected. The first element in the pair will always de lower or equal than the second one, so that given any host and the access point it's connected to, we can uniquely identify it with an address pair.

typedef std::function<void(const std::string&, const address_type&)> Tins::Crypto::WPA2Decrypter::ap_found_callback_type

The type used to store the callback type used when a new access point is found.

The first argument to the function will be the access point's SSID and the second one its BSSID.

typedef std::function<void(const std::string&, const address_type&, const address_type&)> Tins::Crypto::WPA2Decrypter::handshake_captured_callback_type

The type used to store the callback type used when a new handshake is captured.

The first argument to the function will be the access point's SSID and the second one its BSSID. The third argument will be the client's hardware address.

Maps an address pair to the session keys.

This type associates an address pair (host, access point) with the session keys, as generated using the packets seen on a handshake.

See Also
addr_pair

Member Function Documentation

void Tins::Crypto::WPA2Decrypter::add_ap_data ( const std::string &  psk,
const std::string &  ssid 
)

Adds an access points's information.

This associates an SSID with a PSK, and allows the decryption of any BSSIDs that broadcast the same SSID.

The decrypter will inspect beacon frames, looking for SSID tags that contain the given SSID.

Note that using this overload, the decryption of data frames and handshake capturing will be disabled until any access point broadcasts the provided SSID(this shouldn't take long at all). If this is not the desired behaviour, then you should check out the ovther add_ap_data overload.

Parameters
pskThe PSK associated with the SSID.
ssidThe network's SSID.
void Tins::Crypto::WPA2Decrypter::add_ap_data ( const std::string &  psk,
const std::string &  ssid,
const address_type addr 
)

Adds a access points's information, including its BSSID.

This overload can be used if the BSSID associated with this SSID is known beforehand. The addr parameter indicates which specific BSSID is associated to the SSID.

Note that if any other access point broadcasts the provided SSID, it will be taken into account as well.

Parameters
pskThe PSK associated with this SSID.
ssidThe network's SSID.
addrThe access point's BSSID.
void Tins::Crypto::WPA2Decrypter::add_decryption_keys ( const addr_pair addresses,
const WPA2::SessionKeys session_keys 
)

Explicitly add decryption keys.

This method associates a pair (host, access point) with the given decryption keys. All encrypted packets sent between the given addresses will be decrypted using the provided keys.

This method shouldn't normally be required. The WPA2Decrypter will be waiting for handshakes and will automatically extract the session keys, decrypting all encrypted packets with them. You should only use this method if for some reason you know the actual keys being used (because you checked and stored the keys_map somewhere).

The actual order of the addresses doesn't matter, this method will make sure they're sorted.

Parameters
addressesThe address pair (host, access point) to associate.
session_keysThe keys to use when decrypting messages sent between the given addresses.
void Tins::Crypto::WPA2Decrypter::ap_found_callback ( const ap_found_callback_type callback)

Sets the access point found callback.

This callback will be executed every time a new access point is found, that's advertising an SSID added when calling add_ap_data.

See Also
ap_found_callback_type
Parameters
callbackThe new callback to be set
bool Tins::Crypto::WPA2Decrypter::decrypt ( PDU pdu)

Decrypts the provided PDU.

A Dot11Data PDU is looked up inside the provided PDU chain. If no such PDU exists or no PSK was associated with the SSID broadcasted by the Dot11 packet's BSSID, or no EAPOL handshake was captured for the client involved in the communication, then the PDU is left intact.

Otherwise, the packet is decrypted using the generated PTK. If the resulting MIC is invalid, then the packet is left intact.

Returns
false if no decryption was performed, or the decryption failed, true otherwise.
const keys_map& Tins::Crypto::WPA2Decrypter::get_keys ( ) const

Getter for the keys on this decrypter.

The returned map will be populated every time a new, complete, handshake is captured.

Returns
The WPA2Decrypter keys map.
void Tins::Crypto::WPA2Decrypter::handshake_captured_callback ( const handshake_captured_callback_type callback)

Sets the handshake captured callback.

This callback will be executed every time a new handshake is captured.

See Also
handshake_captured_callback_type
Parameters
callbackThe new callback to be set

The documentation for this class was generated from the following file: