Add boundary check for 802.11 decryption
[metze/wireshark/wip.git] / 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. Must have room for at least AIRPDCAP_MAX_CAPLEN bytes.
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 */