| Wireshark 4.7.0 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Enumerations | Functions
dot11decrypt_system.h File Reference
`#include <stdint.h>`
`#include <stdbool.h>`
`#include "dot11decrypt_user.h"`
`#include "ws_symbol_export.h"`

Go to the source code of this file.

## Classes
struct | _DOT11DECRYPT_SEC_ASSOCIATION_ID
struct | _DOT11DECRYPT_SEC_ASSOCIATION
struct | _DOT11DECRYPT_CONTEXT
struct | _DOT11DECRYPT_FTE
struct | _DOT11DECRYPT_EAPOL_PARSED
struct | _DOT11DECRYPT_EAPOL_PARSED::DOT11DECRYPT_EAPOL_PARSED_MLO_LINK
struct | _DOT11DECRYPT_EAPOL_PARSED::DOT11DECRYPT_EAPOL_PARSED_MLO_GTK
struct | _DOT11DECRYPT_ASSOC_PARSED

## Macros
#define | DOT11DECRYPT_RET_SUCCESS 0
#define | DOT11DECRYPT_RET_UNSUCCESS 1
#define | DOT11DECRYPT_RET_NO_DATA 1
#define | DOT11DECRYPT_RET_WRONG_DATA_SIZE 2
#define | DOT11DECRYPT_RET_REQ_DATA 3
#define | DOT11DECRYPT_RET_NO_VALID_HANDSHAKE 4
#define | DOT11DECRYPT_RET_NO_DATA_ENCRYPTED 5
#define | DOT11DECRYPT_RET_SUCCESS_HANDSHAKE -1
#define | DOT11DECRYPT_MAX_KEYS_NR 64
#define | DOT11DECRYPT_WPA_NONCE_LEN 32
#define | DOT11DECRYPT_WPA_PTK_MAX_LEN 96 /* TKIP 48, AKM 18/24/25 96 */
#define | DOT11DECRYPT_WPA_MICKEY_MAX_LEN 32
#define | DOT11DECRYPT_WEP_128_KEY_LEN 16 /* 128 bits */
#define | DOT11DECRYPT_MAC_LEN 6
#define | DOT11DECRYPT_RADIOTAP_HEADER_LEN 24
#define | DOT11DECRYPT_EAPOL_MAX_LEN 1024U
#define | DOT11DECRYPT_TK_LEN 16
#define | DOT11DECRYPT_MAX_CAPLEN (12 * 1024)
#define | DOT11DECRYPT_WEP_IVLEN 3 /* 24bit */
#define | DOT11DECRYPT_WEP_KIDLEN 1 /* 1 octet */
#define | DOT11DECRYPT_WEP_ICV 4
#define | DOT11DECRYPT_WEP_HEADER DOT11DECRYPT_WEP_IVLEN + DOT11DECRYPT_WEP_KIDLEN
#define | DOT11DECRYPT_WEP_TRAILER DOT11DECRYPT_WEP_ICV
#define | DOT11DECRYPT_RSNA_EXTIV 0x20
#define | DOT11DECRYPT_RSNA_EXTIVLEN 4 /* extended IV length */
#define | DOT11DECRYPT_TKIP_MICLEN 8 /* trailing MIC */
#define | DOT11DECRYPT_RSNA_HEADER DOT11DECRYPT_WEP_HEADER + DOT11DECRYPT_RSNA_EXTIVLEN
#define | DOT11DECRYPT_CCMP_HEADER DOT11DECRYPT_RSNA_HEADER
#define | DOT11DECRYPT_CCMP_TRAILER 8 /* IEEE 802.11-2016 12.5.3.2 CCMP MPDU format */
#define | DOT11DECRYPT_CCMP_256_TRAILER 16 /* IEEE 802.11-2016 12.5.3.2 CCMP MPDU format */
#define | DOT11DECRYPT_GCMP_HEADER 8 /* IEEE 802.11-206 12.5.5.2 GCMP MPDU format */
#define | DOT11DECRYPT_GCMP_TRAILER 16
#define | DOT11DECRYPT_TKIP_HEADER DOT11DECRYPT_RSNA_HEADER
#define | DOT11DECRYPT_TKIP_TRAILER DOT11DECRYPT_TKIP_MICLEN + DOT11DECRYPT_WEP_ICV
#define | DOT11DECRYPT_RSNA_MIN_TRAILER 8
#define | DOT11DECRYPT_MAX_MLO_LINKS 3

## Typedefs
typedef struct _DOT11DECRYPT_SEC_ASSOCIATION_ID | DOT11DECRYPT_SEC_ASSOCIATION_ID
typedef struct _DOT11DECRYPT_SEC_ASSOCIATION_ID * | PDOT11DECRYPT_SEC_ASSOCIATION_ID
typedef struct _DOT11DECRYPT_SEC_ASSOCIATION | DOT11DECRYPT_SEC_ASSOCIATION
typedef struct _DOT11DECRYPT_SEC_ASSOCIATION * | PDOT11DECRYPT_SEC_ASSOCIATION
typedef struct _DOT11DECRYPT_CONTEXT | DOT11DECRYPT_CONTEXT
typedef struct _DOT11DECRYPT_CONTEXT * | PDOT11DECRYPT_CONTEXT
typedef enum _DOT11DECRYPT_HS_MSG_TYPE | DOT11DECRYPT_HS_MSG_TYPE
typedef struct _DOT11DECRYPT_FTE | DOT11DECRYPT_FTE
typedef struct _DOT11DECRYPT_FTE * | PDOT11DECRYPT_FTE
typedef struct _DOT11DECRYPT_EAPOL_PARSED | DOT11DECRYPT_EAPOL_PARSED
typedef struct _DOT11DECRYPT_EAPOL_PARSED * | PDOT11DECRYPT_EAPOL_PARSED
typedef struct _DOT11DECRYPT_ASSOC_PARSED | DOT11DECRYPT_ASSOC_PARSED
typedef struct _DOT11DECRYPT_ASSOC_PARSED * | PDOT11DECRYPT_ASSOC_PARSED

## Enumerations
enum | _DOT11DECRYPT_HS_MSG_TYPE { DOT11DECRYPT_HS_MSG_TYPE_INVALID = 0 , DOT11DECRYPT_HS_MSG_TYPE_4WHS_1 , DOT11DECRYPT_HS_MSG_TYPE_4WHS_2 , DOT11DECRYPT_HS_MSG_TYPE_4WHS_3 , DOT11DECRYPT_HS_MSG_TYPE_4WHS_4 , DOT11DECRYPT_HS_MSG_TYPE_GHS_1 , DOT11DECRYPT_HS_MSG_TYPE_GHS_2 }

## Functions
int | Dot11DecryptDecryptPacket (PDOT11DECRYPT_CONTEXT ctx, const uint8_t *data, const unsigned data_off, const unsigned data_len, unsigned char *decrypt_data, uint32_t *decrypt_len, PDOT11DECRYPT_KEY_ITEM key)
int | Dot11DecryptDecryptKeyData (PDOT11DECRYPT_CONTEXT ctx, PDOT11DECRYPT_EAPOL_PARSED eapol_parsed, const unsigned char bssid[6], const unsigned char sta[6], unsigned char *decrypted_data, unsigned *decrypted_len, PDOT11DECRYPT_KEY_ITEM key)
int | Dot11DecryptScanEapolForKeys (PDOT11DECRYPT_CONTEXT ctx, PDOT11DECRYPT_EAPOL_PARSED eapol_parsed, const uint8_t *eapol_raw, const unsigned tot_len, const unsigned char bssid[6], const unsigned char sta[6])
int | Dot11DecryptScanFtAssocForKeys (const PDOT11DECRYPT_CONTEXT ctx, const PDOT11DECRYPT_ASSOC_PARSED assoc_parsed, uint8_t *decrypted_gtk, size_t *decrypted_len, DOT11DECRYPT_KEY_ITEM *used_key)
int | Dot11DecryptScanTdlsForKeys (PDOT11DECRYPT_CONTEXT ctx, const uint8_t *data, const unsigned tot_len)
int | Dot11DecryptGetKCK (const PDOT11DECRYPT_KEY_ITEM key, const uint8_t **kck)
int | Dot11DecryptGetKEK (const PDOT11DECRYPT_KEY_ITEM key, const uint8_t **kek)
| Retrieves the Key Encryption Key (KEK) for a given decryption key item.
int | Dot11DecryptGetTK (const PDOT11DECRYPT_KEY_ITEM key, const uint8_t **tk)
| Retrieves the TK (Temporal Key) from a given key item.
int | Dot11DecryptGetGTK (const PDOT11DECRYPT_KEY_ITEM key, const uint8_t **gtk)
| Retrieves the GTK (Group Temporal Key) from a given key item.
int | Dot11DecryptSetKeys (PDOT11DECRYPT_CONTEXT ctx, DOT11DECRYPT_KEY_ITEM keys[], const size_t keys_nr)
int | Dot11DecryptSetLastSSID (PDOT11DECRYPT_CONTEXT ctx, char *pkt_ssid, size_t pkt_ssid_len)
WS_DLL_PUBLIC int | Dot11DecryptInitContext (PDOT11DECRYPT_CONTEXT ctx)
WS_DLL_PUBLIC int | Dot11DecryptDestroyContext (PDOT11DECRYPT_CONTEXT ctx)

## Detailed Description

Copyright (c) 2006 CACE Technologies, Davis (California) All rights reserved.

SPDX-License-Identifier: (BSD-3-Clause OR GPL-2.0-only)

## Function Documentation

## ◆ Dot11DecryptDecryptKeyData()

int Dot11DecryptDecryptKeyData | ( | PDOT11DECRYPT_CONTEXT | ctx,
|  | PDOT11DECRYPT_EAPOL_PARSED | eapol_parsed,
|  | const unsigned char | bssid[6],
|  | const unsigned char | sta[6],
|  | unsigned char * | decrypted_data,
|  | unsigned * | decrypted_len,
|  | PDOT11DECRYPT_KEY_ITEM | key
| ) |  |
| extern

This will try to decrypt the encrypted keydata field of an EAPOL KEY frame.

Parameters

  ctx | [IN] Pointer to the current context
  eapol_parsed | [IN] Extracted/Parsed pieces of eapol frame
  bssid | [IN] bssid of AP
  sta | [IN] sta MAC address
  decrypted_data | [OUT] Pointer to a buffer that will contain decrypted data. Must have room for at least DOT11DECRYPT_EAPOL_MAX_LEN bytes.
  decrypted_len | [OUT] Length of decrypted data.
  key | [OUT] Pointer to a preallocated key structure containing the key used during the decryption process (if done). If this parameter is set to NULL, the key will be not returned.

Returns
  - DOT11DECRYPT_RET_SUCCESS: Decryption has been done (decrypt_data and decrypt_length will contain the packet data decrypted and the length of the new packet)
  - DOT11DECRYPT_RET_UNSUCCESS: Generic unspecified error (decrypt_data and decrypt_length will be not modified).

## ◆ Dot11DecryptDecryptPacket()

int Dot11DecryptDecryptPacket | ( | PDOT11DECRYPT_CONTEXT | ctx,
|  | const uint8_t * | data,
|  | const unsigned | data_off,
|  | const unsigned | data_len,
|  | unsigned char * | decrypt_data,
|  | uint32_t * | decrypt_len,
|  | PDOT11DECRYPT_KEY_ITEM | key
| ) |  |
| extern

This will try to decrypt a 802.11 frame.

Parameters

  ctx | [IN] Pointer to the current context
  data | [IN] Pointer to a buffer with an 802.11 frame, including MAC header and payload
  data_off | [IN] Payload offset (aka the MAC header length)
  data_len | [IN] Total length of the MAC header and the payload
  decrypt_data | [OUT] Pointer to a buffer that will contain decrypted data. Must have room for at least DOT11DECRYPT_MAX_CAPLEN bytes.
  decrypt_len | [OUT] Length of decrypted data.
  key | [OUT] Pointer to a preallocated key structure containing the key used during the decryption process (if done). If this parameter is set to NULL, the key will be not returned.

Returns
  - DOT11DECRYPT_RET_SUCCESS: Decryption has been done (decrypt_data and decrypt_length will contain the packet data decrypted and the length of the new packet)
  - DOT11DECRYPT_RET_NO_DATA: The packet is not a data packet
  - DOT11DECRYPT_RET_WRONG_DATA_SIZE: The size of the packet is below the accepted minimum
  - DOT11DECRYPT_RET_REQ_DATA: Required data is not available and the processing must be interrupted
  - DOT11DECRYPT_RET_NO_DATA_ENCRYPTED: Not encrypted
  - DOT11DECRYPT_RET_UNSUCCESS: Generic unspecified error (decrypt_data and decrypt_length will be not modified).

Note
  The decrypted buffer should be allocated for a size equal or greater than the packet data buffer size. Before decryption process original data is copied in the buffer pointed by decrypt_data not to modify the original packet.
  The length of decrypted data will consider the entire 802.11 frame (thus the MAC header, the frame body and the recalculated FCS -if initially present-)
  This function is not thread-safe when used in parallel with context management functions on the same context.

## ◆ Dot11DecryptDestroyContext()

WS_DLL_PUBLIC int Dot11DecryptDestroyContext | ( | PDOT11DECRYPT_CONTEXT | ctx | ) |

Clean up the specified context. After the cleanup the pointer should not be used anymore.

Parameters

  ctx | [IN|OUT] pointer to the current context structure

Returns
  DOT11DECRYPT_RET_SUCCESS: the context has been successfully initialized DOT11DECRYPT_RET_UNSUCCESS: the context has not been initialized

Note
  This function is not thread-safe when used in parallel with context management functions and the packet process function on the same context.

## ◆ Dot11DecryptGetGTK()

int Dot11DecryptGetGTK | ( | const PDOT11DECRYPT_KEY_ITEM | key,
|  | const uint8_t ** | gtk
| ) |  |

Retrieves the GTK (Group Temporal Key) from a given key item.

This function extracts the Group Temporal Key (GTK) from the provided key item and stores it in the gtk pointer.

Parameters

  key | Pointer to the DOT11DECRYPT_KEY_ITEM containing the encryption keys.
  gtk | Pointer to store the retrieved GTK.

Returns
  The length of the GTK if successful, 0 otherwise.

## ◆ Dot11DecryptGetKCK()

int Dot11DecryptGetKCK | ( | const PDOT11DECRYPT_KEY_ITEM | key,
|  | const uint8_t ** | kck
| ) |  |

These are helper functions to retrieve KCK, KEK, TK portion of PTK for a certain "key"

Parameters

  key | [IN] Pointer to a key structure containing the key retrieved from functions Dot11DecryptDecryptPacket, Dot11DecryptKeydata
  kck | [OUT] Pointer to the KCK/KEK/TK portion of PTK.

Returns
  length in bytes of KCK/KEK/TK

## ◆ Dot11DecryptGetKEK()

int Dot11DecryptGetKEK | ( | const PDOT11DECRYPT_KEY_ITEM | key,
|  | const uint8_t ** | kek
| ) |  |

Retrieves the Key Encryption Key (KEK) for a given decryption key item.

Parameters

  kek | Pointer to a pointer that will receive the KEK data.

Returns
  The length of the KEK in bytes, or 0 if an error occurred.

## ◆ Dot11DecryptGetTK()

int Dot11DecryptGetTK | ( | const PDOT11DECRYPT_KEY_ITEM | key,
|  | const uint8_t ** | tk
| ) |  |

Retrieves the TK (Temporal Key) from a given key item.

This function extracts the TK from a DOT11DECRYPT_KEY_ITEM and returns its pointer along with its length.

Parameters

  key | Pointer to the DOT11DECRYPT_KEY_ITEM containing the key information.
  tk | Pointer to store the extracted TK.

Returns
  Length of the TK in bytes, or 0 if an error occurred.

## ◆ Dot11DecryptInitContext()

WS_DLL_PUBLIC int Dot11DecryptInitContext | ( | PDOT11DECRYPT_CONTEXT | ctx | ) |

Initialize a context used to manage decryption and keys collection.

Parameters

  ctx | [IN|OUT] pointer to a preallocated context structure

Returns
  DOT11DECRYPT_RET_SUCCESS: the context has been successfully initialized DOT11DECRYPT_RET_UNSUCCESS: the context has not been initialized

Note
  Only a correctly initialized context can be used to manage decryption processes and keys.
  This function is not thread-safe when used in parallel with context management functions and the packet process function on the same context.

## ◆ Dot11DecryptScanEapolForKeys()

int Dot11DecryptScanEapolForKeys | ( | PDOT11DECRYPT_CONTEXT | ctx,
|  | PDOT11DECRYPT_EAPOL_PARSED | eapol_parsed,
|  | const uint8_t * | eapol_raw,
|  | const unsigned | tot_len,
|  | const unsigned char | bssid[6],
|  | const unsigned char | sta[6]
| ) |  |
| extern

This will try to extract keys from an EAPOL frame and add corresponding SAs to current context. eapol_parsed must contain the already parsed EAPOL key frame and for frames that contain encrypted EAPOL keydata the keydata must first be decrypted with Dot11DecryptDecryptKeyData before calling this function.

Parameters

  ctx | [IN] Pointer to the current context
  eapol_parsed | [IN] Extracted/Parsed pieces of eapol frame
  eapol_raw | [IN] Pointer to a buffer with an EAPOL frame
  tot_len | [IN] Total length of the EAPOL frame
  bssid | [IN] bssid of AP
  sta | [IN] sta MAC address

Returns
  - DOT11DECRYPT_RET_REQ_DATA: Required data is not available and the processing must be interrupted
  - DOT11DECRYPT_RET_UNSUCCESS: Generic unspecified error (decrypt_data and decrypt_length will be not modified).
  - DOT11DECRYPT_RET_SUCCESS_HANDSHAKE: An eapol handshake packet was successfuly parsed and key information extracted.
  - DOT11DECRYPT_RET_NO_VALID_HANDSHAKE: The handshake is invalid or was not used for some reason. For encrypted packets decryption was still successful.

Note
  This function is not thread-safe when used in parallel with context management functions on the same context.

## ◆ Dot11DecryptScanFtAssocForKeys()

int Dot11DecryptScanFtAssocForKeys | ( | const PDOT11DECRYPT_CONTEXT | ctx,
|  | const PDOT11DECRYPT_ASSOC_PARSED | assoc_parsed,
|  | uint8_t * | decrypted_gtk,
|  | size_t * | decrypted_len,
|  | DOT11DECRYPT_KEY_ITEM * | used_key
| ) |  |

This will try to extract keys from an FT (re)association frame and add corresponding SAs to current context. assoc_parsed must contain the already parsed association frame content. If the FT BSS Transition IE contains an encrypted GTK subelem and decryption is successful the decrypted GTK will be returned in decrypted_gtk.

Parameters

  ctx | [IN] Pointer to the current context
  assoc_parsed | [IN] Extracted/Parsed pieces of association frame
  decrypted_gtk | [OUT] Buffer for decrypted GTK subelem
  decrypted_len | [OUT] Decrypted GTK subelem key length
  used_key | [OUT] Buffer to hold the key used during the decryption process.

Returns
  - DOT11DECRYPT_RET_UNSUCCESS: Generic unspecified error (decrypted_gtk and decrypted_len will be not modified).
  - DOT11DECRYPT_RET_SUCCESS_HANDSHAKE: An association frame was successfuly parsed and key information extracted.
  - DOT11DECRYPT_RET_NO_VALID_HANDSHAKE: The association is invalid or no matching key for decryption was found.

## ◆ Dot11DecryptScanTdlsForKeys()

int Dot11DecryptScanTdlsForKeys | ( | PDOT11DECRYPT_CONTEXT | ctx,
|  | const uint8_t * | data,
|  | const unsigned | tot_len
| ) |  |
| extern

This will try to extract keys from a TDLS action frame (without MAC headers) and add corresponding SAs to current context.

Parameters

  ctx | [IN] Pointer to the current context
  data | [IN] Pointer to a buffer with a TDLS action frame
  tot_len | [IN] Total length of the TDLS action frame

Returns
  - DOT11DECRYPT_RET_REQ_DATA: Required data is not available and the processing must be interrupted
  - DOT11DECRYPT_RET_SUCCESS_HANDSHAKE: The TDLS action frame was successfuly parsed and key information extracted.
  - DOT11DECRYPT_RET_NO_VALID_HANDSHAKE: No keys extracted

## ◆ Dot11DecryptSetKeys()

int Dot11DecryptSetKeys | ( | PDOT11DECRYPT_CONTEXT | ctx,
|  | DOT11DECRYPT_KEY_ITEM | keys[],
|  | const size_t | keys_nr
| ) |  |
| extern

It sets a new keys collection to use during packet processing. Any key should be well-formed, thus: it should have a defined key type and the specified length should be conforming WEP or WPA/WPA2 standards. A general WEP keys could be of any length (in the range defined in DOT11DECRYPT_KEY_ITEM), if a specific WEP key is used, the length of the key will be the one specified in 802.11i-2004 (40 bits or 104 bits). For WPA/WPA2 the password (passphrase and SSID), the PSK and the PMK are in alternative, as explain in the DOT11DECRYPT_KEY_ITEM structure description.

Parameters

  ctx | [IN] pointer to the current context
  keys | [IN] an array of keys to set.
  keys_nr | [IN] the size of the keys array

Returns
  The number of keys correctly inserted in the current database.

Note
  Before inserting new keys, the current database will be cleaned.
  This function is not thread-safe when used in parallel with context management functions and the packet process function on the same context.

## ◆ Dot11DecryptSetLastSSID()

int Dot11DecryptSetLastSSID | ( | PDOT11DECRYPT_CONTEXT | ctx,
|  | char * | pkt_ssid,
|  | size_t | pkt_ssid_len
| ) |  |

Sets the "last seen" SSID. This allows us to pick up previous SSIDs and use them when "wildcard" passphrases are specified in the preferences.

Parameters

  ctx | [IN|OUT] pointer to a preallocated context structure
  pkt_ssid | [IN] pointer to the packet's SSID
  pkt_ssid_len | [IN] length of the packet's SSID

Returns
  DOT11DECRYPT_RET_SUCCESS: The key has been set. DOT11DECRYPT_RET_UNSUCCESS: The has not been set, e.g. the length was too long.