epan/crypt/airpdcap_system.h

   1 /* airpdcap_system.h
   2  *
   3  * Copyright (c) 2006 CACE Technologies, Davis (California)
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  * 3. Neither the name of the project nor the names of its contributors
  15  *    may be used to endorse or promote products derived from this software
  16  *    without specific prior written permission.
  17  *
  18  * Alternatively, this software may be distributed under the terms of the
  19  * GNU General Public License ("GPL") version 2 as published by the Free
  20  * Software Foundation.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  23  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25  * ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  26  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32  * SUCH DAMAGE.
  33  */
  34
  35 #ifndef _AIRPDCAP_SYSTEM_H
  36 #define _AIRPDCAP_SYSTEM_H
  37
  38 /************************************************************************/
  39 /*      Constant definitions                                            */
  40
  41 /*      General definitions                                             */
  42 #ifndef TRUE
  43 #define TRUE    1
  44 #endif
  45 #ifndef FALSE
  46 #define FALSE   0
  47 #endif
  48
  49 #define AIRPDCAP_RET_SUCCESS                      0
  50 #define AIRPDCAP_RET_UNSUCCESS                    1
  51
  52 #define AIRPDCAP_RET_NO_DATA                      1
  53 #define AIRPDCAP_RET_WRONG_DATA_SIZE              2
  54 #define AIRPDCAP_RET_REQ_DATA                     3
  55 #define AIRPDCAP_RET_NO_VALID_HANDSHAKE           4
  56 #define AIRPDCAP_RET_NO_DATA_ENCRYPTED            5
  57
  58 #define AIRPDCAP_RET_SUCCESS_HANDSHAKE           -1
  59
  60 #define AIRPDCAP_MAX_KEYS_NR                     64
  61 #define AIRPDCAP_MAX_SEC_ASSOCIATIONS_NR        256
  62
  63 /*      Decryption algorithms fields size definition (bytes)            */
  64 #define AIRPDCAP_WPA_NONCE_LEN                   32
  65 #define AIRPDCAP_WPA_PTK_LEN                     64     /* TKIP uses 48 bytes, CCMP uses 64 bytes       */
  66 #define AIRPDCAP_WPA_MICKEY_LEN                  16
  67
  68 #define AIRPDCAP_WEP_128_KEY_LEN                 16     /* 128 bits     */
  69
  70 /* General 802.11 constants                                             */
  71 #define AIRPDCAP_MAC_LEN                           6
  72 #define AIRPDCAP_RADIOTAP_HEADER_LEN              24
  73
  74 #define AIRPDCAP_EAPOL_MAX_LEN                  1024
  75
  76 #define AIRPDCAP_TK_LEN                           16
  77
  78 /* Max length of capture data                                           */
  79 #define AIRPDCAP_MAX_CAPLEN                     8192
  80
  81 #define AIRPDCAP_WEP_IVLEN      3       /* 24bit */
  82 #define AIRPDCAP_WEP_KIDLEN     1       /* 1 octet */
  83 #define AIRPDCAP_WEP_ICV        4
  84 #define AIRPDCAP_WEP_HEADER     AIRPDCAP_WEP_IVLEN + AIRPDCAP_WEP_KIDLEN
  85 #define AIRPDCAP_WEP_TRAILER    AIRPDCAP_WEP_ICV
  86
  87 /*
  88  * 802.11i defines an extended IV for use with non-WEP ciphers.
  89  * When the EXTIV bit is set in the key id byte an additional
  90  * 4 bytes immediately follow the IV for TKIP.  For CCMP the
  91  * EXTIV bit is likewise set but the 8 bytes represent the
  92  * CCMP header rather than IV+extended-IV.
  93  */
  94 #define AIRPDCAP_RSNA_EXTIV     0x20
  95 #define AIRPDCAP_RSNA_EXTIVLEN  4       /* extended IV length */
  96 #define AIRPDCAP_RSNA_MICLEN    8       /* trailing MIC */
  97
  98 #define AIRPDCAP_RSNA_HEADER    AIRPDCAP_WEP_HEADER + AIRPDCAP_RSNA_EXTIVLEN
  99
 100 #define AIRPDCAP_CCMP_HEADER    AIRPDCAP_RSNA_HEADER
 101 #define AIRPDCAP_CCMP_TRAILER   AIRPDCAP_RSNA_MICLEN
 102
 103 #define AIRPDCAP_TKIP_HEADER    AIRPDCAP_RSNA_HEADER
 104 #define AIRPDCAP_TKIP_TRAILER   AIRPDCAP_RSNA_MICLEN + AIRPDCAP_WEP_ICV
 105
 106 #define AIRPDCAP_CRC_LEN        4
 107
 108 /************************************************************************/
 109 /*      File includes                                                   */
 110
 111 #include "airpdcap_interop.h"
 112 #include "airpdcap_user.h"
 113 #include "ws_symbol_export.h"
 114
 115 /************************************************************************/
 116 /*      Macro definitions                                               */
 117
 118 /************************************************************************/
 119 /*      Type definitions                                                */
 120
 121 typedef struct _AIRPDCAP_SEC_ASSOCIATION_ID {
 122         UCHAR bssid[AIRPDCAP_MAC_LEN];
 123         UCHAR sta[AIRPDCAP_MAC_LEN];
 124 } AIRPDCAP_SEC_ASSOCIATION_ID, *PAIRPDCAP_SEC_ASSOCIATION_ID;
 125
 126 typedef struct _AIRPDCAP_SEC_ASSOCIATION {
 127     /* This is for reassociations. A linked list of old security
 128      * associations is kept.  GCS
 129      */
 130     struct _AIRPDCAP_SEC_ASSOCIATION* next;
 131
 132         /**
 133          * This flag define whether this item is used or not. Accepted
 134      * values are TRUE and FALSE
 135          */
 136         UINT8 used;
 137         AIRPDCAP_SEC_ASSOCIATION_ID saId;
 138         AIRPDCAP_KEY_ITEM *key;
 139         UINT8 handshake;
 140         UINT8 validKey;
 141
 142         struct {
 143                 UINT8 key_ver;          /* Key descriptor version       */
 144                 UINT64 pn;              /* only used with CCMP AES -if needed replay check- */
 145                 UCHAR nonce[AIRPDCAP_WPA_NONCE_LEN];
 146                 /* used to derive PTK, ANonce stored, SNonce taken      */
 147                 /* the 2nd packet of the 4W handshake                   */
 148
 149                 UCHAR ptk[AIRPDCAP_WPA_PTK_LEN];                /* session key used in decryption algorithm     */
 150         } wpa;
 151
 152
 153 } AIRPDCAP_SEC_ASSOCIATION, *PAIRPDCAP_SEC_ASSOCIATION;
 154
 155 typedef struct _AIRPDCAP_CONTEXT {
 156         AIRPDCAP_SEC_ASSOCIATION sa[AIRPDCAP_MAX_SEC_ASSOCIATIONS_NR];
 157         INT sa_index;
 158         AIRPDCAP_KEY_ITEM keys[AIRPDCAP_MAX_KEYS_NR];
 159         size_t keys_nr;
 160
 161         CHAR pkt_ssid[AIRPDCAP_WPA_SSID_MAX_LEN];
 162         size_t pkt_ssid_len;
 163
 164         INT index;
 165         INT first_free_index;
 166 } AIRPDCAP_CONTEXT, *PAIRPDCAP_CONTEXT;
 167
 168 /************************************************************************/
 169 /*      Function prototype declarations                                 */
 170
 171 #ifdef  __cplusplus
 172 extern "C" {
 173 #endif
 174
 175 /**
 176  * This will try to decrypt a 802.11 frame. If scanHandshake is
 177  * true it will also check if it's a cleartext or encrypted eapol key
 178  * frame which can be used to setup TK or GTK decryption keys.
 179  * @param ctx [IN] Pointer to the current context
 180  * @param data [IN] Pointer to a buffer with an 802.11 frame, including MAC
 181  *   header and payload
 182  * @param data_off [IN] Payload offset (aka the MAC header length)
 183  * @param data_len [IN] Total length of the MAC header and the payload
 184  * @param decrypt_data [OUT] Pointer to a buffer that will contain
 185  *   decrypted data. If this parameter is set to NULL, decrypted data will
 186  *   be discarded.
 187  * @param decrypt_len [OUT] Length of decrypted data if decrypt_data
 188  *   is not NULL.
 189  * @param key [OUT] Pointer to a preallocated key structure containing
 190  *   the key used during the decryption process (if done). If this parameter
 191  *   is set to NULL, the key will be not returned.
 192  * @param scanHandshake [IN] If TRUE this function will additional check if
 193  *   the 802.11 frame data is pointing to has key information and if so use
 194  *   it to setup potential decryption keys. Enables handshake return codes.
 195  * @return
 196  * - AIRPDCAP_RET_SUCCESS: Decryption has been done (decrypt_data and
 197  *   decrypt_length will contain the packet data decrypted and the length of
 198  *   the new packet)
 199  * - AIRPDCAP_RET_NO_DATA: The packet is not a data packet
 200  * - AIRPDCAP_RET_WRONG_DATA_SIZE: The size of the packet is below the
 201  *   accepted minimum
 202  * - AIRPDCAP_RET_REQ_DATA: Required data is not available and the
 203  *   processing must be interrupted (can also occur after decryption when
 204  *   scanHandshake is TRUE)
 205  * - AIRPDCAP_RET_NO_DATA_ENCRYPTED: Not encrypted and no attempt to
 206  *   extract key information
 207  * - AIRPDCAP_RET_UNSUCCESS: Generic unspecified error (decrypt_data
 208  *   and decrypt_length will be not modified).
 209  * - AIRPDCAP_RET_SUCCESS_HANDSHAKE: An eapol handshake packet was successfuly parsed
 210  *   and key information extracted
 211  * - AIRPDCAP_RET_NO_VALID_HANDSHAKE: The handshake is invalid or was not used
 212  *   for some reason. For encrypted packets decryption was still successful.
 213  * @note
 214  * The decrypted buffer should be allocated for a size equal or greater
 215  * than the packet data buffer size. Before decryption process original
 216  * data is copied in the buffer pointed by decrypt_data not to modify the
 217  * original packet.
 218  * @note
 219  * The length of decrypted data will consider the entire 802.11 frame
 220  * (thus the MAC header, the frame body and the recalculated FCS -if
 221  * initially present-)
 222  * @note
 223  * This function is not thread-safe when used in parallel with context
 224  *  management functions on the same context.
 225  */
 226 extern INT AirPDcapPacketProcess(
 227         PAIRPDCAP_CONTEXT ctx,
 228         const guint8 *data,
 229         const guint data_off,
 230         const guint data_len,
 231         UCHAR *decrypt_data,
 232         guint32 *decrypt_len,
 233         PAIRPDCAP_KEY_ITEM key,
 234         gboolean scanHandshake)
 235         ;
 236
 237 /**
 238  * It sets a new keys collection to use during packet processing.
 239  * Any key should be well-formed, thus: it should have a defined key
 240  * type and the specified length should be conforming WEP or WPA/WPA2
 241  * standards. A general WEP keys could be of any length (in the range
 242  * defined in AIRPDCAP_KEY_ITEM), if a specific WEP key is used, the
 243  * length of the key will be the one specified in 802.11i-2004 (40 bits or
 244  * 104 bits).
 245  * For WPA/WPA2 the password (passphrase and SSID), the PSK and the PMK
 246  * are in alternative, as explain in the AIRPDCAP_KEY_ITEM structure
 247  * description.
 248  * @param ctx [IN] pointer to the current context
 249  * @param keys [IN] an array of keys to set.
 250  * @param keys_nr [IN] the size of the keys array
 251  * @return The number of keys correctly inserted in the current database.
 252  * @note Before inserting new keys, the current database will be cleaned.
 253  * @note
 254  * This function is not thread-safe when used in parallel with context
 255  * management functions and the packet process function on the same
 256  * context.
 257  */
 258 extern INT AirPDcapSetKeys(
 259         PAIRPDCAP_CONTEXT ctx,
 260         AIRPDCAP_KEY_ITEM keys[],
 261         const size_t keys_nr)
 262         ;
 263
 264 /**
 265  * It gets the keys collection fom the specified context.
 266  * @param ctx [IN] pointer to the current context
 267  * @param keys [IN] a preallocated array of keys to be returned
 268  * @param keys_nr [IN] the number of keys to return (the key array must
 269  * be able to contain at least keys_nr keys)
 270  * @return The number of keys returned
 271  * @note
 272  * Any key could be modified, as stated in the AIRPDCAP_KEY_ITEM description.
 273  * @note
 274  * This function is not thread-safe when used in parallel with context
 275  * management functions and the packet process function on the same
 276  * context.
 277  */
 278 INT AirPDcapGetKeys(
 279         const PAIRPDCAP_CONTEXT ctx,
 280         AIRPDCAP_KEY_ITEM keys[],
 281         const size_t keys_nr)
 282         ;
 283
 284 /**
 285  * Sets the "last seen" SSID.  This allows us to pick up previous
 286  * SSIDs and use them when "wildcard" passphrases are specified
 287  * in the preferences.
 288  * @param ctx [IN|OUT] pointer to a preallocated context structure
 289  * @param pkt_ssid [IN] pointer to the packet's SSID
 290  * @param pkt_ssid_len [IN] length of the packet's SSID
 291  * @return
 292  *   AIRPDCAP_RET_SUCCESS: The key has been set.
 293  *   AIRPDCAP_RET_UNSUCCESS: The has not been set, e.g. the length was
 294  *   too long.
 295  */
 296 INT AirPDcapSetLastSSID(
 297         PAIRPDCAP_CONTEXT ctx,
 298         CHAR *pkt_ssid,
 299         size_t pkt_ssid_len)
 300         ;
 301
 302 /**
 303  * Initialize a context used to manage decryption and keys collection.
 304  * @param ctx [IN|OUT] pointer to a preallocated context structure
 305  * @return
 306  *   AIRPDCAP_RET_SUCCESS: the context has been successfully initialized
 307  *   AIRPDCAP_RET_UNSUCCESS: the context has not been initialized
 308  * @note
 309  * Only a correctly initialized context can be used to manage decryption
 310  * processes and keys.
 311  * @note
 312  * This function is not thread-safe when used in parallel with context
 313  * management functions and the packet process function on the same context.
 314  */
 315 WS_DLL_PUBLIC
 316 INT AirPDcapInitContext(
 317         PAIRPDCAP_CONTEXT ctx)
 318         ;
 319
 320 /**
 321  * Clean up the specified context. After the cleanup the pointer should
 322  * not be used anymore.
 323  * @param ctx [IN|OUT] pointer to the current context structure
 324  * @return
 325  *  AIRPDCAP_RET_SUCCESS: the context has been successfully initialized
 326  *  AIRPDCAP_RET_UNSUCCESS: the context has not been initialized
 327  * @note
 328  * This function is not thread-safe when used in parallel with context
 329  * management functions and the packet process function on the same
 330  * context.
 331  */
 332 WS_DLL_PUBLIC
 333 INT AirPDcapDestroyContext(
 334         PAIRPDCAP_CONTEXT ctx)
 335         ;
 336
 337 extern INT AirPDcapCcmpDecrypt(
 338         UINT8 *m,
 339         gint mac_header_len,
 340         INT len,
 341         UCHAR TK1[16])
 342         ;
 343 extern INT AirPDcapTkipDecrypt(
 344         UCHAR *tkip_mpdu,
 345         size_t mpdu_len,
 346         UCHAR TA[AIRPDCAP_MAC_LEN],
 347         UCHAR TK[AIRPDCAP_TK_LEN])
 348         ;
 349
 350 #ifdef  __cplusplus
 351 }
 352 #endif
 353
 354 #endif /* _AIRPDCAP_SYSTEM_H */