Wireshark 4.5.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_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   88 /* TKIP 48, CCMP 64, GCMP-256 88 bytes */
 
#define DOT11DECRYPT_WPA_MICKEY_MAX_LEN   24
 
#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   8192
 
#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_CRC_LEN   4
 

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[DOT11DECRYPT_MAC_LEN], const unsigned char sta[DOT11DECRYPT_MAC_LEN], 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[DOT11DECRYPT_MAC_LEN], const unsigned char sta[DOT11DECRYPT_MAC_LEN])
 
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)
 
int Dot11DecryptGetTK (const PDOT11DECRYPT_KEY_ITEM key, const uint8_t **tk)
 
int Dot11DecryptGetGTK (const PDOT11DECRYPT_KEY_ITEM key, const uint8_t **gtk)
 
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[DOT11DECRYPT_MAC_LEN],
const unsigned char  sta[DOT11DECRYPT_MAC_LEN],
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.

◆ 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

◆ 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[DOT11DECRYPT_MAC_LEN],
const unsigned char  sta[DOT11DECRYPT_MAC_LEN] 
)
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.
Generated by doxygen 1.9.8