1 /* dot11decrypt_user.h 2 * 3 * Copyright (c) 2006 CACE Technologies, Davis (California) 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: (BSD-3-Clause OR GPL-2.0-only) 7 */ 8 9 #ifndef _DOT11DECRYPT_USER_H 10 #define _DOT11DECRYPT_USER_H 11 12 /******************************************************************************/ 13 /* File includes */ 14 /* */ 15 #include "dot11decrypt_interop.h" 16 #include "ws_symbol_export.h" 17 18 /* */ 19 /* */ 20 /******************************************************************************/ 21 22 /******************************************************************************/ 23 /* Constant definitions */ 24 /* */ 25 /* Decryption key types */ 26 #define DOT11DECRYPT_KEY_TYPE_WEP 0 27 #define DOT11DECRYPT_KEY_TYPE_WEP_40 1 28 #define DOT11DECRYPT_KEY_TYPE_WEP_104 2 29 #define DOT11DECRYPT_KEY_TYPE_WPA_PWD 3 30 #define DOT11DECRYPT_KEY_TYPE_WPA_PSK 4 31 #define DOT11DECRYPT_KEY_TYPE_WPA_PMK 5 32 #define DOT11DECRYPT_KEY_TYPE_TK 6 33 #define DOT11DECRYPT_KEY_TYPE_MSK 7 34 35 #define DOT11DECRYPT_KEY_TYPE_TKIP 100 36 #define DOT11DECRYPT_KEY_TYPE_CCMP 101 37 #define DOT11DECRYPT_KEY_TYPE_CCMP_256 102 38 #define DOT11DECRYPT_KEY_TYPE_GCMP 103 39 #define DOT11DECRYPT_KEY_TYPE_GCMP_256 104 40 #define DOT11DECRYPT_KEY_TYPE_UNKNOWN -1 41 42 /* Decryption algorithms fields size definition (bytes) */ 43 #define DOT11DECRYPT_WEP_KEY_MINLEN 1 44 #define DOT11DECRYPT_WEP_KEY_MAXLEN 32 45 #define DOT11DECRYPT_WEP_40_KEY_LEN 5 46 #define DOT11DECRYPT_WEP_104_KEY_LEN 13 47 48 #define DOT11DECRYPT_WPA_PASSPHRASE_MIN_LEN 8 49 #define DOT11DECRYPT_WPA_PASSPHRASE_MAX_LEN 63 /* null-terminated string, the actual length of the storage is 64 */ 50 #define DOT11DECRYPT_WPA_SSID_MIN_LEN 0 51 #define DOT11DECRYPT_WPA_SSID_MAX_LEN 32 52 #define DOT11DECRYPT_WPA_PMK_MAX_LEN 48 53 #define DOT11DECRYPT_WPA_PWD_PSK_LEN 32 54 #define DOT11DECRYPT_TK_MAX_LEN 32 55 #define DOT11DECRYPT_MSK_MIN_LEN 64 56 #define DOT11DECRYPT_MSK_MAX_LEN 128 57 /* */ 58 /* */ 59 /******************************************************************************/ 60 61 /******************************************************************************/ 62 /* Macro definitions */ 63 /* */ 64 /* */ 65 /******************************************************************************/ 66 67 /******************************************************************************/ 68 /* Type definitions */ 69 /* */ 70 /** 71 * Struct to store info about a specific decryption key. 72 */ 73 typedef struct { 74 GString *key; 75 GByteArray *ssid; 76 guint bits; 77 guint type; 78 } decryption_key_t; 79 80 /** 81 * Key item used during the decryption process. 82 */ 83 typedef struct _DOT11DECRYPT_KEY_ITEM { 84 /** 85 * Type of key. The type will remain unchanged during the 86 * processing, even if some fields could be changed (e.g., WPA 87 * fields). 88 * @note 89 * You can use constants DOT11DECRYPT_KEY_TYPE_xxx to indicate the 90 * key type. 91 */ 92 UINT8 KeyType; 93 94 /** 95 * Key data. 96 * This field can be used for the following decryptographic 97 * algorithms: WEP-40, with a key of 40 bits (10 hex-digits); 98 * WEP-104, with a key of 104 bits (or 26 hex-digits); WPA or 99 * WPA2. 100 * @note 101 * For WPA/WPA2, the PMK is calculated from the PSK, and the PSK 102 * is calculated from the passphrase-SSID pair. You can enter one 103 * of these 3 values and subsequent fields will be automatically 104 * calculated. 105 * @note 106 * For WPA and WPA2 this implementation will use standards as 107 * defined in 802.11i (2004) and 802.1X (2004). 108 */ 109 union DOT11DECRYPT_KEY_ITEMDATA { 110 struct DOT11DECRYPT_KEY_ITEMDATA_WEP { 111 /** 112 * The binary value of the WEP key. 113 * @note 114 * It is accepted a key of length between 115 * DOT11DECRYPT_WEP_KEY_MINLEN and 116 * DOT11DECRYPT_WEP_KEY_MAXLEN. A WEP key 117 * standard-compliante should be either 40 bits 118 * (10 hex-digits, 5 bytes) for WEP-40 or 104 bits 119 * (26 hex-digits, 13 bytes) for WEP-104. 120 */ 121 UCHAR WepKey[DOT11DECRYPT_WEP_KEY_MAXLEN]; 122 /** 123 * The length of the WEP key. Acceptable range 124 * is [DOT11DECRYPT_WEP_KEY_MINLEN;DOT11DECRYPT_WEP_KEY_MAXLEN]. 125 */ 126 size_t WepKeyLen; 127 } Wep; 128 129 /** 130 * WPA/WPA2 key data. Note that the decryption process 131 * will use the PMK (equal to PSK), that is calculated 132 * from passphrase-SSID pair. You can define one of these 133 * three fields and necessary fields will be automatically 134 * calculated. 135 */ 136 struct DOT11DECRYPT_KEY_ITEMDATA_WPA { 137 UCHAR Psk[DOT11DECRYPT_WPA_PMK_MAX_LEN]; 138 UCHAR Ptk[DOT11DECRYPT_WPA_PTK_MAX_LEN]; 139 UINT8 PskLen; 140 UINT8 PtkLen; 141 UINT8 Akm; 142 UINT8 Cipher; 143 } Wpa; 144 145 } KeyData; 146 147 struct DOT11DECRYPT_KEY_ITEMDATA_TK { 148 guint8 Tk[DOT11DECRYPT_TK_MAX_LEN]; 149 guint8 Len; 150 } Tk; 151 152 struct DOT11DECRYPT_KEY_ITEMDATA_MSK { 153 guint8 Msk[DOT11DECRYPT_MSK_MAX_LEN]; 154 guint8 Len; 155 } Msk; 156 157 struct DOT11DECRYPT_KEY_ITEMDATA_PWD { 158 /** 159 * The string (null-terminated) value of 160 * the passphrase. 161 */ 162 CHAR Passphrase[DOT11DECRYPT_WPA_PASSPHRASE_MAX_LEN+1]; 163 /** 164 * The value of the SSID (up to 165 * DOT11DECRYPT_WPA_SSID_MAX_LEN octets). 166 * @note 167 * A zero-length SSID indicates broadcast. 168 */ 169 CHAR Ssid[DOT11DECRYPT_WPA_SSID_MAX_LEN]; 170 /** 171 *The length of the SSID 172 */ 173 size_t SsidLen; 174 } UserPwd; 175 } DOT11DECRYPT_KEY_ITEM, *PDOT11DECRYPT_KEY_ITEM; 176 177 /** 178 * Collection of keys to use to decrypt packets 179 */ 180 typedef struct _DOT11DECRYPT_KEYS_COLLECTION { 181 /** 182 * Number of stored keys 183 */ 184 size_t nKeys; 185 186 /** 187 * Array of nKeys keys 188 */ 189 DOT11DECRYPT_KEY_ITEM Keys[256]; 190 } DOT11DECRYPT_KEYS_COLLECTION, *PDOT11DECRYPT_KEYS_COLLECTION; 191 /* */ 192 /******************************************************************************/ 193 194 /******************************************************************************/ 195 /* Function prototype declarations */ 196 197 /** 198 * Returns the decryption_key_t struct given a string describing the key. 199 * @param key_string [IN] Key string in one of the following formats: 200 * - 0102030405 (40/64-bit WEP) 201 * - 01:02:03:04:05 (40/64-bit WEP) 202 * - 0102030405060708090a0b0c0d (104/128-bit WEP) 203 * - 01:02:03:04:05:06:07:08:09:0a:0b:0c:0d (104/128-bit WEP) 204 * - MyPassword (WPA + plaintext password + "wildcard" SSID) 205 * - MyPassword:MySSID (WPA + plaintext password + specific SSID) 206 * - 01020304... (WPA + 256-bit raw key) 207 * @param key_type [IN] Type of key used for string. Possibilities include: 208 * - DOT11DECRYPT_KEY_TYPE_WEP (40/64-bit and 104/128-bit WEP) 209 * - DOT11DECRYPT_KEY_TYPE_WPA_PWD (WPA + plaintext password + "wildcard" SSID or 210 * WPA + plaintext password + specific SSID) 211 * - DOT11DECRYPT_KEY_TYPE_WPA_PSK (WPA + 256-bit raw key) 212 * @return A pointer to a freshly-g_malloc()ed decryption_key_t struct on 213 * success, or NULL on failure. 214 * @see free_key_string() 215 */ 216 WS_DLL_PUBLIC 217 decryption_key_t* 218 parse_key_string(gchar* key_string, guint8 key_type); 219 220 /** 221 * Releases memory associated with a given decryption_key_t struct. 222 * @param dk [IN] Pointer to the key to be freed 223 * @see parse_key_string() 224 */ 225 WS_DLL_PUBLIC 226 void 227 free_key_string(decryption_key_t *dk); 228 229 /******************************************************************************/ 230 231 #endif /* _DOT11DECRYPT_USER_H */ 232