> For the complete documentation index, see [llms.txt](https://documentation.hak5.org/wifi-pineapple-pager/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.hak5.org/wifi-pineapple-pager/handshake-collection.md).

# Handshake Collection

Wi-Fi networks using the WPA-PSK and WPA2-PSK suites are vulnerable to an offline dictionary attack against the secret key.

{% hint style="info" %}
An *offline attack* means the attacker has collected all the information needed to attempt to attack the network key, and can do so at leisure.\
\
Offline attacks are typically performed on a computer with a GPU to accelerate calculations, and with password lists of hundreds of thousands or millions of attempts.
{% endhint %}

### WPA Handshakes  <a href="#wpa-handshakes" id="wpa-handshakes"></a>

Rather than simply using the same encryption key for all clients, when a device joins a WPA-PSK or WPA2-PSK network, it performs a special packet exchange - dubbed a handshake - to establish a temporary key which the client uses.

By collecting this handshake, it is possible to attempt to recreate the secret data by trying thousands (or millions) of passwords. When the secret matches, you now know the original pre-shared key (PSK).

Handshakes are generated when a client connects to a network and when a client session is refreshed (by default, each client refreshes the temporary encryption data every 300 seconds, or 5 minutes.)

### Collecting handshakes  <a href="#collecting-handshakes" id="collecting-handshakes"></a>

Collecting a handshake requires several things:

1. A client actively connecting to a WPA-PSK or WPA2-PSK network. Handshakes are only generated when a client is connecting.
2. The Wi-Fi Pineapple Pager must be on the correct channel at this moment. During normal [recon mode](/wifi-pineapple-pager/recon.md) the Pager rapidly changes channels to build a view of the Wi-Fi environment.
3. Critical portions of the handshake must be captured. A handshake consists of 4 specific packets; to successfully attack a handshake specific packets from each side of the conversation are required.

### Difficulties in collecting handshakes  <a href="#difficulties-in-collecting-handshakes" id="difficulties-in-collecting-handshakes"></a>

Collecting handshakes in the wild faces several challenges. Understanding these challenges and where they stem from can help explain the behavior:

1. Handshakes are extremely intermittent. A handshake is only generated when a client *joins a WPA-PSK network*, or when a client *renews the connection* with a WPA-PSK network. On standard networks, the encryption for each client is renewed every 5 minutes.
2. Handshakes are data packets. This has significant implications for capture, because data packets are subject to speed scaling on Wi-Fi networks. The higher the data rata a packet is sent with, the harder it can be to capture. Higher speed packets may also be sent as MIMO packets, in which multiple antennas are used to transmit and receive the packet.
3. Handshakes are not available on 6GHz networks. Moving security forwards can be difficult; to accomplish this, the Wi-Fi standards board often blocks older encryption when introducing new standards. As part of this initiative, security standards older than WPA3 can not be used on 6GHz networks.
4. Handshakes are not available on WPA3 5GHz or 2.4GHz networks. While research on weaknesses in WPA3 continues, they are not currently vulnerable to offline attacks that WPA1 and WPA2 networks are vulnerable to.
5. Handshakes are more visible on 2.4GHz networks. Wi-Fi channels on 2.4 GHz networks overlap; capturing on one channel may show packets from several channels in either direction. Wi-Fi devices typically will not enable MIMO on 2.4GHz and data is generally sent at lower data rates, which makes capturing handshake packets simpler.

{% hint style="info" %}
Handshake capture can sometimes be difficult for all these reasons, and the fact that handshakes are transmitted as `data packets`. While beacon packets (network advertisements) are `management packets` which are typically sent at lower transmission speeds, `data packets` are subject to automatic speed scaling.\
\
Based on the capabilities of the client and access point, and the signal quality of the connection, data packets can be sent at variable speeds. The higher the capabilities and connection quality, the faster the data rate used for clients.\
\
As the data rate of the packets increases, it becomes more difficult to passively capture a packet. Higher speeds are transmitted with more complex encodings, and on multiple antenna systems, they are transmitted with radio modes which can make capture very challenging. The Pineapple recon engine is designed to maximize the chances of capturing a handshake, including setting channel configuration to capture the most data encoding types possible, and pausing channel hopping the instant the first packet in a handshake is seen.\
\
It may be necessary to monitor for a long period of time (even up to hours, in a completely passive environment) to capture a full handshake - this is a normal part of how Wi-Fi operates.
{% endhint %}

### Maximizing handshake collection  <a href="#maximizing-handshake-collection" id="maximizing-handshake-collection"></a>

To maximize handshake collection, the Pager can be set to a specific channel. This can be done using the DuckyScript commands `PINEAPPLE_EXAMINE_CHANNEL` and `PINEAPPLE_EXAMINE_BSSID` to stop channel hopping and pause on a single channel, or to automatically find the channel of a known access point and pause hopping, respectively.

These commands can be run from a `ssh` session or the terminal in the [Virtual Pager](/wifi-pineapple-pager/connecting-to-the-wifi-pineapple-pager/virtual-pager.md), or activated by user or recon payloads.

When locked to a channel, the Pager has the maximum chance of collecting handshakes, but will not be able to monitor devices or access points on other channels.

Handshake collection can be combined with client deauthentication to increase the chances of capture - whenever a client joins a network it performs a handshake, so by forcing clients to reconnect, new handshakes may be generated. The Pineapple client disconnection feature can be triggred from the command line or a payload using the `PINEAPPLE_DEAUTH_CLIENT` command.

{% hint style="warning" %}
Be sure to only trigger client deauthentication against networks that are in the scope of your engagement!\
\
Deauthenticating clients from networks which aren’t yours and which you haven’t been given permission to test isn’t only a jerk move, it may be illegal in some jurisdictions. Know the laws of your region!
{% endhint %}

Return to normal recon mode with `PINEAPPLE_EXAMINE_RESET`.

### Downloading Handshakes <a href="#downloading-handshakes" id="downloading-handshakes"></a>

Captured handshakes are stored in `/root/loot/handshakes/`. Handshake files are stored in the original `pcap` format and the [Hashcat](https://hashcat.net/) hcappx format.

You can download handshakes from your Pager using [scp or sftp](/wifi-pineapple-pager/connecting-to-the-wifi-pineapple-pager/ssh-and-the-wifi-pineapple-pager.md), or by downloading loot via the [Virtual Pager](/wifi-pineapple-pager/connecting-to-the-wifi-pineapple-pager/virtual-pager.md).

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.hak5.org/wifi-pineapple-pager/handshake-collection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.