epan/crypt/dot11decrypt_user.h

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