--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/eapol/eapol_framework/eapol_common/am/include/abs_eap_am_tools.h Thu Dec 17 08:47:43 2009 +0200
@@ -0,0 +1,838 @@
+/*
+* Copyright (c) 2001-2006 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of the License "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: EAP and WLAN authentication protocols.
+*
+*/
+
+
+
+
+
+#if !defined( _ABS_EAP_AM_TOOLS_H_ )
+#define _ABS_EAP_AM_TOOLS_H_
+
+#include "eap_am_types.h"
+#include "eap_am_export.h"
+#include "eap_status.h"
+#include "abs_eap_base_timer.h"
+//#include "eap_am_memory_store_data.h"
+
+
+#if defined(EAP_LITTLE_ENDIAN) && defined(EAP_BIG_ENDIAN)
+#error Do not define both EAP_LITTLE_ENDIAN and EAP_BIG_ENDIAN
+#endif
+
+#if !defined(EAP_LITTLE_ENDIAN) && !defined(EAP_BIG_ENDIAN)
+#error Do define either EAP_LITTLE_ENDIAN or EAP_BIG_ENDIAN
+#endif
+
+class abs_eap_am_crypto_c;
+class eap_variable_data_c;
+class abs_eap_am_mutex_c;
+class eap_buf_chain_wr_c;
+class eap_configuration_field_c;
+class eap_tlv_message_data_c;
+
+/// This class offers some services that are dependent of platform Y.
+/**
+ * Current services are timer handling, crypto library, trace functions,
+ * memory manipulation and hardware tick counter. Use of eap_am_tools is through
+ * abstract virtual class abs_eap_am_tools. A pointer to the abs_eap_am_tools
+ * class is given to all other classes as a parameter to each constructor.
+ * Adaptation module creates the eap_am_tools_Y class before it initializes the stack.
+ * This prevents the need of global objects.
+ */
+class EAP_EXPORT abs_eap_am_tools_c
+{
+
+public:
+
+ /**
+ * The destructor of the abs_eap_am_tools_c class does nothing special.
+ */
+ virtual ~abs_eap_am_tools_c()
+ {
+ }
+
+ /**
+ * The constructor of the abs_eap_am_tools_c does nothing special.
+ */
+ abs_eap_am_tools_c()
+ {
+ }
+
+ /**
+ * This function allocates platform specific tools object.
+ * Note this function calls also configure() of the allocated tools object.
+ * The platform specific module must implement this function.
+ */
+ EAP_FUNC_IMPORT_INTERFACE static abs_eap_am_tools_c * new_abs_eap_am_tools_c();
+
+ /**
+ * This function deletes platform specific tools object.
+ * Note this function calls also shutdown() of the allocated tools object.
+ * The platform specific module must implement this function.
+ */
+ EAP_FUNC_IMPORT_INTERFACE static void delete_abs_eap_am_tools_c(abs_eap_am_tools_c * const am_tools);
+
+ /**
+ * The configure() function is called after the constructor of the
+ * object is successfully executed. During the function call the object
+ * could query the configuration. Each derived class must define this function.
+ * Needed configuration depends on the implementation.
+ */
+ virtual eap_status_e configure() = 0;
+
+ /**
+ * The shutdown() function is called before the destructor of the
+ * object is executed. During the function call the object
+ * could shutdown the operations, for example cancel timers.
+ * Each derived class must define this function.
+ */
+ virtual eap_status_e shutdown() = 0;
+
+ /**
+ * Function converts unicode characters into UTF8 characters.
+ * @param dest is reference to destination utf8 variable data.
+ * @param src is refrence to unicode variable data.
+ * @return eap status code.
+ */
+ virtual eap_status_e convert_unicode_to_utf8(
+ eap_variable_data_c & dest,
+ const eap_variable_data_c & src) = 0;
+
+ /**
+ * Function converts UTF8 characters into unicode characters.
+ * @param dest is reference to destination unicode variable data.
+ * @param src is refrence to UTF8 variable data.
+ * @return eap status code.
+ */
+ virtual eap_status_e convert_utf8_to_unicode(
+ eap_variable_data_c & dest,
+ const eap_variable_data_c & src) = 0;
+
+ /**
+ * Function parses NAI to usename and realm.
+ * If either is missing the corresponding value will be invalid.
+ */
+ virtual eap_status_e parse_nai(
+ const eap_variable_data_c * const nai,
+ eap_variable_data_c * const username,
+ eap_variable_data_c * const realm) = 0;
+
+ /**
+ * Function converts one octet to ascii character.
+ * @param octet is the converted octet.
+ * @return acsii byte.
+ */
+ virtual u8_t octet_to_ascii(i32_t octet) = 0;
+
+ /**
+ * Function converts one ascii character to octet.
+ * @param character is the converted ascii character.
+ * @return octet.
+ */
+ virtual u8_t ascii_to_octet(i32_t character) = 0;
+
+ /**
+ * The memmove() function copies count bytes from src to dest.
+ * The implementation must handle overlapping memory areas correctly.
+ * Check always the destination is correct memory.
+ * This function is low level and cannot check the used memory.
+ * @param dest is pointer to the destination.
+ * @param src is pointer to the source.
+ * @param count indicates the count of copied bytes.
+ */
+ virtual void memmove(
+ void *dest,
+ const void *src,
+ const u32_t count) = 0;
+
+ /**
+ * The memcmp() function compares count bytes from buf1 and buf2.
+ * @return Returns zero when all count bytes are equal.
+ * @return Returns negative integer when buf1 contains smaller different byte.
+ * @return Returns positive integer when buf1 contains bigger different byte.
+ */
+ virtual i32_t memcmp(
+ const void * const buf1,
+ const void * const buf2,
+ const u32_t count) = 0;
+
+ /**
+ * The memset function sets the first count bytes of dest to the character fill_byte.
+ * Check always the destination is correct memory.
+ * This function is low level and cannot check the used memory.
+ * @param dest is pointer to the destination.
+ * @param fill_byte is the fill value.
+ * @param count indicates the count of set bytes.
+ */
+ virtual void memset(
+ void * const dest,
+ const i32_t fill_byte,
+ const u32_t count) = 0;
+
+ /**
+ * The memchr function searches the first occurence of character starting from buf.
+ * Maximum count bytes are searched.
+ */
+ virtual void *memchr(
+ const void *buf,
+ u8_t character,
+ u32_t count) = 0;
+
+ /**
+ * The memchr function searches the last occurence of character starting from the enf of the buf.
+ * Maximum count bytes are searched.
+ */
+ virtual void *memrchr(
+ const void *buf,
+ u8_t character,
+ u32_t count) = 0;
+
+ /**
+ * Get the length of a string.
+ * @return Function returns the number of characters in string,
+ * excluding the terminal NULL. No return value is reserved to indicate an error.
+ */
+ virtual u32_t strlen(
+ eap_const_string string) = 0;
+
+ /**
+ * Get the length of a string.
+ * @return Function returns the number of characters in string,
+ * excluding the terminal NULL. No return value is reserved to indicate an error.
+ */
+ virtual u32_t config_strlen(
+ eap_config_string string) = 0;
+
+ /**
+ * Function converts lovercase ascii characters to uppercase.
+ * @param source_bytes is pointer to the source bytes.
+ * @param source_bytes_length is length of source bytes.
+ */
+ virtual eap_status_e convert_ascii_to_uppercase(
+ u8_t * const source_bytes,
+ const u32_t source_bytes_length) = 0;
+ /**
+ * Function converts bytes to hex ascii.
+ * @param source_bytes is pointer to the source bytes.
+ * @param source_bytes_length is length of source bytes.
+ * @param target is pointer to the target bytes.
+ * @param target_length is length of target bytes.
+ */
+ virtual eap_status_e convert_bytes_to_hex_ascii(
+ const u8_t * const source_bytes,
+ const u32_t source_bytes_length,
+ u8_t * const target,
+ u32_t *target_length) = 0;
+
+ /**
+ * Function converts bytes to hex ascii.
+ * @param source_bytes is pointer to the source bytes.
+ * @param source_bytes_length is length of source bytes.
+ * @param target is pointer to the target buffer.
+ */
+ virtual eap_status_e convert_bytes_to_hex_ascii(
+ const void * const source_bytes,
+ const u32_t source_bytes_length,
+ eap_variable_data_c * const target) = 0;
+
+ /**
+ * Function converts hex ascii to bytes.
+ * @param source_bytes is pointer to the source bytes.
+ * @param source_bytes_length is length of source bytes.
+ * @param target is pointer to the target bytes.
+ * @param target_length is length of target bytes.
+ */
+ virtual eap_status_e convert_hex_ascii_to_bytes(
+ const u8_t * const source_bytes,
+ const u32_t source_bytes_length,
+ u8_t * const target,
+ u32_t *target_length) = 0;
+
+ /**
+ * Function converts hex ascii to bytes.
+ * @param source_bytes is pointer to the source bytes.
+ * @param source_bytes_length is length of source bytes.
+ * @param target is pointer to the target bytes.
+ * @param target_length is length of target bytes.
+ */
+ virtual eap_status_e convert_hex_ascii_to_bytes(
+ const void * const source_bytes,
+ const u32_t source_bytes_length,
+ eap_variable_data_c * const target) = 0;
+
+ /**
+ * Function converts bytes to ascii armored bytes.
+ * @param source_bytes is pointer to the source bytes.
+ * @param source_bytes_length is length of source bytes.
+ * @param target is pointer to the target bytes.
+ * @param target_length is length of target bytes.
+ * @code
+ * Binary 6-bit blocks are converted to 8-bit ascii values. Ascii values can easily represent 2^6=64 values.
+ * If length of target array is not module 3, padding zero bits are ignored.
+ *
+ * |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|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 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|
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * @endcode
+ */
+ virtual eap_status_e convert_bytes_to_ascii_armor(
+ const u8_t * const source_bytes,
+ const u32_t source_bytes_length,
+ u8_t * const target,
+ u32_t *target_length) = 0;
+
+ /**
+ * Function converts ascii armored bytes to bytes.
+ * @param source_bytes is pointer to the source bytes.
+ * @param source_bytes_length is length of source bytes.
+ * @param target is pointer to the target bytes.
+ * @param target_length is length of target bytes.
+ * @code
+ * 8-bit ascii values are converted to binary 6-bit blocks. Ascii values can easily represent 2^6=64 values.
+ * If length of source array is not module 3, missing bits are padded with zero bits.
+ *
+ * |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:0:0:0|
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * |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|
+ * | | | | | | +
+ * | | | | | | \
+ * | | | | | + \
+ * | | | | | \ \
+ * | | | | + \ \
+ * | | | | \ \ \
+ * | | | + \ \ \
+ * | | | \ \ \ \
+ * | | + \ \ \ \
+ * | | \ \ \ \ \
+ * | + \ \ \ \ \
+ * | \ \ \ \ \ \
+ * | \ \ \ \ \ \
+ * | + + + + + +
+ * | | | | | | |
+ * |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|
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : | : : : : : : : |
+ * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ * @endcode
+ */
+ virtual eap_status_e restore_bytes_from_ascii_armor(
+ const u8_t * const source_bytes,
+ const u32_t source_bytes_length,
+ u8_t * const target,
+ u32_t *target_length) = 0;
+
+ /**
+ * Gets the current trace mask.
+ */
+ virtual u32_t get_trace_mask() const = 0;
+
+ /**
+ * This function sets the current trace mask.
+ */
+ virtual void set_trace_mask(const u32_t mask) = 0;
+
+ /**
+ * This function sets the trace output file name.
+ */
+ virtual eap_status_e set_trace_file_name(const eap_variable_data_c * const trace_output_file) = 0;
+
+ /**
+ * This function sets the maximum size of trace output file in bytes.
+ * Note this is not absolute value. New file is generated when size of trace log file
+ * exceeds this limitation.
+ */
+ virtual void set_max_trace_file_size(const u32_t max_trace_file_size) = 0;
+
+ /**
+ * This functions allows activation of trace when the error occurs.
+ * Look at the set_activate_trace_on_error() and eap_status_return()
+ * functions. NOTE the always active traces are only left active.
+ * That means set_activate_trace_on_error() function calls
+ * set_trace_mask(eap_trace_mask_always).
+ */
+ virtual void set_activate_trace_on_error() = 0;
+
+ virtual void check_activate_trace_on_error() = 0;
+
+ /**
+ * This function formats string to buffer.
+ * Function returns number of written bytes.
+ */
+ virtual u32_t snprintf(u8_t * const buffer, u32_t buffer_size, eap_format_string format, ...) = 0;
+
+ /**
+ * The formatted_print() function traces format string and formatted parameters to file.
+ * File is set as a parameter to constructor. This is used in macros
+ * EAP_TRACE_DEBUG(object_name, _parameter_list_) and
+ * EAP_TRACE_ERROR(object_name, _parameter_list_).
+ */
+ virtual void formatted_print(
+ eap_format_string format,
+ ...) = 0;
+
+ /**
+ * The trace_data() function traces null terminated prefix string
+ * and data_length bytes from p_data to file. This is used in macros
+ * EAP_TRACE_DATA_DEBUG(object_name, _parameter_list_) and
+ * EAP_TRACE_DATA_ERROR(object_name, _parameter_list_).
+ */
+ virtual void trace_data(
+ eap_const_string prefix,
+ const void * const p_data,
+ const u32_t data_length) = 0;
+
+ /**
+ * The get_crypto() function returns a pointer to object of type eap_am_crypto.
+ */
+ virtual abs_eap_am_crypto_c * get_crypto() = 0;
+
+ /**
+ * This function returns the current time and date in standard UNIX 32-bit format (seconds
+ * since the midnight starting Jan 1, 1970, GMT) according to the
+ * sender's internal clock.
+ */
+ virtual u32_t get_gmt_unix_time() = 0;
+
+ /**
+ * The get_hardware_ticks() function returns current value of hardware ticks counter.
+ */
+ virtual u64_t get_hardware_ticks() = 0;
+
+ /**
+ * Function returns count of hardware ticks in one second.
+ */
+ virtual u64_t get_hardware_ticks_of_second() = 0;
+
+ /**
+ * Function returns count of clock ticks in one second.
+ */
+ virtual u64_t get_clock_ticks_of_second() = 0;
+
+ /**
+ * Function returns current value of clock ticks counter.
+ */
+ virtual u64_t get_clock_ticks() = 0;
+
+ /**
+ * Returns true when timer queue is used.
+ * Returns false when timer queue is not used.
+ */
+ virtual bool get_use_timer_queue() = 0;
+
+ /**
+ * Returns true when timer thread is stopped.
+ * Returns false when timer thread is running.
+ */
+ virtual bool get_thread_stopped() = 0;
+
+ /**
+ * The set_timer() function initializes timer to be elapsed after p_time_ms milliseconds.
+ * @param initializer is pointer to object which timer_expired() function will
+ * be called after timer elapses.
+ * @param id is identifier which will be returned in timer_expired() function.
+ * The user selects and interprets the id for this timer.
+ * @param data is pointer to any user selected data which will be returned in timer_expired() function.
+ *
+ * Adaptation module of tools includes internal attribute eap_timer_queue_c to
+ * which this call is directed.
+ */
+ virtual eap_status_e am_set_timer(
+ abs_eap_base_timer_c * const initializer,
+ const u32_t id,
+ void * const data,
+ const u32_t p_time_ms) = 0;
+
+ /**
+ * The cancel_timer() function cancels the timer id initiated by initializer.
+ *
+ * Adaptation module of tools includes internal attribute eap_timer_queue_c to
+ * which this call is directed.
+ */
+ virtual eap_status_e am_cancel_timer(
+ abs_eap_base_timer_c * const initializer,
+ const u32_t id) = 0;
+
+ /**
+ * The cancel_all_timers() function cancels all timers.
+ * User should use this in termination of the stack before
+ * the adaptation module of tools is deleted.
+ *
+ * Adaptation module of tools includes internal attribute eap_timer_queue_c to
+ * which this call is directed.
+ *
+ * This function de-activated timer queue.
+ * You could re-activate timer queue with re_activate_timer_queue function.
+ */
+ virtual eap_status_e am_cancel_all_timers() = 0;
+
+ /**
+ * This function re-activates timer queue.
+ * Symbian AM call this function when AM-tools object is re-used.
+ * This can be called after am_cancel_all_timers() function.
+ * am_cancel_all_timers() function de-activated timer queue.
+ */
+ virtual eap_status_e re_activate_timer_queue() = 0;
+
+ /**
+ * This function sets the resolution of the timer.
+ * The default value is EAP_TIMER_RESOLUTION.
+ * Each pulse increases time by this value.
+ *
+ * Adaptation module of tools includes internal attribute eap_timer_queue_c to
+ * which this call is directed.
+ */
+ virtual void set_timer_resolution_ms(const u32_t timer_resolution_ms) = 0;
+
+ /**
+ * This function returns the resolution of the timer.
+ * Each pulse increases time by this value.
+ *
+ * Adaptation module of tools includes internal attribute eap_timer_queue_c to
+ * which this call is directed.
+ */
+ virtual u32_t get_timer_resolution_ms() = 0;
+
+ /**
+ * Pulses timer. Time is increased by get_timer_resolution_ms() milli seconds.
+ * Timer pulse is run parallel to the stack operation.
+ * This causes the use of global mutex.
+ *
+ * Adaptation module of tools includes internal attribute eap_timer_queue_c to
+ * which this call is directed.
+ * Function returns the next sleep time in milli seconds.
+ */
+ virtual u32_t pulse_timer(const u32_t elapsed_time_in_ms) = 0;
+
+ /**
+ * This function checks whether the internal timer queue is empty.
+ */
+ virtual bool get_timer_queue_is_empty() = 0;
+
+ /**
+ * Starts the thread to pulse timer.
+ * User of tools should call this after the stack is created.
+ */
+ virtual eap_status_e start_timer_thread() = 0;
+
+ /**
+ * Stops the timer thread.
+ * User of tools should call this before the stack is deleted.
+ */
+ virtual eap_status_e stop_timer_thread() = 0;
+
+ /**
+ * Function runs the timer thread loop. This function calls the pulse_timer()
+ * function to increase the elapsed time.
+ */
+ virtual eap_status_e timer_thread_function() = 0;
+
+ /**
+ * Returns the value of timer thread activity.
+ * Timer thread stops when this functions returns false.
+ */
+ virtual bool get_is_timer_thread_active() = 0;
+
+ /**
+ * This function enters the global mutex. Mutex is needed to synchronize
+ * the timer thread and stack call operations.
+ * Timer pulse is run parallel to the stack operation.
+ * This causes the use of global mutex.
+ */
+ virtual void enter_global_mutex() = 0;
+
+ /**
+ * This function leaves the global mutex.
+ * Timer pulse is run parallel to the stack operation.
+ * This causes the use of global mutex.
+ */
+ virtual void leave_global_mutex() = 0;
+
+ /**
+ * Returns the global mutex. This is used in some assertion tests.
+ */
+ virtual abs_eap_am_mutex_c * get_global_mutex() = 0;
+
+ #define ENTER_CRYPTO()
+ #define LEAVE_CRYPTO()
+
+ /**
+ * The timer_sleep function suspends the execution of the current timer thread for the specified interval.
+ * Timer could be set any value. When timer is set to shorter timeout than the smallest current
+ * timeout is the timer_sleep() will cancel sleep and the new sleep time could be calculated.
+ * @param milli_seconds is the suspension time in milli seconds.
+ */
+ virtual void timer_sleep(u32_t milli_seconds) = 0;
+
+ /**
+ * The sleep function suspends the execution of the current thread for the specified interval.
+ * @param milli_seconds is the suspension time in milli seconds.
+ */
+ virtual void sleep(u32_t milli_seconds) = 0;
+
+ /**
+ * The get_is_valid() function returns the status of the object.
+ * True indicates the object is initialized succesfully.
+ */
+ virtual bool get_is_valid() const = 0;
+
+#if (defined(DMALLOC) || defined(USE_EAP_CRYPTO_MEMORY_LEAK_FUNCTIONS)) && !defined(USE_EAP_LOCAL_TRACE_FILE_OPEN)
+ virtual const EAP_FILE_POINTER * get_trace_file() = 0;
+#endif //#if defined(DMALLOC) && !defined(USE_EAP_LOCAL_TRACE_FILE_OPEN)
+
+ /// This function is global proxy for return values.
+ virtual eap_status_e eap_status_return(
+ const bool print_error_when_true,
+ const eap_status_e status,
+ const eap_char * const file_name,
+ const i32_t line_number) = 0;
+
+ /// This function is global proxy for return values with file name and line number.
+ /// This is used in traces.
+ virtual eap_status_e eap_status_return_file_number(
+ const bool print_error_when_true,
+ const eap_status_e status,
+ const u32_t file_date,
+ const u32_t file_number,
+ const i32_t line_number) = 0;
+
+ /// Memory store is visible only during the eap_am_tools_c object is alive.
+ /// This function add flat data to memory store.
+ /// You must format your data to eap_tlv_message_data_c object.
+ /// Data is identified by key parameter.
+ /// You can set timeout to data. Data will be automatically removed after timeout.
+ /// Timeout value zero means no timeout is set.
+ /// Serious WARNING: do use really good key values.
+ /// Memory store is globally used by all EAP Core objects.
+ /// Key must be good that other users do not use others data.
+ /// Add the real data type as a string to the key and other identifiers
+ /// that separate data between the other users that store same data type
+ /// to the memory store.
+ virtual eap_status_e memory_store_add_data(
+ const eap_variable_data_c * const key,
+ eap_tlv_message_data_c * const data,
+ const u32_t timeout) = 0;
+
+ /// Memory store is visible only during the eap_am_tools_c object is alive.
+ /// This function gets data from memory store.
+ /// Data is returned in eap_tlv_message_data_c object.
+ /// Data is identified by key parameter.
+ /// Serious WARNING: do use really good key values.
+ /// Memory store is globally used by all EAP Core objects.
+ /// Key must be good that other users do not use others data.
+ /// Add the real data type as a string to the key and other identifiers
+ /// that separate data between the other users that store same data type
+ /// to the memory store.
+ virtual eap_status_e memory_store_get_data(
+ const eap_variable_data_c * const key,
+ eap_tlv_message_data_c * const data) = 0;
+
+
+ /// Memory store is visible only during the eap_am_tools_c object is alive.
+ /// This function removes data from memory store.
+ /// Data is identified by key parameter.
+ /// Serious WARNING: do use really good key values.
+ /// Memory store is globally used by all EAP Core objects.
+ /// Key must be good that other users do not use others data.
+ /// Add the real data type as a string to the key and other identifiers
+ /// that separate data between the other users that store same data type
+ /// to the memory store.
+ virtual eap_status_e memory_store_remove_data(
+ const eap_variable_data_c * const key) = 0;
+
+
+
+#if defined(USE_EAP_ERROR_TESTS)
+ /**
+ * This function generates random error to message.
+ * This is used in protocol testing.
+ */
+ virtual eap_status_e generate_random_error(
+ eap_buf_chain_wr_c * const sent_packet,
+ const bool forse_error,
+ const u32_t packet_index,
+ const u32_t minimum_index,
+ const u32_t error_probability,
+ const u32_t minimum_packet_length) = 0;
+
+ /**
+ * This function returns index of message.
+ * This is used in protocol testing.
+ */
+ virtual u32_t get_packet_index() = 0;
+
+ /**
+ * This function increases index of message.
+ * This is used in protocol testing.
+ */
+ virtual void increase_packet_index() = 0;
+#endif //#if defined(USE_EAP_ERROR_TESTS)
+
+
+ /**
+ * Function converts AM error value to eap_status_e.
+ * @param am_error_value is the AM error value.
+ */
+ virtual eap_status_e convert_am_error_to_eapol_error(const i32_t am_error_value) = 0;
+
+ /**
+ * Function converts eap_status_e to AM error value.
+ * @param eap_error is the eap_status_e error value.
+ */
+ virtual i32_t convert_eapol_error_to_am_error(eap_status_e eap_error) = 0;
+
+ /**
+ * This function returns true when milli second timer is used.
+ */
+ virtual bool get_use_eap_milli_second_timer() = 0;
+
+ /**
+ * This function sets the flag whether to use milli second timer (true) or not (false).
+ */
+ virtual void set_use_eap_milli_second_timer(
+ const bool use_eap_millisecond_timer) = 0;
+
+ /**
+ * This function reads value of environment variable.
+ * Note the all environments does not support this, for example Symbian.
+ */
+ virtual eap_status_e getenv(
+ const eap_variable_data_c * const environment_variable_name,
+ eap_variable_data_c * const environment_variable_value) = 0;
+
+ /**
+ * This function converts string to u32_t value.
+ */
+ virtual eap_status_e number_string_to_u32(
+ const u8_t * const number_string,
+ const u32_t number_string_length,
+ u32_t * const integer) = 0;
+
+ /**
+ * This function checks whether the character is space.
+ */
+ virtual bool isspace(const u8_t character) = 0;
+
+ /**
+ * This function traces read configure field and data.
+ */
+ virtual void trace_configuration(
+ const eap_status_e configuration_read_status,
+ const eap_configuration_field_c * const field,
+ const eap_variable_data_c * const data) = 0;
+
+ /**
+ * This function converts u64_t to u64_struct type.
+ * This is used in some 64-bit calculations.
+ */
+ virtual u64_struct u64_t_to_u64_struct(const u64_t value) = 0;
+
+ /**
+ * This function converts u64_struct to u64_t type.
+ * This is used in some 64-bit calculations.
+ */
+ virtual u64_t u64_struct_to_u64_t(const u64_struct value) = 0;
+
+ /**
+ * This function xors two 64-bit integers.
+ */
+ virtual u64_t xor_u64(const u64_t a, const u64_t b) = 0;
+
+ /**
+ * This function multiplys two 64-bit integers.
+ * Returned value is remainder of 2^64, so overflow is not detected.
+ */
+ virtual u64_t multiply_u64(const u64_t a, const u64_t b) = 0;
+
+ /**
+ * This function compares two 64-bit integers.
+ * If a is bigger function returns positive integer.
+ * If b is bigger function returns negative integer.
+ * If a == b function returns zero integer.
+ */
+ virtual i32_t compare_u64(const u64_t a, const u64_t b) = 0;
+
+ /**
+ * The create_uuid_v5() method creates an UUID version 5 (SHA-1) from the
+ * name space UUID and name (RFC 4122). The name space UUID should be in
+ * hex format (e.g. 3d813cbb47fb52ba91df831e1593ac29). The name space UUID
+ * and name must be in network byte order (little endiann).
+ *
+ * @param ns_uuid pointer to the UUID of the name space in hex format.
+ * @param ns_uuid_length lenght of the name space UUID in bytes (should be 16 bytes).
+ * @param name pointer to the name (e.g. MAC address) in the name space in hex format.
+ * @param name_length length of the name in bytes.
+ * @param uuid pointer to an eap_variable_data_c instance to
+ * which the UUID will be created.
+ * @return status status code: eap_status_ok when successful,
+ * otherwise an error code.
+ */
+ virtual eap_status_e create_uuid_v5(
+ const void* const ns_uuid,
+ const u32_t ns_uuid_length,
+ const void* const name,
+ const u32_t name_length,
+ eap_variable_data_c* const uuid ) = 0;
+
+ /**
+ * The create_uuid_v5_from_mac_address() method creates an UUID version 5
+ * from a MAC address. Uses an internally defined, fixed name space UUID
+ * allocated for EAP MAC addresses. The MAC address should be in
+ * hex format (little endiann).
+ *
+ * @param mac_address pointer to the MAC address in hex format.
+ * @param mac_address_length length of the MAC address (should be 6 bytes).
+ * @param uuid pointer to an eap_variable_data_c instance to
+ * which the UUID will be created.
+ * @return status status code: eap_status_ok when successful,
+ * otherwise an error code.
+ */
+ virtual eap_status_e create_uuid_v5_from_mac_address(
+ const u8_t* const mac_address,
+ const u32_t mac_address_length,
+ eap_variable_data_c* const uuid ) = 0;
+
+};
+
+
+#endif //#if !defined( _ABS_EAP_AM_TOOLS_H_ )
+
+
+
+// End.