|
1 /* |
|
2 * Copyright (c) 2001-2006 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of the License "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: EAP and WLAN authentication protocols. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 #if !defined( _ABS_EAP_AM_TOOLS_H_ ) |
|
23 #define _ABS_EAP_AM_TOOLS_H_ |
|
24 |
|
25 #include "eap_am_types.h" |
|
26 #include "eap_am_export.h" |
|
27 #include "eap_status.h" |
|
28 #include "abs_eap_base_timer.h" |
|
29 //#include "eap_am_memory_store_data.h" |
|
30 |
|
31 |
|
32 #if defined(EAP_LITTLE_ENDIAN) && defined(EAP_BIG_ENDIAN) |
|
33 #error Do not define both EAP_LITTLE_ENDIAN and EAP_BIG_ENDIAN |
|
34 #endif |
|
35 |
|
36 #if !defined(EAP_LITTLE_ENDIAN) && !defined(EAP_BIG_ENDIAN) |
|
37 #error Do define either EAP_LITTLE_ENDIAN or EAP_BIG_ENDIAN |
|
38 #endif |
|
39 |
|
40 class abs_eap_am_crypto_c; |
|
41 class eap_variable_data_c; |
|
42 class abs_eap_am_mutex_c; |
|
43 class eap_buf_chain_wr_c; |
|
44 class eap_configuration_field_c; |
|
45 class eap_tlv_message_data_c; |
|
46 |
|
47 /// This class offers some services that are dependent of platform Y. |
|
48 /** |
|
49 * Current services are timer handling, crypto library, trace functions, |
|
50 * memory manipulation and hardware tick counter. Use of eap_am_tools is through |
|
51 * abstract virtual class abs_eap_am_tools. A pointer to the abs_eap_am_tools |
|
52 * class is given to all other classes as a parameter to each constructor. |
|
53 * Adaptation module creates the eap_am_tools_Y class before it initializes the stack. |
|
54 * This prevents the need of global objects. |
|
55 */ |
|
56 class EAP_EXPORT abs_eap_am_tools_c |
|
57 { |
|
58 |
|
59 public: |
|
60 |
|
61 /** |
|
62 * The destructor of the abs_eap_am_tools_c class does nothing special. |
|
63 */ |
|
64 virtual ~abs_eap_am_tools_c() |
|
65 { |
|
66 } |
|
67 |
|
68 /** |
|
69 * The constructor of the abs_eap_am_tools_c does nothing special. |
|
70 */ |
|
71 abs_eap_am_tools_c() |
|
72 { |
|
73 } |
|
74 |
|
75 /** |
|
76 * This function allocates platform specific tools object. |
|
77 * Note this function calls also configure() of the allocated tools object. |
|
78 * The platform specific module must implement this function. |
|
79 */ |
|
80 EAP_FUNC_IMPORT_INTERFACE static abs_eap_am_tools_c * new_abs_eap_am_tools_c(); |
|
81 |
|
82 /** |
|
83 * This function deletes platform specific tools object. |
|
84 * Note this function calls also shutdown() of the allocated tools object. |
|
85 * The platform specific module must implement this function. |
|
86 */ |
|
87 EAP_FUNC_IMPORT_INTERFACE static void delete_abs_eap_am_tools_c(abs_eap_am_tools_c * const am_tools); |
|
88 |
|
89 /** |
|
90 * The configure() function is called after the constructor of the |
|
91 * object is successfully executed. During the function call the object |
|
92 * could query the configuration. Each derived class must define this function. |
|
93 * Needed configuration depends on the implementation. |
|
94 */ |
|
95 virtual eap_status_e configure() = 0; |
|
96 |
|
97 /** |
|
98 * The shutdown() function is called before the destructor of the |
|
99 * object is executed. During the function call the object |
|
100 * could shutdown the operations, for example cancel timers. |
|
101 * Each derived class must define this function. |
|
102 */ |
|
103 virtual eap_status_e shutdown() = 0; |
|
104 |
|
105 /** |
|
106 * Function converts unicode characters into UTF8 characters. |
|
107 * @param dest is reference to destination utf8 variable data. |
|
108 * @param src is refrence to unicode variable data. |
|
109 * @return eap status code. |
|
110 */ |
|
111 virtual eap_status_e convert_unicode_to_utf8( |
|
112 eap_variable_data_c & dest, |
|
113 const eap_variable_data_c & src) = 0; |
|
114 |
|
115 /** |
|
116 * Function converts UTF8 characters into unicode characters. |
|
117 * @param dest is reference to destination unicode variable data. |
|
118 * @param src is refrence to UTF8 variable data. |
|
119 * @return eap status code. |
|
120 */ |
|
121 virtual eap_status_e convert_utf8_to_unicode( |
|
122 eap_variable_data_c & dest, |
|
123 const eap_variable_data_c & src) = 0; |
|
124 |
|
125 /** |
|
126 * Function parses NAI to usename and realm. |
|
127 * If either is missing the corresponding value will be invalid. |
|
128 */ |
|
129 virtual eap_status_e parse_nai( |
|
130 const eap_variable_data_c * const nai, |
|
131 eap_variable_data_c * const username, |
|
132 eap_variable_data_c * const realm) = 0; |
|
133 |
|
134 /** |
|
135 * Function converts one octet to ascii character. |
|
136 * @param octet is the converted octet. |
|
137 * @return acsii byte. |
|
138 */ |
|
139 virtual u8_t octet_to_ascii(i32_t octet) = 0; |
|
140 |
|
141 /** |
|
142 * Function converts one ascii character to octet. |
|
143 * @param character is the converted ascii character. |
|
144 * @return octet. |
|
145 */ |
|
146 virtual u8_t ascii_to_octet(i32_t character) = 0; |
|
147 |
|
148 /** |
|
149 * The memmove() function copies count bytes from src to dest. |
|
150 * The implementation must handle overlapping memory areas correctly. |
|
151 * Check always the destination is correct memory. |
|
152 * This function is low level and cannot check the used memory. |
|
153 * @param dest is pointer to the destination. |
|
154 * @param src is pointer to the source. |
|
155 * @param count indicates the count of copied bytes. |
|
156 */ |
|
157 virtual void memmove( |
|
158 void *dest, |
|
159 const void *src, |
|
160 const u32_t count) = 0; |
|
161 |
|
162 /** |
|
163 * The memcmp() function compares count bytes from buf1 and buf2. |
|
164 * @return Returns zero when all count bytes are equal. |
|
165 * @return Returns negative integer when buf1 contains smaller different byte. |
|
166 * @return Returns positive integer when buf1 contains bigger different byte. |
|
167 */ |
|
168 virtual i32_t memcmp( |
|
169 const void * const buf1, |
|
170 const void * const buf2, |
|
171 const u32_t count) = 0; |
|
172 |
|
173 /** |
|
174 * The memset function sets the first count bytes of dest to the character fill_byte. |
|
175 * Check always the destination is correct memory. |
|
176 * This function is low level and cannot check the used memory. |
|
177 * @param dest is pointer to the destination. |
|
178 * @param fill_byte is the fill value. |
|
179 * @param count indicates the count of set bytes. |
|
180 */ |
|
181 virtual void memset( |
|
182 void * const dest, |
|
183 const i32_t fill_byte, |
|
184 const u32_t count) = 0; |
|
185 |
|
186 /** |
|
187 * The memchr function searches the first occurence of character starting from buf. |
|
188 * Maximum count bytes are searched. |
|
189 */ |
|
190 virtual void *memchr( |
|
191 const void *buf, |
|
192 u8_t character, |
|
193 u32_t count) = 0; |
|
194 |
|
195 /** |
|
196 * The memchr function searches the last occurence of character starting from the enf of the buf. |
|
197 * Maximum count bytes are searched. |
|
198 */ |
|
199 virtual void *memrchr( |
|
200 const void *buf, |
|
201 u8_t character, |
|
202 u32_t count) = 0; |
|
203 |
|
204 /** |
|
205 * Get the length of a string. |
|
206 * @return Function returns the number of characters in string, |
|
207 * excluding the terminal NULL. No return value is reserved to indicate an error. |
|
208 */ |
|
209 virtual u32_t strlen( |
|
210 eap_const_string string) = 0; |
|
211 |
|
212 /** |
|
213 * Get the length of a string. |
|
214 * @return Function returns the number of characters in string, |
|
215 * excluding the terminal NULL. No return value is reserved to indicate an error. |
|
216 */ |
|
217 virtual u32_t config_strlen( |
|
218 eap_config_string string) = 0; |
|
219 |
|
220 /** |
|
221 * Function converts lovercase ascii characters to uppercase. |
|
222 * @param source_bytes is pointer to the source bytes. |
|
223 * @param source_bytes_length is length of source bytes. |
|
224 */ |
|
225 virtual eap_status_e convert_ascii_to_uppercase( |
|
226 u8_t * const source_bytes, |
|
227 const u32_t source_bytes_length) = 0; |
|
228 /** |
|
229 * Function converts bytes to hex ascii. |
|
230 * @param source_bytes is pointer to the source bytes. |
|
231 * @param source_bytes_length is length of source bytes. |
|
232 * @param target is pointer to the target bytes. |
|
233 * @param target_length is length of target bytes. |
|
234 */ |
|
235 virtual eap_status_e convert_bytes_to_hex_ascii( |
|
236 const u8_t * const source_bytes, |
|
237 const u32_t source_bytes_length, |
|
238 u8_t * const target, |
|
239 u32_t *target_length) = 0; |
|
240 |
|
241 /** |
|
242 * Function converts bytes to hex ascii. |
|
243 * @param source_bytes is pointer to the source bytes. |
|
244 * @param source_bytes_length is length of source bytes. |
|
245 * @param target is pointer to the target buffer. |
|
246 */ |
|
247 virtual eap_status_e convert_bytes_to_hex_ascii( |
|
248 const void * const source_bytes, |
|
249 const u32_t source_bytes_length, |
|
250 eap_variable_data_c * const target) = 0; |
|
251 |
|
252 /** |
|
253 * Function converts hex ascii to bytes. |
|
254 * @param source_bytes is pointer to the source bytes. |
|
255 * @param source_bytes_length is length of source bytes. |
|
256 * @param target is pointer to the target bytes. |
|
257 * @param target_length is length of target bytes. |
|
258 */ |
|
259 virtual eap_status_e convert_hex_ascii_to_bytes( |
|
260 const u8_t * const source_bytes, |
|
261 const u32_t source_bytes_length, |
|
262 u8_t * const target, |
|
263 u32_t *target_length) = 0; |
|
264 |
|
265 /** |
|
266 * Function converts hex ascii to bytes. |
|
267 * @param source_bytes is pointer to the source bytes. |
|
268 * @param source_bytes_length is length of source bytes. |
|
269 * @param target is pointer to the target bytes. |
|
270 * @param target_length is length of target bytes. |
|
271 */ |
|
272 virtual eap_status_e convert_hex_ascii_to_bytes( |
|
273 const void * const source_bytes, |
|
274 const u32_t source_bytes_length, |
|
275 eap_variable_data_c * const target) = 0; |
|
276 |
|
277 /** |
|
278 * Function converts bytes to ascii armored bytes. |
|
279 * @param source_bytes is pointer to the source bytes. |
|
280 * @param source_bytes_length is length of source bytes. |
|
281 * @param target is pointer to the target bytes. |
|
282 * @param target_length is length of target bytes. |
|
283 * @code |
|
284 * Binary 6-bit blocks are converted to 8-bit ascii values. Ascii values can easily represent 2^6=64 values. |
|
285 * If length of target array is not module 3, padding zero bits are ignored. |
|
286 * |
|
287 * |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| |
|
288 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
|
289 * | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | |
|
290 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
|
291 * |0 1 2 3 4 5|0 1 2 3 4 5|0 1 2 3 4 5|0 1 2 3 4 5|0 1 2 3 4 5|0 1 2 3 4 5| |
|
292 * | | | | | | + |
|
293 * | | | | | | \ |
|
294 * | | | | | + \ |
|
295 * | | | | | \ \ |
|
296 * | | | | + \ \ |
|
297 * | | | | \ \ \ |
|
298 * | | | + \ \ \ |
|
299 * | | | \ \ \ \ |
|
300 * | | + \ \ \ \ |
|
301 * | | \ \ \ \ \ |
|
302 * | + \ \ \ \ \ |
|
303 * | \ \ \ \ \ \ |
|
304 * | \ \ \ \ \ \ |
|
305 * | + + + + + + |
|
306 * | | | | | | | |
|
307 * |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| |
|
308 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
|
309 * | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | |
|
310 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
|
311 * @endcode |
|
312 */ |
|
313 virtual eap_status_e convert_bytes_to_ascii_armor( |
|
314 const u8_t * const source_bytes, |
|
315 const u32_t source_bytes_length, |
|
316 u8_t * const target, |
|
317 u32_t *target_length) = 0; |
|
318 |
|
319 /** |
|
320 * Function converts ascii armored bytes to bytes. |
|
321 * @param source_bytes is pointer to the source bytes. |
|
322 * @param source_bytes_length is length of source bytes. |
|
323 * @param target is pointer to the target bytes. |
|
324 * @param target_length is length of target bytes. |
|
325 * @code |
|
326 * 8-bit ascii values are converted to binary 6-bit blocks. Ascii values can easily represent 2^6=64 values. |
|
327 * If length of source array is not module 3, missing bits are padded with zero bits. |
|
328 * |
|
329 * |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| |
|
330 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
|
331 * | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : |0:0:0:0| |
|
332 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
|
333 * |0 1 2 3 4 5|0 1 2 3 4 5|0 1 2 3 4 5|0 1 2 3 4 5|0 1 2 3 4 5|0 1 2 3 4 5| |
|
334 * | | | | | | + |
|
335 * | | | | | | \ |
|
336 * | | | | | + \ |
|
337 * | | | | | \ \ |
|
338 * | | | | + \ \ |
|
339 * | | | | \ \ \ |
|
340 * | | | + \ \ \ |
|
341 * | | | \ \ \ \ |
|
342 * | | + \ \ \ \ |
|
343 * | | \ \ \ \ \ |
|
344 * | + \ \ \ \ \ |
|
345 * | \ \ \ \ \ \ |
|
346 * | \ \ \ \ \ \ |
|
347 * | + + + + + + |
|
348 * | | | | | | | |
|
349 * |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| |
|
350 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
|
351 * | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | |
|
352 * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
|
353 * @endcode |
|
354 */ |
|
355 virtual eap_status_e restore_bytes_from_ascii_armor( |
|
356 const u8_t * const source_bytes, |
|
357 const u32_t source_bytes_length, |
|
358 u8_t * const target, |
|
359 u32_t *target_length) = 0; |
|
360 |
|
361 /** |
|
362 * Gets the current trace mask. |
|
363 */ |
|
364 virtual u32_t get_trace_mask() const = 0; |
|
365 |
|
366 /** |
|
367 * This function sets the current trace mask. |
|
368 */ |
|
369 virtual void set_trace_mask(const u32_t mask) = 0; |
|
370 |
|
371 /** |
|
372 * This function sets the trace output file name. |
|
373 */ |
|
374 virtual eap_status_e set_trace_file_name(const eap_variable_data_c * const trace_output_file) = 0; |
|
375 |
|
376 /** |
|
377 * This function sets the maximum size of trace output file in bytes. |
|
378 * Note this is not absolute value. New file is generated when size of trace log file |
|
379 * exceeds this limitation. |
|
380 */ |
|
381 virtual void set_max_trace_file_size(const u32_t max_trace_file_size) = 0; |
|
382 |
|
383 /** |
|
384 * This functions allows activation of trace when the error occurs. |
|
385 * Look at the set_activate_trace_on_error() and eap_status_return() |
|
386 * functions. NOTE the always active traces are only left active. |
|
387 * That means set_activate_trace_on_error() function calls |
|
388 * set_trace_mask(eap_trace_mask_always). |
|
389 */ |
|
390 virtual void set_activate_trace_on_error() = 0; |
|
391 |
|
392 virtual void check_activate_trace_on_error() = 0; |
|
393 |
|
394 /** |
|
395 * This function formats string to buffer. |
|
396 * Function returns number of written bytes. |
|
397 */ |
|
398 virtual u32_t snprintf(u8_t * const buffer, u32_t buffer_size, eap_format_string format, ...) = 0; |
|
399 |
|
400 /** |
|
401 * The formatted_print() function traces format string and formatted parameters to file. |
|
402 * File is set as a parameter to constructor. This is used in macros |
|
403 * EAP_TRACE_DEBUG(object_name, _parameter_list_) and |
|
404 * EAP_TRACE_ERROR(object_name, _parameter_list_). |
|
405 */ |
|
406 virtual void formatted_print( |
|
407 eap_format_string format, |
|
408 ...) = 0; |
|
409 |
|
410 /** |
|
411 * The trace_data() function traces null terminated prefix string |
|
412 * and data_length bytes from p_data to file. This is used in macros |
|
413 * EAP_TRACE_DATA_DEBUG(object_name, _parameter_list_) and |
|
414 * EAP_TRACE_DATA_ERROR(object_name, _parameter_list_). |
|
415 */ |
|
416 virtual void trace_data( |
|
417 eap_const_string prefix, |
|
418 const void * const p_data, |
|
419 const u32_t data_length) = 0; |
|
420 |
|
421 /** |
|
422 * The get_crypto() function returns a pointer to object of type eap_am_crypto. |
|
423 */ |
|
424 virtual abs_eap_am_crypto_c * get_crypto() = 0; |
|
425 |
|
426 /** |
|
427 * This function returns the current time and date in standard UNIX 32-bit format (seconds |
|
428 * since the midnight starting Jan 1, 1970, GMT) according to the |
|
429 * sender's internal clock. |
|
430 */ |
|
431 virtual u32_t get_gmt_unix_time() = 0; |
|
432 |
|
433 /** |
|
434 * The get_hardware_ticks() function returns current value of hardware ticks counter. |
|
435 */ |
|
436 virtual u64_t get_hardware_ticks() = 0; |
|
437 |
|
438 /** |
|
439 * Function returns count of hardware ticks in one second. |
|
440 */ |
|
441 virtual u64_t get_hardware_ticks_of_second() = 0; |
|
442 |
|
443 /** |
|
444 * Function returns count of clock ticks in one second. |
|
445 */ |
|
446 virtual u64_t get_clock_ticks_of_second() = 0; |
|
447 |
|
448 /** |
|
449 * Function returns current value of clock ticks counter. |
|
450 */ |
|
451 virtual u64_t get_clock_ticks() = 0; |
|
452 |
|
453 /** |
|
454 * Returns true when timer queue is used. |
|
455 * Returns false when timer queue is not used. |
|
456 */ |
|
457 virtual bool get_use_timer_queue() = 0; |
|
458 |
|
459 /** |
|
460 * Returns true when timer thread is stopped. |
|
461 * Returns false when timer thread is running. |
|
462 */ |
|
463 virtual bool get_thread_stopped() = 0; |
|
464 |
|
465 /** |
|
466 * The set_timer() function initializes timer to be elapsed after p_time_ms milliseconds. |
|
467 * @param initializer is pointer to object which timer_expired() function will |
|
468 * be called after timer elapses. |
|
469 * @param id is identifier which will be returned in timer_expired() function. |
|
470 * The user selects and interprets the id for this timer. |
|
471 * @param data is pointer to any user selected data which will be returned in timer_expired() function. |
|
472 * |
|
473 * Adaptation module of tools includes internal attribute eap_timer_queue_c to |
|
474 * which this call is directed. |
|
475 */ |
|
476 virtual eap_status_e am_set_timer( |
|
477 abs_eap_base_timer_c * const initializer, |
|
478 const u32_t id, |
|
479 void * const data, |
|
480 const u32_t p_time_ms) = 0; |
|
481 |
|
482 /** |
|
483 * The cancel_timer() function cancels the timer id initiated by initializer. |
|
484 * |
|
485 * Adaptation module of tools includes internal attribute eap_timer_queue_c to |
|
486 * which this call is directed. |
|
487 */ |
|
488 virtual eap_status_e am_cancel_timer( |
|
489 abs_eap_base_timer_c * const initializer, |
|
490 const u32_t id) = 0; |
|
491 |
|
492 /** |
|
493 * The cancel_all_timers() function cancels all timers. |
|
494 * User should use this in termination of the stack before |
|
495 * the adaptation module of tools is deleted. |
|
496 * |
|
497 * Adaptation module of tools includes internal attribute eap_timer_queue_c to |
|
498 * which this call is directed. |
|
499 * |
|
500 * This function de-activated timer queue. |
|
501 * You could re-activate timer queue with re_activate_timer_queue function. |
|
502 */ |
|
503 virtual eap_status_e am_cancel_all_timers() = 0; |
|
504 |
|
505 /** |
|
506 * This function re-activates timer queue. |
|
507 * Symbian AM call this function when AM-tools object is re-used. |
|
508 * This can be called after am_cancel_all_timers() function. |
|
509 * am_cancel_all_timers() function de-activated timer queue. |
|
510 */ |
|
511 virtual eap_status_e re_activate_timer_queue() = 0; |
|
512 |
|
513 /** |
|
514 * This function sets the resolution of the timer. |
|
515 * The default value is EAP_TIMER_RESOLUTION. |
|
516 * Each pulse increases time by this value. |
|
517 * |
|
518 * Adaptation module of tools includes internal attribute eap_timer_queue_c to |
|
519 * which this call is directed. |
|
520 */ |
|
521 virtual void set_timer_resolution_ms(const u32_t timer_resolution_ms) = 0; |
|
522 |
|
523 /** |
|
524 * This function returns the resolution of the timer. |
|
525 * Each pulse increases time by this value. |
|
526 * |
|
527 * Adaptation module of tools includes internal attribute eap_timer_queue_c to |
|
528 * which this call is directed. |
|
529 */ |
|
530 virtual u32_t get_timer_resolution_ms() = 0; |
|
531 |
|
532 /** |
|
533 * Pulses timer. Time is increased by get_timer_resolution_ms() milli seconds. |
|
534 * Timer pulse is run parallel to the stack operation. |
|
535 * This causes the use of global mutex. |
|
536 * |
|
537 * Adaptation module of tools includes internal attribute eap_timer_queue_c to |
|
538 * which this call is directed. |
|
539 * Function returns the next sleep time in milli seconds. |
|
540 */ |
|
541 virtual u32_t pulse_timer(const u32_t elapsed_time_in_ms) = 0; |
|
542 |
|
543 /** |
|
544 * This function checks whether the internal timer queue is empty. |
|
545 */ |
|
546 virtual bool get_timer_queue_is_empty() = 0; |
|
547 |
|
548 /** |
|
549 * Starts the thread to pulse timer. |
|
550 * User of tools should call this after the stack is created. |
|
551 */ |
|
552 virtual eap_status_e start_timer_thread() = 0; |
|
553 |
|
554 /** |
|
555 * Stops the timer thread. |
|
556 * User of tools should call this before the stack is deleted. |
|
557 */ |
|
558 virtual eap_status_e stop_timer_thread() = 0; |
|
559 |
|
560 /** |
|
561 * Function runs the timer thread loop. This function calls the pulse_timer() |
|
562 * function to increase the elapsed time. |
|
563 */ |
|
564 virtual eap_status_e timer_thread_function() = 0; |
|
565 |
|
566 /** |
|
567 * Returns the value of timer thread activity. |
|
568 * Timer thread stops when this functions returns false. |
|
569 */ |
|
570 virtual bool get_is_timer_thread_active() = 0; |
|
571 |
|
572 /** |
|
573 * This function enters the global mutex. Mutex is needed to synchronize |
|
574 * the timer thread and stack call operations. |
|
575 * Timer pulse is run parallel to the stack operation. |
|
576 * This causes the use of global mutex. |
|
577 */ |
|
578 virtual void enter_global_mutex() = 0; |
|
579 |
|
580 /** |
|
581 * This function leaves the global mutex. |
|
582 * Timer pulse is run parallel to the stack operation. |
|
583 * This causes the use of global mutex. |
|
584 */ |
|
585 virtual void leave_global_mutex() = 0; |
|
586 |
|
587 /** |
|
588 * Returns the global mutex. This is used in some assertion tests. |
|
589 */ |
|
590 virtual abs_eap_am_mutex_c * get_global_mutex() = 0; |
|
591 |
|
592 #define ENTER_CRYPTO() |
|
593 #define LEAVE_CRYPTO() |
|
594 |
|
595 /** |
|
596 * The timer_sleep function suspends the execution of the current timer thread for the specified interval. |
|
597 * Timer could be set any value. When timer is set to shorter timeout than the smallest current |
|
598 * timeout is the timer_sleep() will cancel sleep and the new sleep time could be calculated. |
|
599 * @param milli_seconds is the suspension time in milli seconds. |
|
600 */ |
|
601 virtual void timer_sleep(u32_t milli_seconds) = 0; |
|
602 |
|
603 /** |
|
604 * The sleep function suspends the execution of the current thread for the specified interval. |
|
605 * @param milli_seconds is the suspension time in milli seconds. |
|
606 */ |
|
607 virtual void sleep(u32_t milli_seconds) = 0; |
|
608 |
|
609 /** |
|
610 * The get_is_valid() function returns the status of the object. |
|
611 * True indicates the object is initialized succesfully. |
|
612 */ |
|
613 virtual bool get_is_valid() const = 0; |
|
614 |
|
615 #if (defined(DMALLOC) || defined(USE_EAP_CRYPTO_MEMORY_LEAK_FUNCTIONS)) && !defined(USE_EAP_LOCAL_TRACE_FILE_OPEN) |
|
616 virtual const EAP_FILE_POINTER * get_trace_file() = 0; |
|
617 #endif //#if defined(DMALLOC) && !defined(USE_EAP_LOCAL_TRACE_FILE_OPEN) |
|
618 |
|
619 /// This function is global proxy for return values. |
|
620 virtual eap_status_e eap_status_return( |
|
621 const bool print_error_when_true, |
|
622 const eap_status_e status, |
|
623 const eap_char * const file_name, |
|
624 const i32_t line_number) = 0; |
|
625 |
|
626 /// This function is global proxy for return values with file name and line number. |
|
627 /// This is used in traces. |
|
628 virtual eap_status_e eap_status_return_file_number( |
|
629 const bool print_error_when_true, |
|
630 const eap_status_e status, |
|
631 const u32_t file_date, |
|
632 const u32_t file_number, |
|
633 const i32_t line_number) = 0; |
|
634 |
|
635 /// Memory store is visible only during the eap_am_tools_c object is alive. |
|
636 /// This function add flat data to memory store. |
|
637 /// You must format your data to eap_tlv_message_data_c object. |
|
638 /// Data is identified by key parameter. |
|
639 /// You can set timeout to data. Data will be automatically removed after timeout. |
|
640 /// Timeout value zero means no timeout is set. |
|
641 /// Serious WARNING: do use really good key values. |
|
642 /// Memory store is globally used by all EAP Core objects. |
|
643 /// Key must be good that other users do not use others data. |
|
644 /// Add the real data type as a string to the key and other identifiers |
|
645 /// that separate data between the other users that store same data type |
|
646 /// to the memory store. |
|
647 virtual eap_status_e memory_store_add_data( |
|
648 const eap_variable_data_c * const key, |
|
649 eap_tlv_message_data_c * const data, |
|
650 const u32_t timeout) = 0; |
|
651 |
|
652 /// Memory store is visible only during the eap_am_tools_c object is alive. |
|
653 /// This function gets data from memory store. |
|
654 /// Data is returned in eap_tlv_message_data_c object. |
|
655 /// Data is identified by key parameter. |
|
656 /// Serious WARNING: do use really good key values. |
|
657 /// Memory store is globally used by all EAP Core objects. |
|
658 /// Key must be good that other users do not use others data. |
|
659 /// Add the real data type as a string to the key and other identifiers |
|
660 /// that separate data between the other users that store same data type |
|
661 /// to the memory store. |
|
662 virtual eap_status_e memory_store_get_data( |
|
663 const eap_variable_data_c * const key, |
|
664 eap_tlv_message_data_c * const data) = 0; |
|
665 |
|
666 |
|
667 /// Memory store is visible only during the eap_am_tools_c object is alive. |
|
668 /// This function removes data from memory store. |
|
669 /// Data is identified by key parameter. |
|
670 /// Serious WARNING: do use really good key values. |
|
671 /// Memory store is globally used by all EAP Core objects. |
|
672 /// Key must be good that other users do not use others data. |
|
673 /// Add the real data type as a string to the key and other identifiers |
|
674 /// that separate data between the other users that store same data type |
|
675 /// to the memory store. |
|
676 virtual eap_status_e memory_store_remove_data( |
|
677 const eap_variable_data_c * const key) = 0; |
|
678 |
|
679 |
|
680 |
|
681 #if defined(USE_EAP_ERROR_TESTS) |
|
682 /** |
|
683 * This function generates random error to message. |
|
684 * This is used in protocol testing. |
|
685 */ |
|
686 virtual eap_status_e generate_random_error( |
|
687 eap_buf_chain_wr_c * const sent_packet, |
|
688 const bool forse_error, |
|
689 const u32_t packet_index, |
|
690 const u32_t minimum_index, |
|
691 const u32_t error_probability, |
|
692 const u32_t minimum_packet_length) = 0; |
|
693 |
|
694 /** |
|
695 * This function returns index of message. |
|
696 * This is used in protocol testing. |
|
697 */ |
|
698 virtual u32_t get_packet_index() = 0; |
|
699 |
|
700 /** |
|
701 * This function increases index of message. |
|
702 * This is used in protocol testing. |
|
703 */ |
|
704 virtual void increase_packet_index() = 0; |
|
705 #endif //#if defined(USE_EAP_ERROR_TESTS) |
|
706 |
|
707 |
|
708 /** |
|
709 * Function converts AM error value to eap_status_e. |
|
710 * @param am_error_value is the AM error value. |
|
711 */ |
|
712 virtual eap_status_e convert_am_error_to_eapol_error(const i32_t am_error_value) = 0; |
|
713 |
|
714 /** |
|
715 * Function converts eap_status_e to AM error value. |
|
716 * @param eap_error is the eap_status_e error value. |
|
717 */ |
|
718 virtual i32_t convert_eapol_error_to_am_error(eap_status_e eap_error) = 0; |
|
719 |
|
720 /** |
|
721 * This function returns true when milli second timer is used. |
|
722 */ |
|
723 virtual bool get_use_eap_milli_second_timer() = 0; |
|
724 |
|
725 /** |
|
726 * This function sets the flag whether to use milli second timer (true) or not (false). |
|
727 */ |
|
728 virtual void set_use_eap_milli_second_timer( |
|
729 const bool use_eap_millisecond_timer) = 0; |
|
730 |
|
731 /** |
|
732 * This function reads value of environment variable. |
|
733 * Note the all environments does not support this, for example Symbian. |
|
734 */ |
|
735 virtual eap_status_e getenv( |
|
736 const eap_variable_data_c * const environment_variable_name, |
|
737 eap_variable_data_c * const environment_variable_value) = 0; |
|
738 |
|
739 /** |
|
740 * This function converts string to u32_t value. |
|
741 */ |
|
742 virtual eap_status_e number_string_to_u32( |
|
743 const u8_t * const number_string, |
|
744 const u32_t number_string_length, |
|
745 u32_t * const integer) = 0; |
|
746 |
|
747 /** |
|
748 * This function checks whether the character is space. |
|
749 */ |
|
750 virtual bool isspace(const u8_t character) = 0; |
|
751 |
|
752 /** |
|
753 * This function traces read configure field and data. |
|
754 */ |
|
755 virtual void trace_configuration( |
|
756 const eap_status_e configuration_read_status, |
|
757 const eap_configuration_field_c * const field, |
|
758 const eap_variable_data_c * const data) = 0; |
|
759 |
|
760 /** |
|
761 * This function converts u64_t to u64_struct type. |
|
762 * This is used in some 64-bit calculations. |
|
763 */ |
|
764 virtual u64_struct u64_t_to_u64_struct(const u64_t value) = 0; |
|
765 |
|
766 /** |
|
767 * This function converts u64_struct to u64_t type. |
|
768 * This is used in some 64-bit calculations. |
|
769 */ |
|
770 virtual u64_t u64_struct_to_u64_t(const u64_struct value) = 0; |
|
771 |
|
772 /** |
|
773 * This function xors two 64-bit integers. |
|
774 */ |
|
775 virtual u64_t xor_u64(const u64_t a, const u64_t b) = 0; |
|
776 |
|
777 /** |
|
778 * This function multiplys two 64-bit integers. |
|
779 * Returned value is remainder of 2^64, so overflow is not detected. |
|
780 */ |
|
781 virtual u64_t multiply_u64(const u64_t a, const u64_t b) = 0; |
|
782 |
|
783 /** |
|
784 * This function compares two 64-bit integers. |
|
785 * If a is bigger function returns positive integer. |
|
786 * If b is bigger function returns negative integer. |
|
787 * If a == b function returns zero integer. |
|
788 */ |
|
789 virtual i32_t compare_u64(const u64_t a, const u64_t b) = 0; |
|
790 |
|
791 /** |
|
792 * The create_uuid_v5() method creates an UUID version 5 (SHA-1) from the |
|
793 * name space UUID and name (RFC 4122). The name space UUID should be in |
|
794 * hex format (e.g. 3d813cbb47fb52ba91df831e1593ac29). The name space UUID |
|
795 * and name must be in network byte order (little endiann). |
|
796 * |
|
797 * @param ns_uuid pointer to the UUID of the name space in hex format. |
|
798 * @param ns_uuid_length lenght of the name space UUID in bytes (should be 16 bytes). |
|
799 * @param name pointer to the name (e.g. MAC address) in the name space in hex format. |
|
800 * @param name_length length of the name in bytes. |
|
801 * @param uuid pointer to an eap_variable_data_c instance to |
|
802 * which the UUID will be created. |
|
803 * @return status status code: eap_status_ok when successful, |
|
804 * otherwise an error code. |
|
805 */ |
|
806 virtual eap_status_e create_uuid_v5( |
|
807 const void* const ns_uuid, |
|
808 const u32_t ns_uuid_length, |
|
809 const void* const name, |
|
810 const u32_t name_length, |
|
811 eap_variable_data_c* const uuid ) = 0; |
|
812 |
|
813 /** |
|
814 * The create_uuid_v5_from_mac_address() method creates an UUID version 5 |
|
815 * from a MAC address. Uses an internally defined, fixed name space UUID |
|
816 * allocated for EAP MAC addresses. The MAC address should be in |
|
817 * hex format (little endiann). |
|
818 * |
|
819 * @param mac_address pointer to the MAC address in hex format. |
|
820 * @param mac_address_length length of the MAC address (should be 6 bytes). |
|
821 * @param uuid pointer to an eap_variable_data_c instance to |
|
822 * which the UUID will be created. |
|
823 * @return status status code: eap_status_ok when successful, |
|
824 * otherwise an error code. |
|
825 */ |
|
826 virtual eap_status_e create_uuid_v5_from_mac_address( |
|
827 const u8_t* const mac_address, |
|
828 const u32_t mac_address_length, |
|
829 eap_variable_data_c* const uuid ) = 0; |
|
830 |
|
831 }; |
|
832 |
|
833 |
|
834 #endif //#if !defined( _ABS_EAP_AM_TOOLS_H_ ) |
|
835 |
|
836 |
|
837 |
|
838 // End. |