epan/crypt/airpdcap_system.h

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